Add initial GDD set for audio horror roguelike

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.