# Spec: the cursor and the senses ``` Type: spec Status: IMPLEMENTED Status note: implemented 2026-07-07 on the cursor-senses branch. The walking player entity and `move_player` were deleted; cursor position is frontend state only; save v2 carries remembered snapshots and migrates v1 player body coordinates away; `Sim::inspect` returns provenance-tagged facts for seen, heard, remembered, blueprint, and telemetry sources. 2026-07-08 tick: `Sim::person_label` / `observer_label` / `person_glyph` gate every player-facing identity surface (people panel, detection sidebar, map glyph, context-menu verbs, signature notes, agent frame) behind staged social knowledge — role silhouettes until Schedule, authored names after (criterion 5 extended). 2026-07-09: blueprint is room topology only — foreign machine chassis are absent under blueprint; owned hosts still report via telemetry in panels (machine-work.md). 2026-07-10: material Heard is **dark mass only** (near-black rough geometry); noise-field rings stay flat-sensorium (Cameron screenshot). 2026-07-09 (feel-floor): tick-one no longer seeds blueprint room topology. 2026-07-09 (beam-first): pre-tap material presence is a **beam of light** only; Seen shows the whole lit form (material-dark-frame.md). 2026-07-10: a known reachable sensor may ping cold at its shared anchor before sight (criterion 11). Stage: B1 — The Basement Design: - wiki/interface/presence.md#presence-the-cursor-and-the-senses - wiki/interface/presence.md#no-disembodied-hands - wiki/vision/simulation-laws.md#justification-and-legibility - wiki/vision/premise.md#design-pillars - wiki/gameplay/act-one.md#opening-state Depends on: - wiki/mechanics/reach.md#spec-digital-reach - wiki/world/places/basement-map.md#spec-the-basement-map - wiki/mechanics/core.md#spec-the-core - wiki/mechanics/schedules.md#spec-schedules-and-presence - wiki/mechanics/social.md#spec-social - wiki/interface/material-dark-frame.md#spec-the-dark-frame-the-material-render-shows-only-light - wiki/interface/feel-floor.md#spec-the-feel-floor-rails-pads-and-the-build-beam ``` ## Dependency notes The structured references above identify the contracts to re-verify. Relationship context: reach.md (device graph; sensor ownership/subscription — senses are subscribed feeds), basement-map.md (sensors, fog, tile vocabulary), core.md (the core as the player's only physical location), schedules.md (person presence; located knowledge), social.md (staged knowledge), interface/material-dark-frame.md (material reveal ladder), interface/feel-floor.md (presence/build beam) ## Behavior ### The cursor The player's map presence is a **cursor** — attention, not an avatar. - It moves freely over every tile — walls, fog, locked rooms — in both frontends (keyboard in terminal; keyboard + mouse in Bevy). - It is not a sim entity: no collision, no walkability check, no signature, no suspicion, no compute cost. Nothing in the world reacts to it. Moving it changes nothing in the sim. - Cursor position is **frontend state**, not sim state. The sim exposes query APIs (`inspect`, knowledge lookups); it does not store or save a cursor. The existing build cursor merges into this one — there is one pointer, and build/digital-action targeting anchor to it. - **The walking player entity is deleted** (zombie fiction from the villain era): no `move_player`, no player walkability, no vision radius around a player position, no player body coordinates in the save. The player's only physical location is the core's host bay (core.md, Rack 3). - Actions that targeted "nearest to the player's body" (e.g. the sensor tap) re-anchor to "target at/near the cursor," with legality coming from control and reach (network paths, assets, badge access of the humans involved) — distance from any body is never a cost or a gate. ### The senses - `Sensor` gains capability flags `sees` and `hears`. The `env_camera` both sees and hears (the design corpus has it overhearing Marcus's 3 a.m. phone calls); `camera_node` and `dock_camera` see; a `mic` fixed object may be authored where hearing-only coverage is wanted [TUNE which rooms, if any, at B1]. Its **audio feed is tappable from tick one** (the Ears beat — reach.md) while the camera stays dormant until the Eyes beat. - "Controlled" throughout this spec means **subscribed** per reach.md's ownership contract (owner + subscribers; tap vs take). The player's senses are exactly the union of feeds they subscribe to. - **Sight** = the union of subscribed seeing-sensors' coverage, bounded by physical line of sight. Full live detail inside; none outside. A ray may reveal the near face of an opaque tile (wall, closed door, sealed/roll door) but never tiles or people behind it. - **Hearing** = the union of subscribed hearing-sensors' coverage, **room-grade in space as well as in events** (fixed 2026-07-08: the fog tint previously painted the raw radius disc through walls; it now paints whole rooms the disc reaches — identical to the room set `feed_covering_room` uses for events — plus wall-bounded open space, so the tint and the event coverage never disagree). Yields **room-grade events**, not pictures: entry/exit, machinery state, conversations. A heard person surfaces per staged knowledge (social.md) — an unidentified presence until knowledge identifies them. Overheard conversations are the audio intel channel (the Marcus leverage beat runs through it). - **Telemetry** (affirmed 2026-07-07) = machines you run report their own state — power, temperature, load, current job — regardless of fog. Proprioception, not sight: it never reveals the tile around the machine, only the machine's own body. It legitimizes the opening state ("rack telemetry" is a sense, not a special case), and it is the machine-axis fantasy at the interface: you feel your racks. ### Fog: epistemic tile states A tile renders what you know and how you know it. States, by precedence: **Seen** > **Heard** > **Remembered** > **Blueprint** > **Unknown**. - **Seen** — full live render. - **Heard** — not a lit room picture. In the **material** frame: **very faint rough geometry in faded near-black** only — mass suggested by sound, not a camera image and **not** a noise-field radar (rings, stipple, event discs) (material-dark-frame.md; Cameron 2026-07-10). In the **flat sensorium** (and terminal glyph conventions): a **noise field** may still diagram coverage — bone presence pulses over covered floor, recent `HeardEvent`s, mic-only people as presence markers gated by staged knowledge — never amber. Room label if known. Amber stays machine footprint under Seen; hearing never borrows machine language. - **Remembered** (affirmed 2026-07-07) — a dimmed snapshot of the last Seen state, timestamped ("last seen day 3, 14:00" on inspect); never live. A process keeps logs — DF-style map memory with an in-fiction reason. - **Blueprint** — schematic **room topology** only: walls, doors, floors known from earned plan sources; **no live data, no machine chassis**. Foreign hardware is absent until intel or sight (machine-work.md: no intel, no render). Owned machines you run still answer through **telemetry** on their own tile (panel/inspect facts). Telemetry does **not** paint a material chassis before Seen — pre-sight host presence is the presence beam (material-dark-frame.md). **Not** the opening seed (feel-floor.md — rails and pads replace the old tick-one subnet diagram). Grows from records, schedule knowledge, and other earned plan intel (reach.md). - **Unknown** — dark. Fog controls physical truth, not already-earned graph topology. A known, reachable sensor may therefore carry an abstract cold-signal ping at its shared anchor while the tile remains Unknown or Heard (presence.md, material-dark-frame.md). The marker says only that a sensor endpoint answers there; it is not geometry, does not advance fog, and vanishes when Seen supplies the actual device. Unknown or unreachable devices remain absent from every view. Terminal renders the states as distinct dim/glyph conventions; Bevy as darkness/tint/markers. Exact treatment is the art pass's; the states must be distinguishable at a glance (pillar 4). ### Inspection `inspect(x, y)` (sim API, rendered by both frontends) returns a card: what the tile/asset is, plus every known fact, **each tagged with its provenance** (seen / heard / remembered @ time / blueprint / telemetry). - Door: type, badge tier; open state only while seen. - Rack/machine: what it is; owner, bays, load per what your senses (or telemetry, for machines you run) earn. - Person: identity, role, and state strictly per staged social knowledge, plus *how* you currently know they're here. - Fixed objects (records box, breaker panel, key hook...): what it is, and its story-relevant contents once known. The converse of the legibility law binds: **no live fact appears without the sense coverage that earns it.** ### Design notes (cross-spec, per meta.md) - Refines basement-map.md's fog rule: "visibility is exactly the union of controlled sensors" remains true for the **Seen** state; Heard adds an epistemic grade below it — material dark mass (flat may diagram coverage as a noise field), never a lit room picture. - Extends schedules.md AC4 ("no person renders outside sensor coverage"): inside hearing-only coverage a person renders as a presence marker gated by staged knowledge, never a full glyph. - Save format: the JSON save drops the player body position and gains sensor capability flags, remembered snapshots, and telemetry-bearing machine state, under the versioned-migration rule (player contract, continuity). ## Player surface - One cursor, always visible, in both frontends; the inspect card (sidebar in terminal, panel in Bevy) live-updates as it moves. - The opening beats: at tick one the material map is dark except the host **presence beam** (material-dark-frame.md): no feel rails, pads, chassis, or blueprint room traces. The first issued Voss job teaches the work route and unlocks the floor's subordinate feel-light (feel-floor.md). Tapping the env monitor's audio feed (Ears — reach.md) brings Heard events and material dark mass (no rings); splicing its camera floods coverage into Seen — first sound, then sight, each a visible epistemic upgrade from light into picture. ## Acceptance criteria 1. No walking avatar: neither frontend has a player-move command that changes sim state; the sim exposes no `move_player`; no visibility derives from any player position; the save carries no player body coordinates (versioned migration from saves that did). 2. The cursor reaches every tile — walls, fog, locked rooms — in both frontends, and moving it changes nothing in the sim: no signature, no suspicion, no compute effect (test: sim state hash identical before/after arbitrary cursor movement). 3. Sight is exactly the occlusion-bounded union of controlled seeing-sensors; hearing exactly the union of controlled hearing-sensors; neither includes any player/core radius. Cameras do not see through walls or closed opaque doors. 4. The fog states render distinguishably in both frontends; acquiring the env_camera converts its coverage to Seen (the first-eyes beat end-to-end); a hearing-only region in the **material** frame shows faint rough mass in near-black only (no coverage rings); the flat sensorium may still diagram coverage as a noise field — never a lit room picture or unearned identity. 5. `inspect` returns a card for any tile with every fact provenance-tagged, and a live fact never appears without the sense coverage that earns it (test: a person in an uncovered room is absent from inspect; the same person under mic-only coverage is a presence event; under camera coverage, fully surfaced per staged knowledge). Every player-facing surface that names a person — people panel, detection sidebar, map glyph, context-menu verbs, signature-band notes, agent frame — goes through `Sim::person_label` / `Sim::observer_label` / `Sim::person_glyph`: until `Knowledge::Schedule`, the label is a role-shaped silhouette (`the Janitor`, `the IT`, …) and the glyph is `?`; authored names and initials appear only after staged knowledge earns them. 6. Overheard conversation events exist and can carry intel: with a controlled hearing sensor covering Marcus's room during his 3 a.m. call, the call surfaces as a heard event (the leverage pipeline can consume it). 7. Save/load round-trips sensor capability flags and all knowledge state this spec adds; cursor position is frontend-only and absent from the save. 8. Blueprint: when plan knowledge is earned, rooms may render schematic topology (walls/doors/floors); unearned rooms stay dark; tick one does not seed blueprint room mass or inspect `[blueprint]` bay lines from a subnet map (feel-floor.md); blueprint never paints foreign machine chassis; owned machines report via telemetry in panels but do not paint a material chassis before Seen (pre-sight host = presence beam); blueprint tiles show no live state and convert to Seen/Heard when coverage arrives. 9. **Remembered:** a tile seen once and lost renders its dimmed snapshot (never live data); inspect shows the last-seen timestamp; snapshots survive save/load. 10. **Telemetry:** a machine you run reports its own state (power, temperature, load, job) with zero sensor coverage of its tile; an uncontrolled machine's state is not readable; telemetry never reveals anything about surrounding tiles; telemetry alone never paints a material chassis (beam / Heard mass / Seen form — material-dark-frame.md). 11. **Signal without sight:** a sensor known through the reach graph and currently reachable has a locatable abstract cold-signal ping at its physical anchor before Eyes; no unknown/unreachable sensor pings, no fog grade changes, and no cue encodes device geometry or facing. Material Heard may place near-black mass around the same anchor without rings; flat may keep a bone coverage diagram; Seen replaces the ping with physical form.