UX Spec: Build Mode — Picker, Ghost, Placement & Demolish

Status: Reviewed — APPROVED (/ux-review re-pass 2026-08-31: 0 blocking, 3 advisory — applied) · v0.3
Author: Jeroen + ux-designer
Last Updated: 2026-08-31
Journey Phase(s): unknown — no player journey map yet (see Open Questions)
Template: UX Spec
Variants: Build Mode (client-local mode: picker + ghost + reach grid; Player map stays live) · Demolish (an instant targeted action from Idle/Move — never a mode)
Requirements input: base-building Rules 3–9, 11a/11b, 12, 13; the BB States & Transitions table; BB UI Requirements (picker, ghost + per-gate reason strings with precedence + hysteresis, grid within reach only, demolish prompt + refund preview, no build log); BB Edge Cases 11 (race no-op) and 21 (displaced-player one-cell correction); the two /ux-design-owned deliverables — repeat-placement cadence (Rule 11b) and snap-nudge tolerance (OQ6 residual); ADR-0007 §1 Build map + rules (a)/(f)/(g) + §3 BuildModeRouting; art bible §7; ui-hud quick-spec Rule 4 (BB row) + queue item ③
Patterns used: #2 List Picker · #6 Reason String · #7 Honest No-Op Cue · #8 Ghost Outline & Reach Grid · #9 Demolish Target Select · #19 Feedback Split · #24 Interact Prompt (suppressed in mode) · #31 Repeat Placement (lifted from this spec)
Related specs: design/ux/hud.md (APPROVED — HUD fully visible in build mode; E11 suppressed), design/ux/inventory.md (storage placement instantiates a chest), design/ux/crafting.md (stationRange draw radius shared)

Purpose & Player Need

Build mode is where the group's home stops being a campsite. The player enters it wanting to put a wall here — and, most sessions, put fifty walls along this line — with placement feeling deliberate (snap-with-nudge, a thunk per wall) but never fiddly (persistent mode, hold-to-repeat, no confirmation dialogs, no timers). It must be honest about refusals (one world-fact reason per ghost, first failing gate, held stable), and it must resist becoming a build tool: no rotation, no move verb, no blueprints, no build log, no per-player credit (Rules 7, 9, 11a). Demolish is the same design in reverse — instant, total refund, "empty the chest first" — a repair verb for collective authorship, never a punishment.

Player Context on Arrival

• First encounter: home after the first haul, timber in the bag, curiosity — "can I build?" Usually the first friend to try teaches the others by doing.
• Typical: (a) a calm perimeter session at home — the multi-wall case the GDD names as the common one (Rule 5); (b) placing a workbench or chest once; (c) fixing a friend's misplaced wall (demolish + re-place — the only relocation path, Rule 9). Never on a docked land: structures are home-only (Rule 3).
• Emotional assumption: calm — home is hostile-free at MVP; the tension is material ("do we have the timber?"), read live from the picker's affordability.
• Voluntary: always. BuildToggle is the only entry.

Navigation Position

Gameplay → Build Mode — a client-local mode, not a panel: no UI capture; the Player map stays live for movement and camera, the Build map is enabled alongside (ADR-0007 §3 BuildModeRouting). Top-level from gameplay via BuildToggle (B / D-pad Up), anywhere; entering on a docked land is legal — no GDD rule gates mode entry by location; opening the mode off-island is this spec's ruling (the mode is client-local and costs nothing) — and every cell fails withinBounds (BB AC-4), so the ghost is dashed everywhere with the bounds gate's off-island string "not home ground". Demolish is not in the navigation tree — an instant verb from Idle/Move (Demolish: RMB outside build mode / D-pad Down). Build mode and any panel are mutually exclusive: opening a panel exits the mode (the Inventory edge exits first, then opens the bag); a panel cannot open inside it.

Entry & Exit Points

Persistence: the mode survives every commit (multi-wall sessions), every refused commit (ghost stays, reason shows), and every race loss (EC11). No one-way exits; every commit is its own host transaction that has already resolved by the time anything changes on screen.

Layout Specification

Information Hierarchy

• The ghost — where the structure will land and whether it is valid (solid vs dashed outline, zero fill — #8)
• The placement reason when invalid — the first failing F1 gate, held stable (#6)
• The picker — which structure is selected + its cost with live ghost-centred affordability
• The reach grid — the placeable radius (placementReach 6 u), build mode only
• (Demolish) the target highlight + refund preview (#9)

Deliberately absent: rotation control (Rule 7), move verb (Rule 9), blueprints / queues (Rule 11a), build log or per-player credit (Rule 7 / UI ban), any placement timer (Rule 6).

Layout Zones

• W1 — Ghost (world): pattern #8 — outline-only at the snapped cell (1 u grid, ADR-0003) with nudge 0.35 u to meet an adjacent footprint edge (OQ6 residual, ruled 2026-08-31); solid = valid, dashed = invalid; footprint-sized; follows PointerWorld (KB/M) or cell-steps along the aim vector (gamepad, #8). Aim semantics (ruled 2026-08-31): the gamepad ghost consumer reads InputFrame.Aim — the same deadzoned right-stick vector camera and combat read (ADR-0007 AimStick) — and quantises it to a dominant-axis cell step with key-repeat; Aim keeps updating normally, so camera aim-bias leans toward where you are placing. Intended; no AimResolver branch for build mode.
• W2 — Placement reason (world): #6, anchored 16 px above the ghost while invalid — the first failing F1 gate in order (reach → bounds → overlap → occupancy → exit → terrain → socket → materials); 250 ms minimum / 2-frame switch hysteresis.
• W3 — Reach grid (world): #8 — cell lines within placementReach (6 u) fading at the edge; build mode only, never full-canvas.
• W4 — Demolish target (world; Idle/Move only): #9 — highlight outline on the targeted structure + refund preview (icon + count per material at current StructureDef cost) above it, or "empty the chest first" (#6) for a non-empty chest.
• S1 — Picker strip (screen): bottom-centre, above the HUD's bottom band (Z1 / Z2 / Z4 untouched), n × 180 px (n = loaded structure count; 3 at MVP → 540 px) @100 %, centred: the entries side by side — icon (tier-shaped, §7.4) · name · cost with ✓ / — per material, affordability ghost-centred (CARRY ∪ STORAGE within stationRange of the ghost, the F1 predicate). Selected entry outlined and raised 2 px. No scrolling at MVP; Tier 1 wraps to a second row before it ever scrolls.
• S2 — Strip footer (screen): the selected entry's affordability reason when unaffordable ("not enough fiber in reach") — distinct from W2, which is the placement reason for the ghost's current cell. Ownership rule (ruled 2026-08-31): S2 is suppressed whenever W2 is showing any string — the ghost's blocker is the live question; the picker's affordability is meaningful only when the cell is otherwise placeable. The two never show at once and never duplicate. n = 0 is impossible (ADR-0006 rejects an empty Structures table at load), so no empty picker state is designed.
• HUD: fully visible (hud.md); E11 interact prompt suppressed; the centre 60 % box is untouched by S1 / S2.

All px at 100 % UI scale.

Component Inventory

ASCII Wireframe

BUILD MODE (home, wall selected, ghost invalid)
┌──────────────────────────────────────────────────────────────┐
│ ◉ Jo ████░                                                    │
│                                                               │
│                 someone is standing there   ← W2 (16 px above)│
│                 ┆‾‾‾‾┆  ← W1 dashed ghost (1×1 wall)          │
│        ▪▪▪▪▪▪▪▪ └┄┄┄┄┘ ▪▪▪▪                                   │
│        · · · · · · · · · · · ·  ← W3 grid, 6 u radius         │
│        · · · ·  ☺  · · · · · ·     (fades at the edge)        │
│        · · · · · · · · · · · ·                                │
│                                                               │
│      ┏━━━━━━━━━━━━━━┓┌──────────────┐┌──────────────┐  ← S1  │
│      ┃▣ Wall  4 timb✓┃│▤ Bench 8t 4f—││▢ Chest  6t ✓ │        │
│      ┗━━━━━━━━━━━━━━┛└──────────────┘└──────────────┘        │
│ ♥♥♥♥♡ ◔ [⚔][🛡]        (S2 empty — wall affordable)  🎒 7/10 │
└──────────────────────────────────────────────────────────────┘
Q / D-pad ← : previous · scroll / D-pad → : next · LMB / South: place (hold to repeat) · RMB / Esc / East: exit

DEMOLISH (Idle/Move, RMB / D-pad Down targeting a wall)
        ┌ +4 timber ┐   ← W4 refund preview
        ┃ ▣ wall    ┃   ← solid highlight outline
        └───────────┘
   (a non-empty chest instead shows: "empty the chest first")

Costs shown are illustrative; live values come from StructureDef (wallCost 4 timber at MVP).

States & Variants

Interaction Map

Mapping for KB/M (primary) and gamepad (partial); Build map per ADR-0007 §1, routing per §3 BuildModeRouting. This is the one screen where the two schemes deliberately differ (ADR-0007 rule (a)): on KB/M LMB / RMB are Confirm / Cancel inside the mode; on gamepad RT still strikes (and exits) while South places.

Repeat Placement — the gesture defined: Confirm.Held after a confirmed commit → when the confirm lands, the ghost advances one cell in the last ghost-move direction and, if the new cell is valid, commits again; direction resets when the player moves the ghost manually; a refused cell stops the row on that cell; release ends the row. Read as ButtonState.Held — not an asset Hold interaction (ADR-0007 rule (d)); its accessibility alternative is single presses (the same action with no hold).

Focus: the mode has no UI focus — nothing captures; the UI map is disabled in-mode; the picker is driven by PickPrev / PickNext and pointer clicks, never UI.Navigate. Exactly one selected picker entry at all times.

Events Fired

No analytics events exist in this project.

Transitions & Animations

• Enter: grid fades in 100 ms; picker strip slides up 100–150 ms ease-out (reduced-motion: appear in place). Exit: reverse; input released on the exit edge.
• Ghost: no animation — it moves per frame with input; solid ↔ dashed swaps instantly (the #6 hysteresis governs only the string, never the outline — the outline must be truthful every frame).
• Commit: the placed structure lands 1 px high and eases down — one impact-only squash-and-stretch beat (BB Visual Requirements) + the host-confirmed thunk. Kept under reduced motion — it is on accessibility-requirements.md's deliberately-kept list (placement squash / settle), and it carries the "placement is an event" tone (corrected 2026-08-31).
• Repeat: identical per cell; no cumulative flourish (11b's tone re-validation: one thunk per wall keeps the "event").
• Demolish: removal instant + understated sound; refund = bag flash (#17).
• Displaced player (EC21): one settle beat on the moved sprite, no sound.
• Nothing gates input (art bible §7.5).

Data Requirements

Architectural flag: the ghost is pure prediction — this spec depends on provisional and authoritative F1 disagreeing gracefully (EC11), never on them agreeing.

Accessibility

Tier: Standard.

• No UI focus in-mode (nothing captures). Operability = the Build map: KB/M fully via B / Q / scroll / LMB / RMB / Esc; gamepad fully via D-pad Up / Left / Right / South / East + right stick — nothing hover-only; the picker is click-or-cycle, never click-only.
• Gamepad parity: outcome parity via ghostSnapResult (BB AC-8); effort differs by design (cell-step vs pointer) — stated. The right-stick ghost never requires simultaneous left-stick input.
• Holds: hold-to-repeat is the project's third held input (after Revive and the title-screen reset) — read as ButtonState.Held, not an asset Hold; the built-in alternative is single presses per cell (identical outcome, no timing). Demolish's press → preview → release is an ordinary click, not a hold (no duration requirement). accessibility-requirements.md hold inventory updated accordingly.
• Colour-independence: valid / invalid = solid vs dashed (never hue); affordability = ✓ / — glyph + the reason string; selected entry = outline weight + 2 px raise; refund preview = text.
• Text: reasons Small 13–14 px with the ink outline (world) / on slate (S2), ≥ 4.5:1; picker names Medium 16–18 px.
• Reduced motion: strip slide → appear; grid fade → appear; the ghost never animates; the placement squash / settle is kept (accessibility keep-list).
• Flash: none introduced. Screen reader: out of scope (documented). Scale: the 540 px strip at 150 % = 810 px, centred → x 555–1365 on 1920; clears Z1 + Z2 (right edge ≈ 468 px at 150 %) and Z4 (left edge ≈ 1682 px), and sits below the centre box's lower edge (y 864), so it never intersects it; world text scales with the UI-scale option.

Localization Considerations

There is no on-screen input-hint bar at MVP (the wireframe's footer line is documentation). HIGH rows must survive 40 % expansion on one line.

Acceptance Criteria

• [ ] B / D-pad Up enters build mode within 1 frame: grid (6 u radius), ghost at the snapped cell, and the 3-entry strip appear; pressing again exits with nothing committed.
• [ ] Moving the pointer across cell boundaries moves the ghost in 1 u steps; within 0.35 u of an existing wall's edge the ghost aligns flush to it; two walls placed this way share an edge with no gap (screenshot).
• [ ] With a friend standing on the target cell the ghost is dashed and reads "someone is standing there"; when both occupancy and materials fail, the occupancy string shows (precedence); the string holds ≥ 250 ms and never flickers at a cell boundary while the outline updates every frame.
• [ ] LMB / South on a valid ghost: nothing changes locally until the host confirms (~1 RTT), then the wall lands with one squash / settle and thunk, 4 timber leaves the bag (flash), the ghost remains and the mode persists.
• [ ] Holding LMB along a clear line places one wall per confirm in the direction the ghost last moved, ≥ 1 RTT apart, one thunk each; a friend stepping into the line stops the row on that cell (dashed + reason) with no wall skipped; releasing stops immediately; pressing once per cell produces the identical row.
• [ ] Two clients confirm the same cell within one tick: exactly one wall exists; the loser's ghost turns dashed "blocked" and their bag is unchanged.
• [ ] Selecting Bench with insufficient fiber shows "—" on its entry and "not enough fiber in reach" in S2 while the ghost's cell is otherwise valid; when the ghost's cell also fails a gate, W2 shows and S2 is empty (never both); adding fiber to a chest within 3 u of the ghost flips the entry to ✓ without leaving the mode.
• [ ] Pressing Strike (RT) on gamepad exits build mode and swings in the same frame; LMB on KB/M places instead (no swing); RMB inside build mode exits without demolishing anything, even with a wall under the cursor; Esc exits then opens pause, never leaving a live ghost.
• [ ] RMB down on a wall (KB/M) / D-pad Down held facing it (gamepad) shows a highlight and "+4 timber"; release removes it with a sound and 4 timber lands in the bag; a non-empty chest shows "empty the chest first" and nothing happens on release.
• [ ] Entering build mode on a docked land shows every cell dashed with "not home ground"; no commit is possible.
• [ ] Gamepad: moving the right stick in build mode steps the ghost one cell per repeat and the camera's aim bias follows the same direction; D-pad Down inside build mode exits the mode and demolishes nothing unless a structure is under the reticle at release.
• [ ] Reduced-motion on: strip and grid appear without motion; walls still land with the settle beat (deliberately kept); outcome identical. At 150 % UI scale the strip does not overlap the HUD's bottom clusters.
• [ ] No rotation control, move verb, build log or per-player credit exists (reflection over the Build map + screenshot; BB AC-33's no-move-verb asset test).

Open Questions

• Player journey map not yet created (.claude/docs/templates/player-journey.md) — contexts assumed; validate at the playtest.
• Rule 11b tone re-validation — hold-to-repeat keeps one thunk per wall; playtest whether a 50-wall run still reads as "placement is an event" or as a paint tool. Fallback: a 250 ms floor between repeat commits.
• ~~Pattern lifts~~ Done 2026-08-31: #31 Repeat Placement in interaction-patterns.md; #9 amended to "preview while held, action on release"; a11y hold inventory → three.
• Repeat direction on KB/M ("last cell-boundary crossing") — if the playtest shows surprising rows on diagonal pointer paths, switch to "toward the pointer" per step.
• Three new reason-string instances — bounds "past the island's edge" (retitled from a system-fact phrasing), terrain "not buildable here", off-island bounds "not home ground" — authored under BB's /ux-design retitling right; owed back to BB's UI Requirements list (note appended to BB's OQ table 2026-08-31).
• Tier 1: strip wrapping at > 6 entries; a Forge category; socketNoBuildRadius re-check (BB OQ2 — LDU-owned).
• EC21 settle beat when the displaced player is in build mode — their ghost re-evaluates; confirm no double beat with the wall's own thunk (BB: the wall's thunk marks the event).
• BB Rule 11b prose (its "AC-48c's playtest must include a drag-row segment" clause and the drag-row reasoning around EC23) still assumes a drag-row; drag-a-row was rejected here in favour of hold-to-repeat (#31, a legal 11b choice) — BB should retarget those clauses to "a held-repeat row" (AC-48c's own current text carries no row segment). Flagged via BB OQ 12(b).
• ADR-0007 amendment: Demolish consumed on Released (Pressed = preview); rule (d) reads "exactly one asset-level hold" — three Held reads exist at the design layer (Revive, title reset, #31). Appended to ADR-0007's Amendments 2026-08-31.