[SandroMaglione]

Why

Movement is the one input every game has, and the one input Controls didn't model. Games split it into four button actions and rebuilt the direction by hand (normalizeMovement in top-down). That meant:

• the code was tied to a device name;
• the touch stick was never read;
• nothing checked that a device could move the player;
• every game re-decided diagonal speed and how a stick and keys combine.

What

• Declaration (breaking): Controls.actions({ buttons, vectors }). A name declared as both kinds doesn't compile.
• Bindings:
  • Keyboard.vector({ up, down, left, right }): opposite keys cancel, diagonals have length 1.
  • Gamepad.vector({ stick, up, down, left, right }): a stick, the d-pad, or both; the longer wins.
  • A Touch layout's stick.vector names the vector the stick drives.
• Snapshots: every device snapshot has vectors; Pointer's is empty.
• Merge:
  • Controls takes the longest vector any device reports, so devices never add up past 1 or cancel each other.
  • Vectors work with lacking, available, idle and lastUsed.
  • Compile errors cover: a vector bound as a button, a button bound as a vector, a missing vector, and reading the wrong kind.
• Rebind: rebind and parseRebinding take vector bindings; Gamepad can swap sticks.
• Timelines (breaking for keyboard): keyboard timelines name directions ("move.right"). Gamepad and touch timelines are unchanged.
• Touch (breaking): Touch.idle({ buttons, vector? }) and Touch.scripted({ buttons, vector? }, timeline).
• Callers:
  • Top-down uses vectors.move and drops normalizeMovement; a new test checks diagonals.
  • The website docs and demos are updated. The town demo keeps its direction buttons, because it steps tile by tile on taps.
  • The unreleased Controls: one input source from several devices; checked input capture #60 changeset is updated to the new Controls.actions shape.

Checks

• pnpm run check (652 tests, with type tests for every error above)
• pnpm pack:check
• pnpm --dir website build
• No runtime internals or core types changed; the browser package has no bench cases.

🤖 Generated with Claude Code