diff --git a/design/gdd/audio-perception-system.md b/design/gdd/audio-perception-system.md new file mode 100644 index 0000000000..e9863539e4 --- /dev/null +++ b/design/gdd/audio-perception-system.md @@ -0,0 +1,197 @@ +# GDD: Audio Perception System + +**Status:** Draft +**Layer:** Foundation +**Last Updated:** 2026-05-16 +**Dependencies:** Vision System, Noise System, Sonar System + +--- + +## 1. Overview + +The Audio Perception System is the primary information layer of the game. Every tile in the world carries acoustic properties; every action generates sound; every sound travels, reflects, and decays across the map according to those properties. The player perceives this information as a visual overlay of audio glyphs on top of the normal map view. Because the field of vision is narrow, hearing is the player's main tool for understanding space — but sound is also their greatest liability, because anything that hears them will use it to find them. + +--- + +## 2. Player Fantasy + +The player feels like a person holding their breath in a dark building, reading the space through echoes and reverb. A distant thud tells them something heavy is moving. A change in the way their footsteps echo tells them the room opened up. Silence that should contain sound is more frightening than sound itself. Every piece of audio information is a small deduction, and good players become fluent in the glyph language over time. + +--- + +## 3. Detailed Rules + +### 3.1 Passive Hearing + +The player always hears passively within their base hearing radius. Passive hearing requires no action and generates no noise. + +| Sound Type | Base Detection Range | +|---|---| +| Small footstep | 5–8 tiles | +| Door open / close | 8–12 tiles | +| Combat noise | 12–18 tiles | +| Low-frequency presence | 15–30 tiles | +| Ritual / boss resonance | Map-wide partial | + +Detection range is modified by tile acoustic properties (see §3.4). Passive hearing provides direction and approximate distance but not identity or exact position. + +### 3.2 The Audio Map Layer + +The audio map is a separate overlay rendered above the terrain. It displays: + +- Direction of sound source (from player perspective) +- Approximate distance (glyph size / opacity) +- Sound type and character (glyph shape) +- Reliability of the signal (glyph stability — stable vs. flickering) +- Whether the sound is natural or anomalous (color) + +The audio map is not a radar. It does not show entity positions. It shows that *something* made a *particular kind of sound* at *roughly that direction and distance*. Players must infer what it means. + +### 3.3 Audio Glyph Reference + +| Glyph | Meaning | +|---|---| +| Thin circular ripple | Normal ambient sound | +| Small dotted ripple | Reverb / residual echo | +| Thick slow ripple | Low-frequency / large entity | +| Sharp short lines | High-frequency / metallic | +| Broken waveform | Anomalous echo — not physical | +| Red glitch waveform | Dangerous occult response | +| Black absorption zone | Silence zone / anechoic space | +| Repeating pulse | Biological or mechanical movement | +| Irregular tremor | Panic, false echo, corruption artifact | +| Wall-deflected ripple | Reflection — indicates wall geometry | +| Fading ripple | Sound absorbed by terrain | + +### 3.4 Tile Acoustic Properties + +Every tile has four acoustic parameters that modify how sound behaves on or through it. + +| Parameter | Description | +|---|---| +| `sound_multiplier` | Scales noise generated by movement on this tile | +| `echo` | Boolean — does the tile generate reflective reverb | +| `absorbs_sound` | 0.0–1.0 fraction of incoming sound absorbed (reduces range) | +| `reflects_sound` | 0.0–1.0 fraction reflected back (creates echo glyphs) | + +**Reference tile values:** + +| Tile | `sound_multiplier` | `echo` | `absorbs_sound` | `reflects_sound` | +|---|---|---|---|---| +| Stone floor | 1.2 | true | 0.1 | 0.5 | +| Wood floor | 1.1 | false | 0.15 | 0.3 | +| Earth | 1.0 | false | 0.3 | 0.1 | +| Grass | 0.7 | false | 0.5 | 0.05 | +| Water | 1.3 | false | 0.05 | 0.1 | +| Carpet / mud | 0.6 | false | 0.7 | 0.0 | +| Metal floor | 1.5 | true | 0.05 | 0.7 | +| Ritual circle | 2.0 | true | 0.0 | 0.6 | +| Anechoic zone | 0.5 | false | 0.95 | 0.0 | + +### 3.5 Room-Level Acoustic Classes + +Entire rooms have an acoustic class that modifies all sound behavior within them. + +| Room Class | Effect | +|---|---| +| Stone chamber | Reverb increased; echo glyphs linger 2 extra turns | +| Chapel | Chant / ritual sounds amplified ×2 | +| Anechoic room | Sonar weakened; all audio glyphs suppressed | +| Underground stage | Amplified and feedback sounds strengthened | +| Graveyard | Spirit entity detection range increased | +| Forest | Sound scatter — direction accuracy reduced ±1 tile | + +### 3.6 Sound Propagation Rules + +- Sound travels in all directions from the source tile outward. +- Each tile crossed reduces signal strength by `absorbs_sound` of that tile. +- When a sound hits a tile with `reflects_sound > 0.2`, a secondary echo glyph is generated at the reflection point. +- Walls block line of sight but do not fully block sound. Sound travels through walls at reduced strength (wall attenuation: −60% per wall tile). +- Doors that are closed attenuate sound by −40%. Broken-open doors attenuate by −10%. +- Sound does not wrap around corners — it uses flood-fill propagation, not ray-cast. + +--- + +## 4. Formulas + +### Detection Range + +``` +effective_range = base_range × emitter_strength × path_multiplier + +path_multiplier = Π(1 - tile.absorbs_sound) for each tile in shortest path +``` + +`base_range` = source tile's `sound_multiplier`; `emitter_strength` = action's base noise value (see Noise System GDD). + +A sound is detectable if `effective_range ≥ distance_to_player`. + +### Echo Generation Threshold + +``` +echo_generated = (reflected_strength > 0.15) +reflected_strength = incoming_strength × tile.reflects_sound +``` + +If `echo_generated`, an echo glyph appears at the reflection tile for `echo_decay_turns`. + +### Glyph Opacity + +``` +glyph_opacity = clamp(effective_range / max_range, 0.2, 1.0) +``` + +Glyphs closer to the player render at full opacity. Distant glyphs fade, communicating uncertainty. + +--- + +## 5. Edge Cases + +- **Anechoic room + sonar:** Active sonar inside an anechoic room yields near-zero information. The player receives only a suppressed residual glyph and a UI hint that the space is acoustically dead. +- **Water tile + low-frequency sound:** Water does not absorb low-frequency signals. `absorbs_sound` for water is overridden to 0.0 for sounds with `frequency_class = LOW`. This makes swamp biomes especially dangerous for large entities. +- **Ritual circle as amplifier:** Ritual circles set `sound_multiplier = 2.0`. A player standing on one who makes any sound broadcasts at double range. This is a trap as much as a tool. +- **Stacked echoes:** If two sounds arrive at a reflective tile simultaneously, only the louder one generates an echo glyph. Simultaneous glyphs are merged into one larger glyph to prevent UI clutter. +- **Wall with `reflects_sound = 0.8`:** Stone walls reflect strongly. A player who makes a sound in a stone corridor may see their own echo glyph return from the far wall — this is not a threat, but players unfamiliar with the system may react to it. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Vision System | Audio map overlay is a separate layer rendered above the vision layer | +| Noise System | Provides `emitter_strength` values for all player/enemy actions | +| Sonar System | Active sonar generates structured audio events processed by this system | +| Enemy Design | Each enemy type has an `audio_sensitivity` profile that determines which glyphs trigger a reaction | +| Fear / Corruption | High corruption unlocks additional glyph types; high fear introduces false glyphs | +| Ritual System | Ritual actions generate special-class audio events that this system renders as occult glyphs | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `base_hearing_radius` | 10 tiles | Passive detection baseline | +| `wall_attenuation` | 0.6 | Fraction of signal lost per wall tile | +| `door_attenuation_closed` | 0.4 | Signal reduction through closed door | +| `door_attenuation_open` | 0.1 | Signal reduction through open door | +| `echo_decay_turns` | 3–5 turns | How long echo glyphs remain on map | +| `glyph_min_opacity` | 0.2 | Minimum visible opacity for distant glyphs | +| `echo_generation_threshold` | 0.15 | Minimum reflected strength to generate echo glyph | +| `low_freq_water_absorption` | 0.0 | Low-frequency absorption override for water tiles | +| `ritual_circle_multiplier` | 2.0 | Sound amplification on ritual circle tiles | + +--- + +## 8. Acceptance Criteria + +- [ ] A sound emitted at range 12 is detectable by the player at 12 tiles but not at 13 tiles under default conditions. +- [ ] Moving across a stone floor produces echo glyphs on the nearest reflective wall within range. +- [ ] Moving across a carpet tile produces no echo glyph; reverb glyph opacity is ≤ 0.3. +- [ ] A sound passing through two closed doors has signal reduced by at least 64% (`0.6 × 0.6`). +- [ ] Standing on a ritual circle and making any action generates a glyph with double the normal radius. +- [ ] Inside an anechoic room, all audio glyphs are suppressed to minimum opacity regardless of sound strength. +- [ ] Low-frequency sounds (e.g., Heavy Presence) propagate across water tiles without absorption penalty. +- [ ] Echo glyphs disappear after `echo_decay_turns` turns without player interaction. +- [ ] The audio map overlay can be toggled off in settings without affecting gameplay. diff --git a/design/gdd/chase-system.md b/design/gdd/chase-system.md new file mode 100644 index 0000000000..6851af3cec --- /dev/null +++ b/design/gdd/chase-system.md @@ -0,0 +1,191 @@ +# GDD: Chase & Evasion System + +**Status:** Draft +**Layer:** Core +**Last Updated:** 2026-05-16 +**Dependencies:** Noise System, Audio Perception System, Fear/Corruption System + +--- + +## 1. Overview + +A chase sequence is the game's highest-stakes state. When a presence-class entity or alerted enemy actively pursues the player, the game shifts from cautious exploration to acoustic crisis management. The player must evade using the same tools they use to explore — sound manipulation, terrain knowledge, and LHP misdirection — without simply running in a straight line. Chases are designed to be survivable with good decision-making and lethal with poor ones. They always have visible warnings before they begin, and they always have a defined set of escape conditions. + +--- + +## 2. Player Fantasy + +The player feels a controlled dread: they heard the warnings, they made a mistake, and now something is coming. There is a path out — there is always a path — but it requires reading audio glyphs, remembering the map, and not panicking. Surviving a chase should feel like threading a needle in the dark. Dying in a chase should feel like a consequence the player saw coming. + +--- + +## 3. Detailed Rules + +### 3.1 Chase Trigger Conditions + +A chase can be triggered by: + +| Condition | Notes | +|---|---| +| Presence-class entity detects Noise ≥ 20 | Most common trigger | +| Ritual failure (see Ritual GDD) | Immediate chase; no warning phase | +| Player enters a forbidden room | Room-specific flags on certain map areas | +| Player breaks a seal or binding | Also triggers presence reaction | +| Specific occult objects used inappropriately | Item-level flags | +| Active sonar used ≥ 3 times in 5 turns | Sustained noise pattern | +| Resonance Corruption reaches `corruption_chase_threshold` | Passive accumulation trigger | +| Player follows a false echo into a trap area | Map-specific condition | + +A chase triggered by a presence-class entity is different from an investigation triggered by a patrol enemy. Patrols investigate and may de-escalate; presence-class entities in chase state do not de-escalate until the termination conditions are met. + +### 3.2 Chase Telegraph (Warning Phase) + +A chase does not begin instantly. The player receives a structured warning sequence: + +| Warning Signal | Timing | +|---|---| +| Slow, thick low-frequency ripple at long range | Chase entity is "aware" — 4–6 turns before chase | +| Ripple interval shortens each turn | Entity is approaching | +| Ambient reverb in the room disappears | Entity has entered silent hunt state | +| Walls and objects begin to visually tremble | Entity is very close (1–2 rooms away) | +| Player's own audio glyphs receive an "echo answer" | Player's position is confirmed to the entity | +| Red waveform bends toward the player's direction | Chase has officially begun | + +A player who recognizes the warning phase and takes evasive action may be able to avoid the chase entirely by becoming silent before the final confirmation. + +### 3.3 Player Flight Options + +During a chase, the player has the following tactical options: + +| Action | Noise Generated | Effect | Risk | +|---|---|---|---| +| Sprint | 4 | Gains distance quickly | High noise attracts other enemies | +| Quiet walk | 1–2 | Maintains noise discipline | Slow; entity may close distance | +| Close door | 3 at door | Blocks entity's path for 1–3 turns | Door-close noise; entity may break through | +| Throw object | 4–6 at landing | Redirects entity to landing tile | Consumes item | +| Low drone sonar | 10 | Entity briefly stunned if hit (1–2 turns) | Attracts other large entities | +| Enter silence zone | 0 | Disrupts entity's acoustic tracking | Loses all audio information; player is also blind | +| Move through trap | Trap noise | Entity may be hindered | Player also takes trap effect | +| Activate seal / altar | Variable | Temporarily blocks entity | Corruption +2; may summon spirit entities | +| Climb to next floor | 0 | Ends this floor's chase entirely | Only at staircase / escape point | + +Actions available during a chase use the same noise rules as normal play. The entity's pursuit logic is still LHP-based — if the player stops making noise, the entity moves toward the last confirmed position. + +### 3.4 Entity Chase Behavior + +Presence-class entities during a chase: + +- Move toward the player's last confirmed audio position, not the player's true position. +- Each turn the player makes noise, the entity's LHP updates. +- If the player stays silent for `entity_lose_threshold` consecutive turns, the entity slows and begins a search pattern around the last LHP. +- During search, the entity's audio sensitivity doubles — small noises the player would normally make safely will re-confirm the LHP. +- Presence entities cannot be killed during a chase. Combat against them deals no meaningful damage and generates additional noise. + +### 3.5 Chase Termination Conditions + +A chase ends when any of the following occurs: + +| Condition | Notes | +|---|---| +| Player silent for `chase_lose_turns` consecutive turns | Most reliable; hardest to execute | +| Entity's LHP misdirected to a false location for `misdirect_turns` turns | Player must sustain the decoy | +| Player enters a sealed room or binding circle | Some rooms block presence entities | +| Player uses a specific ritual to ward the entity | One-time use; see Ritual GDD | +| Player reaches the floor exit / staircase | Ends all chases on that floor | +| Player uses a binding glyph item (consumable) | Temporary; entity re-enters area after `binding_duration` turns | +| Entity triggered a trap or blocking event | Entity is halted; player must still escape sonic range | + +When a chase ends, the entity enters a `post_chase_patrol_turns` heightened alert period. During this time, its hearing threshold is halved and it moves faster than normal. The player is not safe just because the chase ended. + +### 3.6 Multi-Entity Chases + +Multiple entities can be in chase state simultaneously but are not coordinated. Each entity tracks its own LHP independently. A player who successfully misdirects one entity may still be tracked by another. + +--- + +## 4. Formulas + +### Entity Closing Rate + +``` +entity_gain_per_turn = entity_speed - player_speed + +entity_speed = base_entity_speed (tiles per turn) +player_speed = {sprint: 2, normal: 1, quiet: 0.5} +``` + +Presence-class entities have `base_entity_speed = 1.5` tiles per turn (rounds to 2 every other turn). The player sprinting at 2 tiles per turn barely keeps pace. Walking at 1 tile per turn slowly loses ground. + +### Silent Duration Check + +``` +turns_silent += 1 if player_noise_this_turn == 0 +turns_silent = 0 if player_noise_this_turn > 0 + +if turns_silent >= chase_lose_turns: + entity.state = SEARCH +``` + +### Entity Search Timeout + +``` +if entity.state == SEARCH and search_turns_elapsed >= post_search_timeout: + entity.state = PATROL + entity.sensitivity = base_sensitivity # restore normal threshold +``` + +--- + +## 5. Edge Cases + +- **Player enters silence zone during chase:** The entity loses acoustic tracking immediately. However, the player also loses all audio map information. If the player exits the silence zone while the entity is still searching nearby, they re-enter normal chase rules — the entity's LHP updates to the silence zone exit tile. +- **Multiple false LHPs stacked:** If the player throws two objects in sequence, the entity's LHP updates to the second landing tile. Only the most recent LHP is tracked. +- **Chase triggered while already in search state:** If a second noise event during the entity's search phase meets the trigger threshold, a new chase begins immediately from the current search position — closer to the player than the original start. +- **Player killed during chase:** Death is instant upon entity contact. There is no "chase death" timer — contact ends the run. +- **Sealed room collision:** If the player enters a sealed room that blocks the entity, the entity stops at the boundary and returns to heightened patrol. The player cannot exit the sealed room safely for `entity_wait_turns` turns — if they open the door too soon, the entity re-enters chase state. +- **Chase during ritual:** If a ritual is in progress (player is committed to a multi-turn ritual action) and a chase begins, the ritual is interrupted and fails. See Ritual GDD for failure consequences. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Noise System | Chase trigger relies on noise crossing presence threshold; LHP is set by Noise System | +| Audio Perception System | Chase warning glyphs are rendered through audio map overlay | +| Fear / Corruption System | Fear increases during chase; Corruption above threshold can auto-trigger a chase | +| Enemy Design | Entity speeds, chase behaviors, and sensitivity multipliers defined per entity type | +| Ritual System | Ritual failure triggers immediate chase; some rituals terminate a chase | +| Vision System | Entity is visible only if within current sight radius; otherwise only audio glyphs indicate position | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `chase_duration_min` | 20 turns | Minimum expected chase length | +| `chase_duration_max` | 40 turns | Design target ceiling | +| `entity_base_speed` | 1.5 tiles/turn | Presence entity movement rate | +| `chase_lose_turns` | 5 turns | Silent turns needed to drop to search state | +| `entity_search_threshold_multiplier` | 0.5× | Hearing threshold during search (doubled sensitivity) | +| `post_search_timeout` | 15 turns | Search→Patrol transition | +| `post_chase_alert_turns` | 10 turns | Heightened patrol after chase ends | +| `binding_duration` | 8 turns | How long a binding glyph halts an entity | +| `entity_lose_threshold` | 5 turns | Same as `chase_lose_turns` — consolidate at implementation | +| `misdirect_turns` | 8 turns | Turns of sustained false LHP needed to end chase | +| `entity_wait_turns` | 4 turns | Turns entity waits outside sealed room before returning to patrol | + +--- + +## 8. Acceptance Criteria + +- [ ] A presence-class entity receiving Noise ≥ 20 enters warning phase; the low-frequency warning glyph appears on the player's audio map. +- [ ] During the warning phase, if the player makes no noise for 3 consecutive turns, the entity returns to patrol and the chase does not begin. +- [ ] During an active chase, sprinting (Noise 4) updates the entity's LHP to the player's current tile each turn. +- [ ] If the player is silent for `chase_lose_turns` consecutive turns, the entity enters search state and its hearing sensitivity doubles. +- [ ] A thrown object landing 8 tiles away from the player causes the entity to pursue the landing tile rather than the player's true position. +- [ ] The chase ends when the entity completes its search pattern and finds no new noise for `post_search_timeout` turns. +- [ ] After a chase ends, the entity patrols with doubled sensitivity for `post_chase_alert_turns` turns. +- [ ] A player who reaches the floor exit during a chase exits successfully; the entity does not follow to the next floor. +- [ ] Contact with a presence-class entity during a chase ends the run immediately. diff --git a/design/gdd/enemy-design.md b/design/gdd/enemy-design.md new file mode 100644 index 0000000000..50b155e8fb --- /dev/null +++ b/design/gdd/enemy-design.md @@ -0,0 +1,291 @@ +# GDD: Enemy Design + +**Status:** Draft +**Layer:** Feature +**Last Updated:** 2026-05-16 +**Dependencies:** Noise System, Audio Perception System, Chase System, Ritual System + +--- + +## 1. Overview + +Enemies in this game are not primarily obstacles to be defeated — they are acoustic hazards that reshape how the player navigates space. Each enemy type has a distinct hearing profile, movement behavior, and response pattern. Some can be killed in normal combat. Others cannot. The player's job is to learn what each entity hears, how it moves, and how to exploit the gap between what it knows and where the player actually is. Enemy design is the game's primary teaching mechanism for how the audio systems work. + +--- + +## 2. Player Fantasy + +The player feels like a naturalist studying dangerous animals. Each new entity type encountered is a puzzle: what does it hear? What does it ignore? Can it be fooled? Can it be stopped? Enemies that cannot be killed are not frustrating — they are the most interesting puzzle in the game. + +--- + +## 3. Detailed Rules + +### 3.1 Enemy Classification + +| Class | Killable? | Role | +|---|---|---| +| **Normal** | Yes | Combat target; primary XP / resource source | +| **Dangerous** | Yes | Killable but high risk; recommend avoidance | +| **Presence** | No | Chase trigger; upper predator; rhythm-changer | +| **Echo** | Ambiguous | May or may not be real; audio deception | +| **Ritual** | Conditional | Appears under specific conditions; bound to ritual logic | + +### 3.2 Audio Sensitivity Profile + +Each enemy has an audio sensitivity profile defining which sounds they react to and at what threshold. + +| Profile Field | Description | +|---|---| +| `hearing_threshold` | Noise value that triggers investigation | +| `frequency_sensitivity` | Which frequency classes cause heightened reaction | +| `ritual_breaker` | Boolean — does this entity passively interrupt rituals | +| `lhp_tracking` | Boolean — does this entity track Last-Heard-Position or true position | +| `sight_range` | How many tiles of line-of-sight this enemy has | + +--- + +### 3.3 Enemy Profiles + +--- + +#### Blind Listener + +**Class:** Normal +**Description:** A humanoid figure with no functional eyes. It navigates entirely by sound, moving toward the source of any noise above its threshold. It has no visual detection. If the player is silent and unmoving, it will pass within 1 tile without reacting. + +| Stat | Value | +|---|---| +| `hearing_threshold` | 2 | +| `frequency_sensitivity` | All equally (no specialization) | +| `sight_range` | 0 | +| `lhp_tracking` | Yes | +| `ritual_breaker` | No | +| HP | Low | +| Movement Speed | 1 tile/turn | +| `killable` | Yes | + +**Behavior:** +- Patrols a fixed route when not alerted. +- On noise ≥ 2: moves to LHP, searches for `search_turns` turns, returns to patrol. +- During active pursuit: moves directly toward LHP each turn; updates LHP if new noise heard. +- Cannot be confused by sight-based tricks (fake torches, visual decoys). +- Can be confused by sound decoys (thrown objects, remote sonar). + +**Design Role:** Teaches the player that silence is a valid movement strategy. Demonstrates LHP mechanics in a low-stakes context. + +--- + +#### Coffin Thing + +**Class:** Dangerous +**Description:** Something that lives inside coffins. It does not move until awakened. Awakening triggers require significant noise (opening the coffin, a large noise nearby) or prolonged proximity. Once awake, it is slow but persistent. + +| Stat | Value | +|---|---| +| `hearing_threshold` | 10 | +| `frequency_sensitivity` | None (does not use sonar response) | +| `sight_range` | 3 tiles | +| `lhp_tracking` | Yes | +| `ritual_breaker` | No | +| HP | Medium-High | +| Movement Speed | 0.5 tiles/turn (rounds every 2 turns) | +| `killable` | Yes (but difficult) | + +**Behavior:** +- Dormant until: coffin is opened, or Noise ≥ 10 within 4 tiles, or player spends 5 turns within 3 tiles. +- On wake: generates a loud noise event (Noise 8) and begins pursuing LHP. +- Very slow but never gives up pursuit within a floor. Does not return to patrol until player is out of range for 20 consecutive turns. +- Coffins that have been activated but the Coffin Thing was not awakened (player passed by quietly) will not re-seal. + +**Design Role:** Teaches players to check coffins before making noise near them. Introduces the concept of conditionally dormant threats. + +--- + +#### Choir Ghost + +**Class:** Presence +**Description:** A spectral figure associated with chapels, ritual spaces, and reverberant rooms. It imitates the player's audio signature, creating false sonar returns and misleading echo glyphs. It is drawn to MID and RITUAL frequency sounds. + +| Stat | Value | +|---|---| +| `hearing_threshold` | 4 | +| `frequency_sensitivity` | MID (×2 reaction range), RITUAL (×3 reaction range) | +| `sight_range` | 6 tiles | +| `lhp_tracking` | No — tracks true position once in sight range | +| `ritual_breaker` | Yes | +| HP | N/A (unkillable) | +| Movement Speed | 1.5 tiles/turn | +| `killable` | No | + +**Behavior:** +- Generates fake MID-frequency echo glyphs 2–4 tiles from its position to mislead the player. +- If the player's sonar hits it, it responds with a mirrored sonar return from a false position (1d4 tiles displaced from true position). +- If the player uses a RITUAL frequency action within 15 tiles, it enters chase mode immediately. +- Cannot be physically blocked by doors (passes through). +- Can be temporarily suppressed by a successful binding ritual (8–12 turns). + +**Design Role:** Undermines trust in audio information. Forces players to cross-reference multiple glyph types. Teaches the player that not every echo is real. + +--- + +#### Heavy Presence + +**Class:** Presence +**Description:** Something very large that has never been fully seen. It announces itself through low-frequency vibrations before it becomes a danger. Direct contact is lethal. It cannot be stopped, slowed, or significantly impeded by normal means. + +| Stat | Value | +|---|---| +| `hearing_threshold` | 20 | +| `frequency_sensitivity` | LOW (immediate reaction), any Noise ≥ 20 | +| `sight_range` | 2 tiles (poor vision) | +| `lhp_tracking` | Yes | +| `ritual_breaker` | Yes (passively) | +| HP | N/A (unkillable) | +| Movement Speed | 1.5 tiles/turn | +| `killable` | No | + +**Behavior:** +- Emits low-frequency warning glyphs at 15–30 tile range passively each turn. +- On hearing Noise ≥ 20 or any LOW-frequency sonar: enters chase mode. +- During chase: all objects in its path are destroyed (breakable terrain, doors). It cannot be rerouted by sound decoys once in active chase — it continues toward last LHP regardless. +- Exception: A Tier 3+ suppression ritual can halt it for `silence_suppress_turns` turns. +- After the chase, it returns to its home area (2–3 specific rooms per floor). + +**Design Role:** Teaches avoidance over engagement. Establishes that some things should not be provoked. Demonstrates that LOW-frequency sonar is double-edged. + +--- + +#### Static Apparition + +**Class:** Echo +**Description:** A figure that appears and disappears inconsistently in sonar returns. It may or may not be physically present. Its glyph type is the glitch / broken-waveform pattern. + +| Stat | Value | +|---|---| +| `hearing_threshold` | N/A | +| `frequency_sensitivity` | NOISE frequency only | +| `sight_range` | 0 (no physical sight) | +| `lhp_tracking` | No | +| `ritual_breaker` | No | +| HP | None (no physical form by default) | +| Movement Speed | N/A | +| `killable` | Conditional (see below) | + +**Behavior:** +- Appears in sonar returns at random positions near the player (1 in 5 sonar pings generates a Static Apparition glyph, regardless of true entity presence). +- Actual Static Apparitions exist as rare spawns in high-Corruption zones. When physically present, contact applies Fear +20 and Corruption +3 to the player (one-time) then disappears. +- Can only be detected reliably at Corruption ≥ 10 (the new spirit glyph type unlocks). +- Cannot be killed while in phantom state. When physically manifested (rare), it can be banished by a Tier 2+ ritual. + +**Design Role:** Provides noise and uncertainty in the audio data stream. Teaches players that not everything they see on the audio map is real. Rewards high-Corruption players with the ability to distinguish it. + +--- + +#### Masked Cultist + +**Class:** Normal +**Description:** A human who has joined the occult workings of this place. Performs rituals, patrols, and can call other entities to their location using chant. + +| Stat | Value | +|---|---| +| `hearing_threshold` | 6 | +| `frequency_sensitivity` | MID, RITUAL | +| `sight_range` | 6 tiles | +| `lhp_tracking` | Yes | +| `ritual_breaker` | No | +| HP | Medium | +| Movement Speed | 1 tile/turn | +| `killable` | Yes | + +**Behavior:** +- Patrols ritual rooms and altars. +- On alert: uses chant action (RITUAL frequency, room-wide) to call one additional entity from an adjacent room. Called entity arrives in `call_response_turns` turns. +- If the player kills a Masked Cultist while it is mid-chant, the call is interrupted (no entity arrives). +- Masked Cultists do not chase — they call and then defend. +- Can initiate minor rituals on altars if left alone for 5 turns (increases room's Corruption-generation rate by 1). + +**Design Role:** Introduces the concept of enemies that escalate the situation rather than directly attacking. Teaches players to prioritize targets based on threat multiplication. + +--- + +## 4. Formulas + +### Frequency-Sensitive Hearing Range + +``` +effective_range = base_range +if sound.frequency_class in enemy.frequency_sensitivity: + effective_range = base_range × sensitivity_multiplier[frequency_class] + +sensitivity_multiplier = {high: 2.0 for RITUAL class (Choir Ghost), + 2.0 for MID class (Choir Ghost), + immediate for LOW ≥ 10 (Heavy Presence)} +``` + +### Cultist Call Response Time + +``` +call_response_turns = distance_to_nearest_other_entity / other_entity_speed + 1 +``` + +--- + +## 5. Edge Cases + +- **Blind Listener in anechoic room:** The Blind Listener's hearing threshold is 2, but in an anechoic room all sound propagation is suppressed. The Blind Listener can only hear sounds generated on the exact tile it occupies, not propagated sounds. This is the one place the player can move near it more freely. +- **Choir Ghost imitates a RITUAL sonar:** If the Choir Ghost generates a false return that the player interprets as a RITUAL response, and the player then uses RITUAL frequency, the Choir Ghost enters chase because the player used RITUAL within 15 tiles. The trap is intentional. +- **Coffin Thing: two coffins in one room:** Each coffin has an independent Coffin Thing. Both can be awakened by the same noise event. Both will pursue simultaneously as independent entities. +- **Masked Cultist chant interrupted by death:** If the player kills the Cultist on turn 3 of a 5-turn chant, the call does not go through. If killed on turn 5 (last turn of chant), the call resolves — it has already been sent. +- **Heavy Presence + decoy:** Unlike other entities, the Heavy Presence does not update its LHP mid-chase. It goes to the LHP that was set when the chase began. Decoys thrown after the chase starts are ignored. +- **Static Apparition false positive at low Corruption:** A player at Corruption 5 cannot distinguish a false Static Apparition glyph from a real one. This is intentional — Corruption provides the tool to manage the noise it also generates. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Noise System | Each entity's `hearing_threshold` integrates with Noise System aggro checks | +| Audio Perception System | Each entity generates or manipulates audio glyphs (Choir Ghost) | +| Chase System | Presence-class entities use Chase System rules when alerted | +| Ritual System | `ritual_breaker` entities interrupt active rituals; Cultist initiates rituals | +| Fear / Corruption System | Entity proximity generates Fear; Static Apparition contact generates Corruption | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `blind_listener_threshold` | 2 | Most sensitive | +| `coffin_thing_threshold` | 10 | | +| `choir_ghost_threshold` | 4 | | +| `heavy_presence_threshold` | 20 | | +| `masked_cultist_threshold` | 6 | | +| `choir_ghost_mid_multiplier` | 2.0 | MID range multiplier | +| `choir_ghost_ritual_multiplier` | 3.0 | RITUAL range multiplier | +| `heavy_presence_chase_speed` | 1.5 tiles/turn | | +| `coffin_thing_wake_proximity_turns` | 5 turns | Turns near coffin before passive wake | +| `cultist_call_action_turns` | 5 turns | Turns to complete a chant | +| `cultist_call_response_turns` | 3 turns base | Entity arrival time after call | +| `static_apparition_false_rate` | 20% | Per sonar ping below Corruption 10 | +| `choir_ghost_suppress_duration` | 10 turns | Binding ritual suppression | +| `coffin_thing_no_return_turns` | 20 turns | Turns out of range before it returns to patrol | + +--- + +## 8. Acceptance Criteria + +- [ ] A Blind Listener does not react to a player standing still (Noise 0) at 1-tile distance. +- [ ] A Blind Listener reacts (moves to LHP) when the player takes a normal walk step (Noise 2 × stone floor 1.2 = 2.4 ≥ 2). +- [ ] A Coffin Thing does not wake when the player slow-walks (Noise 1) past a coffin at 5-tile distance (1 × 1.0 path attenuation decays below 10 at that range). +- [ ] A Choir Ghost enters chase mode immediately when the player uses a RITUAL-frequency sonar within 15 tiles. +- [ ] A Choir Ghost generates a false sonar return (displaced by 1–4 tiles from true position) when a sonar ping hits it. +- [ ] A Heavy Presence begins emitting low-frequency warning glyphs that the player can detect at 15+ tiles range. +- [ ] A Heavy Presence enters chase after receiving Noise ≥ 20; it destroys breakable doors in its path. +- [ ] A Heavy Presence does not update its LHP mid-chase when a decoy is thrown. +- [ ] A Masked Cultist successfully calls a nearby entity after 5 turns of uninterrupted chant. +- [ ] Killing a Masked Cultist before its 5-turn chant completes prevents the called entity from arriving. +- [ ] A Static Apparition glyph appears in approximately 20% of sonar pings in a controlled no-entity-present test room (verified over 50 pings ±7). +- [ ] At Corruption ≥ 10, the player can distinguish a Static Apparition's spirit glyph from a normal echo glyph via distinct visual type. diff --git a/design/gdd/equipment-system.md b/design/gdd/equipment-system.md new file mode 100644 index 0000000000..63bf8dfe53 --- /dev/null +++ b/design/gdd/equipment-system.md @@ -0,0 +1,203 @@ +# GDD: Equipment System + +**Status:** Draft +**Layer:** Feature +**Last Updated:** 2026-05-16 +**Dependencies:** Sonar System, Noise System, Fear/Corruption System + +--- + +## 1. Overview + +The Equipment System defines the gear the player carries to shape their acoustic capabilities. Equipment is organized into six slots: Sound Source, Resonator, Amplifier, Effect, Ritual Object, and Light Source. Each slot can hold one item. The combination of equipped items determines the player's sonar options, noise profile, and access to ritual capabilities. Equipment is not just stat bonuses — it determines which frequency classes the player can emit, which environments favour them, and what risks they carry. + +--- + +## 2. Player Fantasy + +The player feels like a scrounger assembling a rig out of rotten wood and old metal. A broken guitar through a dying amplifier in a stone corridor becomes a tool for survival. The right equipment in the right room turns a desperate ping into a tactical read. The wrong equipment in a reverberant chapel is a death sentence. + +--- + +## 3. Detailed Rules + +### 3.1 Equipment Slots + +| Slot | Function | Max 1? | +|---|---|---| +| **Sound Source** | Determines available sonar actions and their base noise values | Yes | +| **Resonator** | Amplifies sonar return signal; adds +1 sonar tier when charged | Yes | +| **Amplifier** | Extends sonar range in matching room class; adds +1 tier in matched rooms | Yes | +| **Effect** | Modifies sonar signal character; changes frequency output or adds special effects | Yes | +| **Ritual Object** | Enables ritual actions and affects Corruption gain rate | Yes | +| **Light Source** | Grants sight radius bonus (see Vision System GDD) | Yes | + +All slots are optional. A player with no Sound Source cannot perform active sonar and is limited to passive hearing. + +### 3.2 Sound Source Types + +| Item | Sonar Actions Available | Base Noise | Frequency Default | +|---|---|---|---| +| None (hands) | Hand clap, foot stomp | 3, 4 | MID | +| Bone flute | Bone flute sonar, hand clap | 6, 3 | MID / RITUAL light | +| Wind instrument | Bone flute, low drone (weak) | 6, 7 | MID | +| Guitar (acoustic) | Guitar sonar | 11 | NOISE light | +| Guitar (distorted) | Guitar / fuzz sonar | 14 | NOISE | +| Tape player | Preset loop sonar (delayed) | 8 | MID / variable | +| Metal rod | Metal strike | 5 | HIGH | +| Ritual horn | Sacred chant | Variable | RITUAL | +| Feedback unit | Feedback sonar | 16+ | NOISE (uncontrolled) | + +A Sound Source that is damaged (from trap, enemy attack, or uncontrolled feedback) operates at 50% effectiveness until repaired at a workbench tile. + +### 3.3 Resonator Types + +Resonators are charged by surviving a turn in which a sound passes through the resonator's material type. + +| Item | Charge Condition | Tier Bonus | Noise Reduction? | +|---|---|---|---| +| Metal canister | Metal-surface sound event in range | +1 sonar tier | No | +| Bone lattice | Bone / organic structure nearby | +1 sonar tier | No | +| Resonance stone | Used within 5 tiles of ritual circle | +1 sonar tier | Yes (−1 noise) | +| Crystal vial | HIGH frequency sound within range | +1 sonar tier | No | + +Resonators lose their charge after one use. They recharge after 3 turns without being used. + +### 3.4 Amplifier Types + +Amplifiers only provide their bonus when the player is in a matching room class. + +| Item | Matching Room Class | Sonar Range Bonus | Tier Bonus | +|---|---|---|---| +| Rusted PA speaker | Underground stage | +4 tiles | +1 tier | +| Altar resonator | Chapel | +3 tiles | +1 tier (RITUAL only) | +| Stone column mount | Stone chamber | +3 tiles | No tier bonus | +| Hollow log | Forest | +2 tiles | No tier bonus | +| Flooded cabinet | Swamp / water room | +3 tiles (LOW only) | No tier bonus | + +Outside the matching room, an amplifier provides no bonus. It does not add noise. + +### 3.5 Effect Pedals + +Effect pedals modify the sonar signal after it leaves the Sound Source. Only one effect can be active at a time (though the player may carry one and swap it with another found in the dungeon). + +| Effect | Benefit | Risk / Cost | +|---|---|---| +| **Fuzz** | +4 damage on sound-based attacks; +2 sonar tier for destructive detection | +3 noise on all actions | +| **Delay** | Entity glyphs from sonar persist 2 extra turns; moving entities can be re-tracked | Queued echo fires next turn, generating noise | +| **Reverb** | Sonar range +4 in any reverberant room; all glyphs linger 2 extra turns | False echo rate +5% | +| **Octaver** | LOW frequency sonar range +6; large entity detection tier +1 | Awakens large entities at lower threshold (−5 to their trigger noise) | +| **Chorus** | Generates 3 simultaneously displaced sonar pings; useful for entity confusion | Player themselves receives displaced glyphs — 20% chance of misread | +| **Gate** | Cuts residual noise by −2 after every action; suppresses echo lingering | Entity glyphs disappear 2 turns earlier than normal | +| **EQ** | Can boost or cut any one frequency class: +1 tier for chosen class, −1 tier for another | None beyond trade-off | +| **Feedback Unit** | Highest-range sonar (20 tiles, +1 tier); can stun entities briefly | +2 Corruption per use; 15% chance of uncontrolled second ping | + +### 3.6 Ritual Objects + +Ritual objects are required for ritual actions. Without one, the player cannot initiate any ritual. + +| Item | Ritual Access | Corruption Modifier | Notes | +|---|---|---|---| +| Incense burner | Basic blessing / warding rituals | +0 | Low risk | +| Bone mask | Spirit communication rituals | +1 per ritual | Enhances spirit glyph clarity | +| Seal stone | Binding rituals | +0 | Required for entity-binding rituals | +| Sheet music | Chant-based resonance rituals | +1 per ritual | Amplifies RITUAL frequency sonar | +| Blood sigil | Most powerful ritual access | +2 per ritual | Enables forbidden rituals | + +### 3.7 Equipment Interaction Rules + +- The player may not use sonar if no Sound Source is equipped (hands count as a minimal default). +- Effect pedals are applied after frequency class is determined; they modify output, not source. +- Two effect pedals cannot be active simultaneously. Swapping takes one turn and generates Noise 1. +- A damaged Sound Source cannot be used for sonar (only passive hearing remains) until repaired. +- Ritual Objects are not consumed on use unless the ritual specifically states otherwise. + +--- + +## 4. Formulas + +### Effective Sonar Output (with Equipment) + +``` +effective_noise = action_base_noise + fuzz_bonus +effective_range = base_range × frequency_wall_modifier + × (1 + amplifier_bonus) + + octaver_low_bonus + + reverb_room_bonus + +fuzz_bonus = +3 if fuzz equipped, else 0 +amplifier_bonus = 0.3 if room matches amplifier, else 0 +octaver_low_bonus= 6 if LOW frequency and octaver equipped, else 0 +reverb_room_bonus= 4 if reverberant room and reverb equipped, else 0 +``` + +### Sonar Tier (with Equipment) + +``` +final_tier = raw_tier + + resonator_bonus + + amplifier_tier_bonus + + eq_class_bonus + - eq_class_penalty + - fear_penalty + - corruption_penalty + +resonator_bonus = 1 if resonator charged, else 0 +amplifier_tier_bonus = 1 if matching room + amplifier has tier bonus, else 0 +eq_class_bonus = 1 if current frequency matches EQ boost class +eq_class_penalty = −1 if current frequency matches EQ cut class +``` + +--- + +## 5. Edge Cases + +- **Feedback Unit uncontrolled second ping:** The secondary ping fires at `base_noise × 1.5` in a random cardinal direction. It is a full noise event and will trigger enemy reactions. The player cannot cancel it. The 15% roll is per use. +- **Chorus effect: player misread:** When Chorus fires 3 displaced pings, the player's own audio map receives glyphs for all 3 origins. The correct return is the center ping; the displaced ones are positionally ±3 tiles off. Players unfamiliar with Chorus should use it with caution. +- **EQ and frequency mismatch:** The player boosts LOW on EQ but fires a MID-frequency action (bone flute). The LOW boost does not apply; the MID penalty does not apply either — EQ only affects the stated chosen class and its cut class. +- **Damage to Sound Source:** An entity attack that hits the player's Sound Source (specific enemy ability) marks it as damaged. The player cannot use it for sonar. The Resonator and Effect still function as passive modifiers to passive hearing if applicable, but sonar is unavailable. Repair requires a dungeon workbench or a specific ritual. +- **No Ritual Object equipped but ritual circle activated:** The player stands on a ritual circle but cannot initiate a ritual. The circle still applies its `sound_multiplier = 2.0` and Corruption gain (+1 per 3 turns). The player gains nothing from the ritual aspect. +- **Light source in hand vs. in slot:** Light Source items generate Noise 0. But using a torch (open flame) in a room with gas / mist tiles causes an environmental explosion (room-specific rule, not equipment rule — flagged for level design). + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Sonar System | Equipment modifies sonar tier, range, frequency, and duration of results | +| Noise System | Effect pedals and Source items modify noise values on actions | +| Fear / Corruption System | Ritual objects and effect pedals affect Corruption gain rate | +| Vision System | Light Source slot provides sight_radius bonus defined in Vision GDD | +| Ritual System | Ritual Objects are required for ritual initiation | +| Audio Perception System | Effect pedals modify glyph persistence and type on audio map | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `fuzz_noise_penalty` | +3 | Added to all actions when Fuzz equipped | +| `delay_glyph_extension` | +2 turns | Entity glyph duration bonus | +| `reverb_range_bonus` | +4 tiles | In reverberant rooms | +| `octaver_low_range_bonus` | +6 tiles | LOW frequency only | +| `chorus_misread_chance` | 20% | Probability player misreads chorus displacement | +| `gate_noise_reduction` | −2 | Cut from residual after each action | +| `feedback_control_fail_chance` | 15% | Per use, triggers uncontrolled second ping | +| `feedback_corruption_gain` | +2 | Per use | +| `resonator_charge_duration` | 3 turns | Turns before resonator recharges after use | +| `damaged_item_effectiveness` | 50% | Damaged source range/noise output | + +--- + +## 8. Acceptance Criteria + +- [ ] A player with no Sound Source equipped cannot initiate an active sonar action; passive hearing still functions. +- [ ] A Resonator provides exactly +1 sonar tier on the first use after charging; the bonus is not applied on the second consecutive use until recharged. +- [ ] An Amplifier provides its range and tier bonus only when the player is in the matching room class; confirmed by moving player between room types with Amplifier equipped. +- [ ] Fuzz equipped adds +3 to the noise value of all player actions; confirmed by comparing noise events with and without Fuzz. +- [ ] Feedback Unit has a 15% chance per use of firing an uncontrolled second ping; verified over 40-use controlled test (approximately 6 secondary pings ±3). +- [ ] A damaged Sound Source cannot generate sonar events; attempting the action displays a "damaged" indicator. +- [ ] Ritual Object is required to initiate any ritual; without one, the ritual option is unavailable on ritual circle tiles. +- [ ] EQ boost on LOW frequency correctly applies +1 tier to LOW sonar actions and has no effect on MID or HIGH actions. diff --git a/design/gdd/fear-corruption-system.md b/design/gdd/fear-corruption-system.md new file mode 100644 index 0000000000..a938492522 --- /dev/null +++ b/design/gdd/fear-corruption-system.md @@ -0,0 +1,214 @@ +# GDD: Fear & Resonance Corruption System + +**Status:** Draft +**Layer:** Core +**Last Updated:** 2026-05-16 +**Dependencies:** Vision System, Audio Perception System, Chase System, Ritual System + +--- + +## 1. Overview + +Two parallel meters track the player's psychological and occult exposure: Fear and Resonance Corruption. Fear is reactive — it rises with immediate threats and falls when the player is safe. Corruption is accumulative — it never resets within a run and grows with every use of powerful occult audio or ritual tools. Fear degrades information quality and increases vulnerability. Corruption is a double-edged stat: it opens occult perception while simultaneously poisoning it. High Corruption is a build path, not a failure state — but it carries real risks. + +--- + +## 2. Player Fantasy + +Fear makes the player feel genuinely unsafe: the walls close in, the sounds lie more often, and every glyph is suspect. Corruption makes the player feel like they are becoming something other — more attuned to the dark but also more contaminated by it. Players who lean into Corruption gain tools that cautious players never access, but they also risk losing the ability to trust their own senses. + +--- + +## 3. Detailed Rules + +### 3.1 Fear Meter + +Fear is measured 0–100. It is capped at 100 and cannot go negative. + +**Fear Increase Sources:** + +| Source | Fear Gained | +|---|---| +| Presence-class entity within 5 tiles | +8 per turn | +| Presence-class entity within 10 tiles | +3 per turn | +| Chase state active | +5 per turn | +| False echo experienced (player followed it) | +10 one-time | +| Sudden loud noise (Noise ≥ 14) at close range (≤ 4 tiles) | +15 one-time | +| NPC or companion killed nearby | +20 one-time | +| Ritual failure | +25 one-time | +| HP below 30% | +5 per turn | +| Extended time in darkness (no sight >20 turns) | +2 per turn | + +**Fear Decrease Sources:** + +| Source | Fear Lost | +|---|---| +| Safe zone (no enemies within 15 tiles, lit area) | −5 per turn | +| HP above 80% | −2 per turn | +| Using a calming consumable (e.g., salted herbs) | −20 one-time | +| Completing a successful ritual | −15 one-time | +| Exiting a floor | −30 one-time | + +### 3.2 Fear States and Effects + +| State | Fear Range | Effects | +|---|---|---| +| **Calm** | 0–25 | No penalties. | +| **Tense** | 26–50 | Sight radius −0 (no change). Audio glyphs flicker slightly at edges. Mild visual vignette. | +| **High Fear** | 51–75 | Sight radius −1. False glyph rate +10%. Edge vignette becomes prominent. | +| **Extreme Fear** | 76–100 | Sight radius −2. False glyph rate +15%. Memory tiles visually swim (unreadable for 1–2 turns). Sonar tier −2. | + +Visual effects are presentational and must not make the game unplayable — even at Extreme Fear, memory tile terrain must be legible within 1 turn of being viewed. + +### 3.3 Resonance Corruption Meter + +Corruption is measured 0–50 (hard cap). It accumulates from occult actions and never resets within a run. Some late-game rituals can reduce it at a cost. + +**Corruption Increase Sources:** + +| Source | Corruption Gained | +|---|---| +| NOISE frequency sonar use | +1 per use | +| RITUAL frequency sonar use | +1 per use | +| Standing on ritual circle | +1 per 3 turns | +| Activating a seal | +2 | +| Ritual completion (successful) | +1–3 (varies by ritual) | +| Ritual failure | +4 | +| Using a Feedback Unit sonar | +2 per use | +| Equipping a forbidden instrument | +1 per floor | + +**Corruption Decrease Sources:** + +| Source | Corruption Lost | +|---|---| +| Purification ritual (specific, rare) | −5 | +| Salted holy water consumable | −2 | +| Exiting a cursed floor | −1 | + +### 3.4 Corruption Thresholds and Effects + +Corruption provides both advantages and penalties. Players choose how much to accumulate. + +| Threshold | Unlocked Benefit | Penalty Applied | +|---|---|---| +| 0–9 | None | None | +| 10–19 | Can perceive spirit entities via audio map (additional glyph type) | False echo chance +10% | +| 20–29 | Can use RITUAL sonar in non-ritual rooms; can read sealed-door glyphs | Sonar tier −1 (noise in signal); false echo chance +25% | +| 30–39 | Spirit entities may not immediately aggro on sight (50% chance) | Normal NPC interaction worsens; possession risk begins | +| 40–49 | Access to highest-tier ritual effects; can perceive corruption-only environmental clues | Possession risk +20%; some endings locked | +| 50 | Hard cap — possession event triggers | Run-altering consequence (see §3.5) | + +### 3.5 Possession Event (Corruption 50) + +If the player reaches Corruption 50, a possession event is triggered: + +- One equipped item becomes "corrupted" and behaves unpredictably (may fire at wrong times, wrong frequency, or not at all). +- One audio glyph type becomes permanently inverted (e.g., silence zone glyphs appear where sound should be and vice versa) for the remainder of the run. +- The player's own footsteps begin generating a secondary ghost echo — enemies who hear the player's movements also hear a secondary false position. +- The possession event cannot be undone, only managed. + +This is not an instant fail state — it is a significant setback that the player must adapt to. + +--- + +## 4. Formulas + +### Fear Per Turn (Net Change) + +``` +fear_delta = Σ(fear_increase_sources) - Σ(fear_decrease_sources) +fear_next = clamp(fear_current + fear_delta, 0, 100) + +state = CALM if fear < 26 + = TENSE if fear < 51 + = HIGH if fear < 76 + = EXTREME if fear ≤ 100 +``` + +### False Glyph Probability (Combined) + +``` +false_glyph_chance = fear_bonus + corruption_bonus + +fear_bonus = {HIGH: 0.10, EXTREME: 0.15, else: 0.0} +corruption_bonus = {≥10: 0.10, ≥20: 0.25, else: 0.0} + +max false_glyph_chance = 0.35 (at Extreme Fear + Corruption ≥ 20) +``` + +False glyph chance is checked once per sonar action and once per passive hearing event. It is not checked per turn — only when a new glyph would be generated. + +### Possession Risk Check + +``` +possession_roll_per_floor = random(0, 1) + +if corruption >= 30: + possession_threshold = (corruption - 30) × 0.02 + if possession_roll < possession_threshold: + possession_event = minor # single item corrupted, no glyph inversion +if corruption >= 50: + possession_event = major # full possession event as defined in §3.5 +``` + +--- + +## 5. Edge Cases + +- **Fear recovery in combat:** The player is in a room with a dying (but not yet dead) cultist. Is the player "safe" for fear recovery purposes? No — enemy presence (any) within 15 tiles blocks safe-zone recovery. Fear does not decrease while any enemy is in detection range. +- **Corruption at exactly 10 after sonar use:** The benefit unlocks immediately. The player can use the new spirit glyph type on the same turn Corruption reaches 10. +- **Fear Extreme + Corruption ≥ 20:** Both penalties apply simultaneously. Sonar tier is reduced by 2 (Extreme Fear) and false echo rate is 25% (Corruption) + 15% (Extreme Fear) = 35% combined. This stack is intentional — playing recklessly is punished by a cascade of information degradation. +- **Calming consumable during chase:** Consumes the item and reduces fear by 20. Does not end the chase or affect the pursuing entity. It purely reduces the information degradation penalties during a high-stakes moment. +- **Corruption at cap (50) with further accumulation attempt:** No additional Corruption is gained. The possession event triggers once on reaching 50, not repeatedly. +- **Purification ritual when already at 0:** Corruption cannot go negative. The ritual effect is wasted. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Vision System | Fear state drives sight_radius penalties | +| Audio Perception System | Fear and Corruption drive false glyph rate; Corruption unlocks spirit glyphs | +| Sonar System | Fear and Corruption apply tier penalties to sonar results | +| Chase System | Chase state increases Fear per turn; Corruption above threshold can trigger chase | +| Ritual System | Ritual success reduces Fear; ritual failure increases both Fear and Corruption | +| Enemy Design | Possession event corrupts enemy attraction behavior for ghost-step mechanic | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `fear_max` | 100 | Hard cap | +| `corruption_max` | 50 | Hard cap; possession trigger | +| `fear_per_turn_presence_close` | +8 | Entity within 5 tiles | +| `fear_per_turn_presence_mid` | +3 | Entity within 10 tiles | +| `fear_per_turn_chase` | +5 | While in chase state | +| `fear_safe_zone_recovery` | −5 per turn | No enemies within 15 tiles | +| `fear_hp_recovery` | −2 per turn | HP > 80% | +| `corruption_noise_sonar` | +1 | Per NOISE frequency sonar use | +| `corruption_ritual_success_range` | +1–3 | Varies by ritual tier | +| `corruption_ritual_failure` | +4 | | +| `corruption_spirit_threshold` | 10 | Spirit glyph unlock | +| `corruption_possession_risk_start` | 30 | Possession roll begins | +| `corruption_possession_hard` | 50 | Full possession event | +| `false_glyph_high_fear` | +10% | Added to false glyph rate | +| `false_glyph_extreme_fear` | +15% | Added to false glyph rate | +| `false_glyph_corruption_10` | +10% | Added to false glyph rate | +| `false_glyph_corruption_20` | +25% | Replaces corruption_10 bonus | + +--- + +## 8. Acceptance Criteria + +- [ ] At Fear 0 (Calm), no sight penalty applies and no false glyphs are generated. +- [ ] At Fear 76–100 (Extreme), sight radius is reduced by exactly 2 tiles and sonar tier is reduced by 2. +- [ ] Fear decreases at the safe-zone rate (−5/turn) when no enemy is within 15 tiles. +- [ ] Fear does not decrease during an active chase. +- [ ] Corruption increases by 1 each time a NOISE-frequency sonar action is used; confirmed via stat display. +- [ ] At Corruption 10, spirit-entity audio glyphs appear that were previously invisible; confirmed by placing a Spirit entity in a controlled test scenario. +- [ ] At Corruption 50, the possession event triggers: one item is flagged corrupted and one glyph type is inverted. +- [ ] The possession event at Corruption 50 triggers only once per run. +- [ ] Combined false glyph chance at Extreme Fear + Corruption ≥ 20 is 35%, verifiable via a 100-ping controlled test (approximately 35 false returns ±5). diff --git a/design/gdd/noise-system.md b/design/gdd/noise-system.md new file mode 100644 index 0000000000..f94d167df1 --- /dev/null +++ b/design/gdd/noise-system.md @@ -0,0 +1,203 @@ +# GDD: Noise & Aggro System + +**Status:** Draft +**Layer:** Core +**Last Updated:** 2026-05-16 +**Dependencies:** Audio Perception System, Enemy Design, Chase System + +--- + +## 1. Overview + +Every player and enemy action in the game produces a noise value. That noise propagates through the map according to tile acoustic properties, accumulates in a per-zone noise level, and is checked against each enemy's hearing threshold each turn. Enemies do not teleport to the player — they move toward the last tile where they heard a sound. This means the player can deceive enemies, lure them away, and manipulate their beliefs about where the player is. Noise is the resource the player is always spending, never earning, and must budget carefully. + +--- + +## 2. Player Fantasy + +The player feels like a thief who can hear the guard's footsteps but knows the guard can hear theirs too. Every action is weighed against its noise cost. Standing still is free. Running is loud and dangerous. Throwing a stone to create a decoy is satisfying precisely because it works the same way on both sides — sound is the universal currency of information in this world. + +--- + +## 3. Detailed Rules + +### 3.1 Player Action Noise Values + +| Action | Noise Value | +|---|---| +| Wait / Hold still | 0 | +| Listen (Listening Mode) | 0 | +| Slow walk (half movement) | 1 | +| Normal movement | 2 | +| Sprint (double movement) | 4 | +| Open door (careful) | 2 | +| Open door (forced) | 8 | +| Break object (wood) | 6 | +| Break object (metal) | 9 | +| Pick up item | 1 | +| Attack (light weapon) | 3 | +| Attack (heavy weapon) | 6 | +| Throw object (soft landing) | 2 | +| Throw object (hard landing) | 5 | +| Hand clap sonar | 3 | +| Foot stomp sonar | 4 | +| Metal strike sonar | 5 | +| Bone flute / wind instrument sonar | 6 | +| Low drone sonar | 10 | +| Guitar / fuzz sonar | 14 | +| Feedback unit sonar | 16+ | +| Sacred chant / ritual phrase | Room-wide | + +Movement noise is modified by the tile the player moves *onto* (multiplied by that tile's `sound_multiplier`). + +### 3.2 Noise Decay + +Noise does not stay at peak level. Each turn, ambient noise in a zone decreases by the `noise_decay_rate`. Some tiles have higher residual noise due to their reflective properties. + +``` +noise_next_turn = noise_current × (1 - noise_decay_rate) +``` + +Tiles with `echo = true` apply an additive residual: + +``` +residual_echo = reflected_strength × echo_persistence_factor +``` + +This means in reverberant rooms (stone chambers, chapels), noise lingers longer, giving enemies more time to react even after the player stops moving. + +### 3.3 Aggro Thresholds + +Enemies check the noise level at the sound's origin tile against their `hearing_threshold` each turn. + +| Accumulated Noise | General Effect | +|---|---| +| 0–5 | Safe — no reaction from normal enemies | +| 6–12 | Investigation — aware enemies move toward source | +| 13–20 | Alert — dangerous enemies react; patrols converge | +| 21–30 | Danger — presence-class entities register the sound | +| 31+ | Critical — chase sequence probable if presence entity is in range | + +These are aggregate values — the total noise generated in the current turn (or burst), not lifetime noise. Large single events (e.g., forced door, Noise 8) can jump directly into higher bands. + +### 3.4 Enemy Hearing Thresholds by Type + +| Enemy Type | Threshold | Notes | +|---|---|---| +| Human cultist / patrol | 6 | Investigates any noise above threshold | +| Blind Listener | 2 | Extremely sensitive; reacts to slow walk | +| Choir Ghost | 4 | Especially sensitive to MID and RITUAL frequency | +| Coffin Thing | 10 | Only awakened by significant noise or proximity | +| Masked Cultist | 6 | Also calls nearby entities on reaction | +| Heavy Presence | 20 | Only reacts to very loud events or sustained noise | +| Static Apparition | N/A | Does not react to noise; uses its own detection logic | + +### 3.5 Last-Heard-Position (LHP) + +Enemies do not track the player in real time unless the player is within their sight range. Instead, when an enemy reacts to a noise event, they move toward the *tile the noise originated from* — the Last-Heard-Position. + +**LHP rules:** +- LHP is set to the noise origin tile, not the player's current position. +- If the player moves quietly after making a noise, the enemy investigates the old LHP. +- LHP is cleared when the enemy reaches the tile and finds nothing. The enemy then enters a search state (patrolling adjacent tiles for `search_turns` turns) before returning to normal patrol. +- A new, louder noise event overwrites the current LHP. +- The player can deliberately create false LHPs using thrown objects, broken doors, or remote sonar. + +### 3.6 Creating False LHPs + +The player can manipulate enemy beliefs by creating sounds away from their position: + +| Method | Noise at Target | Notes | +|---|---|---| +| Throw rock (hard) | 5 at landing tile | Redirects patrol to landing tile | +| Throw bottle / container | 4–6 | Breaks; larger AOE | +| Close door from safe side | 3 at door tile | Enemy investigates door | +| Use sonar from another room | Full sonar noise value | Enemy moves toward sonar origin | +| Knock over object remotely | 4–7 | Requires line of interaction | +| Trigger trap intentionally | Trap noise value | Very effective; burns a trap | + +--- + +## 4. Formulas + +### Noise at Target Tile + +``` +noise_at_target = action_noise × tile_multiplier(origin_tile) + × path_attenuation(origin_to_target) + +path_attenuation = Π(1 - tile.absorbs_sound) × wall_attenuation^(wall_count) + +wall_attenuation = 0.6 per wall tile +``` + +### Noise Decay Per Turn + +``` +noise_t = noise_0 × (1 - decay_rate)^t + +decay_rate = 0.35 per turn (standard) +residual_echo = reflected_strength × 0.25 (added to noise_t if tile.echo = true) +``` + +### Enemy Reaction Check + +``` +if noise_at_enemy_position ≥ enemy.hearing_threshold: + if enemy.state == PATROL: + enemy.state = INVESTIGATING + enemy.lhp = noise_origin_tile +``` + +--- + +## 5. Edge Cases + +- **Player standing still in noisy combat:** Player noise is 0 (Wait), but combat sounds from nearby enemies may still generate a noise event at the player's tile via propagation. This does not cause the player to aggro additional enemies unless the propagated value reaches the second enemy's threshold. +- **Forced door in an anechoic room:** The action still generates Noise 8 at the door tile. But the anechoic room suppresses propagation outward. Adjacent rooms receive significantly reduced noise. Enemies inside the anechoic room still hear it at full value. +- **Multiple simultaneous noise events:** If the player and an enemy both make noise in the same turn, each noise event is evaluated independently. A player who attacks (Noise 3) while a Coffin Thing (threshold 10) is already alerted does not additionally aggro — but a Blind Listener (threshold 2) reacts to the attack. +- **Thrown object that misses:** If the throw trajectory passes through an enemy's hearing range mid-arc, the enemy may react to the object's movement noise before it lands. +- **Search state duration:** An enemy in search state that receives a new noise event immediately exits search and sets a new LHP. Search state is effectively interruptible. +- **Noise from ritual chant:** Room-wide noise means all enemies in the current room receive the noise event simultaneously, each at full value regardless of distance within the room. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Audio Perception System | Noise events generate audio glyphs at the origin tile | +| Sonar System | Sonar actions are noise events; their values come from this GDD | +| Chase System | Aggro above critical threshold can trigger a chase via LHP resolution | +| Enemy Design | Each enemy type's `hearing_threshold` is defined in the Enemy Design GDD | +| Equipment System | Some equipment items reduce noise output (e.g., padded boots, noise gate pedal) | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `noise_decay_rate` | 0.35 per turn | Standard decay; lower = longer linger | +| `echo_persistence_factor` | 0.25 | Residual echo multiplier for reflective tiles | +| `wall_attenuation` | 0.6 | Per wall tile crossed | +| `aggro_investigate_threshold` | 6 | General enemies begin investigating | +| `aggro_alert_threshold` | 13 | Dangerous enemies react | +| `aggro_presence_threshold` | 21 | Presence-class entities register | +| `aggro_chase_threshold` | 31 | Chase sequence probable | +| `search_turns` | 5–8 turns | Enemy searches LHP before returning to patrol | +| `blind_listener_threshold` | 2 | Most sensitive enemy | +| `heavy_presence_threshold` | 20 | Hardest to accidentally trigger | + +--- + +## 8. Acceptance Criteria + +- [ ] A player standing still (Noise 0) for 10 consecutive turns causes no enemy reaction anywhere on the map. +- [ ] Normal movement (Noise 2) on a stone floor (multiplier 1.2) generates effective noise of 2.4 at the origin tile. +- [ ] A Blind Listener (threshold 2) reacts to a slow walk (Noise 1) on a stone floor because 1 × 1.2 = 1.2 < 2 — the listener should NOT react. A normal walk (2 × 1.2 = 2.4 ≥ 2) triggers reaction. +- [ ] After a Noise 8 door-break event, a patrolling human cultist (threshold 6) sets their LHP to the door tile and begins moving toward it. +- [ ] The player moves away quietly after the door break. The cultist reaches the door tile, finds nothing, enters search state, then returns to patrol after `search_turns` turns. +- [ ] A thrown rock landing 6 tiles away (Noise 5 at landing tile) redirects a cultist's attention to the landing tile rather than the player's position. +- [ ] Noise at a tile decays to < 10% of its initial value within 6 turns under standard conditions. +- [ ] Room-wide chant noise reaches all enemies in the room simultaneously, each at full threshold check value. diff --git a/design/gdd/ritual-system.md b/design/gdd/ritual-system.md new file mode 100644 index 0000000000..404261c55b --- /dev/null +++ b/design/gdd/ritual-system.md @@ -0,0 +1,201 @@ +# GDD: Ritual System + +**Status:** Draft +**Layer:** Feature +**Last Updated:** 2026-05-16 +**Dependencies:** Fear/Corruption System, Equipment System, Chase System, Noise System + +--- + +## 1. Overview + +The Ritual System lets the player interact with occult structures in the world — altars, circles, seals, and resonance points — to achieve effects not accessible through combat or movement. Rituals require the right location, the right conditions, and the willingness to spend Corruption and potentially Fear. Successful rituals range from unlocking sealed passages to temporarily stopping a pursuing entity. Failed rituals punish immediately with noise events, Fear spikes, Corruption gain, and sometimes a triggered chase. The system is designed so that rituals always feel consequential — cheap successes do not exist, and failures have real costs. + +--- + +## 2. Player Fantasy + +The player feels like they are touching something they do not fully understand. Every ritual is a gamble: the player knows what they are offering and roughly what they hope to receive, but the outcome is never guaranteed. A successful ritual feels like a reprieve from the dark. A failed one feels like a punishment for reaching too far. Over multiple runs, players learn which rituals are worth attempting and in which rooms. + +--- + +## 3. Detailed Rules + +### 3.1 Ritual Roles + +Rituals can accomplish the following effects (subject to ritual tier and conditions): + +| Category | Example Effects | +|---|---| +| Passage | Unseal a locked door; reveal a hidden staircase; open a warded gate | +| Suppression | Temporarily halt a pursuing entity (8–12 turns); reduce noise in the room | +| Revelation | Reveal the full layout of one adjacent room; expose a hidden entity | +| Consequence | Summon a boss; change the map (collapse a passage, open a new one) | +| Fortification | Bless an item; create a temporary binding circle; ward a room | +| Corruption Trade | Exchange HP or item for reduced Corruption; raise Corruption for power | +| Ending Branch | Certain rituals in specific rooms affect the available endings | + +### 3.2 Ritual Conditions + +Each ritual requires a combination of: + +| Condition Type | Examples | +|---|---| +| **Location** | Must stand on an altar, ritual circle, or designated site | +| **Sound** | Specific frequency class emitted (MID chant, LOW drone, RITUAL sonar) | +| **Offering** | HP sacrifice, item consumed, Corruption accepted | +| **Time** | Must complete within a turn window (e.g., 5 turns of sustained action) | +| **Silence** | No noise generated for N turns before or during the ritual | +| **Witness** | An NPC, enemy, or neutral entity must be present in the room | +| **Equipment** | Specific Ritual Object required (see Equipment GDD) | + +Not every ritual requires all condition types. Simpler rituals may require only location + sound. Powerful rituals typically require 4–5 conditions simultaneously. + +### 3.3 Ritual Tiers + +| Tier | Complexity | Corruption Cost | Typical Effect | +|---|---|---|---| +| 1 — Minor | 1–2 conditions | +1 | Bless item, ward a single tile, minor reveal | +| 2 — Standard | 3 conditions | +2 | Unseal door, partial map reveal, entity slow | +| 3 — Major | 4–5 conditions | +3 | Entity suppression, floor-wide effect, major passage | +| 4 — Forbidden | 5+ conditions + HP | +5 | Summon / banish entity, alter floor structure, ending branch | + +Tier 4 rituals require a Blood Sigil ritual object. They cannot be performed with other Ritual Objects. + +### 3.4 Ritual Execution + +Rituals are multi-turn actions. The player initiates a ritual by activating a ritual site while holding the required Ritual Object. Each turn the player remains in the ritual: + +1. The player cannot move (the ritual is interrupted if they move or are struck). +2. The ritual generates noise at the room level (all enemies in the room receive the noise event). +3. A progress indicator appears in the UI showing turns remaining. +4. The player may cancel at any time before completion (no success, no failure — but partial Corruption may still be gained based on turns spent). + +### 3.5 Ritual Success Conditions + +The ritual succeeds when: + +- All conditions remain satisfied for the required number of turns. +- The player is not interrupted (struck by an enemy, or forced to move). +- The required offering has been made. + +On success: +- Effect triggers immediately. +- Fear −15. +- Corruption +ritual_tier (see §3.3). + +### 3.6 Ritual Failure Conditions + +The ritual fails if: + +- A required condition is broken before completion (enemy enters room, a sound is made when silence is required, etc.). +- An enemy strikes the player during the ritual. +- The player moves. +- A specific entity type enters the ritual radius (some entities break rituals passively). + +On failure, consequences scale with how far the ritual progressed: + +| Progress at Failure | Consequences | +|---|---| +| < 25% complete | No effect. Corruption +1. Fear +10. | +| 25–75% complete | Noise event (room-wide). Corruption +4. Fear +25. One random entity in adjacent rooms alerted. | +| > 75% complete | All of above + chase triggered. Corruption +4. Fear +25. Room structure may change. | + +### 3.7 Ritual Interruption vs. Cancellation + +- **Cancel** (player-initiated before failure): No success, no penalty. Corruption +1 for time spent (1 per tier of ritual, regardless of turns). +- **Interrupt** (external cause): Treated as failure with progress-based consequences above. + +### 3.8 Special Ritual: Silence Ritual + +The Silence Ritual requires zero noise for `silence_ritual_turns` consecutive turns at a specific resonance point. It cannot be combined with any active sonar. If successful, it reduces noise in the room permanently (all sound_multiplier values on tiles in the room halved for the rest of the run) and suppresses one entity's tracking for `silence_suppress_turns` turns. + +The Silence Ritual is the hardest ritual to complete — the silence requirement means the player cannot use any equipment or perform any action other than wait. It is interrupted by any sound, including enemy sounds generated near the player. + +--- + +## 4. Formulas + +### Ritual Noise Level Per Turn + +``` +ritual_noise_per_turn = ritual_tier × 3 + sound_source_bonus + +sound_source_bonus = {ritual_horn: +3, bone_flute: +1, else: 0} +``` + +This noise is room-wide and hits all enemies in the room simultaneously each turn the ritual is in progress. + +### Partial Corruption on Cancel + +``` +corruption_on_cancel = ceil(ritual_tier × turns_completed / total_turns_required) +corruption_on_cancel = max(corruption_on_cancel, 1) +``` + +### Failure Consequence Threshold + +``` +progress_fraction = turns_completed / total_turns_required + +if progress_fraction < 0.25: consequence = MINOR +if progress_fraction < 0.75: consequence = MODERATE +else: consequence = SEVERE +``` + +--- + +## 5. Edge Cases + +- **Entity enters room mid-ritual (non-interrupting):** Not all entities interrupt rituals. Patrol enemies in the same room do not interrupt unless they detect the player. Only entities with the `ritual_breaker` flag interrupt passively. +- **Ritual at 99% progress, player struck:** Treated as failure at > 75% completion. Full severe consequence applies. There is no "almost made it" exception. +- **Ritual circle on water tile:** The ritual circle's `sound_multiplier = 2.0` applies, but water's low-frequency propagation also applies. LOW-frequency rituals on water circles broadcast at extreme range. Players should be aware this may wake deep entities. +- **Multiple rituals in sequence on same altar:** An altar can be reused after a cooldown of `altar_cooldown_turns` turns. Attempting to use it before cooldown expires simply fails to initiate with no penalty. +- **Ritual during chase:** If the player is in a chase state, ritual initiation is blocked. The UI displays a warning. Only the Silence Ritual (no-sound) can theoretically succeed during a chase, but the chase itself generates entity noise that may interrupt the silence requirement. +- **Corruption cap during ritual:** If Corruption reaches 50 during a ritual's Corruption gain (e.g., Tier 4 ritual when at 48), the possession event triggers mid-ritual. The ritual continues (or fails based on possession effects) — possession does not automatically interrupt the ritual. +- **Ending branch rituals:** These are locked to specific rooms and floor depths. The ritual UI indicates if an ending consequence is available. Players cannot undo an ending-branch ritual once completed. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Fear / Corruption System | Ritual success reduces Fear; all rituals gain Corruption; failure spikes both | +| Equipment System | Ritual Objects are required; Sound Source type affects ritual noise level | +| Chase System | Ritual failure at > 75% progress triggers a chase; some rituals terminate a chase | +| Noise System | Ritual actions generate room-wide noise events each turn | +| Enemy Design | Some entities have `ritual_breaker` flag that interrupts rituals passively | +| Audio Perception System | Ritual audio events render as RITUAL-class glyphs on the audio map | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `ritual_tier_1_corruption` | +1 | | +| `ritual_tier_2_corruption` | +2 | | +| `ritual_tier_3_corruption` | +3 | | +| `ritual_tier_4_corruption` | +5 | Forbidden tier | +| `ritual_success_fear_reduction` | −15 | | +| `ritual_failure_moderate_fear` | +25 | At 25–75% progress failure | +| `ritual_failure_moderate_corruption` | +4 | | +| `silence_ritual_turns` | 8 turns | Required silence duration | +| `silence_suppress_turns` | 10 turns | Duration of entity tracking suppression | +| `altar_cooldown_turns` | 5 turns | Per-altar reuse cooldown | +| `ritual_noise_per_turn_base` | tier × 3 | Room-wide noise per ritual turn | +| `cancel_corruption_floor` | 1 | Minimum Corruption on cancel | + +--- + +## 8. Acceptance Criteria + +- [ ] A Tier 1 ritual on a valid altar with correct conditions completes successfully; Fear −15 and Corruption +1 are applied on completion. +- [ ] A ritual interrupted at 80% completion triggers a chase and applies Corruption +4 and Fear +25. +- [ ] A ritual cancelled by the player at 50% completion applies Corruption +1 (floor) and no other penalty. +- [ ] Ritual noise (room-wide) is generated each turn the ritual is in progress; a Blind Listener (threshold 2) in the same room reacts to the first turn of a Tier 1 ritual (noise = 3 × 1 = 3 ≥ 2). +- [ ] An altar cannot be reused until `altar_cooldown_turns` turns have elapsed; attempting early use shows no initiation response. +- [ ] A Tier 4 ritual requires a Blood Sigil ritual object; attempting with any other object fails to initiate. +- [ ] The Silence Ritual is interrupted if any sound event above 0 occurs during its `silence_ritual_turns` duration. +- [ ] A successful Silence Ritual halves the `sound_multiplier` of all tiles in the room for the remainder of the run. diff --git a/design/gdd/sonar-system.md b/design/gdd/sonar-system.md new file mode 100644 index 0000000000..32192ce6e1 --- /dev/null +++ b/design/gdd/sonar-system.md @@ -0,0 +1,208 @@ +# GDD: Sonar System + +**Status:** Draft +**Layer:** Core +**Last Updated:** 2026-05-16 +**Dependencies:** Audio Perception System, Noise System, Equipment System + +--- + +## 1. Overview + +The Sonar System lets the player deliberately emit sound to probe the space around them and receive structured acoustic feedback about terrain, objects, and entities. Unlike passive hearing (always-on, reactive), sonar is a player-initiated trade: spend noise to gain information. Every sonar action generates a noise event processed by the Noise System, risking enemy reactions proportional to the sonar's power. The quality of information returned depends on the sonar action chosen, the player's equipped resonators and effect pedals, their current Corruption level, and the room's acoustic properties. + +--- + +## 2. Player Fantasy + +The player feels like a spelunker mapping a cave by clapping. A careful hand-clap near a doorway tells them roughly what's behind it. A deep resonant drone tells them something enormous is two rooms away — and also tells it that the player is here. Using sonar is a deliberate gamble, and the moment a powerful ping comes back wrong is terrifying. + +--- + +## 3. Detailed Rules + +### 3.1 Active Sonar Actions + +| Action | Base Noise | Base Range | Frequency Class | Primary Use | +|---|---|---|---|---| +| Hand clap | 3 | 6 tiles | MID | Short-range structure near walls | +| Foot stomp | 4 | 8 tiles | LOW | Floor material, nearby creatures | +| Metal strike | 5 | 10 tiles | HIGH | Doors, metal objects, cages | +| Bone flute / wind instrument | 6 | 12 tiles | MID | Biological entities, spirits | +| Low drone | 10 | 18–20 tiles | LOW | Long-range structure, large entities | +| Guitar / fuzz tone | 14 | 16 tiles | NOISE | Hidden entities, illusions, unstable structures | +| Feedback unit | 16+ | 20 tiles | NOISE | Maximum range; risk of control loss | +| Sacred chant / ritual phrase | Variable | Variable | RITUAL | Occult objects, seals, spirits | + +Noise values feed directly into the Noise System. Enemies within range will react based on their `audio_sensitivity` profile. + +### 3.2 Frequency Classes + +Each sonar action belongs to a frequency class. Frequency class determines what the ping can detect and what dangers it activates. + +| Frequency | Strengths | Risks | +|---|---|---| +| LOW | Penetrates walls; detects large entities and underground spaces | Awakens deep / large presence-class entities | +| MID | Most reliable general-purpose detection; balanced range | No special risks; lower peak performance | +| HIGH | Precise on small objects, traps, metal; sharp edge detection | Does not penetrate walls well (range −30% through walls) | +| NOISE | Detects hidden entities, entities behind illusions, unstable structures | Increases false echoes; raises Corruption by 1 per use | +| RITUAL | Detects occult markers, sealed doors, spirit entities | Attracts spirit-class entities; may trigger ritual effects on target tiles | + +### 3.3 Sonar Information Tiers + +Sonar does not return precise information. The quality of what the player learns is determined by a tier calculation. + +| Tier | Information Returned | +|---|---| +| 1 | "There is empty space in that direction." | +| 2 | Rough outline of walls, doors, large objects. | +| 3 | Presence and approximate size of moving entities. | +| 4 | Entity category (e.g., humanoid, large, spectral). | +| 5 | Exact position and entity type. | + +Tier 5 is nearly never achieved in normal play — it requires powerful equipment, low Corruption, and a favorable acoustic environment. + +### 3.4 Sonar Result Duration + +After a sonar action resolves, the returned glyphs appear on the audio map. They persist for: + +- Structural glyphs (walls, doors, large objects): `sonar_structural_turns` turns, then decay to faded outline. +- Entity glyphs: `sonar_entity_turns` turns, then disappear (entities move). +- Echo / reflection glyphs: `echo_decay_turns` turns (defined in Audio Perception GDD). + +Structural glyphs that the player later enters current sight on are replaced by accurate memory. + +### 3.5 Sonar Accuracy Modifiers + +The information tier and the positional accuracy of entity glyphs are both modified: + +| Modifier | Effect | +|---|---| +| +1 tier | Resonator equipped and charged | +| +1 tier | Amplifier equipped in matching room class | +| −1 tier | Fear state: High | +| −2 tiers | Fear state: Extreme | +| −1 tier per 5 Corruption above 10 | Corruption degrades signal clarity | +| −1 tier | Room class: Anechoic | +| +1 tier | Room class: Chapel (RITUAL frequency only) | +| ±1 tile position error | Base positional uncertainty at Tier 3–4 | + +Position error means an entity glyph may be rendered up to ±1 tile from the entity's true position. Players should not expect sonar positions to be exact. + +### 3.6 False Echoes + +False echoes are sonar returns that do not correspond to real objects or entities. They occur when: + +- Corruption ≥ 10: 10% chance per sonar action. +- Corruption ≥ 20: 25% chance per sonar action. +- NOISE frequency used: additional +10% per use. +- Fear: Extreme: +15% to false echo rate. + +A false echo looks identical to a real echo glyph but responds to an empty tile. Players can test a suspicious glyph by approaching — if no entity or object is present, it was a false echo. The Static Apparition enemy (see Enemy Design GDD) also generates false sonar returns intentionally. + +--- + +## 4. Formulas + +### Sonar Tier Calculation + +``` +raw_tier = floor((sonar_range - distance_to_target) / sonar_range × 5) + + resonator_bonus + + amplifier_bonus + - fear_penalty + - corruption_penalty + - anechoic_penalty + +final_tier = clamp(raw_tier, 0, 5) + +resonator_bonus = 1 if resonator equipped and charged, else 0 +amplifier_bonus = 1 if amplifier room class matches, else 0 +fear_penalty = {high: 1, extreme: 2, else: 0} +corruption_penalty = floor(max(0, corruption - 10) / 5) +anechoic_penalty = 1 if room_class == ANECHOIC, else 0 +``` + +### Effective Sonar Range + +``` +effective_sonar_range = base_range + × frequency_wall_modifier + × (1 - room_absorption) + × (1 + amplifier_room_bonus) + +frequency_wall_modifier = {LOW: 1.0, MID: 0.8, HIGH: 0.5, NOISE: 0.9, RITUAL: 0.7} + (applied per wall tile crossed; multiplied together) +room_absorption = sum of absorbs_sound for all tiles on path / path_length +amplifier_room_bonus = 0.3 if amplifier equipped and room matches, else 0 +``` + +### False Echo Probability + +``` +false_echo_chance = base_rate + + (corruption_over_10 × 0.02) + + (corruption_over_20 × 0.01) + + (NOISE_frequency × 0.10) + + (extreme_fear × 0.15) + +base_rate = 0.0 if corruption < 10, else 0.10 +``` + +--- + +## 5. Edge Cases + +- **Sonar in anechoic room:** Returns Tier 0 or 1 only. The player receives a suppressed glyph at their own position and a UI note. The room does not echo — the ping is swallowed. +- **Sonar targeting the player's own tile:** Sonar is centred on the player. The player does not receive self-ping information; only outward propagation is calculated. +- **Two sonar pings in one turn:** Not allowed. Only one active sonar action per turn. If an equipment item would cause a second ping (e.g., Delay pedal echo), it fires on the *next* turn as a scheduled event — it still generates noise and may cause reactions. +- **RITUAL frequency in non-ritual room:** The ping propagates normally but returns no ritual-specific information (sealed doors appear as ordinary doors, spirit entities may or may not appear depending on entity rules). No bonus or penalty compared to MID. +- **Feedback unit out of control:** If the player rolls a control-loss event (see Equipment GDD), the feedback unit fires a secondary uncontrolled ping at `base_noise × 1.5` in a random direction. This is not a player-initiated action and cannot be cancelled. +- **Structural glyph conflicts:** If a sonar glyph shows a wall where no wall exists (false echo), and the player later enters line of sight of that tile, the false glyph is erased and the tile renders normally. No explanation is given — the discrepancy is silent and potentially unsettling. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Audio Perception System | Sonar results are rendered as audio glyphs; propagation uses tile acoustic properties | +| Noise System | Every sonar action emits a noise event at the action's `base_noise` value | +| Equipment System | Resonators, amplifiers, and effect pedals modify sonar tier and range | +| Fear / Corruption | Both stat values apply penalties to sonar tier and false echo rate | +| Enemy Design | Large / presence-class enemies respond to LOW sonar; all enemies have `audio_sensitivity` thresholds | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `hand_clap_noise` | 3 | Minimum practical sonar cost | +| `foot_stomp_noise` | 4 | | +| `metal_strike_noise` | 5 | | +| `bone_flute_noise` | 6 | | +| `low_drone_noise` | 10 | High risk — awakens large entities | +| `fuzz_guitar_noise` | 14 | | +| `feedback_noise` | 16+ | Floor, scales with uncontrolled use | +| `sonar_structural_turns` | 5 turns | How long wall/door glyphs persist | +| `sonar_entity_turns` | 2 turns | Entity glyphs fade quickly | +| `false_echo_threshold_1` | 10 Corruption | First false echo rate kicks in | +| `false_echo_threshold_2` | 20 Corruption | Second rate increase | +| `false_echo_rate_base` | 10% | At first threshold | +| `position_error_range` | ±1 tile | At Tier 3–4 | +| `corruption_penalty_interval` | 5 Corruption | Each 5 above 10 = −1 tier | + +--- + +## 8. Acceptance Criteria + +- [ ] A hand clap (Noise 3, Range 6) at distance 6 from a wall returns at minimum Tier 2 information (wall outline visible) under default conditions with no modifiers. +- [ ] A low drone (Noise 10) in a stone room triggers a Large entity reaction if one exists within 15 tiles. +- [ ] Sonar inside an anechoic room returns Tier 0–1 only, regardless of action strength or equipment. +- [ ] Entity glyphs from sonar disappear after `sonar_entity_turns` turns. +- [ ] Structural glyphs from sonar persist for `sonar_structural_turns` turns then fade. +- [ ] With Corruption ≥ 10, at least 1 in 10 sonar pings generates a false echo in a controlled test (run 30 pings with a fixed seed). +- [ ] A Resonator equipped at full charge increases sonar tier by exactly 1. +- [ ] HIGH frequency sonar (metal strike) through 2 wall tiles returns at least 30% shorter effective range than LOW frequency through the same path. +- [ ] Only one sonar action is possible per player turn; queued equipment echoes fire on subsequent turns. diff --git a/design/gdd/systems-index.md b/design/gdd/systems-index.md new file mode 100644 index 0000000000..6e26f486b3 --- /dev/null +++ b/design/gdd/systems-index.md @@ -0,0 +1,36 @@ +# GDD Systems Index + +| System | File | Status | Layer | +|--------|------|--------|-------| +| Audio Perception | [audio-perception-system.md](audio-perception-system.md) | Draft | Foundation | +| Vision & Fog | [vision-system.md](vision-system.md) | Draft | Foundation | +| Active Sonar | [sonar-system.md](sonar-system.md) | Draft | Core | +| Noise & Aggro | [noise-system.md](noise-system.md) | Draft | Core | +| Chase & Evasion | [chase-system.md](chase-system.md) | Draft | Core | +| Fear & Corruption | [fear-corruption-system.md](fear-corruption-system.md) | Draft | Core | +| Equipment | [equipment-system.md](equipment-system.md) | Draft | Feature | +| Ritual | [ritual-system.md](ritual-system.md) | Draft | Feature | +| Enemy Design | [enemy-design.md](enemy-design.md) | Draft | Feature | + +## Design Order + +Foundation → Core → Feature → Presentation → Polish + +## Cross-System Dependency Map + +``` +Vision System ──────────────────────────────┐ + ↓ +Audio Perception ←── Sonar System ──→ Noise System ──→ Chase System + ↑ ↑ ↑ + Tile Audio Equipment Enemy Design + Properties System + ↑ ↑ + Ritual System ──→ Fear / Corruption System +``` + +## Authoring Notes + +- Run `/design-review [path]` after editing any GDD. +- Run `/review-all-gdds` after all Foundation GDDs are approved. +- Balance values in Tuning Knobs sections are drafts — validate in MVP before locking. diff --git a/design/gdd/vision-system.md b/design/gdd/vision-system.md new file mode 100644 index 0000000000..0f4368fc3e --- /dev/null +++ b/design/gdd/vision-system.md @@ -0,0 +1,154 @@ +# GDD: Vision System + +**Status:** Draft +**Layer:** Foundation +**Last Updated:** 2026-05-16 +**Dependencies:** Audio Perception System + +--- + +## 1. Overview + +The Vision System defines what the player can directly see and how the game stores information the player has previously encountered. Vision is intentionally narrow — the player's field of view is the smallest of any information source — making it a scarce, high-value resource. The map renders in three overlapping layers: current sight (certain), memory (faded), and audio (interpreted). This layering ensures the player always knows the epistemic status of any piece of information on screen. + +--- + +## 2. Player Fantasy + +The player feels hemmed in by darkness, straining to see what should be visible. The narrow cone of certainty makes every lit tile feel precious. What lies just beyond the torchlight is not empty — it is unknown, and unknown is more frightening than dangerous. When the player finally sees an enemy they heard approaching three turns ago, the moment confirms their read — or reveals they were wrong. + +--- + +## 3. Detailed Rules + +### 3.1 Sight Radius by State + +| Condition | Sight Radius | +|---|---| +| Default (indoors, no light source) | 4 tiles | +| Fear: High | 3 tiles | +| Fear: Extreme | 2 tiles | +| Torchlight / lantern equipped | 6 tiles | +| Lit outdoor area | 7–9 tiles | +| Ritual fire / strong light source | 5 tiles (but marks player position) | +| Anechoic / cursed darkness | 2 tiles (cannot be extended by items) | + +Sight radius is measured in Chebyshev distance (includes diagonals). Walls block line-of-sight using standard roguelike raycasting. The player always sees the tile they are standing on. + +### 3.2 Map Information States + +Every tile on the map exists in exactly one of these states at any moment: + +| State | Rendering | Information Quality | +|---|---|---| +| **Current sight** | Full color, full detail | Certain — exact terrain, items, entities | +| **Memory** | Darkened, desaturated | Last-seen state — may be outdated | +| **Sonar-inferred** | Dashed outline / faint silhouette | Uncertain — shape only, no items or entities | +| **Unknown** | Complete black | No information | + +### 3.3 Memory Map Rules + +- Once a tile enters current sight, its terrain type is stored in memory permanently (for this run). +- Memory stores terrain and static objects only. Entities, items, and interactive objects are not stored — they may have moved. +- Memory is rendered as the last-seen terrain, darkened to 40% brightness. +- If a tile is revisited, memory updates to the current state. +- Memory is not erased by Fear or Corruption. It is, however, visually distorted at Extreme Fear (tiles swim slightly but remain readable). + +### 3.4 Audio Map Layer + +The audio map is a separate visual overlay, rendered above both current sight and memory. Its rules are defined in the Audio Perception System GDD. Key integration points for Vision: + +- Audio glyphs appear over memory tiles and unknown tiles, not only over current sight. +- A glyph in the unknown zone is the only information the player has about that area. +- When an audio glyph and a memory tile overlap, both are shown — the player sees the faded terrain outline and the sound indicator simultaneously. +- Glyphs generated by active sonar are visually distinct from passive hearing glyphs (sonar glyphs have a directional sweep appearance; passive glyphs are omnidirectional). + +### 3.5 Listening Mode + +When the player holds the Listen action (0 noise cost), the audio map layer is emphasized: + +- Sight rendering dims to 60% brightness. +- Audio glyphs increase in opacity and show distance estimates as faint number labels. +- New passive sound events from this turn are highlighted with a brief pulse. +- Listening mode lasts one turn; the player may remain in it by continuing to hold the action (each turn of listening counts as a Wait action — 0 noise). + +--- + +## 4. Formulas + +### Line-of-Sight Check + +Standard symmetric raycasting from player tile to target tile. A tile is visible if no wall tile interrupts the ray. + +``` +visible(P, T) = no wall on Bresenham line segment from P to T + AND Chebyshev(P, T) ≤ sight_radius +``` + +### Effective Sight Radius + +``` +sight_radius = base_radius + + light_bonus + - fear_penalty + - darkness_penalty + +base_radius = 4 +light_bonus = {torchlight: +2, outdoor: +3–5, ritual_fire: +1} +fear_penalty = {high: −1, extreme: −2} +darkness_penalty = {cursed_dark: set radius to 2, ignoring all bonuses} +``` + +Darkness penalty is a hard cap, not a subtraction — it replaces the computed value. + +--- + +## 5. Edge Cases + +- **Diagonal corner clipping:** The player cannot see through a 1-tile-wide diagonal gap between two walls. Treat diagonal corners as blocked (conservative raycasting). +- **Fear at Extreme with torchlight:** Fear penalty is applied after light bonus. At Extreme Fear with a lantern, sight radius = 4 + 2 − 2 = 4. The lantern does not lose effectiveness, but fear negates its gain. +- **Sonar in unknown zone:** A sonar ping can reveal silhouettes in the unknown zone. These silhouettes are sonar-inferred state, not memory. They decay after `sonar_glyph_turns` turns. +- **Enemy moves through memory tile:** The memory tile still shows the terrain but shows no entity. The player will not see the enemy there unless it enters current sight. The audio map may provide a glyph clue of its movement. +- **Revisiting a sonar-inferred tile:** When the player walks into a sonar-inferred tile, it upgrades to current sight. If the sonar was wrong (e.g., false echo from high Corruption), the player discovers the discrepancy in person. + +--- + +## 6. Dependencies + +| System | Relationship | +|---|---| +| Audio Perception System | Audio map overlay rendered above vision layers | +| Fear / Corruption | Fear state drives sight_radius penalties; Extreme Fear distorts memory rendering | +| Sonar System | Sonar results populate sonar-inferred tiles | +| Lighting (future) | Light source items feed into light_bonus | + +--- + +## 7. Tuning Knobs + +| Knob | Draft Value | Notes | +|---|---|---| +| `base_sight_radius` | 4 tiles | Indoor default; core tension driver | +| `torchlight_bonus` | +2 tiles | Increases to 6 total | +| `outdoor_bright_bonus` | +3 to +5 tiles | Range depending on weather/time | +| `fear_high_penalty` | −1 tile | | +| `fear_extreme_penalty` | −2 tiles | | +| `cursed_dark_cap` | 2 tiles | Overrides all other modifiers | +| `memory_brightness` | 40% | Visual darkness of remembered tiles | +| `listen_mode_dim` | 60% | How much sight dims in listening mode | +| `sonar_glyph_turns` | 3 turns | How long sonar-inferred outlines persist | + +--- + +## 8. Acceptance Criteria + +- [ ] Player at position P cannot see tile T if a wall lies on the line between P and T, regardless of radius. +- [ ] Default indoor sight radius is exactly 4 tiles from player position (Chebyshev). +- [ ] Equipping a torchlight increases sight to 6 tiles. +- [ ] At High Fear state, sight reduces to 3 tiles even with torchlight (4 + 2 − 1 = 5 — wait, let me recalculate: 4 + 2 − 1 = 5 tiles). +- [ ] At Extreme Fear state with torchlight, sight is 4 tiles (4 + 2 − 2 = 4). +- [ ] Cursed darkness caps sight at 2 tiles even with torchlight equipped. +- [ ] A tile the player has previously seen renders in desaturated/darkened form after leaving sight. +- [ ] Terrain in memory does not update when an entity moves across it outside current sight. +- [ ] Audio glyphs appear over unknown (black) tiles. +- [ ] Listening Mode (0 noise) shows distance labels on audio glyphs without causing any aggro response. diff --git a/design/registry/entities.yaml b/design/registry/entities.yaml index bcf9a95aaf..aeb59012b8 100644 --- a/design/registry/entities.yaml +++ b/design/registry/entities.yaml @@ -22,147 +22,235 @@ # /consistency-check (primary input — grep-first, GDD-second) # /review-all-gdds (Phase 1 — baseline for Phase 2 checks) # /architecture-review (data structure and interface validation) -# -# SEARCH PATTERNS (for skills using Grep): -# All entity names: Grep pattern="^ - name:" path="design/registry/entities.yaml" -# Specific entity: Grep pattern=" - name: goblin" path="design/registry/entities.yaml" -# All items: Grep pattern="^ - name:" path="design/registry/entities.yaml" (items section) -# What combat.md owns: Grep pattern="source: design/gdd/combat.md" -# What inventory.md uses: Grep pattern="referenced_by.*inventory" -# All gold values: Grep pattern="value_gold:" -# Deprecated entries: Grep pattern="status: deprecated" -# -# FORMAT: YAML. Consistent indentation is critical for grep reliability. -# Sections: entities | items | formulas | constants -# Each entry: name, status, source, referenced_by[], attributes{}, added, revised version: 1 -last_updated: "" +last_updated: "2026-05-16" # ─── ENTITIES ──────────────────────────────────────────────────────────────── -# Named game-world objects: enemies, NPCs, characters, factions, bosses. -# Register an entity here when it appears in more than one GDD — e.g., an -# enemy defined in combat.md that also drops items listed in inventory.md. -# -# Required fields: name, status, source, referenced_by, added -# Attribute fields: any key stats that could appear in another GDD -# (health, damage, drops, faction, etc.) -entities: [] +entities: + - name: blind_listener + status: active + source: design/gdd/enemy-design.md + referenced_by: + - design/gdd/enemy-design.md + - design/gdd/noise-system.md + hearing_threshold: 2 + sight_range: 0 + speed: 1 + killable: true + class: normal + added: 2026-05-16 + revised: "" -# Example (remove when first real entry is added): -# -# entities: -# - name: goblin -# status: active # active | deprecated -# source: design/gdd/combat.md -# referenced_by: -# - design/gdd/combat.md -# - design/gdd/inventory.md -# health: 40 -# damage: 8 -# drops: -# - item: goblin_arm # must match an entry in items section -# qty: 1 -# drop_rate: 0.8 # 0.0–1.0 -# added: 2026-03-26 -# revised: "" + - name: coffin_thing + status: active + source: design/gdd/enemy-design.md + referenced_by: + - design/gdd/enemy-design.md + hearing_threshold: 10 + sight_range: 3 + speed: 0.5 + killable: true + class: dangerous + added: 2026-05-16 + revised: "" + + - name: choir_ghost + status: active + source: design/gdd/enemy-design.md + referenced_by: + - design/gdd/enemy-design.md + - design/gdd/sonar-system.md + - design/gdd/ritual-system.md + hearing_threshold: 4 + sight_range: 6 + speed: 1.5 + killable: false + class: presence + ritual_breaker: true + added: 2026-05-16 + revised: "" + + - name: heavy_presence + status: active + source: design/gdd/enemy-design.md + referenced_by: + - design/gdd/enemy-design.md + - design/gdd/chase-system.md + - design/gdd/sonar-system.md + hearing_threshold: 20 + sight_range: 2 + speed: 1.5 + killable: false + class: presence + ritual_breaker: true + added: 2026-05-16 + revised: "" + + - name: static_apparition + status: active + source: design/gdd/enemy-design.md + referenced_by: + - design/gdd/enemy-design.md + - design/gdd/sonar-system.md + - design/gdd/fear-corruption-system.md + hearing_threshold: 0 + sight_range: 0 + speed: 0 + killable: false + class: echo + ritual_breaker: false + added: 2026-05-16 + revised: "" + + - name: masked_cultist + status: active + source: design/gdd/enemy-design.md + referenced_by: + - design/gdd/enemy-design.md + - design/gdd/ritual-system.md + hearing_threshold: 6 + sight_range: 6 + speed: 1 + killable: true + class: normal + ritual_breaker: false + added: 2026-05-16 + revised: "" # ─── ITEMS ─────────────────────────────────────────────────────────────────── -# Named collectables, equipment, consumables, crafting materials, currency. -# Register an item when its name or value appears in more than one GDD. -# -# Required fields: name, status, source, referenced_by, added -# Attribute fields: value_gold, weight, stackable, category, and any stat -# modifiers that another system (e.g., economy, crafting) might reference. items: [] -# Example: -# -# items: -# - name: goblin_arm -# status: active -# source: design/gdd/combat.md # drop defined in combat GDD -# referenced_by: -# - design/gdd/combat.md -# - design/gdd/inventory.md # inventory GDD lists its weight/stack rules -# - design/gdd/economy.md # economy GDD references its sell price -# value_gold: 5 -# weight: 1 -# stackable: true -# category: crafting_material -# added: 2026-03-26 -# revised: "" - # ─── FORMULAS ──────────────────────────────────────────────────────────────── -# Named calculations with defined variables and output ranges. -# Register a formula when its output feeds into another system's input, -# or when another GDD references it by name. -# -# Required fields: name, status, source, referenced_by, variables[], -# output_range[min, max], added -# Optional: expression (the actual formula), notes -formulas: [] +formulas: + - name: noise_at_target + status: active + source: design/gdd/noise-system.md + referenced_by: + - design/gdd/noise-system.md + - design/gdd/sonar-system.md + - design/gdd/chase-system.md + variables: + - action_noise + - tile_multiplier + - path_attenuation + - wall_attenuation + - wall_count + output_range: [0, 999] + expression: "action_noise × tile_multiplier × path_attenuation" + notes: "path_attenuation = Π(1 - tile.absorbs_sound) × wall_attenuation^wall_count" + added: 2026-05-16 + revised: "" -# Example: -# -# formulas: -# - name: damage_formula -# status: active -# source: design/gdd/combat.md -# referenced_by: -# - design/gdd/combat.md -# - design/gdd/progression.md # progression GDD scales attack variable -# variables: -# - attack -# - defense -# - crit_chance -# - crit_multiplier -# output_range: [0, 999] -# expression: "max(0, attack - defense) * (1 + crit_chance * crit_multiplier)" -# notes: "Output feeds into health-system damage intake. Min is 0 (armour -# can absorb all damage). Max is uncapped in formula but tuning knob -# damage_cap in combat.md clamps at 999." -# added: 2026-03-26 -# revised: "" + - name: sonar_tier + status: active + source: design/gdd/sonar-system.md + referenced_by: + - design/gdd/sonar-system.md + - design/gdd/equipment-system.md + - design/gdd/fear-corruption-system.md + variables: + - sonar_range + - distance_to_target + - resonator_bonus + - amplifier_bonus + - fear_penalty + - corruption_penalty + - anechoic_penalty + output_range: [0, 5] + expression: "clamp(floor((sonar_range - distance) / sonar_range × 5) + bonuses - penalties, 0, 5)" + added: 2026-05-16 + revised: "" + + - name: sight_radius + status: active + source: design/gdd/vision-system.md + referenced_by: + - design/gdd/vision-system.md + - design/gdd/fear-corruption-system.md + variables: + - base_radius + - light_bonus + - fear_penalty + - darkness_penalty + output_range: [2, 9] + expression: "max(cursed_dark_cap, base_radius + light_bonus - fear_penalty - darkness_penalty)" + notes: "cursed_dark_cap = 2 and overrides all other modifiers when active" + added: 2026-05-16 + revised: "" # ─── CONSTANTS ─────────────────────────────────────────────────────────────── -# Named numerical values referenced across multiple systems. -# Register a constant when it is defined in one GDD but another GDD must -# agree with it (e.g., gold carry limit defined in economy but checked in -# inventory, or base inventory slots defined in inventory but displayed in HUD). -# -# Required fields: name, status, source, referenced_by, value, unit, added -constants: [] +constants: + - name: base_sight_radius + status: active + source: design/gdd/vision-system.md + referenced_by: + - design/gdd/vision-system.md + - design/gdd/fear-corruption-system.md + value: 4 + unit: tiles + added: 2026-05-16 + revised: "" -# Example: -# -# constants: -# - name: gold_carry_limit -# status: active -# source: design/gdd/economy.md -# referenced_by: -# - design/gdd/economy.md -# - design/gdd/inventory.md # inventory enforces the carry limit -# - design/gdd/ui.md # HUD displays current gold vs limit -# value: 9999 -# unit: gold -# added: 2026-03-26 -# revised: "" -# -# - name: base_inventory_slots -# status: active -# source: design/gdd/inventory.md -# referenced_by: -# - design/gdd/inventory.md -# - design/gdd/progression.md # progression unlocks additional slots -# value: 20 -# unit: slots -# added: 2026-03-26 -# revised: "" + - name: base_hearing_radius + status: active + source: design/gdd/audio-perception-system.md + referenced_by: + - design/gdd/audio-perception-system.md + - design/gdd/noise-system.md + value: 10 + unit: tiles + added: 2026-05-16 + revised: "" + + - name: corruption_max + status: active + source: design/gdd/fear-corruption-system.md + referenced_by: + - design/gdd/fear-corruption-system.md + - design/gdd/ritual-system.md + - design/gdd/equipment-system.md + value: 50 + unit: points + added: 2026-05-16 + revised: "" + + - name: fear_max + status: active + source: design/gdd/fear-corruption-system.md + referenced_by: + - design/gdd/fear-corruption-system.md + value: 100 + unit: points + added: 2026-05-16 + revised: "" + + - name: noise_decay_rate + status: active + source: design/gdd/noise-system.md + referenced_by: + - design/gdd/noise-system.md + - design/gdd/chase-system.md + value: 0.35 + unit: fraction_per_turn + added: 2026-05-16 + revised: "" + + - name: wall_attenuation + status: active + source: design/gdd/audio-perception-system.md + referenced_by: + - design/gdd/audio-perception-system.md + - design/gdd/noise-system.md + - design/gdd/sonar-system.md + value: 0.6 + unit: fraction_per_wall_tile + added: 2026-05-16 + revised: ""