Input actions

An action is a name for something the player is doing — Move, Jump, Fire — and a set of bindings that can produce it. They live in a .vxinput asset as maps of actions, and at run time as four objects:

Vixen.Input deliberately references nothing platform-shaped. It is handed device state by the host and asked for values; it never polls an OS, which is what makes a whole game's input testable by submitting keystrokes to an InputDeviceSet.

Anything a player does on purpose, when you want it under a name rather than under a key code: rebinding, gamepad and keyboard from one code path, a Menu map that switches off the Player map, and analogue values that arrive already dead-zoned.

You do not want it for text entry or for the editor's own UI — Vixen.Ui has its own keyboard layer and uses only this package's InputKey enum, not its actions. You also do not want it for something that is not a player decision: a replay, an AI, or a network peer produces intent directly, which is why players and possession puts an interface between the two.

Three things happen in order, and only the middle one is yours:

1. InputService.BeginFrame() — clears the deltas (mouse and touch motion), keeps the positions. VixenApplication calls it before draining the platform's event queue.
2. The host submits events into InputDeviceSet as they arrive. Two mouse moves in one frame add; they do not replace.
3. InputService.Update(time) — resolves every enabled action. With an engine this is InputUpdateSystem, in SystemPhase.Input; without one, the application calls it inline.

⚠ WasPressedThisFrame and its siblings are cleared at the top of Update, not at the end of the frame. They are true from that call until the next one. A system that reads them before SystemPhase.Input sees last frame's answer, and a system that reads them in a fixed step sees the same press once per sub-step. Put anything that polls after the update:

Samples/13-ThirdPersonShooter's MouseCaptureSystem is exactly that shape, and it is the one to copy.

A narrow YAML subset — block mappings, block sequences, scalars, # comments. Anchors, aliases, tags, flow collections and tabs are refused with a parse error naming the line, because a dialect that quietly accepts half of YAML is one nobody can predict.

Core/Vixen.Input.Tests/Assets/SampleInput.vxinput is that file in full, and Samples/13-ThirdPersonShooter/Assets/Input/GameInput.vxinput is a game's.

⚠ A misspelled control path is not an error. It is an action that reads zero for ever. The reader checks the document's shape, not the meaning of a path: — an unresolved binding simply never produces a value, and unknown processor and interaction names are dropped at construction with no diagnostic at all. When an action does nothing, suspect the spelling before the wiring: <Gamepad>/leftStick is the stick and <Gamepad>/leftStickPress is the button under it; <Keyboard>/26 is not w.

Two routes exist, and the difference between them is whether a renamed action is a compiler error:

• InputActions.Load(text, name), then Enable(), then InputService.Add. Lookups are strings and a typo is a KeyNotFoundException at run time. This is what Samples/13 does.
• The generator. Vixen.Input.Generators turns a .vxinput in AdditionalFiles into a partial class with a property per map and per action, so Input.Player.Move binds at compile time. The targets file globs .vxinput automatically for projects that consume the package.

⚠ Nothing in this repository outside Vixen.Input.Tests uses the generated accessor, including the sample whose asset says it will. Both routes work; only the first is demonstrated, so treat the sample as a description of the string route and not as advice.

InputActionType picks the default interaction — what "the action happened" means:

⚠ value uses "not zero", not the press point. A stick nudged to 0.05 has already performed a value action and has not touched a button one.

InputActionPhase is Disabled, Waiting, Started, Performed, Canceled — and:

⚠ InputAction.Phase is never Canceled. A cancel returns the action to Waiting; the Canceled member exists as the Phase field of the InputActionContext handed to the event. Poll WasCanceledThisFrame, or subscribe. Testing Phase == InputActionPhase.Canceled is a condition that cannot be true, and it fails silently.

InputControlType — Button, Axis, Vector2 — decides how many dimensions the value has, and it is the action's property, not the binding's. An axis action bound to a stick gets |X| as its magnitude with the Y still sitting in Value.Y, unread.

⚠ The polled flags use one global press point and the events use the binding's. IsPressed, WasPressedThisFrame and ReadValue<bool>() all compare against InputSettings.DefaultPressPoint (0.5). A binding written press(pressPoint=0.2) raises Performed at 0.2 while IsPressed is still false — the event and the poll genuinely disagree, on purpose, and mixing them in one feature is how a trigger ends up firing twice.

An action with a keyboard composite and a stick takes whichever reads highest this frame; ActiveBinding is the one it took — useful for showing the right glyph. Two bindings held at once do not add up, and a release while another binding is still down does not cancel: the action stays Performed for as long as anything holds it.

<Gamepad>/south means the pad this asset is paired to — InputActions.GamepadSlot, which is how one asset per player works. An explicitly indexed path (<Gamepad>2/south) names the second pad and ignores the pairing.

⚠ A disconnected pad keeps its slot until InputDeviceSet.RemoveDisconnected() is called, so player two's controller coming back finds their slot where they left it. Disconnection also clears the held state, which is what stops a dying pad leaving a character sprinting for ever.

Honest, because all of it looks wired from the outside:

• InputRebindingOperation — press-a-key rebinding with settle time, conflict detection and device filtering — is complete and has no caller outside its own tests. The .vxinput editor records keys with a listener of its own, keyboard only.
• SaveBindingOverrides / LoadBindingOverrides produce and consume a small line-based format (Player/Fire[0]=<Keyboard>/space) and nothing in the engine persists it, so a game that wants rebinding to survive a restart writes that part itself. Loading skips lines naming actions that no longer exist and returns the count applied.
• Control schemes are parsed and never activated: every shipped path runs with ActiveControlScheme null, which means every binding is live at once. AutoSwitchControlSchemes is off by default, and switching resets every action rather than merely re-filtering them.

Loading an asset and reading it, which is the whole of what a game does with this. The action lookup is by Map/Action; a bare name is searched across every map.

⚠ FindAction throws KeyNotFoundException and TryFindAction does not. Which one to use is a statement about the asset: an action the game cannot run without should throw at load, where the message names the asset, rather than read zero on the frame the player presses it.

Subscribing instead of polling. The context carries the value that caused the event, so a handler never has to go back and read the action — which matters because the events fire during InputService.Update, before anything else in the phase has run.

Switching maps rather than filtering keys. A pause menu enables Menu and disables Player; nothing else has to know:

Disabling a map sets every action in it to InputActionPhase.Disabled and drops whatever was half-finished, which is the point: a jump held across the pause does not fire when the game resumes.

• Binding controls, and rebinding them — the layer below: what a path names, what a composite does with its parts, and the rebinding operation nothing drives yet.
• Players and possession — ActionPlayerInput, the adapter from an action map to a pawn's MoveIntent, and the Y flip between the two conventions.
• Character movement — what that intent drives.
• Core/Vixen.Input/README.md — the binding resolver, the processors and the interaction set in detail.