game-feedback-mandate

Game Feedback Mandate

Always-loaded, engine-agnostic. Every player-facing action ships WITH its feedback — animation, VFX, SFX, haptics, UI reaction — in the same PR as the action itself. Feedback is not a polish pass that happens later; a feature that resolves a player action with no sensory confirmation is an incomplete feature, exactly like one with no test.

For the theory of why feedback timing matters (perception thresholds, ADSR response curves) see t1k:designer:base:feel-foundations; for the tactical toolbox (shake values, hit-stop frames, particle counts) see t1k:designer:base:feel-juice. This rule is the shipping-discipline arm: what must exist, in what channel, by when, before the feature is done.

The Contract

Five feedback channels (fixed ids, fixed order): visual (animation/tween/state change on the actor itself) · vfx (particles, trails, flashes, screen effects separate from the actor) · sfx (sound) · haptic (vibration) · ui (HUD/counter/label reaction, including number popups).

Six action classes (fixed ids): input-ack (the instant a touch registers, before any outcome is known) · valid-action (a legal move resolves) · invalid-action (a rejected or blocked input) · progress (one step toward the goal) · milestone (a threshold crossed — combo, level-up, star, streak) · terminal (win / lose / out-of-moves).

Mandatory minimum per class — this table IS the blocking gate:

action class	visual	vfx	sfx	haptic	ui
`input-ack`	REQUIRED	—	optional	REQUIRED	—
`valid-action`	REQUIRED	optional	REQUIRED	optional	—
`invalid-action`	REQUIRED	—	REQUIRED	REQUIRED	—
`progress`	REQUIRED	optional	REQUIRED	—	REQUIRED
`milestone`	REQUIRED	REQUIRED	REQUIRED	optional	REQUIRED
`terminal`	REQUIRED	REQUIRED	REQUIRED	optional	REQUIRED

SFX loudness — required, not implicit: every sfx order states a target loudness (“normalize it” is not a spec); volume scales inversely with fire rate:

Fire rate	Target
more than 2/sec	−18 to −24 LUFS
0.3 to 2/sec	−12 to −18 LUFS
less than 0.3/sec	−8 to −12 LUFS
once per level	−3 to −8 LUFS

True peak ≤ −1 dBFS; declare max concurrent voices per cue; the vendor must not peak-normalize (it erases the relative mix this table creates). The target lives in the Asset Slot’s specs (rules/placeholder-first-handoff.md), verification in accept.

No stated target, or a rapid-fire cue specced at one-shot loudness, fails the gate like a missing channel — the band table is the blocking part; peak/voice/vendor rules below it are strong defaults. Full standard, worked examples, swap-verification checklist: t1k:designer:base:feel-juice’s references/feedback-matrix.md.

Timing budget (mobile): input-ack must BEGIN within 100 ms of touch and must never be gated behind gameplay resolution · valid-action and invalid-action peak within 250 ms · progress ≤ 400 ms and must not block the next input · milestone ≤ 800 ms, interruptible · terminal may run longer but must be skippable by tap.

Invariants (every engine): each channel independently mutable by the player (sfx volume, haptics off, reduced-motion) · haptics no-op silently on unsupported platforms · gameplay correctness NEVER depends on a feedback channel firing · feedback never blocks the input queue.

The artifact: every feature ships a Feedback Matrix — one row per player-facing action, columns = the five channels + timing class. A feature is not done until every REQUIRED cell is filled.

Waiver: a REQUIRED cell may be left empty only with an inline feedback-waiver: <reason> recorded in the feature’s PR description or module contract. No waiver = the gate fails.

Variation

A game replays the same moment thousands of times per session. Feedback that is present but identical on the 400th repeat stops carrying information and starts carrying fatigue — variation is a shipping requirement, not polish, exactly like the presence of feedback itself.

Rule	Detail
V1 — Variant floor	Any moment firing more than 3× per level or session ships ≥3 variants on its dominant channel. Below that threshold, one is fine.

V1 is part of the blocking gate — a >3×-per-level moment shipping one variant fails review the same way a missing channel does, waivable only with the same inline feedback-waiver: <reason>. V2–V7 are strong defaults a reviewer should raise but not block on, never all seven as blocking: no-immediate-repeat, a jitter floor, streak ladders (not lottery), rare delight, context-over-chance for one-shots, and variation-never-carries-meaning.

Full V2–V7 table, worked examples, the diminishing-returns/mobile-memory-budget guidance, and the Variants column added to the Feedback Matrix template: t1k:designer:base:feel-juice’s references/feedback-matrix.md § Variation Rules (V1–V7).

Enforcement — HARD-GATE

The Feedback Matrix is a HARD-GATE under rules/workflow-gates.md — its universal contract (no bypass without a named override, evidence not assertion, gate failure stops the workflow, 3+ failed attempts escalate) applies here without restatement. The only named override is the waiver above.

t1k:cook / t1k:review: treat a missing Feedback Matrix, a REQUIRED cell that is empty and unwaived, a >3×-per-level moment shipping fewer than 3 variants (V1), or an SFX order with no stated loudness target or a rate-inappropriate one as a completion-blocking finding — exactly as they would a missing test. Do not mark the feature done; use AskUserQuestion to surface the gap (per always-ask-on-unresolved.md) rather than silently shipping without feedback, without variation, or without a loudness spec.
Code/design review: a reviewer blocks the merge on a missing REQUIRED cell, an unmet V1 floor, or a missing/wrong-band SFX loudness target the same way they would on a missing test — cite this rule and the offending cell, not a vague “needs polish.” V2–V7 and the SFX peak/voice/vendor defaults are raised as review comments, not blockers.
Waivers are visible, not silent. A feedback-waiver: note in the PR/contract is the only way a REQUIRED cell or a V1 floor ships unmet; an empty cell or an unwaived V1 gap with no waiver is a gate failure, not a judgment call left to the implementer.

How to apply

Before implementing a player-facing action, classify it into one of the six action classes.
Fill its row in the feature’s Feedback Matrix using t1k:designer:base:feel-juice’s references/feedback-matrix.md (blank table, worked examples, accessibility invariants).
Implement every REQUIRED cell in the same PR as the action, or record a feedback-waiver:. If the action fires >3× per level/session, budget ≥3 variants on its dominant channel (V1).
At review, check the matrix against this rule’s table and the Variation rules before approving.

t1k:designer:base:feel-juice § references/feedback-matrix.md — the full contract, blank matrix template, worked examples, accessibility invariants
t1k:designer:base:feel-foundations — perception-threshold theory backing the timing budget above
rules/observable-gameplay.md — the observational counterpart: the console-closed test that catches a slice whose matrix was never written, plus the three traps a filled cell can still miss
rules/workflow-gates.md (core) — the universal HARD-GATE contract this rule cites
t1k-designer-base-skill-domain-routing — routes “feel / juice / feedback” requests to the owning skill
game-feedback-mandate-unity.md (theonekit-unity) — Unity/DOTS engine mechanics for these channels
game-feedback-mandate-cocos.md (theonekit-cocos) — Cocos engine mechanics for these channels