t1k:playablelabs:base:shade-parity
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | high |
| Tools | — |
Keywords: check-shade3d, planar shadow parity, plashade1, shade extraction, shade parity, shading parity gate
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:shade-parity<extract | validate | gate | selftest | unit> [--game-profile <file>] [--bundle <dir>]PlayableLabs shading parity (plashade1): port a reference game’s lights, materials and shadows with proof
Section titled “PlayableLabs shading parity (plashade1): port a reference game’s lights, materials and shadows with proof”One engine-neutral package, installed with every PlayableLabs kit install (module base). It turns a reference scene’s shading
(lights, ambient, materials, planar and authored shadows, colour pipeline, fog verdict) into a data format (plashade1), applies it
with a deterministic pure-JS runtime, and judges the port with a parity gate (S1..S8) that has named RED arms. The renderer sits on a
thin adapter; extractors stay per source. Nothing in the core or gate names a game: per-game data lives in a profile you own
(references/PROFILE-GUIDE.md). Particles are NOT here: see t1k-playablelabs-base-vfx-core.
What ships (all under scripts/)
Section titled “What ships (all under scripts/)”| Piece | File | Role |
|---|---|---|
| format | references/CONTRACT.md | the spec; validate-shade.cjs is its executable form |
| core | shade-core.js | Shade load/attach/lights/materialFor/shadowState/shadowItems/project; ZERO three/cocos/DOM imports |
| gate | check-shade3d.cjs, shade3d.reader.cjs, shade3d.profile.cjs | S1..S8 + --selftest (49 RED arms, +1 per game arm) |
| runtime unit suite | check-shade-unit.cjs | 120+ numeric checks of core and adapter + 55 named breaks |
| extractor (Cocos 3.x bundle) | extract-shade.cjs | bundle -> shade.json + evidence doc, --check for drift |
| web adapter | adapter-three.js | draws a display list; THREE and Shade injected |
| worked example | examples/topforce/game.profile.cjs | ONE game’s profile and measured S8 table; fixtures in fixtures/shade3d/ |
There is no Cocos adapter: the Cocos side is UNVERIFIED (references/OPEN-ITEMS.md row 7).
Workflow
Section titled “Workflow”- Get plashade1. Cocos bundle:
bun scripts/extract-shade.cjs --bundle <build> --game-profile <yours> --out <dir>, thenbun scripts/validate-shade.cjs --json <dir>/shade.json --docs <dir>/SHADE-EXTRACTION.md. Other source: write the same files (references/CONTRACT.mdsections 1-5). Read the evidence doc’s “Fog verdict” and “Colour pipeline” before porting. - Run the gate:
bun scripts/check-shade3d.cjs --shade <dir>/shade.json --evidence <docs> --bundle <build> --game-profile <yours> --root <game>(--require-render --compare-play <tool> --ref-html <ref>adds S7/S8 on a real page). Exit 0 green, 1 red (aFAIL Snline), 2 harness. - Prove the gate and the runtime before trusting a green:
bun scripts/check-shade3d.cjs --selftest(every arm RED for ITS check) andbun scripts/check-shade-unit.cjsplus--selftest. A gate green does not cover the adapter (OPEN-ITEMS.mdrows 3-5). - Adapt.
ShadeThree.create(THREE, Shade, canvas),Shade.attach(models, layout), thendraw(frame)withShade.lights(),Shade.ambient(),Shade.fog()andShade.shadowItems(...)in the frame. - Hand over evidence: the gate output with its SKIP/PENDING list and the
OPEN-ITEMS.mdrows that apply to your game.
- Shading is cosmetic:
shadowItemsand every API leave the document and the frame untouched; muting shading changes no gameplay. - A fog exists only from a decoded enabled
Fog; a light, tint or threshold is read fromshade.json, never fitted. A fitted constant is a defect. - Unknown enums and unknown colour-pipeline fields are errors, not guesses. A field the source has and plashade1 cannot carry goes to
gaps[]. - A tolerance or an S8 threshold is never loosened without its measurement and reason written beside it in the profile.
- An arm that cannot run (no
--bundle, no game files) is a named SKIP/PENDING;--require-render,--require-realfail it. - Do not claim what
references/OPEN-ITEMS.mdlists as unverified: S8 beyond one game, a Cocos target, a real GL frame of the adapter.
Second game, and the fx module split
Section titled “Second game, and the fx module split”A second game is a second profile file, no code edit (see examples/topforce/game.profile.cjs; references/PROFILE-GUIDE.md). Every
vfx3d.* / shade3d.* script here and in t1k-playablelabs-base-vfx-core takes --game-profile; nothing in the cores, gates or
readers names a game (the CI face asserts it: a worked example’s uuid, scene name or threshold may not appear outside examples/).
Second-game generality is UNVERIFIED. As of 2026-10-16 only one game has a 3D-path profile of this family (a scripts/shade3d.profile.cjs
beside the game, the worked example); the other game repositories in this workspace carry either the 2D canvas FX profile (a different
capability) or no 3D extractor. The gate’s own cross-check on the one game’s real data (the reachable 3D-path evidence) is green:
--vfx <game>/vfx.json --xf <game>/vfx.xf.json prints OK: V1 x82, V2 x42, V3 x36, V4 x101, V6 x6, V7 x12 with four V4/V5 SKIPs
(four mesh emitters plus the page marker). That is ONE game re-run. Do not read it as second-game evidence.
Decision: the adapters stay in this module (base), not in a separate fx module. Trigger conditions that would revisit it —
all three, or a maintainer call: (a) a SECOND engine adapter (Cocos) is VERIFIED against a real engine; (b) that adapter makes base
carry engine-specific weight the profile seam cannot absorb; (c) a second game’s profile proves a real per-engine split. Today only a
three.js adapter exists, no Cocos shading adapter is shipped, and shading just landed beside VFX; splitting now would move a
one-engine, one-game body of code behind an untested boundary. A second engine is the moment the seam earns its keep
(code-conventions.md § “Modular Boundaries”), not before.
Known open items (short form; full table in references/OPEN-ITEMS.md)
Section titled “Known open items (short form; full table in references/OPEN-ITEMS.md)”S8 shadow metrics are fixture-validated and checked on a real page for one game only, with thin margins. A flipped lit-sun position
is caught only by the unit suite; adapter-only defects reach only S7, S8 and the unit suite. Dropping or mis-reporting the planar pass
state in shadowState() (stencil, blend, depth) is now caught by S6 (+4 RED arms); the residue is any future field an adapter reads off
shadowState() that S6 does not name. The colour input decode is a one-game measurement. Only directional lights and linear fog are implemented.
Executed by
Section titled “Executed by”Running the extractor, validator, gate, unit suite and selftests and tabulating their output is mechanical; judging a RED, measuring
S8 thresholds, deciding a gap and writing a game profile is not. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run extract-shade.cjs, validate-shade.cjs, check-shade3d.cjs --selftest, check-shade-unit.cjs and tabulate PASS/RED/SKIP | t1k-data-verifier |
| Run the gate on a game’s data and report FAIL/SKIP lines per check | t1k-tester |
| Judge a RED or a SKIP, write the game profile, measure S8 thresholds, map the page contract | t1k-playablelabs-base-packer-engineer (sonnet, native) |