t1k:playablelabs:base:vfx-core
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/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.
What ships (all under scripts/)
Section titled “What ships (all under scripts/)”| Piece | File | Role |
|---|---|---|
| formats | references/CONTRACT.md (plafx1 s1-10, plafx2 s11), references/plafx1.schema.json, references/plafx2.schema.json | the spec; validate-vfx.cjs is its executable form (dispatches on format) |
| 3D core | plafx-core.js, plafx-rng.js | Fx3D load/attach/emit/step/items/digest/snapshot; ZERO three/cocos/DOM imports, seedable, stepped by dt |
| 2D core | plafx-core2d.js | Plafx 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 data | v1-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 gate | check-vfx3d.cjs, vfx3d.reader.cjs, vfx3d.profile.cjs | V1..V7 + --selftest (50 RED arms) |
| 3D core unit suite | check-core-unit.cjs | 96 numeric checks + 23 named breaks of the 3D core |
| 2D gate | check-vfx2d-unit.cjs, vfx2d.checks.cjs, validate-plafx2.cjs | C1..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 adapter | adapter-three.js | instanced quads from Fx3D.items(); THREE injected |
| cocos adapter | adapter-cocos.cjs | plafx1 -> cc.ParticleSystem property bags; UNVERIFIED against an engine |
| worked example | examples/topforce/ | one game’s profile + driver; fixtures in fixtures/ |
Workflow
Section titled “Workflow”- 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.mds11; start fromfixtures/plafx2/).bun scripts/validate-vfx.cjs <dir>/vfx.jsonaccepts both formats. - 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. ReadFAIL Vnlines; exit 0 green, 1 red, 2 harness error. ASKIPis a named gap in proof, not a pass. - 2D core. Copy the region between
PLAFX-CORE v2 BEGIN/ENDofplafx-core2d.js, pin its sha256 in your gate (bun scripts/check-vfx2d-unit.cjsprints it;--pin <sha>enforces it). Gameplay pushes plain cues on a queue, the host callsPlafx.drain(queue)thenPlafx.step(dt)once per frame and drawsitems()/screen()itself. FX-CORE v1 games keepFXunchanged; the v1-compat pack is the migration bridge, proven by C6. - Prove the gates before trusting a green:
bun scripts/check-vfx3d.cjs --selftest [--bundle ... --src ... --sim ...] [--strict](35 of 50 arms offline;--bundleadds 13, game source 2) andbun scripts/check-vfx2d-unit.cjs --selftest(all arms offline). Every arm must be RED for ITS named check. - Adapt. Web:
PlafxThree.create(THREE, scene, {texture})thenrender(Fx3D.items())afterFx3D.step(dt). Cocos:bun scripts/adapter-cocos.cjs --vfx ... --xf ... --tex-index ...(references/ADAPTER-COCOS.mdlists what is verified). There is no 2D draw adapter yet (references/OPEN-ITEMS.md). - Hand over evidence: the gate output with its SKIP list, plus the
references/OPEN-ITEMS.mdrows 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[]withpartial: 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,--strictfail it. - Do not claim what
references/OPEN-ITEMS.mdlists as unverified (mesh emitters, the Cocos adapter, a real WebGL frame, any 2D adapter, CocosParticleSystem2Dmapping,scene.expandandbullet.hitbindings).
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.
Module split (the fx decision)
Section titled “Module split (the fx decision)”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.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run extract-vfx.cjs, validate-vfx.cjs, check-vfx3d.cjs --selftest, check-vfx2d-unit.cjs --selftest and tabulate PASS/RED/SKIP | t1k-data-verifier |
| Run a 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 and driver, map events to gameplay moments | t1k-playablelabs-base-packer-engineer (sonnet, native) |