Skip to content

t1k:playablelabs:base:shade-parity

FieldValue
Modulebase
Version2.29.2
Efforthigh
Tools—

Keywords: check-shade3d, planar shadow parity, plashade1, shade extraction, shade parity, shading parity gate

/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.

PieceFileRole
formatreferences/CONTRACT.mdthe spec; validate-shade.cjs is its executable form
coreshade-core.jsShade load/attach/lights/materialFor/shadowState/shadowItems/project; ZERO three/cocos/DOM imports
gatecheck-shade3d.cjs, shade3d.reader.cjs, shade3d.profile.cjsS1..S8 + --selftest (49 RED arms, +1 per game arm)
runtime unit suitecheck-shade-unit.cjs120+ numeric checks of core and adapter + 55 named breaks
extractor (Cocos 3.x bundle)extract-shade.cjsbundle -> shade.json + evidence doc, --check for drift
web adapteradapter-three.jsdraws a display list; THREE and Shade injected
worked exampleexamples/topforce/game.profile.cjsONE 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).

  1. Get plashade1. Cocos bundle: bun scripts/extract-shade.cjs --bundle <build> --game-profile <yours> --out <dir>, then bun scripts/validate-shade.cjs --json <dir>/shade.json --docs <dir>/SHADE-EXTRACTION.md. Other source: write the same files (references/CONTRACT.md sections 1-5). Read the evidence doc’s “Fog verdict” and “Colour pipeline” before porting.
  2. 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 (a FAIL Sn line), 2 harness.
  3. Prove the gate and the runtime before trusting a green: bun scripts/check-shade3d.cjs --selftest (every arm RED for ITS check) and bun scripts/check-shade-unit.cjs plus --selftest. A gate green does not cover the adapter (OPEN-ITEMS.md rows 3-5).
  4. Adapt. ShadeThree.create(THREE, Shade, canvas), Shade.attach(models, layout), then draw(frame) with Shade.lights(), Shade.ambient(), Shade.fog() and Shade.shadowItems(...) in the frame.
  5. Hand over evidence: the gate output with its SKIP/PENDING list and the OPEN-ITEMS.md rows that apply to your game.
  • Shading is cosmetic: shadowItems and 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 from shade.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-real fail it.
  • Do not claim what references/OPEN-ITEMS.md lists as unverified: S8 beyond one game, a Cocos target, a real GL frame of the adapter.

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.

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”.

StepAgent
Run extract-shade.cjs, validate-shade.cjs, check-shade3d.cjs --selftest, check-shade-unit.cjs and tabulate PASS/RED/SKIPt1k-data-verifier
Run the gate on a game’s data and report FAIL/SKIP lines per checkt1k-tester
Judge a RED or a SKIP, write the game profile, measure S8 thresholds, map the page contractt1k-playablelabs-base-packer-engineer (sonnet, native)