Skip to content

t1k:playablelabs:base:vfx-core

FieldValue
Modulebase
Version2.29.2
Efforthigh
Tools—

Keywords: 2d particle vfx core, check-vfx2d, check-vfx3d, fx-core v1 as data, particle core, particle emitter parity, particle vfx parity, plafx1, plafx2, vfx extraction, vfx parity gate

/t1k:playablelabs:base:vfx-core
<extract | validate | gate | selftest | check2d | adapt-three | adapt-cocos> [--game-profile <file>] [--bundle <dir>]

PlayableLabs VFX core (plafx1 / plafx2): port a reference game’s particle effects with proof

Section titled “PlayableLabs VFX core (plafx1 / plafx2): port a reference game’s particle effects with proof”

One engine-neutral package, installed with every PlayableLabs kit install (module base). It turns a reference game’s particle effects into data (plafx1 = 3D emitters, plafx2 = a superset adding 2D emitters, rings, floaters, shake, flash, pop and tweens), simulates them with deterministic pure-JS cores, and judges the port with gates that have named RED arms. Web and Cocos targets sit on thin adapters; extractors stay per source. Nothing in a core or gate names a game: per-game data lives in a profile you own (references/PROFILE-GUIDE.md).

Shading (materials, lights, ground and shadow drawing) is NOT here. See the extension point in references/OPEN-ITEMS.md.

PieceFileRole
formatsreferences/CONTRACT.md (plafx1 s1-10, plafx2 s11), references/plafx1.schema.json, references/plafx2.schema.jsonthe spec; validate-vfx.cjs is its executable form (dispatches on format)
3D coreplafx-core.js, plafx-rng.jsFx3D load/attach/emit/step/items/digest/snapshot; ZERO three/cocos/DOM imports, seedable, stepped by dt
2D coreplafx-core2d.jsPlafx load/attach/seed/play/drain/step/items/screen/digest; FX-CORE v1’s cue protocol and semantics driven by plafx2 data; draws nothing
v1 as datav1-to-plafx2.cjs, presets/v1-compat.fx.json, fixtures/fxcore-v1/FX-CORE v1’s five kinds + cues as a generated plafx2 pack; the frozen v1 source is the C6 reference
3D gatecheck-vfx3d.cjs, vfx3d.reader.cjs, vfx3d.profile.cjsV1..V7 + --selftest (50 RED arms)
3D core unit suitecheck-core-unit.cjs96 numeric checks + 23 named breaks of the 3D core
2D gatecheck-vfx2d-unit.cjs, vfx2d.checks.cjs, validate-plafx2.cjsC1..C9 + --selftest (every break RED for its own check; digest equality with FX-CORE v1)
extractor (Cocos prefab bundle)extract-vfx.cjs, tools/bundle -> vfx.json + vfx.xf.json + tex/
web adapteradapter-three.jsinstanced quads from Fx3D.items(); THREE injected
cocos adapteradapter-cocos.cjsplafx1 -> cc.ParticleSystem property bags; UNVERIFIED against an engine
worked exampleexamples/topforce/one game’s profile + driver; fixtures in fixtures/
  1. Get the data. Cocos prefab bundle (3D): bun scripts/extract-vfx.cjs --bundle <build> --game-profile <yours> --out <dir>. Any other source, or any 2D effect: write plafx2 yourself (references/CONTRACT.md s11; start from fixtures/plafx2/). bun scripts/validate-vfx.cjs <dir>/vfx.json accepts both formats.
  2. 3D gate. bun scripts/check-vfx3d.cjs --vfx <dir>/vfx.json --xf <dir>/vfx.xf.json --sim <driver> --src <game logic> --bundle <build> --game-profile <yours> --require-bundle. Read FAIL Vn lines; exit 0 green, 1 red, 2 harness error. A SKIP is a named gap in proof, not a pass.
  3. 2D core. Copy the region between PLAFX-CORE v2 BEGIN/END of plafx-core2d.js, pin its sha256 in your gate (bun scripts/check-vfx2d-unit.cjs prints it; --pin <sha> enforces it). Gameplay pushes plain cues on a queue, the host calls Plafx.drain(queue) then Plafx.step(dt) once per frame and draws items() / screen() itself. FX-CORE v1 games keep FX unchanged; the v1-compat pack is the migration bridge, proven by C6.
  4. Prove the gates before trusting a green: bun scripts/check-vfx3d.cjs --selftest [--bundle ... --src ... --sim ...] [--strict] (35 of 50 arms offline; --bundle adds 13, game source 2) and bun scripts/check-vfx2d-unit.cjs --selftest (all arms offline). Every arm must be RED for ITS named check.
  5. Adapt. Web: PlafxThree.create(THREE, scene, {texture}) then render(Fx3D.items()) after Fx3D.step(dt). Cocos: bun scripts/adapter-cocos.cjs --vfx ... --xf ... --tex-index ... (references/ADAPTER-COCOS.md lists what is verified). There is no 2D draw adapter yet (references/OPEN-ITEMS.md).
  6. Hand over evidence: the gate output with its SKIP list, plus the references/OPEN-ITEMS.md rows that apply to your game.
  • Gameplay names events or cues only (Fx3D.emit(event, {pos, dir}), { k:'burst', kind, x, y }), never emitter ids. The cosmetic RNG stream is separate from gameplay’s; muting every emit/play must change no gameplay state (V6, C4).
  • The 3D sidecar is mandatory: ignoring emitter-node and instance rotation/scale is the “wrong particle direction” bug.
  • A field the source has and the format cannot carry goes to gaps[] with partial: true. Unknown enums are errors, not guesses.
  • plafx1 files load unchanged; a contract change (field name, unit, RNG draw order) is made in the kit with the scripts, never in one game.
  • A tolerance is never loosened without its reason written beside it (vfx3d.profile.cjs; C8 tolerances state theirs inline).
  • An arm that cannot run (no --bundle, no game source) is SKIPped by name; --require-bundle, --require-render, --strict fail it.
  • Do not claim what references/OPEN-ITEMS.md lists as unverified (mesh emitters, the Cocos adapter, a real WebGL frame, any 2D adapter, Cocos ParticleSystem2D mapping, scene.expand and bullet.hit bindings).

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

Mesh-renderer emitters are skipped by the core and their play-compare is unverified; V4 now prints a coverage note (V4 covered N of M emitter(s); K mesh-renderer emitter(s) are named SKIPs) so a green V4 x n cannot be read as “every emitter was simulated”. The 2D core has no draw adapter, no Cocos mapping and no frame-parity table yet (C10). Radius-mode particles, relative/grouped position types and sprite-sheet frames are rejected by the validator, not guessed. The scene.expand event mapping is a game decision the extractor cannot make. The bullet.hit instance selection is unresolved. The additive-vs-alpha page twin is a named SKIP until the page honours ?vfxblend=alpha. V2/V3 need the source bundle, which the kit cannot ship.

Decision: the three.js and Cocos adapters stay in this module (base), not in a separate fx module. Same call and same revisit triggers as t1k-playablelabs-base-shade-parity (SKILL.md § “Second game, and the fx module split”): a second engine adapter VERIFIED against a real engine is the moment the boundary earns its keep; today one adapter is proven only against a recording stand-in and the Cocos adapter is UNVERIFIED against any engine, so a split would be a boundary around unverified code.

Running the extractor, validator, gates and selftests and tabulating their output is mechanical; judging a RED, deciding a gap (extend the contract or accept partial), choosing a trigger or cue mapping and writing a game’s driver is not. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run extract-vfx.cjs, validate-vfx.cjs, check-vfx3d.cjs --selftest, check-vfx2d-unit.cjs --selftest and tabulate PASS/RED/SKIPt1k-data-verifier
Run a gate on a game’s data and report FAIL/SKIP lines per checkt1k-tester
Judge a RED or a SKIP, write the game profile and driver, map events to gameplay momentst1k-playablelabs-base-packer-engineer (sonnet, native)