AGENT SKILL

input

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.

License 许可
Apache-2.0
所属仓库
ByteTerrace/Puck
最近更新
2026-11-12
Stars
★ 2
Forks
0

01 前言 Front Matter

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.

02 资源文件 19

03 SKILL.md 正文

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 owns the model and its reasoning; commands and device input are the human references; 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
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, switching
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
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
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, commands: bindings
A control no page or overlay can take (the console key, the pause menu) IAlwaysActiveInputBindings, implemented by TerminalInputBindings (Puck.Launcher) below
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
A machine's buttons while a seat is engaged the route's kit pad map (WorldKit, WorldPadElement) engagement (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.
  • 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 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).

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).
  • 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.

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)
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). 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).
  • 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).

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). 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 InputSignals 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). Never inject real input to test.
  • Output goes through IGamepadOutput (capability-gated; rumble is finite by contract). Protocol work consults several independent sources and cites each (AGENTS.md); hardware evidence and owed runs are in device input.

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
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.
  • No world drives device output. No Puck.World* code calls IGamepadOutput, and a cartridge's IFeedbackMachine.MotorLevel has no consumer. Keep both: 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.

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

04 同仓库更多 Skills