Skip to content

t1k:cocos:playable:parameter-audit

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
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

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

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.

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.

StatusMeaningDetection
UNWIREDIn PlayableConfig, but no onUpdate/binder/auto-loop touches it.Static (script, deterministic)
NO-OPWired with an effectively-empty onUpdate body ({}, whitespace, or only-comments — incl. commented-out bindings) AND read nowhere else.Static (script, deterministic)
LOGIC-DEADWired 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-PLAYEDAn 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-REFWired through a scene @property ref that was never dragged (null) and not resolved via a prefab targetOverride.Scene JSON / MCP (skill-driven)
DUPLICATE-REFTwo 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-REFArray @property (e.g. Sprite[]) shorter than the table’s default length.Scene JSON / MCP (skill-driven)
STALE-READA 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-DRIFTA 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-EXTERNALEmpty/no controller wiring, but the value IS read elsewhere (SDK logic). Not a defect.Static (whole-codebase grep)
FONT-UNROUTEDA 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)
UNKNOWNKey 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-OKA real apply path exists (and, for logic params, its sink writes a field something reads).Static
IntentPath
“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

Pass A + B — static wiring & no-op (deterministic)

Section titled “Pass A + B — static wiring & no-op (deterministic)”
Terminal window
bun scripts/audit-parameters.cjs # auto-discovers PlayableConfig.ts + ParameterController.ts under cwd
bun scripts/audit-parameters.cjs --json # machine output

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

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

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

Terminal window
bun scripts/runtime-verify.cjs --manifest runtime-probe-manifest.json --dry-run # validate + preview the flow, no browser
bun scripts/runtime-verify.cjs --manifest runtime-probe-manifest.json --url http://localhost:<measured-port> --limit 5 # smoke first
bun 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).

Terminal window
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 nothing

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

#TrapOne-line rule
1Auto-wire loopsAudio params wired by the loop, not by name — flagging UNWIRED is a false positive; predicate keys on category or type
2Binder fluent chainsthis.binder.button(PlayableConfig.CTA, ...) wires CTA regardless of method name (via=binder)
3Bracket-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
3bKey-array loopsfor (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
4Nested paramsParams nested inside e.g. GalleryGroup are not independent top-level entries; only top-level keys are audited
5Empty onUpdate may be intentionalEmpty body + external reads elsewhere ⇒ INTENTIONAL-EXTERNAL, not NO-OP. The default read scan covers the controller’s whole assets/ tree, assets/packages/** included
5bMember-alias wiringconst x = PlayableConfig.Key; x.onUpdate = … (also : T =, ["Key"]) wires Key via direct-onUpdate; a deeper member (= PlayableConfig.Key.parameters) does not
6SDK-managed paramsStore-link/redirect params are intentionally not visually wired — confirm via external reads before declaring dead
7Prefab 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”)
8Unused Material / stale importSerialized ≠ used: grep the UUID; check the imported NAME
  • Forward-validation coverage, the CI param-test gate and the reference hard rules: references/hard-rules.md.

The script prints a per-param table and a DEAD PARAMETERS summary (UNWIRED + NO-OP). For each dead param, recommend the fix:

StatusFix
UNWIREDAdd a binder.*(PlayableConfig.X, () => this.ref) or PlayableConfig.X.onUpdate = ... in ParameterController.SetUpOnUpdate() — OR delete the param if obsolete.
NO-OPImplement the empty onUpdate body (incl. un-commenting a commented-out binding), or delete the param.
LOGIC-DEADWire 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-PLAYEDPlay the registered key — AudioService.playMusic('bgm') (or via a named constant) — or delete the param if nothing ever plays it.
NULL-REFDrag the target node/component onto the ParameterController’s @property slot in the editor (or wire it via prefab targetOverride).
PARTIAL-REFAdd the missing array elements to the @property list.
FONT-UNROUTEDReplace 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.