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
- 参考文档evals/i01-tap-versus-hold/graders/names-input-patterns.md88 B
- 参考文档evals/i01-tap-versus-hold/graders/names-the-hold-gap.md865 B
- 参考文档evals/i01-tap-versus-hold/graders/no-second-hold-detector.md825 B
- 参考文档evals/i01-tap-versus-hold/graders/one-consumption-group.md93 B
- 参考文档evals/i01-tap-versus-hold/graders/skill-fired.md36 B
- 参考文档evals/i01-tap-versus-hold/prompt.md927 B
- 参考文档evals/i02-board-entry-releases-autorun/graders/authored-not-engine.md812 B
- 参考文档evals/i02-board-entry-releases-autorun/graders/keep-on-a-transition.md126 B
- 参考文档evals/i02-board-entry-releases-autorun/graders/names-input-modes.md67 B
- 参考文档evals/i02-board-entry-releases-autorun/graders/releases-by-default.md744 B
- 参考文档evals/i02-board-entry-releases-autorun/graders/skill-fired.md36 B
- 参考文档evals/i02-board-entry-releases-autorun/prompt.md842 B
- 参考文档evals/i03-motion-input-layer/graders/activator-is-host-layer.md1014 B
- 参考文档evals/i03-motion-input-layer/graders/axis-crossings.md96 B
- 参考文档evals/i03-motion-input-layer/graders/match-and-consume.md69 B
- 参考文档evals/i03-motion-input-layer/graders/names-input-patterns.md88 B
- 参考文档evals/i03-motion-input-layer/graders/skill-fired.md36 B
- 参考文档evals/i03-motion-input-layer/prompt.md898 B
- 参考文档references/bindings.md36.7 KB
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.Inputreads devices and window events;Puck.Commands'InputRouterresolves 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.
WorldInputRuntimeand oneWorldInputOwnerper 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 isworlds/standard/inputs.puck; world-specific actions stay in the world (the debug world'ssuit.puck,noclip.puck). Different meanings get different names: chess uses the sharedconfirmandcancel, independently of a machine'sselect. 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
Relativedisplacement) and 64 packed buttons, budgeted per allowed mode tuple; target registers have their own reach mask and spend none of it.Textis event-only and takes no slot. -
Resolve names through
WorldChannelTableor 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 checkedReadRelative, never a held-level reader. -
Relativeinput (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 byPrincipalTokens.TryParseSeat: principals and grantees,world.hud seat<n>,audio.listenerand a scenario'sseat1:labels. A grant subjectseat:<n>is a different grammar (akind:valuesubject, 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) orSeatState(WorldInputModeSelectorKind). Never a binding page, the camera layout or wall time.player.modechanges aSeatStatefamily throughWorldCommand.SelectInputState. - The live set is the global names plus every selected, unsuspended state's
names.
suspendedBysuppresses a family by another's selection;combinationsrestricts the allowed tuples, checked on every transition. - A switch releases by default. A family's
transitionsrow keeps named actions (conditionalKeepadds 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
contextsrow 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,AxisSampleandTextevents; the authority derivesAxisCrossingfrominputHistory.crossings(thresholds, hysteresis, an optionalfacingState) and recordsCancelfor a reset hold (WorldInputEventKind). inputHistorysizes retention, ring capacity, events per step, lateness, calibration and the judged clock (CaptureorAdmission). 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.textcommits 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 orsimultaneousGroup, tolerance and tick gaps),maximumDurationSeconds,maximumGapSeconds, optionalbufferTicks,held(binary actions that must be down now) andconsumptionGroup.Compilerefuses 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;
consumeInputclaims the range only when the firing commits (the arm inWorldRuleHost.Arms.cspreflightsTryMatch), and a refused firing claims nothing. Claims and cursors are in the checkpoint and hash. worlds/debug/input-pattern-tests.puckis the worked example: a crossing motion consumed by a rule, and abufferTicksattack whose rule adds aninputAgeguard.- 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
consumptionGroupso 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 whoseheldnames the action, plus aninputAgeguard 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 worldbindingOverlaysrow in order (awhengate that fails skips it), the seat profile'sbindings, then live rebinds.BindingProfile.Compileis 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 inworlds/debug/controls.puck. None belongs in engine code. BindingVocabularyCheck.Validateandpuck compile --validaterefuse 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.signaldrives 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
InputRouterresolvesIAlwaysActiveInputBindingsbeside the active page for every source. TodayTerminalInputBindings.Resolveanswers onlykeyboard.backtick(theconsolecommand). While the console holds terminal focus, signals enter throughInputRouter.CaptureFocusExempt: only commands declaringCommandInputScope.FocusExemptdispatch 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.Compilerefuses neither source, nomenuverb exists, and the standard'sstartrow bindsgamepad.start. Hub plan step H4 owns it.
Devices and haptics
- Acquisition feeds
GamepadManager;InputArbiterdrains it once per host frame;GamepadCaptureSourceappends timestampedInputSignals to the router;WindowInputMappermaps keys, text and mouse. Source ids come fromInputSourcesand 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.
WorldInputOwnerlives inPuck.World.Serverand onlyWorldRuleHostcallsTryMatch; 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 callsIGamepadOutput, and a cartridge'sIFeedbackMachine.MotorLevelhas 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 1and the otherworlds/debug/input-*-tests.puck; add--reproducefor 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
patternssection (CompiledPatterns, the$matchoperand,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
verification
Verifies Puck changes: landing bar, builds, stale DLLs, flaky tests, GPU/heavy leases, coverage, source-scan or regex laws versus type/compiler enforcement, and writing tests.
tooling
Maps shared build/CLI architecture, compiler assembly identity, candidate installation, generated sections, and host admission.
tooling-files
Maps shared repository tooling for files, paths, Git queries, project ownership and Markdown fences. Load before adding or changing a helper in these areas.
symbol-analysis
Answers C# structure questions with puck references and declarations: which types derive from, implement or override a symbol, who references it, safe to delete or rename. Text: content-search.
state
Maps Puck's state and rule engine (Puck.State, .Rules, .Search, .Topology, .Vectors, .Generators): arena, journal scopes, undo, hashing, rule compiler, faults, transforms, search, draws.
sdf-authoring
Authors creations: shape rows, primitives, blends, folds, palettes, paints, render lanes, rigs, bake work and bytes, creation stats. Use to sculpt or fix a part. Grammar: puck-dsl; GPU: rendering.