ADR-0007: Input Action Map — The Project-Wide .inputactions Asset, Three Maps, Two Schemes, the InputFrame Snapshot, and Rebind Persistence

Status

Accepted

Accepted 2026-08-28 — architecture-review-2026-08-28.md (verdict CONCERNS; review amendments applied before acceptance).

Date

2026-08-28

Engine Compatibility

Documents Amended by This ADR

ADR Dependencies

Context

Problem Statement

Architecture fixes a flat IPlayerInput and "one .inputactions, Player + Build maps, KB/M + gamepad schemes, decoupled aim, rebind persistence" — but not the asset's action list and types, how mouse position and right-stick direction become one aim vector that persists on stick release (movement Rule 3), who detects button edges (combat, harvesting and build mode all react to presses; three edge detectors is a double-fire bug), how the Build map coexists with the Player map (BB Rule 5: any non-Build action exits, move and camera stay live), where rebinds persist, or what input.json holds. Unity 6 adds a question none of the docs asked: the project-wide actions asset is auto-instantiated and auto-enabled, and UI Toolkit reads its UI map directly — so "who owns the instance" must be decided before anything else.

Constraints

• Technical preferences: Input System only; KB/M primary (WASD + mouse-aim), gamepad secondary twin-stick; no hover-only-critical interactions; every action reachable on gamepad.
• Owner rail (ADR-0002): move, dash, aim, ghost preview are local; input never rides the network.
• hardcoded_gameplay_value (ADR-0006): deadzones and thresholds are data, validated at boot.
• Pillar 4: no input gated by an animation; combat: dash i-frames start on input, owner-authoritative.
• Harvesting Rule 1 / combat Rule 1: Strike is one input; the referent rule decides enemy vs node client-side; no hold-to-channel harvest.
• Combat Rule 9: revive is a short channel (reviveChannelTime 3 s) cancelled by damage (EC5) or the reviver dashing (EC6) — the one hold in the game.
• BB Rule 5 + transition table: build mode is client-local; "non-build action" = attack, interact, inventory, menu; move and camera never exit. BB Rule 7: no rotation at MVP (schema-banned). BB Rule 9: demolish is an instant targeted action from Idle/Move, not a state. BB AC-33: the Build map contains no move/relocate verb.
• UI/HUD: explicit gamepad navigation order + visible focus on every panel; rebinding surface in Settings (ADR-0014).

Requirements

• One asset, one live instance, one adapter; consumers read an immutable per-frame snapshot.
• One aim vector, one code path, parity by construction.
• Edges computed once, observed identically by every consumer in that frame; edge consumers run in Update.
• Rebinds persist per machine, atomically, outside the world save; conflicts surfaced; reset always reachable in-game.
• Device switch, disconnect and reconnect safe mid-session.

Decision

**Alternative A: Driftlands.inputactions is the project's project-wide actions asset (generated C# wrapper DriftlandsControls for typed access) with three maps — Player, Build, UI (Unity's reference names/types, consumed by UI Toolkit directly) — and two control schemes — KeyboardMouse, Gamepad. A single Runtime InputAdapter references the one instance through InputSystem.actions (never new), takes ownership of enabling/disabling the Player/Build maps, and reads every action once per frame in Update into an immutable InputFrame (in Driftlands.Rules.Input) exposed through IPlayerInput.Current; aim is resolved by one pure function with last-direction persistence; BB's build-mode routing is one pure function; binding overrides persist as JSON under persistentDataPath/Driftlands/settings/bindings.json; tunables live in input.json.**

1. The asset

Rules: (a) Strike and Confirm share LMB; Demolish and Cancel share RMB — deliberate; the adapter routes by build-mode state (§3), so one physical button is "strike/demolish" outside and "place/cancel" inside (BB's "no menu confirmation"). (b) Every Player/Build action has a binding in both schemes except the two aim sources — asserted by the EditMode asset test. (c) Player/Build are disabled by the adapter at boot (project-wide auto-enable would otherwise enable them before the adapter runs) and enabled by it; UI is enabled only while a panel is open. (d) Exactly one action is a hold: Revive. Harvesting Rule 1 and combat Rules 1–3 are press-only. The revive channel is modelled as ButtonState.HeldFor seconds read by ADR-0015 — not as a Hold interaction on the asset — so combat EC5/EC6's cancel rules stay in a pure state machine. The asset test asserts no Hold/MultiTap/SlowTap interaction exists on any binding. (e) No Rotate action — BB Rule 7 bans structure rotation at MVP and AC-2 makes the absent field a schema check; adding rotation is a BB design change. (f) The Build map contains no move/relocate verb (BB AC-33 — asset test). (g) Menu exits build mode before opening pause (BB transition table) — the player never resumes from pause into a live ghost with LMB bound to Confirm. (h) Processors on the asset are limited to deadzones and the RT Press threshold; everything else is adapter/Rules logic.

2. The snapshot

namespace Driftlands.Rules.Input          // Rules declares, Runtime implements — ADR-0003's IHostPositions precedent
{
    public readonly record struct ButtonState(bool Pressed, bool Held, bool Released, float HeldFor);  // edges are THIS-FRAME; HeldFor = seconds held (Revive channel)
    public enum InputScheme : byte { KeyboardMouse, Gamepad }

    /// One immutable snapshot per rendered frame. Every consumer in a frame reads the same instance.
    public sealed record InputFrame(
        int          FrameIndex,
        InputScheme  Scheme,               // PRESENTATION ONLY (prompt glyphs, settings list) — referenced from Driftlands.Presentation alone (analyzer test)
        Vector2      Move,                 // normalised, deadzoned; zero when no device
        Vector2      Aim,                  // unit; persists at last value when neither source is live
        bool         AimIsPointer,         // this frame's aim came from the pointer — THE discriminator for BB Rule 5's cursor-vs-stick ghost
        Vector2?     PointerWorld,         // mouse world position when present — BB ghost follows this on KB/M
        ButtonState  Strike, Dash, Interact, Revive, Demolish, Inventory, BuildToggle, Menu,
        ButtonState  Confirm, Cancel, PickPrev, PickNext,   // Build map; all-false unless build mode is active
        bool         BuildModeActive,
        bool         UiCaptured);          // a panel is open: every Player/Build edge is false EXCEPT Menu and Inventory (§3)

    public interface IPlayerInput { InputFrame Current { get; } }
}
namespace Driftlands.Data { public sealed record InputConfig(float MoveStickDeadzone, float AimStickDeadzone, float AimPointerMinDistance, float TriggerPressPoint); }  // input.json — NO aim-persistence key (schema-negative)

Vector2 is System.Numerics.Vector2 (ADR-0003). Architecture's flat IPlayerInput is superseded by IPlayerInput.Current. IAimSource is retained (ruled 2026-08-28): PlayerMovement implements AimVector => _input.Current.Aim as a pass-through, and Camera, Combat and the BB ghost keep depending on Movement — this ADR fixes where aim is computed, not who publishes it.

3. The adapter — one instance, one read point, one aim function, one routing function

InputAdapter : MonoBehaviour (Runtime; injected as IPlayerInput; one per machine; [DefaultExecutionOrder(-1000)]):

• Instance ownership. _controls = new DriftlandsControls(InputSystem.actions) is not used — the wrapper is a typed view over InputSystem.actions (FindActionMap/FindAction with the generated ids); the adapter never creates a second InputActionAsset instance. At Awake it disables Player/Build/UI, then enables Player. An EditMode test asserts exactly one enabled Player map exists in play (Verification 5). Rebind overrides therefore apply to the one live instance.
• Update mode ProcessEventsInDynamicUpdate; the adapter reads in Update at −1000 so every other Update in the frame sees the finished snapshot (the documented pattern: latest events at the start of each frame; poll edges in Update).
• Binding on consumers: edge consumers run in Update. Movement (ADR-0009), the combat player state machine and dash i-frame start (ADR-0015 — "i-frames start on input" means the same Update), harvest intent, and build-mode ghost/confirm are Update-driven — a constraint this ADR imposes, not an observation. No FixedUpdate consumer may read InputFrame edges: FixedUpdate runs zero-or-more times per rendered frame (60 Hz render vs 50 Hz physics ≈ one frame in six has none) and would drop a one-frame press. Held/HeldFor/Move are safe anywhere. A consumer that needs edges on the physics step takes them from a queue this adapter fills — a new ADR. This says nothing about ADR-0002's open QQ-01 (Drain vs NetworkTransform receive): this ADR fixes the owner-rail sample point only.
• Aim — one pure function. AimResolver.Resolve(prev, pointerWorld?, playerWorld, stick, cfg): stick above AimStickDeadzone → normalize(stick); else pointer present and |pointerWorld − playerWorld| ≥ AimPointerMinDistance → normalize(pointerWorld − playerWorld); else prev. Last live source wins per frame; the result persists when neither is live (movement Rule 3 — the else prev branch, not a config). Camera.ScreenToWorldPoint is the only Unity call in the aim path, converted through UnityInterop before Resolve; the world point is also published as PointerWorld.
• Edges once. ButtonState(action.WasPressedThisFrame(), action.IsPressed(), action.WasReleasedThisFrame(), heldFor) per action, once per frame; heldFor accumulates from the press frame. Consumers never call the Input System.
• Build-mode routing (BB Rule 5 / transition table) — BuildModeRouting.Step(active, scheme, rawEdges) → (active, EdgeMask, exitedThisFrame), pure. Exit set = BuildToggle, Cancel, and any Player-map edge other than Move and the aim sources — Strike, Dash, Interact, Revive, Demolish, Inventory, Menu (BB's enumerated "attack, interact, inventory, menu") — except that where Strike/Confirm (LMB) or Demolish/Cancel (RMB) share a physical control (KB/M), the edge inside build mode is consumed as the Build action and does not exit: LMB places, RMB cancels. The exception is keyed on control identity, not action identity (amended 2026-08-31): whichever Player action currently holds a control that a Build action shares is the one masked inside build mode — so after a rebind moves Strike off LMB, the Player action now on LMB is masked and Confirm still places. Exits happen first, then the exiting edge is delivered in the same frame ("ghost vanishes; nothing committed" — then the action applies). Scheme asymmetry, intended: on gamepad Strike (RT) and Confirm (South) are distinct controls — RT exits and strikes, South places; a gamepad player has a dedicated place button. EdgeMask names every suppressed action so tests assert the whole mask. While inactive the Build map is disabled and its ButtonStates are all-false.
• UI capture. ADR-0014's panel manager calls SetUiCaptured(bool) from an Update after −1000, so capture applies from the next frame (the opening frame delivers the Inventory edge; the panel owns the closing edge). While captured: the UI map is enabled; every Player/Build edge is false except Menu and Inventory — Menu is protected and must reach the player from every state (it closes the open panel via the panel stack rather than opening pause); Inventory closes the bag it opened (a panel you cannot dismiss with the key that opened it fails the new-friend test). Move is still reported (locomotion decelerates naturally; ADR-0009 stops on UiCaptured regardless). Build mode does not survive capture.
• Title-screen map state (added 2026-09-01 by ADR-0014 §5; architecture review). Rule (c) above enumerates only the in-world states, where UI is enabled while a panel is open. The title screen is a fourth state it does not cover: there is no world behind it, so UI is enabled standing (no panel-open handoff) while Player is present but only Menu is consumed — the 3-second reset floor (§4) reads Menu, which is a Player-map action. ADR-0014's panel manager derives this from an explicit UiContext (Title | World) set once at scene load; it never inspects which screen is open (that would be scheme_gating_gameplay's sibling). This is a clarification of rule (c)'s scope, not a change to it — title-screen.md OQ 10 requested it and is closed by ADR-0014.
• Combat state is not input state. Downed (crawl-speed, no combat) and Dead suppress Strike/Dash/Demolish inside ADR-0015's state machine, never here; UiCaptured is not a proxy for it. The adapter's one gate is UI capture.
• Devices. Scheme = the last device that produced input (from the action's active control's device); no modal "controller mode". Device removal cancels in-progress actions (documented) → Move zero; Aim keeps prev. Reconnect needs no action.
• No PlayerInput component, no Send Messages, no per-consumer callbacks. Nothing but InputAdapter and the rebind service references UnityEngine.InputSystem (ADR-0003 reflection test Input_OnlyAdapterReferencesInputSystem); UnityEngine.Input nowhere.

4. Rebinding and persistence

• Mechanism: action.PerformInteractiveRebinding(bindingIndex).WithControlsExcluding(<other scheme's devices>) per scheme, wrapped in Awaitable<RebindResult> (project preference — current-best-practices.md; Verification 2).
• Protected actions: Menu and UI.Cancel cannot be unbound; a rebind leaving any Player-map action with no binding in that scheme is refused with a named reason.
• **Conflict rule (ruled 2026-08-28: swap on confirm; amended 2026-08-31: confirming exchanges — see Amendments)**: a rebind duplicating an existing binding within the same map and scheme surfaces the colliding action; confirming exchanges the two controls (the colliding action receives the control the rebound action vacated; the empty-binding refusal remains for the residual case), cancelling keeps both unchanged. Cross-map duplicates are legal by design (§1 Rule (a)); the Interact / Revive pair is exempt (bound together by design — Amendments).
• Recovery floor: Reset-to-defaults is reachable without a working binding — holding Menu's default control (Esc / Start) for 3 s at the title screen resets all overrides regardless of the current set, and the settings screen exposes the same reset. A player can never rebind themselves out of Settings.
• Persistence: SaveBindingOverridesAsJson() → persistentDataPath/Driftlands/settings/bindings.json, written with ADR-0004's atomic writer (temp + File.Replace; no F_FULLFSYNC — a lost rebind is not data loss). Loaded at adapter start with LoadBindingOverridesFromJson(json) (default replace semantics — never pass false, which merges). Missing file = defaults. Malformed JSON → defaults + loud log + file renamed bindings.bad.json. Overrides naming an unknown action: behaviour decided by Verification 3 (skip-and-log vs catch) — either way the log names the action. Never in the world save — bindings are per machine; ADR-0004's save has no settings table (schema-negative).

5. input.json (ADR-0006 stage 9 — amended)

Schema-negative (movement Rule 3): input.json has no aimPersistsOnRelease key and no key that could disable aim persistence — persistence is AimResolver's else prev branch, not a configuration; an EditMode test asserts InputConfig declares no such field (ADR-0003 Schema_* family, the MoveSpeedModifier pattern). No hold durations exist here (reviveChannelTime is combat's, in combat.json).

Amendment to ADR-0006 (same change as Migration step 3): §1 file list gains input.json moveStickDeadzone, aimStickDeadzone, aimPointerMinDistance, triggerPressPoint, listed in manifest.json.files; §2 step 3 Configs.{…, Camera, Input, Save, …}; stage 9 title gains Input and these rows. Source assets/data/input.json, build-mirrored to StreamingAssets/data/; the data-overrides/ folder applies identically.

Architecture Diagram

 Project Settings ─► project-wide actions = Driftlands.inputactions (Player / Build / UI · KeyboardMouse / Gamepad)
                                              │  InputSystem.actions — ONE instance, Unity-owned
                                     InputAdapter (Runtime, Update @ -1000) — references, never new()s; owns Player/Build enable
                                              │  reads each action once; ScreenToWorldPoint → PointerWorld
                                     AimResolver.Resolve (Rules, pure) ◄── InputConfig (Data, input.json)
                                     BuildModeRouting.Step (Rules, pure) · UI capture · edges/HeldFor
                                              ▼
                                     InputFrame (Rules.Input, immutable)  ◄── IPlayerInput.Current
              ┌──────────────┬──────────────────┬──────────────────┬──────────────────┐
        PlayerMovement    Combat (ADR-0015)   Harvest intent    BaseBuilding (ADR-0011)   UI Toolkit panels
        (ADR-0009)        Strike/Dash/Revive  Strike + referent  Confirm/Cancel/Demolish   ◄── UI map (UI Toolkit default event system, direct)
              │ IAimSource.AimVector (pass-through, retained)
              └──► Camera (aimBiasFrac) · Combat · BB ghost (PointerWorld on KB/M, projected Aim on gamepad — AimIsPointer decides, never Scheme)
 bindings.json (persistentDataPath/Driftlands/settings) ◄──► Save/LoadBindingOverridesFromJson (replace semantics)

Key Interfaces

namespace Driftlands.Rules.Input
{
    public static class AimResolver
    {   /// Pure. One path for both schemes; returns prev when neither source is live (movement Rule 3).
        public static (Vector2 aim, bool isPointer) Resolve(Vector2 prev, Vector2? pointerWorld, Vector2 playerWorld, Vector2 stick, InputConfig cfg); }

    [Flags] public enum EdgeMask { None = 0, Strike = 1, Demolish = 2, Confirm = 4, Cancel = 8 /* … one bit per maskable action */ }
    public static class BuildModeRouting
    {   /// Pure. BB Rule 5 + transition table incl. the shared-control exception (LMB/RMB on KB/M) and the gamepad asymmetry.
        public static (bool active, EdgeMask mask, bool exitedThisFrame) Step(bool active, InputScheme scheme, RawEdges raw); }
}

namespace Driftlands.Runtime.Input
{
    public sealed class InputAdapter : MonoBehaviour, IPlayerInput
    {
        public InputFrame Current { get; private set; }
        public void SetUiCaptured(bool captured);        // ADR-0014's panel manager; takes effect next frame
        public IRebindService Rebind { get; }
    }
    public interface IRebindService
    {
        Awaitable<RebindResult> RebindAsync(string actionId, InputScheme scheme, CancellationToken ct);  // Awaitable, not Task; refuses protected actions / empty-scheme results; surfaces conflicts for swap-on-confirm
        void ResetToDefaults();
        IReadOnlyList<BindingDisplay> Display(InputScheme scheme);
    }
}

Alternatives Considered

Alternative B: PlayerInput component with Send Messages / Unity Events

• Cons: Callbacks arrive at arbitrary points in the frame, so combat, harvesting and build mode see edges at different times (the double-fire class); aim persistence and build-mode routing would live in three places; PlayerInput couples input to a scene object, but input must exist before the character spawns and survive despawn (Downed/Dead, land teardown).
• Rejection Reason: The GDDs' shared-verb rules need one frame view.

Alternative C: Direct device polling in each consumer

• Rejection Reason: No rebinding, no schemes, Unity references in every consumer (ADR-0003 forbids) — fails technical preferences outright.

Alternative D: Exclusive Build map

• Rejection Reason: BB keeps Move and camera live in build mode; an exclusive map duplicates them and a rebind of Move would apply to two bindings. Ruled: both maps enabled, routing in the adapter.

Alternative E: Adapter-owned asset instance, no project-wide asset

• Description: Leave project-wide unassigned; new DriftlandsControls() in the adapter; wire UI Toolkit through InputSystemUIInputModule + EventSystem by hand.
• Cons: Unity 6 documents the module as not required for UI Toolkit and the project-wide asset as the recommended single instance; hand-wiring adds two components and a second input path for the UI to diverge on.
• Rejection Reason: Ruled 2026-08-28 — project-wide asset, referenced by the adapter.

Consequences

Positive

• One asset, one Unity-owned instance, one read point, one frame: every "on press" rule in five GDDs observes identical edges.
• Gamepad parity by construction (one aim function; both-schemes binding test); the one intended asymmetry (RT vs South in build mode) is stated.
• UI Toolkit needs zero input components; rebinds apply to the instance the UI reads.
• Build-mode routing, aim resolution and the revive channel's cancel rules are pure functions with unit tests.

Negative

• Input is sampled at the top of Update; edge consumers are pinned to Update by rule.
• Architecture's flat IPlayerInput becomes Current; the generated wrapper is a checked-in artefact (merge noise on asset edits).
• Player/Build must be explicitly disabled at boot against the project-wide auto-enable — a line that, if lost, double-drives nothing but reads input before the adapter's first frame.

Risks

• Edge starvation on FixedUpdate — closed by construction (edges Update-only); enforcement candidate: an EditMode test that no FixedUpdate body references IPlayerInput.
• Mouse aim ↔ camera aim-bias is a real closed loop (camera offsets toward Aim → world point under a stationary cursor moves → Aim rotates → camera moves): bounded, not absent — Aim being unit-length bounds the bias magnitude, not the loop; convergence depends on followSmoothTime × aimBiasFrac; at aimBiasFrac = 0 there is no loop; the gamepad path has none. Camera's "identical on mouse and stick" AC holds in the steady state — stated. Verification (camera story, PlayMode): mouse held still 5 s at aimBiasFrac = 0.20 → Aim settles within 1° without oscillation; if it oscillates, the camera reads the previous frame's Aim (one-frame lag breaks the loop at zero perceptual cost).
• Trigger press point: per-binding Press interaction on Strike's RT, not the global defaultButtonPressPoint (which would also affect every analog button); 1.20.0 made action-level press APIs follow the interaction's threshold — the asset test asserts the interaction is present with the data-sourced parameter.
• Override-file recovery semantics depend on Verification 3 (skip vs throw); both paths log the action name.
• Protected/collision rules drift: asset + EditMode tests over the action set.
• Allocation: one InputFrame record per frame (~4 KB/s at 60 Hz); pool only if it appears in a GC profile at ≥ 0.1 % of frame budget — it will not.

GDD Requirements Addressed

Deferred, with owners

Performance Implications

• CPU: ~16 action reads + one ScreenToWorldPoint + two pure functions per frame — microseconds.
• Memory: one asset instance (Unity's), one frame record per frame.
• Load Time: bindings.json read once.
• Network: none — input never leaves the machine.

Migration Plan

No production code. (1) Driftlands.inputactions assigned project-wide + generated wrapper; EditMode asset tests (both schemes bound; protected actions; no hold interactions; no Rotate; Build map has no move verb; UI map matches Unity's reference set; one enabled Player map); (2) InputFrame/ButtonState/IPlayerInput/AimResolver/BuildModeRouting in Rules.Input with UNIT tests; InputConfig in Data; (3) InputAdapter + input.json + stage-9 rows + the aim-persistence schema-negative (ADR-0006 amendment applied in this change); (4) bindings.json via ADR-0004's atomic writer; (5) IRebindService (Awaitable) for ADR-0014; (6) architecture §2/§4 amendments (IPlayerInput.Current; IAimSource retained as pass-through); (7) registry sync in the same change.

Validation Criteria

• UNIT: AimResolver — stick above deadzone wins; pointer wins when the stick is dead; neither live → prev; identical output for a mouse direction and the same stick direction.
• UNIT: BuildModeRouting — toggle enters; Dash/Interact/Inventory/Menu/Revive edge exits and is delivered; Move never exits; KB/M in build mode: LMB → Confirm.Pressed, Strike masked, BuildModeActive unchanged; RMB → Cancel, Demolish masked; Gamepad: RT → Strike true, Confirm false, BuildModeActive false; South → Confirm.
• UNIT (asset): every Player/Build action bound in both schemes (except aim sources); Menu/UI.Cancel protected; no Hold/MultiTap/SlowTap interactions; no Rotate; Build map has no move/relocate verb (BB AC-33); UI map name/actions/types equal Unity's reference set; Strike RT carries a Press interaction.
• UNIT (schema-negative): InputConfig declares no aim-persistence toggle.
• UNIT (reflection): UnityEngine.InputSystem referenced only by InputAdapter/rebind types; UnityEngine.Input nowhere; InputScheme referenced only from Driftlands.Presentation; no FixedUpdate body references IPlayerInput.
• PlayMode: exactly one enabled Player map; a one-frame Strike yields exactly one Pressed across combat and harvest consumers; gamepad unplug mid-aim leaves Aim unchanged and Move zero.
• PlayMode: rebind Dash, restart → restored; corrupt bindings.json → defaults + bindings.bad.json; hold default Esc 3 s at title → overrides cleared.
• PlayMode (camera story): stationary-mouse aim settles within 1° at aimBiasFrac = 0.20.
• Playtest: the new-friend test on both schemes.

Amendments

• 2026-08-31, design/ux/build-mode.md (via /ux-review) — Demolish release semantics and the hold count. (1) Demolish is consumed on Released: Pressed opens the targeting preview (highlight + refund, pattern #9); the release resolves the action in one frame — BB Rule 9's "instant" describes the commit, not the gesture. Inside build mode: on KB/M RMB is Build.Cancel (rule (a), unchanged); on gamepad D-pad Down's Pressed edge exits build mode (§3 exit set) and the subsequent Released demolishes only if a candidate is under the reticle — ordinarily nothing. InputFrame.Demolish.Released is therefore a consumed edge (edge consumers stay Update-only). (2) Rule (d) is clarified: "exactly one action is a hold" means exactly one asset-level Hold interaction (Revive — and even that is read as HeldFor, not an asset interaction; the asset test stands). At the design layer three Held reads exist — Revive (#10), the title-screen reset floor (§4), and hold-to-repeat placement (Confirm.Held, pattern #31) — each with a no-hold alternative inventoried in design/accessibility-requirements.md.
• 2026-08-31, design/ux/settings.md — conflict rule = exchange; the Interact / Revive pair; aim sources. (1) §4's conflict rule as written — "confirming clears the other binding (subject to the empty-binding refusal)" — is refused on every conflict in the default set: each Player/Build action has exactly one rebindable binding per scheme (rule (b) is a minimum; the two KB/M actions with a second binding — Build.Cancel RMB / Esc, PickPrev/PickNext Q / scroll — carry it as a fixed secondary, see (4)), so clearing the colliding action's binding always trips the refusal; the prompt said "swap" and never swapped. Amended: confirming exchanges — the rebound action takes the captured control and the colliding action takes the control the rebound action vacated, applied as one atomic RebindResult (fields: actionIds, scheme, newPath, exchangedActionId?, exchangedPath? — nothing is cleared under exchange); the empty-binding refusal remains only for the residual case where an action would still end unbound (possible after earlier edits gave an action several bindings). Protected collision: a captured control that belongs to a protected action (Menu) is refused before any prompt — Menu never moves, so the reset floor's "default control" premise stays true. Shared-control pairs: Strike/Confirm and Demolish/Cancel are not paired for rebinding; §3's shared-control exception follows control identity (amended above), so moving one half away changes which Player action is masked in build mode, never whether Confirm/Cancel work. When the Interact / Revive pair is the rebound row and collides with a third action, that action receives the pair's single vacated control. (2) Interact and Revive share E / West in both schemes by design (§1) — the same-map duplicate rule exempts this pair, IRebindService applies one override to both action ids, and the settings screen shows one row ("Interact / Revive (hold)"). (3) AimPointer (mouse position) is not rebindable — there is nothing to rebind a pointer to; AimStick is (stick swap) — a UX ruling for ADR-0014 to confirm. (4) Fixed secondary bindings (ruled 2026-08-31, second /ux-review pass): a rebind row edits one binding — the action's primary for that scheme (binding index 0 of the scheme's group, passed to PerformInteractiveRebinding). Build.Cancel's Esc and PickPrev/PickNext's scroll (down / up) are fixed secondaries — their KB/M primaries are Q and R (§1 row split in this amendment; the pair's single row had left PickNext with no rebindable key): never displayed, never rebindable, never present in bindings.json overrides — Esc because it is Menu's protected control (protection is keyed on Menu's control regardless of sharers, so a capture of Esc is refused pre-prompt and Cancel can never leave Esc — rule (g) and BB's Esc exit always hold), scroll because it is a pointer affordance like AimPointer. An override file that names a secondary binding index is treated like an unknown action (Verification 3 path). Validation Criteria gain: UNIT (rebind service) — an exchange on conflict leaves no action unbound; the Interact / Revive row yields one override on both ids; a capture of Menu's control is refused with no conflict surfaced; UNIT (BuildModeRouting) — with Inventory rebound to LMB, LMB inside build mode → Confirm.Pressed, Inventory masked, BuildModeActive unchanged; UNIT (asset): Build.Cancel keeps Esc and PickPrev/PickNext keep scroll after any override load, and no override targets a secondary index; UNIT (rebind service): rebinding Inventory to LMB and confirming yields Strike = Tab, Inventory = LMB; PlayMode: rebind Dash to E → Dash = E and Interact/Revive = Space.

Related Decisions

• ADR-0002 (owner rail; QQ-01 untouched), ADR-0003 (assemblies; Rules declares/Runtime implements; reflection tests), ADR-0004 (atomic writer; settings never in the save), ADR-0006 (amended: input.json, Configs.Input, stage 9), ADR-0009/0011/0014/0015 (consumers)
• design/quick-specs/player-movement-2026-08-27.md, design/gdd/combat-system.md, design/gdd/harvesting-system.md, design/gdd/base-building.md, design/quick-specs/ui-hud-2026-08-27.md, design/quick-specs/camera-2026-08-27.md, .claude/docs/technical-preferences.md
• docs/architecture/architecture.md §2 Input row, §4 IPlayerInput (amended) / IAimSource (retained), Required-ADR row 7