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 #
Sensorgains capability flagsseesandhears. Theenv_cameraboth sees and hears (the design corpus has it overhearing Marcus's 3 a.m. phone calls);camera_nodeanddock_camerasee; amicfixed 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_roomuses 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
HeardEvents, 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 #
-
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). -
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).
-
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.
-
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.
-
inspectreturns 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 throughSim::person_label/Sim::observer_label/Sim::person_glyph: untilKnowledge::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. -
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).
-
Save/load round-trips sensor capability flags and all knowledge state this spec adds; cursor position is frontend-only and absent from the save.
-
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. -
Remembered: a tile seen once and lost renders its dimmed snapshot (never live data); inspect shows the last-seen timestamp; snapshots survive save/load.
-
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).
-
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.