t1k:cocos:playable:parameter-audit
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: applied-ok, applyFont, audit playable parameter, called-no-effect, coverage, dead-parameter, font-unrouted, fontFamily, FontService, misrouted-parameter, no-op, null-ref, orphan-param, param-screenshot, parameter-audit, parameter-test, parameter-validation, pass-f, playable-config, preview-verify, requirement-coverage, requirement-gap, requirement-manifest, runtime-identity, runtime-verification, runtime-verify, screenshot, test-parameters, undragged, unused-parameter, unwired, verify-parameter, wrong-target
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:parameter-audit[--config <PlayableConfig.ts>] [--controller <ParameterController.ts>] [--scene <MainScene.scene>] [--labels <playable-config.json>] [--report <path>] [--coverage <manifest.json>] [--no-fail] [--json] [--verdict [--require-scene]]Cocos Playable Parameter Audit
Section titled “Cocos Playable Parameter Audit”Reverse-validation for the flat-primitive parameter system. The forward skills
(scan → composite → implement → mcp) create parameters; this skill finds
parameters that do nothing — defined but with no path from a dashboard value
change to any gameplay or visual effect.
This is the inverse of t1k-cocos-playable-parameter-implement, whose gotcha
warns “a scanned node not wired in the controller will silently never apply” —
but provides no detector. This skill is that detector.
Executed by
Section titled “Executed by”Every static pass applies an already-stated rubric to a fixed item list — the canonical
t1k-list-classifier shape. Pass F and the paramTest stamp are Bash-only invocations of
deterministic scripts instead, and a flagged LOGIC-DEAD sink needs a reasoning-tier
(t1k-debugger) confirmation before anyone deletes anything. Per-pass table, the two
“never edits” exceptions, and why Pass F is deliberately NOT t1k-gamedev-playable-runtime-verifier:
references/executed-by-routing.md.
What “dead” means — three classes
Section titled “What “dead” means — three classes”| Status | Meaning | Detection |
|---|---|---|
| UNWIRED | In PlayableConfig, but no onUpdate/binder/auto-loop touches it. | Static (script, deterministic) |
| NO-OP | Wired with an effectively-empty onUpdate body ({}, whitespace, or only-comments — incl. commented-out bindings) AND read nowhere else. | Static (script, deterministic) |
| LOGIC-DEAD | Wired with a non-empty body, but its only sink writes a flag/counter/config field that nothing reads (effect-reachability dead). | Static (script, Pass D — single-hop heuristic) |
| REGISTERED-NEVER-PLAYED | An AudioParameter wired only by the audio auto-loop, whose registered key name no play*() call site ever plays (playMusic('bgm'), or a constant resolving to it — playSFX(AUDIO_NAME.INPUT)). Registered, so wiring looks fine; nothing consumes it by name, so it can never make sound. Fail-open: an unresolvable play argument (a variable, an interpolated name) or zero play-shaped calls suppresses the status. | Static (script, play-site pass, deterministic) |
| NULL-REF | Wired through a scene @property ref that was never dragged (null) and not resolved via a prefab targetOverride. | Scene JSON / MCP (skill-driven) |
| DUPLICATE-REF | Two or more different @property fields resolve to the same node. Signature of a copy-pasted targetOverride: the ref exists, so null-checks clear it, but one of the fields is applying to a node that cannot satisfy it. Confirm — a shared node is occasionally deliberate. | Scene JSON / MCP (skill-driven, Pass C step 2b) |
| PARTIAL-REF | Array @property (e.g. Sprite[]) shorter than the table’s default length. | Scene JSON / MCP (skill-driven) |
| STALE-READ | A live Pass D sink whose only reader(s) run inside a one-shot lifecycle method — cached once at boot, dead to later dashboard updates. Warning, not dead (a value WAS applied once). | Static (script, Pass D overlay) |
| DEFAULT-DRIFT | A direct-onUpdate scene-ref param’s PlayableConfig default disagrees with the scene-serialized value it applies to. Warning, not dead. | Scene JSON (script, Pass C overlay, --scene only) |
INTENTIONAL-EXTERNAL | Empty/no controller wiring, but the value IS read elsewhere (SDK logic). Not a defect. | Static (whole-codebase grep) |
| FONT-UNROUTED | A fontFamily / font param whose apply path assigns label.fontFamily (directly, or via applyLabelComponentParams / FormattedTextParameter.apply) instead of calling FontService.applyFont. System families still resolve, so this is only visibly dead for a custom face — but every static pass AND Pass F call it healthy. Warning-class unless the project ships a custom font. | Static (skill-driven grep, no script support) |
UNKNOWN | Key enumerated from ParameterToolBuild/playable-config.json because it comes from a config spread the parser cannot resolve statically (e.g. ...createSharedConfig(...)) and the controller does not wire it. Not audited (maybe base-class wired) — never a pass, never omitted. A ...Facade.params(FLAGS) feature spread (share-parameter) stays here too, with featureSpreads + a per-row unknownReason saying whether Facade.bindAll(…, FLAGS) was found; confirm with Pass F. | Static (manifest read) |
WIRED-OK | A real apply path exists (and, for logic params, its sink writes a field something reads). | Static |
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Find parameters that don’t do anything” | Run all 3 passes → Workflow |
| “Just the static wiring/no-op audit” | Pass A+B only (scripts/audit-parameters.cjs) |
| “Check if scene refs were dragged” | Pass C → Scene null-ref pass |
| “The static passes report clean but the parameter still does nothing (or the wrong thing) in the running game” | Pass F (opt-in, needs a running preview) → Pass F — runtime verification |
| “Are all REQUIRED params present & live?” (gap gate) | --coverage <manifest> → Forward-validation |
| “Record this run’s verdict where CI/Jenkins reads it” | scripts/stamp-param-test.cjs → Stamping the paramTest receipt |
| “CI-friendly machine output” | Add --json |
Workflow
Section titled “Workflow”Pass A + B — static wiring & no-op (deterministic)
Section titled “Pass A + B — static wiring & no-op (deterministic)”bun scripts/audit-parameters.cjs # auto-discovers PlayableConfig.ts + ParameterController.ts under cwdbun scripts/audit-parameters.cjs --json # machine outputThe script classifies every PlayableConfig key as WIRED-OK / UNWIRED / NO-OP / LOGIC-DEAD / REGISTERED-NEVER-PLAYED / INTENTIONAL-EXTERNAL (plus UNKNOWN for keys of an unresolvable spread). It accounts for all three wiring mechanisms
(see traps below) so audio/auto-wired params are not false-flagged.
Checkpoints mode (--verdict)
Section titled “Checkpoints mode (--verdict)”Stdout is ONE JSON object { "status": "green|red|unknown", "evidence", "detail" }. A red/unknown result exits 0; non-zero means the audit could not run. unknown is never green. Root discovery and the exit contract: references/workflow-detail.md § “Checkpoints mode (--verdict)”.
Pass D — effect-reachability (logic params, deterministic)
Section titled “Pass D — effect-reachability (logic params, deterministic)”A non-empty onUpdate proves a call happens, not that the call has effect. A
“logic” param (no scene ref) copies its value into a bridge/store setter or a
service; the game only changes if a reader consumes what was written. Pass D
traces onUpdate body → sink → field written → is that field read anywhere? and
flags LOGIC-DEAD when a param’s only sink writes a flag/counter/field that
nothing reads. Service sinks (AudioService.*, SignalBus.fire, *View refresh)
are treated as inherently effectful; scene-ref sinks defer to Pass C. The
effect=live|logic-dead|unknown(via) fact is emitted per param. It’s a single-hop
heuristic — confirm the named sink before deleting a LOGIC-DEAD param.
Pass C — scene null-ref
Section titled “Pass C — scene null-ref”Pass A+B prove a param has an apply path in code. Pass C proves the scene
@property it applies through is actually wired in the editor.
--scene <MainScene.scene> runs a real, script-computed slot-level Pass C
(prefab-targetOverride-aware — NULL-REF / OVERRIDE-WIRED / WIRED per @property
slot, emitted as sceneRefs and folded into the passes.C / confirmed fields —
references/pass-coverage-flags.md). It proves
each SLOT is wired; it does not map a slot back to the param(s) it serves, or
run the DUPLICATE-REF comparison — that semantic mapping stays skill-driven.
Without --scene, passes.C reports skipped(...) and confirmed=false even
when deadCount === 0 — dead=0 is never a clean result on its own.
Full manual procedure — building the prefab-override set, the mandatory
DUPLICATE-REF comparison (step 2b), classifying NULL-REF/PARTIAL-REF, the Cocos
MCP alternative, and mapping each @property back to its param via the
controller’s binder closures (() => this.logoSprite ⇒ Logo) and onUpdate
bodies: references/detection-algorithm.md
§ “Pass C — scene null-ref”.
A --coverage-only READY is not a wiring claim. It checks the manifest against PlayableConfig
code only, and reported 25/25 READY on a project whose AppIcon.logoNode was null and warned on
every boot — only --scene Pass C catches that class. Always pass --scene alongside --coverage.
Pass E — ambiguous labels (deterministic, runs off the generated config)
Section titled “Pass E — ambiguous labels (deterministic, runs off the generated config)”Two children of one ObjectParameter rendering the same label leaves the operator unable to tell
which row does what. Reads the GENERATED playable-config.json, so it audits what the dashboard
will actually show. --labels <playable-config.json> runs the AMBIGUOUS-LABEL half inline
(passes.E + labelIssues); UNQUALIFIED-LABEL is still a hand-run one-liner. Both statuses,
that one-liner, and the relabel rule ("{ParentLabel} — {Component} {Field}", never rename a KEY):
references/detection-algorithm.md § “Pass E”.
Font-routing check — FONT-UNROUTED (skill-driven, no script support)
Section titled “Font-routing check — FONT-UNROUTED (skill-driven, no script support)”The one defect class every other pass reports GREEN on, Pass F included: label.fontFamily = value satisfies A, B, C, D and F alike (the state read-back sees fontFamily genuinely change)
while the label on screen never changes face — a family string resolves system fonts only, and a
face in resources/font/ needs FontService.applyFont. Textbook
theonekit-core/.claude/modules/t1k-verification/rules/green-that-proves-nothing.md. Not covered by audit-parameters.cjs: run the four greps by
hand before calling any Label-bearing audit clean —
references/detection-algorithm.md § “Font-routing check”.
Pass F — runtime verification
Section titled “Pass F — runtime verification”Opt-in, needs a running preview — never part of the default audit. Passes A-E prove a parameter has
an apply path in code (A/B/D) and a non-null scene @property ref (C); none can prove that path
lands on the RIGHT node, and a check that cannot go red for the failure you care about is decoration
(same rule). Pass F drives each probed value through the REAL update path,
wraps the expected target’s setter AND every other plausible target’s, and reads back a STATE fact
(its authored stateExpr) for each. The gate is the STATE CHANGE, never the call count — a call
can fire with zero effect, and only the state-and-identity read-back separates a WRONG-TARGET bug
from a CALLED-NO-EFFECT one. The incident this pass exists for (the real TutorialHand case) and
its relation to Pass C step 2b (DUPLICATE-REF):
references/pass-f-runtime-verification.md § “Why
this pass exists”.
bun scripts/runtime-verify.cjs --manifest runtime-probe-manifest.json --dry-run # validate + preview the flow, no browserbun scripts/runtime-verify.cjs --manifest runtime-probe-manifest.json --url http://localhost:<measured-port> --limit 5 # smoke firstbun scripts/runtime-verify.cjs --manifest runtime-probe-manifest.json --url http://localhost:<measured-port> # full run<measured-port> is never assumed: measure the target project’s preview port per project and
confirm the page <title> (Cocos Creator - <ProjectName>) before any run — 7456 is only the
first open editor’s port and can be serving a different project
(references/pass-f-runtime-verification.md §
“Resolving the preview URL”).
Five verdicts — APPLIED-OK (expected target’s state changed, nothing else did) · CALLED-NO-EFFECT
(setter fired, state did not move) · NO-CHANGE (nothing called, nothing moved — real dead wiring) ·
WRONG-TARGET (an unexpected probed target moved — the class the static passes cannot see) ·
UNVERIFIABLE (target never resolved / driver threw / no stateExpr — never read as a pass). Exact
per-verdict conditions: the reference § “Reading the result”.
Every real --url run also writes pass-f-results.json and pass-f-report.md (verdict, before/after state, visibility read, screenshot per probe). Manifest schema, wrap-drive-restore, port resolution and the smoke gate: references/pass-f-runtime-verification.md.
Pass F has a second axis: does the change RENDER? A visualVerdict and a combined gate report alongside the state verdict and never rewrite it. APPLIED-OK-NOT-VISIBLE and UNVERIFIABLE-visual always block the paramTest receipt, and stamp-param-test.cjs fails CLOSED on an unrecognised gate or a probe with no gate. Declarations the gate cannot infer (nonVisual, expectHidden, per-probe settle), control-pair noise and the --fail-on-not-visible exit: references/pass-f-visual-gate.md § “Declaring what the gate cannot infer”.
Pass coverage & report (--report, passes, confirmed)
Section titled “Pass coverage & report (--report, passes, confirmed)”Every run emits passes: {A,B,C,D,E,F} (ran (...) / skipped(reason)) plus a confirmed boolean —
confirmed=false means deadCount === 0 proves only “no statically-dead param found”, NOT “clean”.
--report <path> persists the full per-param facts to disk, which is both durable evidence of which
passes ran AND the input stamp-param-test.cjs derives the receipt’s static half from. Full flag
reference and the --require-scene opt-in (OFF by default, for checkpoints back-compat):
references/pass-coverage-flags.md.
Stamping the paramTest receipt (derived, never asserted)
Section titled “Stamping the paramTest receipt (derived, never asserted)”The audit’s verdict for a project is recorded in that project’s own project-info.json as a
top-level paramTest block — a SIBLING of project, never nested inside it — which a publish gate
reads: Jenkins publishes only on verdict === "PASS". That makes it a gate, so it is DERIVED by a
script and never written by hand. A verdict a model decides on is an assertion wearing a deriver’s
clothes (a real consumer receipt credited a tools/ci/stamp-param-test.cjs that existed in no
repo).
bun scripts/stamp-param-test.cjs \ --report reports/parameter-audit.json \ # static half — audit-parameters.cjs --report --pass-f reports/pass-f-out/pass-f-results.json # runtime half — runtime-verify.cjs (Pass F)bun scripts/stamp-param-test.cjs --report … --dry-run --json # derive, print, write nothingA web port (PARAM_ENGINE_HOST=web, no controller or scene) stamps through --config <PlayableConfig.ts> --web-receipt <receipt>: references/web-host-receipt.md.
A static-only run cannot stamp PASS. PASS is reachable from exactly one input pair —
static clean AND runtime clean — so omitting --pass-f leaves runtime: "unknown" and the verdict
withholds as UNKNOWN. No flag relaxes that: without it the field is a publish gate that opens on
unverified runtime, which is worse than no gate (same rule). Absent
evidence is UNKNOWN, never FAIL — withheld and failed are different states. This is the ONE
file this otherwise report-only skill writes, and it touches only paramTest, never
project._checkpointsStatus. The 6-key shape, the clean/fail/partial/unknown state tokens,
the full verdict table, and how paramTest differs from the unrelated paramTestGate key:
references/ci-param-gate-contract.md.
False-positive traps (READ BEFORE flagging anything dead)
Section titled “False-positive traps (READ BEFORE flagging anything dead)”A naive grep PlayableConfig.X audit is wrong. Full prose + code examples for each:
references/detection-algorithm.md § “False-positive traps”.
| # | Trap | One-line rule |
|---|---|---|
| 1 | Auto-wire loops | Audio params wired by the loop, not by name — flagging UNWIRED is a false positive; predicate keys on category or type |
| 2 | Binder fluent chains | this.binder.button(PlayableConfig.CTA, ...) wires CTA regardless of method name (via=binder) |
| 3 | Bracket-table loops | [[PlayableConfig.X, "kind"], ...] + destructure loop wires X via via=table-loop, not a direct PlayableConfig.X reference — check for the loop before flagging |
| 3b | Key-array loops | for (const k of KEYS) c[k].onUpdate = h (block or brace-less) and KEYS.forEach((k) => c[k].onUpdate = h) credit every string literal in KEYS (local/module-level/exported const, same file or imported, as const or plain) via via=key-loop. An array of OBJECTS (for (const g of GROUPS) { const p = PlayableConfig[g.key]; p.onUpdate = h }, GROUPS = Object.freeze([{ key: "A", … }])) credits each element’s string-literal key, and const p = c[k]; p.onUpdate = h counts as the alias form. A computed/unresolvable array is NOT credited: its keys stay UNWIRED and unresolvedLoopArrays names it (loop-wired via unresolved array <ident>) — read that loop by hand |
| 4 | Nested params | Params nested inside e.g. GalleryGroup are not independent top-level entries; only top-level keys are audited |
| 5 | Empty onUpdate may be intentional | Empty body + external reads elsewhere ⇒ INTENTIONAL-EXTERNAL, not NO-OP. The default read scan covers the controller’s whole assets/ tree, assets/packages/** included |
| 5b | Member-alias wiring | const x = PlayableConfig.Key; x.onUpdate = … (also : T =, ["Key"]) wires Key via direct-onUpdate; a deeper member (= PlayableConfig.Key.parameters) does not |
| 6 | SDK-managed params | Store-link/redirect params are intentionally not visually wired — confirm via external reads before declaring dead |
| 7 | Prefab targetOverrides (Pass C) | Inline null does not mean unwired when a cc.TargetOverrideInfo resolves it — resolve the override set before declaring any field NULL-REF. An override naming a property the class no longer declares is dead to the runtime only — unproven, not proven-safe; never report it as safe to delete (see § “Removing an override entry”) |
| 8 | Unused Material / stale import | Serialized ≠ used: grep the UUID; check the imported NAME |
Hard rules
Section titled “Hard rules”- Forward-validation coverage, the CI param-test gate and the reference hard rules: references/hard-rules.md.
Output classification
Section titled “Output classification”The script prints a per-param table and a DEAD PARAMETERS summary
(UNWIRED + NO-OP). For each dead param, recommend the fix:
| Status | Fix |
|---|---|
| UNWIRED | Add a binder.*(PlayableConfig.X, () => this.ref) or PlayableConfig.X.onUpdate = ... in ParameterController.SetUpOnUpdate() — OR delete the param if obsolete. |
| NO-OP | Implement the empty onUpdate body (incl. un-commenting a commented-out binding), or delete the param. |
| LOGIC-DEAD | Wire a reader for the flag/counter the sink writes (the value is stored but never consumed), or delete the param. Confirm the named sink first. |
| REGISTERED-NEVER-PLAYED | Play the registered key — AudioService.playMusic('bgm') (or via a named constant) — or delete the param if nothing ever plays it. |
| NULL-REF | Drag the target node/component onto the ParameterController’s @property slot in the editor (or wire it via prefab targetOverride). |
| PARTIAL-REF | Add the missing array elements to the @property list. |
| FONT-UNROUTED | Replace the label.fontFamily = … assignment with FontService.applyFont(label, value) from @playablelabs/game-foundation/ui/utils/FontService, and drain the returned promise before AllAsyncParametersReadySignal. Never add a project-local applyFont helper. See t1k-cocos-playable-parameter-implement § Font. |