wizwar6e/research/fx3d-sprite-spec.md

The conjuration sprites — a spec for the artist

The first-person view (/?fpv, and the replay's "your eyes" mode) throws spell moments through the air as billboard sprites: flat images that always face the camera, drawn glowing in mid-air, occluded by walls, and scaled by distance. Nine sprites cover every spell moment in the game. Each lives at packages/web/public/textures/../fx3d/<name>.png — replace the file, refresh, done. The current files are placeholder radial glows; all nine are shown side by side at /?tokens under "The conjurations."

Technical requirements

• Format: PNG with a transparent background. The transparent area is essential — whatever is opaque is what flies.
• Size: square, any resolution; 128×128 or 256×256 recommended. The renderer scales freely and pixelates on magnification (the whole view is deliberately chunky, like the wall textures).
• Drawn additively: sprites are composited in "lighter" (additive) mode over a dark dungeon, so dark pixels vanish and bright pixels glow. Paint light-on-transparent; pure black will be invisible. Midtones read as translucent light.
• No animation frames. Each sprite is a single still. Motion comes from the renderer: projectiles streak across the room, impacts swell from small to large while fading out. Radially symmetric (or nearly so) designs work best since the image does not rotate.
• Fills most of the canvas. Leave only a small transparent margin; the renderer sizes the sprite by its canvas, not its painted extent.

The nine sprites and where they appear

file	flies as	moment
fireball.png	projectile	Fireball, Sudden Death, Blaster Wand — a ball of fire streaking caster → target
bolt.png	projectile	Lightning Blast, Power Drain — a crackling bolt
waterbolt.png	projectile	Waterbolt — a hurled gout of water
spark.png	projectile	anything else that travels: thrown objects, bodies knocked back, dragged things — a neutral streak of force
burst.png	impact	a fireball landing; victory fireworks — swells and fades
splash.png	impact	waterbolt landing, stone turned to water
hit.png	impact	damage landing on someone you can see; punches, claws
shimmer.png	impact	teleports, warps, illusions, minds touched — the general "magic happened here" glimmer, violet by tradition
shield.png	impact	an attack fully stopped; absorbed spells
rubble.png	prop	a destroyed wall's remains: bursts on the kill, then stands as a mound at the fallen edge for the rest of the reel. Unlike the others this is drawn OPAQUE (normal compositing) — paint it as solid debris, not light

Projectiles hold their size in flight (about a third of a wizard's height). Impacts start small and swell to roughly double while fading — so an impact painted as a ring or burst reads especially well.

What the sprites do NOT need to carry: screen-wide flashes when YOU are hit (red), healed (green), or teleported (violet), the camera shake, the door slide (doors animate by sliding door.png along its own edge — no separate art), and the jammed-lock seethe (a pulsing rust glow the renderer lays over the door) — those are renderer effects, not images.

The terrain, in two families

Floor decals — public/textures/pit.png, slime.png, tacks.png, dimwarp.png — are painted INTO the flagstones by the floor caster, alpha-blended texel by texel like the home tile: transparent wherever plain floor should show. The pit can carry its own painted label if wanted. Square, any size.

Standing volumes — public/terrain3d/thornbush.png, rosebush.png, jello.png, dust.png, warpglow.png — are billboards in the room. The hedges render CELL-WIDE at half wall height (paint them twice as wide as tall; a wizard in the square peeks over the top). The jello cube fills the whole square and is drawn ~60% opaque — paint it solid, the renderer supplies the translucency. Dust likewise. warpglow is a pillar of light drawn ADDITIVELY (like the old glow sprites): bright means bright, black vanishes. Rehearse any of them in place: /?fpv&terrain=thornbush@3,7;jello@4,7;dimwarp@2,7.

Walls' dressing and damage

public/textures/doorframe.png dresses OPEN doorways: paint an empty stone doorway on transparency — posts in the outer ~8% columns, the lintel in the top ~16% rows, nothing in the middle (the way through). public/textures/cracks.png is battle damage: dark fractures on transparency, laid over any damaged wall with opacity rising as the harm mounts. public/textures/underbrush.png is the ground beneath a hedge — leaf litter to the square's edges, a floor decal like the pit. public/terrain3d/safe.png is the wall safe, standing as an opaque strongbox (square, transparent ground).

Note on rubble.png: it renders stretched ACROSS the fallen wall's whole gap — one cell wide, half a cell tall — so piles painted at the canvas's lower corners land at the two posts.

One more paintable surface: the home tile

public/textures/home.png is a floor overlay for home-base cells, drawn over the flagstones and TINTED by the owning wizard's color at draw time. Paint it near-white/neutral with transparency wherever the plain floor should show through; the tint does the rest. Square, any size, same as the other textures.