Six abilities to one hundred, plus a program-cache bug in the shader patcher

[majidmanzarpour]

Your sandbox had six abilities. This takes it to one hundred, across fifteen schools, without changing the rules it was built under.

I started from your code because the discipline in it is unusual: no dimensions on the CPU, nothing is a texture, one technique per ability. Everything here obeys those rules, and there is now a headless test that enforces the first one mechanically instead of trusting it.

This is a big PR, and you should feel free to take part of it

318 files. I do not expect you to merge it as one lump, so the commits are ordered so each layer stands on its own and you can stop anywhere:

#	Commit	What it is	Useful alone?
1	feat(core)	Abilities become data: one registry, per-ability settings modules, schema-driven editor, spellbook UI, and the test harness	Yes
2	feat(vfx)	26 shared VFX modules, and the distortion pass switched on	Yes, depends on 1
3	feat(abilities)	The 94 new abilities	Depends on 1 and 2
4	fix	Three rendering bugs, one of them pre-existing in your code	Yes, standalone
5	docs	README brought up to date, plus the design specs	Yes

If only commit 4 is interesting to you, say so and I will open it as its own small PR against a clean branch and close this one. Genuinely no hard feelings.

The bug that was already there

Three abilities were blacking out the entire screen. Chasing it turned up something systemic in the original code:

patchOnBeforeCompile wraps every shader injection in an identically worded closure. three.js keys its program cache on onBeforeCompile.toString() by default, and the injected code lives in the closed-over function, so it never appears in that string. The result is that every patched material in the project shares one cache key, and each one after the first silently renders with a different material's compiled program: its own uniforms absent, the ones present holding another shader's values. Which ability broke depended on which was cast first, which is why it looked intermittent.

Fixed by deriving customProgramCacheKey from the injection's own source, composed down the chain. Materials that genuinely share an injection still share a program, so the cache keeps working.

The other two were pow() on a negative base. One was cos() of about 10,000 radians losing its mantissa to argument reduction and returning just outside [-1, 1]. The other was pow(sin(x), e), where float32 sin() returns roughly -1e-7 at its zeroes. Two of those sites are in SnareMaterial and predate this work. One NaN fragment is not one bad pixel: the bloom blur spreads it across its whole kernel and tone mapping NaN gives black, so a few bad fragments on one object turn the whole frame black. check.mjs now fails the build on pow() over a raw trig base, and I confirmed that check catches the bug by reintroducing it.

Also worth knowing: post.distortion shipped at 0.045, which was correct back when nothing wrote to that buffer. Now that emitters exist, every refraction effect was running at 4.5% of its authored strength.

Two things you flagged in the README, now closed

• "The distortion pass runs with nothing writing to it." It has five emitter types now, and Layers.js counts its writers so the clear, the draw and the resample are all skipped on frames where nothing is refracting. Turning it on would have been a poor trade if it then ran unconditionally.
• Adding an ability was four edits across four files. It is one registry descriptor now. ELEMENTS and ELEMENT_META still exist as derived views, which is why AimController, HUD and App needed no changes at all.

Verifying it

npm install
npm run check     # 100/100 abilities, 116 tech-library cases
npm run build
npm run dev       # Tab opens the spellbook

npm run check runs headless, with no WebGL. For each ability it cross-checks every settings.<id>.<key> reference against that ability's block, simulates the whole cast, and then mutates sliders on a zero-length frame and fails if nothing observable changes. That last one is your edit-while-paused invariant, turned into a test. It does not compile GLSL, so shader errors still need a browser; I verified all 100 cast in Chrome with zero console errors and no leaked scene state.

The six original abilities are untouched apart from the settings-module move, which I verified is byte-identical in value against HEAD.

A few of the new ones

• Dawnbreak borrows the scene's directional light and swings it, so every object in the world throws a real sweeping shadow. The ability itself draws almost nothing.
• Stasis Field draws nothing at all. It clamps other systems' clocks inside a radius, so a Storm Lance already in flight stops guttering.
• Thunderclap is mostly the silence between the flash and the pressure front arriving.
• Silence renders a hole in the frame. Not black, absent.
• Mirage is the caster's own skinned rig, cloned and posed from a recorded track, drawn with nothing but refraction.

docs/ROSTER.md and docs/ROSTER-II.md list all 94 with the single technique each one exists to show off, since an ability that is another slot with a different palette should not exist.

Thanks for publishing the original. The bolt's piecewise-linear noise and the beam's inverted core weighting are both lovely, and most of the new work is built on ideas taken straight from them.

🤖 Generated with Claude Code