ByteTerrace/Puck / .claude/skills/input
input
VerifiedMaps Puck input: channels, inputModes, sub-tick ingress, tap/hold/chords/sequences (inputPatterns), bindings and overlays, the always-active plane, devices, haptics. Grammar: puck-dsl.
SKILL.md
View on GitHub---
name: input
description: "Maps Puck input: channels, inputModes, sub-tick ingress, tap/hold/chords/sequences (inputPatterns), bindings and overlays, the always-active plane, devices, haptics. Grammar: puck-dsl."
---
# Input
A map of how a physical press becomes authoritative semantic input and what
judges it. Input has two layers, and most mistakes come from picking the wrong
one:
- **The host's physical layer.** `Puck.Input` reads devices and window events;
`Puck.Commands`' `InputRouter` resolves each source through the composed
binding profile (pages, chords, toggles, wheels, activators) per seat. It is
presentation-side: it never decides a rule, and its gesture state is not
replayed authority.
- **The authority's semantic layer.** `WorldInputRuntime` and one
`WorldInputOwner` per admitted seat or session hold modes, epochs, timed
event history and pattern matches. Rules read it; checkpoints, hashes and
replay carry it.
[Input channels](../../../docs/decisions/input-channels.md) owns the model and
its reasoning; [commands](../../../docs/reference/commands.md) and
[device input](../../../docs/reference/input.md) are the human references;
[references/bindings.md](references/bindings.md) holds the binding composition
contracts. When this file and the code disagree, the code wins and this file
is corrected in the same change.
## Find the owner by what you need
| You need | Owner | Read |
|---|---|---|
| Name an action and give it a shape (button, axis, relative look, text) | `channels` rows → `WorldChannel`, `WorldChannelTable`; `ChannelShape` (`PlayerIntent.cs`); motion `ChannelRole`; shared names in `worlds/standard/inputs.puck` | [semantic names](../../../docs/decisions/input-channels.md#semantic-names-and-typed-values) |
| Decide which actions are live while walking, flying, seated or engaged, and what survives a switch | `inputModes` → `WorldInputModes`, `WorldInputCatalog` (one `WorldInputMapping` per allowed tuple), `WorldInputSelector`, `WorldInputOwner.Switch`; the debug policy is `worlds/debug/input-modes.puck` | [modes](../../../docs/decisions/input-channels.md#modes-are-simulation-state), [switching](../../../docs/decisions/input-channels.md#switching-releases-input) |
| The time of a press inside a tick, several presses per tick, typed text | `WorldInputProducer` → `WorldInputBatch` → `WorldInputRuntime.TryAdmit` → `WorldInputOwner.TryAdmit`; `WorldInputInterval`; `inputHistory` (`WorldInputHistory`) | [sub-tick time](../../../docs/decisions/input-channels.md#sub-tick-time-and-clocks) |
| Tell a tap from a hold; a double tap, a fighting motion, a simultaneous press, a buffered attack, a rhythm note | `inputPatterns` (`WorldInputPattern`, compiled by `CompiledWorldInputPattern.Compile`), matched by `WorldInputOwner.TryMatch`, read by `inputMatch`, consumed by `consumeInput` | [below](#press-release-tap-hold-chords-sequences-and-rhythm) |
| Drive a seat's controls from a program each tick, as a player at a pad would (a benchmark route) | `seatPrograms` rows (`WorldSeatProgram`: `move`, `turn`, `hold`, `pulse`, `tap`) evaluated by `WorldSeatDriver` in the tick-complete hook (`WorldTickScript.Ticked`) and submitted through the seat's ingress (`WorldTickScript.SubmitSeat`); `routes` rows say where to go. The driver is the seat's client: it reads only what the seat's authority delivered (`WorldSeatSenses`), in process or remote | [the benchmark plan](../../../docs/plans/benchmark.md#the-route-is-places-played-by-an-authored-seat-program-stage-4) |
| Map a key or button to an action or command; pages, chords, autorun toggles, wheels | `bindingOverlays` → `WorldBindingComposer.Compose` → `BindingProfile.Compile` → `PagedInputBindings` inside `InputRouter`, composed per seat by `WorldSeatBindings`; the standard's rows in `worlds/standard/controls.puck` | [bindings.md](references/bindings.md), [commands: bindings](../../../docs/reference/commands.md#bindings) |
| A control no page or overlay can take (the console key, the pause menu) | `IAlwaysActiveInputBindings`, implemented by `TerminalInputBindings` (`Puck.Launcher`) | [below](#the-always-active-plane-and-reserved-gestures) |
| Read a controller, keyboard or mouse; rumble, lights, adaptive triggers | `Puck.Input` (`GamepadManager`, `InputArbiter`, `GamepadCaptureSource`, `WindowInputMapper`, `InputSources`, `IGamepadOutput`); OS transports in `Puck.Platform.Windows` | [device input](../../../docs/reference/input.md) |
| A machine's buttons while a seat is engaged | the route's kit `pad` map (`WorldKit`, `WorldPadElement`) | [engagement](../puck-world/references/engagement.md) (`puck-world`) |
## Semantic channels and typed values
- A world declares each action once in `channels`; modules, bindings, kits,
rules, engagement maps and grants name it. The standard's shared vocabulary
is `worlds/standard/inputs.puck`; world-specific actions stay in the world
(the debug world's `suit.puck`, `noclip.puck`). Different meanings get
different names: chess uses the shared `confirm` and `cancel`, independently
of a machine's `select`. The engine
knows only the motion roles (`ChannelRole`), never a genre's vocabulary.
- Each active input owner has 32 numeric slots (Q48.16 levels, or Q32.32
`Relative` displacement) and 64 packed buttons, budgeted per allowed mode
tuple; target registers have their own reach mask and spend none of it.
`Text` is event-only and takes no slot.
- Resolve names through `WorldChannelTable` or the owner's published mapping. A
declaration index is not a storage address, and a slot may hold different
actions in different tuples. Read relative input with the table's checked
`ReadRelative`, never a held-level reader.
- `Relative` input (mouse look) shares the numeric bank as Q32.32
displacement: the host accumulates samples and drains them once per routed
tick, rules read a Q48.16 projection whose fractional residue stays in
authority state, and it is never kept across a switch, toggled, or used by an
activator. Binding compilation must receive the routed channel shapes.
- **A seat in one token is `seat<n>`** (1-based, case-insensitive, `seat1`..`seat4`), parsed once by
`PrincipalTokens.TryParseSeat`: principals and grantees, `world.hud seat<n>`, `audio.listener` and a scenario's
`seat1:` labels. A grant subject `seat:<n>` is a different grammar (a `kind:value` subject, zero-based); a
keyword argument (`screen.source ... seat <n>`) and a HUD binding path (`seat.<n>.position.x`) keep their own
shapes.
## Modes and what survives a switch
- A family's selector reads authoritative state only: `ActiveKit`,
`Engagement`, `BodyState` (a finite or range-partitioned register) or
`SeatState` (`WorldInputModeSelectorKind`). Never a binding page, the camera
layout or wall time. `player.mode` changes a `SeatState` family through
`WorldCommand.SelectInputState`. Every family with a camera-targeting state also
takes that authority path, even without an `inputModes` selector; the authority
composes or dissolves the application and publishes the seat state together.
- The live set is the global names plus every selected, unsuspended state's
names. `suspendedBy` suppresses a family by another's selection;
`combinations` restricts the allowed tuples, checked on every transition.
- **A switch releases by default.** A family's `transitions` row keeps named
actions (`conditionalKeep` adds tuple-conditioned ones); with several changed
families an action must be kept by every one, so an engagement row with an
empty keep wins. The barrier (`WorldInputOwner.Switch`) advances the epoch,
consumes the edge that caused it, and admits fresh input from the next tick;
a kept hold continues with no new press.
- A source the barrier released waits for neutral before it can act again, and
the router reports a button's edge once. A seat whose registry is rebuilt
(every crossing) misses a release the router dispatched elsewhere, so each
tick the seat reports neutral for every waiting button its router reports up
(`WorldSeatInput.AcknowledgeReleasedButtons`, from `WorldClient.SynchronizeInput`);
a button held through a portal then works on its next press.
- A binding page or `contexts` row changes which binding group a seat uses,
never simulation eligibility. Install the barrier with the firing's commit,
before another rule reads channels ([bindings.md](references/bindings.md)).
## Timed ingress and sub-tick time
- The host quantizes each device event once to a simulation interval and a
Q48.16 offset (`WorldInputInterval`) on the 50,400 Hz engine clock
(`FixedTickConversion`). No wall clock reaches simulation.
- Producers send `Press`, `Release`, `AxisSample` and `Text` events; the
authority derives `AxisCrossing` from `inputHistory.crossings` (thresholds,
hysteresis, an optional `facingState`) and records `Cancel` for a reset hold
(`WorldInputEventKind`).
- `inputHistory` sizes retention, ring capacity, events per step, lateness,
calibration and the judged clock (`Capture` or `Admission`). An overflowing
batch is refused whole and resets the owner into a new epoch; history is
never truncated. Size it for the rate and sample density
([bindings.md](references/bindings.md)). A `forEach: $inputEvents:<owner>`
rule binds only the step's events and is priced at `maximumEventsPerStep`
plus the terminal cancellations (`WorldInputIteration.StepCapacity`); a read
through `each` costs one record. A rule reading a literal owner's events or
holds is scheduled on that owner's input version, so the due list leaves it
alone on a tick the owner's history did not change (`WorldRuleHost.TryInputScope`).
- In a scenario, `seat1: player.signal <source> press at:<seconds>` places a
press at a sub-tick offset; `keyboard.text` commits text as ordered Unicode
scalar events.
- Calibration is a per-owner signed offset in seconds that the judgement adds
to a press's captured time. `player.calibrate <seconds> [seat]` (bindable,
and a scenario step) submits `WorldCommand.CalibrateInput`; the authority
bounds it by `inputHistory.calibrationLimitSeconds` (zero when unauthored)
and applies it at an epoch boundary. A refusal narrates on `input.refused`.
## Press, release, tap, hold, chords, sequences and rhythm
Pick the layer by who must agree on the answer:
| You want | Use | Not |
|---|---|---|
| A gesture the simulation judges, replays and consumes once: tap versus hold, double tap, a motion, a buffered attack, a note | an `inputPatterns` row, read with `inputMatch(owner, pattern)` and claimed with `consumeInput` | a binding activator, a chord row or `BindingChordTracker` held state, which are host-only and not authority |
| The newest edge of an action, its time or its age | `inputEdge`, `inputTime`, `inputAge(owner, name, kind, occurrence)` | comparing two tick images, which loses a press and release inside one tick |
| How long the current hold has lasted, including across a kept switch | `inputHeldSince`, `inputHeldPress`, guarded by a current held level | |
| A page or command while modifiers are held (trigger pages) | chord rows: `held` is a set, `chord` an ordered sequence ([bindings.md](references/bindings.md)) | |
| A host-side tap code that fires a command | `BindingActivatorDefinition` with `Mode: Tapped` and `TimeoutTicks` (engine ticks), tracked by `RowActivatorTracker` | |
| An action latched on (autorun, autofly) | a `mode: Toggle` entry or chord row on the channel | a new command or state register |
The pattern contract (`WorldInputPattern.cs`, `WorldInputOwner.Patterns.cs`):
- A row has ordered `steps` (a channel, an event kind, an optional raw value,
crossing or `simultaneousGroup`, tolerance and tick gaps),
`maximumDurationSeconds`, `maximumGapSeconds`, optional `bufferTicks`,
`held` (binary actions that must be down now) and `consumptionGroup`.
`Compile` refuses more than 64 rows, a row outside 1 to 16 steps, a duration
beyond retention, a kind that disagrees with the channel's shape, and
overlapping or non-contiguous simultaneous predicates.
- Matching reads only the current epoch, picks the earliest-ending match, then
the latest start, then the lowest event ids. Within one consumption group an
earlier row has priority: its match removes those events from later rows'
candidates. A read never consumes; `consumeInput` claims the range only when
the firing commits (the arm in `WorldRuleHost.Arms.cs` preflights
`TryMatch`), and a refused firing claims nothing. Claims and cursors are in
the checkpoint and hash.
- `worlds/debug/input-pattern-tests.puck` is the worked example: a crossing
motion consumed by a rule, and a `bufferTicks` attack whose rule adds an
`inputAge` guard.
- **Tap versus hold.** The tap is a pattern of a press then a release within a
window shorter than the hold; the hold and the tap share one
`consumptionGroup` so one press cannot be both. The pause menu's Menu button
is specified this way ([hub plan](../../../docs/plans/hub-and-saves.md#11-menu-routing)).
A pattern step matches events only, so no step means "still held after N
seconds": today the duration goes in the rule (a press pattern whose `held`
names the action, plus an `inputAge` guard like the buffered example's), not
in the pattern's data. That composition is an inference from the matcher's
code, not a run scenario.
## Bindings and overlays
- Layers compose base first: the engine's build layer
(`WorldEditorBindings.Layer`), each world `bindingOverlays` row in order
(a `when` gate that fails skips it), the seat profile's `bindings`, then
live rebinds. `BindingProfile.Compile` is the one compiler; never copy it.
- An overlay replaces only the pages it declares; everything else stays the
player's ([the owner's ruling](../../../docs/decisions/input-channels.md#an-overlay-replaces-only-what-it-declares)).
- Concrete designs (bar layouts, wheels, trigger pages, keys) are standard
data: `worlds/standard/controls.puck` (`bare`, `play-wheel`, `pad-pages`),
`pad-kit.puck`'s modifiers; the debug world refines them in
`worlds/debug/controls.puck`. None belongs in engine code.
- `BindingVocabularyCheck.Validate` and `puck compile --validate` refuse an
unknown source, an unknown or unbindable command and a mismatched value kind.
- Live surface: `player.bind`, `player.bindings` (leads with the group
derivation), `player.signal`, `world.affordances`, `body.rig`,
`body.channels`, `world.binding-bar`. `player.signal` drives the same binding
path a device does, headless included.
- The router delivers every edge it synthesizes (an impulse's inactive twin, a
cancellation from focus loss, reload or a map change) on the next tick
([commands](../../../docs/reference/commands.md#quick-start)).
## The always-active plane and reserved gestures
- `InputRouter` resolves `IAlwaysActiveInputBindings` beside the active page
for every source. Today `TerminalInputBindings.Resolve` answers only
`keyboard.backtick` (the `console` command). While the console holds
terminal focus, signals enter through `InputRouter.CaptureFocusExempt`: only
commands declaring `CommandInputScope.FocusExempt` dispatch and only the
plane answers presses.
- Host-reserved gestures outside the binding profile: Control+Alt+Escape
returns keyboard focus from a passthrough source (`SourceFocus`), and Escape
closes an open console (`ConsoleInputSink`).
- Ruled but not yet built: the pad's Menu (`gamepad.start`) and Escape always
reach the pause menu, and no binding may name them
([play decisions](../../../docs/decisions/play.md#the-game)). Nothing
enforces it yet: `BindingProfile.Compile` refuses neither source, no `menu`
verb exists, and the standard's `start` row binds `gamepad.start`. Hub plan
step H4 owns it.
## Devices and haptics
- Acquisition feeds `GamepadManager`; `InputArbiter` drains it once per host
frame; `GamepadCaptureSource` appends timestamped `InputSignal`s to the
router; `WindowInputMapper` maps keys, text and mouse. Source ids come from
`InputSources` and resolve case-insensitively (`InputSourceVocabulary`).
- An agent's World passes `--devices none`: no pad opens and every OS event is
dropped before a seat (`WorldWindowInputFilters.ConsumesEveryEvent`), while
scripted input still drives it
([the ruling](../puck-world/SKILL.md#an-agents-world-opens-no-physical-device)).
Never inject real input to test.
- Output goes through `IGamepadOutput` (capability-gated; rumble is finite by
contract). `WorldHapticDirector` evaluates world-authored `haptics` rows
(`WorldHapticRow`) per local seat against each seat's routed
`WorldStateMirror` (including `$body` keys via `WorldStateLease`) and
drives the seat's assigned pad via `PlayerRoster.TryGetSeatDevice` and
`GamepadManager.TryGetOutput`; `haptics.state` echoes per-seat status.
Protocol work consults several independent sources and cites each
(AGENTS.md); hardware evidence and owed runs are in
[device input](../../../docs/reference/input.md#limits-and-hardware-evidence).
## Where each contract is enforced
| Contract | Enforced by |
|---|---|
| Names, shapes and the 32/64 budget per allowed tuple | `WorldInputCatalog` compilation and `WorldDefinitionValidator.Channels.cs`, `.Modes.cs` |
| A selector reads only finite authoritative state | the closed `WorldInputModeSelectorKind` and `WorldInputSelector`'s partition proof |
| A switch releases what no keep set names, and consumes its edge | `WorldInputOwner.Switch`, the one barrier door |
| A stale-epoch or malformed batch is refused atomically | `WorldInputOwner.TryAdmit` |
| A pattern is bounded and well-formed | `CompiledWorldInputPattern.Compile` |
| Consumption happens only on a committed firing | the `consumeInput` arm in `WorldRuleHost.Arms.cs` |
| A binding names known sources and bindable commands | `BindingVocabularyCheck` |
| Same input, same state | history, holds and claims in `WorldInputOwner.Checkpoint.cs`; `puck test --reproduce` |
| World `haptics` rows | `WorldDefinitionValidator.Haptics.cs` (unique ids, unit intensities, positive duration within `WorldHapticCapacity.MaxDurationSeconds`, `mode`/`signal` agreement, seat tokens) and `WorldValueDomainGuard` |
| Menu and Escape are reserved | nothing yet (H4) |
## Open gaps
- **A hold completes with no closing event.** A pattern stage is satisfied
only by an event, so a hold of N seconds cannot be pattern data; a term
satisfied by time with the action still held (or a tick event closing the
stage) is the hub plan's H4 work.
- **The matcher runs only in the authority.** `WorldInputOwner` lives in
`Puck.World.Server` and only `WorldRuleHost` calls `TryMatch`; the
always-active plane runs no matcher, so a remote authority decides every
pattern. H4 runs the one matcher on the plane over its local events.
- **Cartridge rumble is unwired.** `WorldHapticDirector` drives
`IGamepadOutput.Rumble` from authored `haptics` rows
(`worlds/standard/instrument.puck` pulses on the beat), while a cartridge's
`IFeedbackMachine.MotorLevel` still has no consumer. Keep it: an unreached
capability is wired, not deleted.
- The typing tutor and chat exhibits, the owed hardware runs and the decision's
raw-slot wording are in [the input packet](../../../docs/plans/open-items.md#input-channels).
## Verify
- Scenarios: `puck test worlds/debug/input-pattern-tests.puck --jobs 1` and
the other `worlds/debug/input-*-tests.puck`; add `--reproduce` for a timing,
history or continuity change.
- Genre sweeps: `puck sweep --plan worlds/debug/<plan>.sweep.json --world
<source>` with the five plans the
[genre check](../../../docs/decisions/input-channels.md#genre-check) lists.
- Unit suites: `tests/Puck.World.Server.Tests/InputPatternTests.cs`,
`tests/Puck.Commands.Tests`, `tests/Puck.Input.Tests`.
- Look-alike: the document's `patterns` section (`CompiledPatterns`, the
`$match` operand, `world.match`) matches words over board cells, not input
history.
## Route adjacent work
| Skill | Route there for |
|---|---|
| `puck-world` | Running and verifying a World, engagement and kit `pad` maps, the seat camera's input feel (`seatCameraFeel`), rules and grants. |
| `puck-dsl` | `.puck` grammar, `let`/`for`, compile and lint verbs, PUCKnnn diagnostics. |
| `gaming-bricks` | An emulated machine's own pad registers and input timing inside the core. |
| `platform` | The OS side of a device: window messages, Raw Input, pointer lock, HID and Xbox transports, lamp arrays. |
| `maths-usage` | Fixed-point types for offsets, calibration and judgement windows. |
| `verification` | Leases, the private CLI copy, flaky versus failing scenarios. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |