From 34d0e7211cd8e0efb01b091c8328cb163add3816 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Mon, 16 Feb 2026 01:03:18 +0100 Subject: [PATCH] docs(assets): add asset pipeline documentation system Category-based asset index for audio, visual, and video pipelines. Audio pipeline fully populated: palette (sonic identity bible), ambient loops, SFX, UI sounds with generation specs and mix parameters. Visual and video are stubs pending their respective workshops. Co-Authored-By: Claude Opus 4.6 --- docs/assets/README.md | 56 +++++++++++++++++++ docs/assets/_templates/audio.md | 33 ++++++++++++ docs/assets/_templates/sprite.md | 31 +++++++++++ docs/assets/_templates/video.md | 30 +++++++++++ docs/assets/audio/README.md | 54 +++++++++++++++++++ docs/assets/audio/ambient.md | 43 +++++++++++++++ docs/assets/audio/palette.md | 93 ++++++++++++++++++++++++++++++++ docs/assets/audio/sfx.md | 41 ++++++++++++++ docs/assets/audio/ui.md | 74 +++++++++++++++++++++++++ docs/assets/video/README.md | 18 +++++++ docs/assets/video/palette.md | 5 ++ docs/assets/visual/README.md | 29 ++++++++++ docs/assets/visual/palette.md | 16 ++++++ 13 files changed, 523 insertions(+) create mode 100644 docs/assets/README.md create mode 100644 docs/assets/_templates/audio.md create mode 100644 docs/assets/_templates/sprite.md create mode 100644 docs/assets/_templates/video.md create mode 100644 docs/assets/audio/README.md create mode 100644 docs/assets/audio/ambient.md create mode 100644 docs/assets/audio/palette.md create mode 100644 docs/assets/audio/sfx.md create mode 100644 docs/assets/audio/ui.md create mode 100644 docs/assets/video/README.md create mode 100644 docs/assets/video/palette.md create mode 100644 docs/assets/visual/README.md create mode 100644 docs/assets/visual/palette.md diff --git a/docs/assets/README.md b/docs/assets/README.md new file mode 100644 index 000000000..dcca40e1c --- /dev/null +++ b/docs/assets/README.md @@ -0,0 +1,56 @@ +# Asset Pipeline Index + +Centralized tracking for all production assets across pipelines. Each pipeline has its own index, palette (style bible), and per-category asset tables. + +## Pipelines + +| Pipeline | Index | Palette | Status | +|----------|-------|---------|--------| +| [Audio](audio/README.md) | [audio/README.md](audio/README.md) | [audio/palette.md](audio/palette.md) | Active — Sprint 7 | +| [Visual](visual/README.md) | [visual/README.md](visual/README.md) | [visual/palette.md](visual/palette.md) | Stub | +| [Video](video/README.md) | [video/README.md](video/README.md) | [video/palette.md](video/palette.md) | Stub | + +## Structure + +``` +docs/assets/ + README.md # This file — master index + _templates/ + audio.md # Row template + detailed entry template for audio + sprite.md # Row template + detailed entry template for sprites + video.md # Row template + detailed entry template for video + audio/ + README.md # Audio pipeline index — categories, status summary + palette.md # Sonic palette, aesthetic guide, generation approach + ambient.md # All ambient loops (station, planet, biome, weather) + sfx.md # All SFX (footsteps, doors, impacts, events) + ui.md # All UI sounds (cursor, chimes, insert-tech) + visual/ + README.md # Visual pipeline index + palette.md # Art direction, "the angle", color relationships + sprites.md # Entities (NPCs, player, creatures) + furniture.md # Furniture items (hundreds, by location/type) + tilesets.md # Floor/wall tiles by biome/planet + icons.md # UI icons, status indicators + effects.md # Fog shaders, particles, overlays + video/ + README.md # Video pipeline index + palette.md # Motion/editing style guide + trailers.md # Marketing / Steam page trailers + cutscenes.md # In-game narrative moments +``` + +## Conventions + +- **One .md per category** — asset table with one row per asset, detailed entries below for complex items +- **palette.md** per pipeline — the style bible. Aesthetic baseline, theme, generation approach. +- **Status values:** `planned` | `in-progress` | `placeholder` | `final` +- **Templates:** `_templates/{type}.md` — row format + detailed entry format +- **Asset files** live in `client/assets/{type}/` — these docs track design and production metadata +- **Category splitting:** When a category file grows too long, split by domain (e.g., `furniture-station.md`, `furniture-colony.md`) + +## Cross-References + +- Decision files: `decisions/` (D-038 audio scope, D-033 entity colors, D-019 camera angle) +- Art direction workshop: `docs/workshops/art-direction-mood-board/` +- Sprint briefings: `docs/sprints/sprint-N/{team}.md` diff --git a/docs/assets/_templates/audio.md b/docs/assets/_templates/audio.md new file mode 100644 index 000000000..5ceadd180 --- /dev/null +++ b/docs/assets/_templates/audio.md @@ -0,0 +1,33 @@ +# Audio Asset Template + +## Table Row Format + +``` +| {ID} | `{filename}.ogg` | {status} | {bus} | {method} | {duration} | {prompt/notes} | {sprint/ticket} | +``` + +**Columns:** +- **ID:** Category prefix + sequential number (AMB-001, SFX-001, UI-001) +- **Filename:** Target filename in `client/assets/audio/` +- **Status:** planned / in-progress / placeholder / final +- **Bus:** Ambient / World SFX / Player Actions / UI Sounds / Music +- **Method:** SAO (Stable Audio Open) / synth (manual synthesis) / hybrid +- **Duration:** Target duration +- **Prompt/Notes:** Generation prompt or design description (keep brief — expand in detailed entry if needed) +- **Sprint/Ticket:** Sprint number and ticket ID + +## Detailed Entry Format + +Use below the asset table for assets that need expanded documentation (complex generation, iteration history, special integration notes). + +```markdown +### {ID}: {filename} +- **Sonic family:** insert-tech / organic +- **Frequency range:** {primary range} +- **Full prompt:** `{complete generation prompt}` +- **Post-processing:** {trim, normalize, EQ, crossfade, loop points} +- **Integration:** {which system triggers this, bus routing, special behavior} +- **Iteration history:** + | Date | Version | Notes | + |------|---------|-------| +``` diff --git a/docs/assets/_templates/sprite.md b/docs/assets/_templates/sprite.md new file mode 100644 index 000000000..dec19e3a1 --- /dev/null +++ b/docs/assets/_templates/sprite.md @@ -0,0 +1,31 @@ +# Sprite Asset Template + +## Table Row Format + +``` +| {ID} | `{filename}.png` | {status} | {layer} | {method} | {directions} | {notes} | {sprint/ticket} | +``` + +**Columns:** +- **ID:** Category prefix + sequential number (SPR-001, FUR-001, TILE-001, ICO-001, FX-001) +- **Filename:** Target filename in `client/assets/sprites/` (or tilesets/, etc.) +- **Status:** planned / in-progress / placeholder / final +- **Layer:** Entity / tile / effect / UI +- **Method:** render pipeline / hand-drawn / AI-assisted +- **Directions:** N/E/S/W (4-dir), S-only, or N/A +- **Notes:** Source model, special render settings, design description +- **Sprint/Ticket:** Sprint number and ticket ID + +## Detailed Entry Format + +```markdown +### {ID}: {filename} +- **Source model:** `{path to .glb/.blend}` +- **Render settings:** Camera angle, lighting, outline width +- **Color relationships:** D-033 mapping if entity +- **Resolutions:** 1024px (working) / 256px (game) / 64px (minimap) +- **Post-processing:** Outline pass, palette adjustment, special effects +- **Iteration history:** + | Date | Version | Notes | + |------|---------|-------| +``` diff --git a/docs/assets/_templates/video.md b/docs/assets/_templates/video.md new file mode 100644 index 000000000..d56e672b7 --- /dev/null +++ b/docs/assets/_templates/video.md @@ -0,0 +1,30 @@ +# Video Asset Template + +## Table Row Format + +``` +| {ID} | `{filename}.{ext}` | {status} | {type} | {duration} | {notes} | {sprint/ticket} | +``` + +**Columns:** +- **ID:** Category prefix + sequential number (TRL-001, CUT-001) +- **Filename:** Target filename +- **Status:** planned / in-progress / placeholder / final +- **Type:** trailer / cutscene / intro +- **Duration:** Target duration +- **Notes:** Purpose, audience, key scenes +- **Sprint/Ticket:** Sprint number and ticket ID + +## Detailed Entry Format + +```markdown +### {ID}: {filename} +- **Resolution:** 1920x1080 / 3840x2160 +- **Frame rate:** 30 / 60 fps +- **Audio track:** {link to audio asset or composition notes} +- **Script/storyboard:** {link or inline} +- **Production method:** In-engine capture / external editing / mixed +- **Iteration history:** + | Date | Version | Notes | + |------|---------|-------| +``` diff --git a/docs/assets/audio/README.md b/docs/assets/audio/README.md new file mode 100644 index 000000000..99f6d9dee --- /dev/null +++ b/docs/assets/audio/README.md @@ -0,0 +1,54 @@ +# Audio Asset Pipeline + +Status: **Active** — Sprint 7 (first audio sprint) + +## Summary + +| Category | File | Total | Planned | In-Progress | Placeholder | Final | +|----------|------|-------|---------|-------------|-------------|-------| +| Ambient | [ambient.md](ambient.md) | 4 | 4 | 0 | 0 | 0 | +| SFX | [sfx.md](sfx.md) | 2 | 2 | 0 | 0 | 0 | +| UI | [ui.md](ui.md) | 6 | 4 | 0 | 0 | 0 | +| **Total** | | **12** | **10** | **0** | **0** | **0** | + +Update counts when asset status changes. + +## Palette + +See [palette.md](palette.md) for the sonic identity: two sonic families (insert-tech / organic), station palette (functional warmth), generation approach, bus architecture. + +## Generation Tools + +- **Stable Audio Open:** Self-hosted, >200ms organic sounds. ~47s ceiling per generation. +- **Manual synthesis:** <200ms insert-tech sounds. Audacity / Python oscillator. +- **Post-processing:** LUFS normalization, EQ carving, crossfade loops (3-5s overlap). + +## Bus Architecture + +5 player-facing buses (see palette.md for full spec): + +| Bus | Content | +|-----|---------| +| Music | Future — empty | +| Ambient | Station hum, zone overlays | +| World SFX | NPC footsteps, doors, conversation murmur | +| Player Actions | Player footsteps, combat | +| UI Sounds | Cursor, implant, chimes, recognition | + +## Sprint Scope + +### Sprint 7 (#440 — 8 assets) +- 4 UI sounds: cursor hover, fog recognition, implant open, weapon aim (sketch) +- 2 UI sounds: monologue chime normal + urgent (PLACEHOLDER — Sprint 8 redo) +- 2 mix specs: dialogue dip, confrontation dip (documentation, not audio files) + +### Sprint 8+ (D-038 — 6 remaining assets) +- 4 ambient loops: station base, workplace layer, bar layer, corridor layer +- 2 SFX: footstep metal walk, footstep metal run +- Monologue chime redo (priority #1) + +## Decision References + +- D-038: Audio in v0.1 scope +- D-018: Three-range sound model +- D-045: Environmental neutrality diff --git a/docs/assets/audio/ambient.md b/docs/assets/audio/ambient.md new file mode 100644 index 000000000..7643e2add --- /dev/null +++ b/docs/assets/audio/ambient.md @@ -0,0 +1,43 @@ +# Ambient — Audio Assets + +Zone-based ambient loops. Station base plays globally; overlays crossfade based on player zone (hard tile boundary, 1.5-2s audio tween). + +## Generation Approach + +Stable Audio Open primary. Prompt strategy: describe the SPACE, not the sound. +- Target: 45s loops with 3-5s overlap crossfade (equal-power) +- Validation: solo test → stack test → fatigue test (5+ minutes) +- Post-processing: LUFS normalize, EQ carve per-layer to avoid masking, crossfade loop points +- Environmental neutrality (D-045): warmth/character is baked into the asset, does not react to narrative state + +## Assets + +| ID | Filename | Status | Bus | Method | Duration | Prompt/Notes | Sprint | +|----|----------|--------|-----|--------|----------|-------------|--------| +| AMB-001 | `amb_station_base.ogg` | planned | Ambient | SAO | 45-60s loop | Station hum, span gate vibration, ventilation. Low-freq foundation (60-120Hz), mid texture (200-800Hz). Always playing — acoustic foundation of being on a station. | S8+ | +| AMB-002 | `amb_workplace_layer.ogg` | planned | Ambient | SAO | 45-60s loop | Cargo machinery, scanner pings, distant procedural voices (designations, not conversation). Rhythmic mechanical cadence. Terminal zone overlay. | S8+ | +| AMB-003 | `amb_bar_layer.ogg` | planned | Ambient | SAO | 45-60s loop | Conversation murmur (300Hz-3kHz), softened glass sounds, faint Meridian music (barely melodic, distant radio). Social warmth. Murmur baked in — bar IS the crowd. Last Shift zone overlay. | S8+ | +| AMB-004 | `amb_corridor_layer.ogg` | planned | Ambient | SAO | 45-60s loop | Echoing footsteps, ventilation whistle with reverb tail, louder gate hum (closer to structure). Emptier mid-range, prominent low-end. Liminal emptiness. Corridor zone overlay. | S8+ | + +## Detailed Entries + +### AMB-001: amb_station_base +- **Sonic family:** organic (environmental) +- **Frequency range:** 60-120Hz foundation, 200-800Hz texture, 2-8kHz sparse detail +- **Role:** Global ambient — always playing, never stops. The acoustic reality of Station Sova. If zone overlays fade, this is "silence" — should feel empty, not quiet. +- **Layering:** Plays on AmbientBase sub-channel. Zone overlays play on AmbientLayer, additive. +- **Integration:** Starts on game load, loops indefinitely. Volume on Ambient bus. +- **Cross-reference:** D-038 (#1), D-039 wow moment #1 (Arrival — station hum is first thing player hears) + +### AMB-003: amb_bar_layer +- **Sonic family:** organic (social space) +- **Murmur note:** Conversation murmur is baked into this asset, not triggered by NPC presence. The bar sounds like a crowd whether 2 or 15 NPCs are present. This is the acoustic character of the space. Separate NPC proximity murmur (event-driven, point-source) is a future asset. +- **Integration:** Crossfades in when player enters bar zone, out when leaving. 1.5-2s tween. +- **Cross-reference:** D-038 (#3), D-045 (warmth is indifference — bar sounds warm always) + +## Future Expansion + +As the game expands beyond Station Sova (multiple planets, biomes, weather), ambient categories will grow significantly. When this file exceeds ~50 entries, split by location: +- `ambient-station.md` (Station Sova zones) +- `ambient-planet-{name}.md` (planetary biomes) +- `ambient-weather.md` (weather overlay loops) diff --git a/docs/assets/audio/palette.md b/docs/assets/audio/palette.md new file mode 100644 index 000000000..3cb5d3a5c --- /dev/null +++ b/docs/assets/audio/palette.md @@ -0,0 +1,93 @@ +# Audio Palette + +The sonic identity of The Settled Reach. Living document — updated as the audio language evolves. + +## Core Principle: Audio as Cognitive Architecture + +Every sound maps to one of two cognitive sources: + +| Source | Sound Type | What it means | Sonic character | +|--------|-----------|---------------|-----------------| +| Biological | Ambient layers, footsteps, fog recognition | "I am a body in a space, and my body knows things" | Organic, warm, natural decay | +| Technological | Cursor hover, implant open, monologue chime | "I am augmented, and my lattice processes things my body can't" | Synthetic, precise, clinical | +| Absence | Dialogue dip, confrontation dip | "I am choosing to focus, and the world continues without my attention" | Reduced ambient, muffled world | + +This split maps to D-018's trust model: organic perception is slow but trustworthy, technological perception is fast but its data can be manipulated. + +## Two Sonic Families + +### Insert-Tech (Synthetic) +- **Character:** Clean waveforms, no reverb (exists in your head, not in space). Digital. Precise. Mathematical. +- **Frequency range:** 800Hz-4kHz primary. Sharp attack, controlled decay. +- **Feel:** "A well-designed touchscreen" — tonal confirmation, not notification beeps. +- **Used for:** Cursor hover, implant open, weapon aim, monologue chimes. +- **Generation method:** Manual synthesis for <200ms sounds. SAO for >200ms. + +### Organic (Biological) +- **Character:** Warm, breathy, slightly resonant. Natural attack and decay. Reverberant (exists in the world). +- **Frequency range:** 300Hz-1.5kHz primary. Soft attack, natural tail. +- **Feel:** "The sound you 'hear' internally when something clicks into place." +- **Used for:** Fog recognition, future character-cognition sounds. +- **Generation method:** Stable Audio Open primary — organic texture is what generative audio does best. + +## Station Sonic Palette: Functional Warmth + +The Settled Reach is a working station. Not military, not luxury — **industrial infrastructure that people made livable.** + +### Base Layer (always present) +- **Low-frequency foundation (60-120Hz):** Generator hum, structural resonance. The span gate's mass holding the station together. Always present, barely noticed. +- **Mid-frequency texture (200-800Hz):** Ventilation, distant pipe flow, air cycling systems. Life support you forget about until it stops. +- **High-frequency detail (2-8kHz):** Occasional scanner pings, distant PA crackle, metal-on-metal contact. Sparse. These break through the baseline — something happened. + +### Zone Overlays (additive to base) +- **Bar (The Last Shift):** More mid-range (voice murmur 300Hz-3kHz), softer high end (glass filtered, not sharp), faint Meridian music barely melodic — someone left a radio on two rooms away. Social warmth. +- **Corridor:** Emptier mid-range, more prominent low-end (gate hum louder — closer to structure), high-frequency echoes (reverb tail on ventilation whistle). Liminal emptiness. +- **Workplace (Terminal):** Rhythmic mechanical elements (cargo cadence), cleaner scanner pings, distant procedural voices (cargo designations, not conversation). Institutional precision. + +### What Silence Sounds Like +Silence on a station isn't silence — it's the base hum with nothing on top. If a zone overlay fades out and you're left with just station base, that should feel **empty**. Not quiet. Empty. Like a room where people were just a moment ago. + +## Environmental Neutrality (D-045) + +The ambient palette **does not shift with narrative state**. The bar sounds warm whether THE FRIEND is honest or lying. The corridor hum doesn't become ominous when you discover the conspiracy. The world is indifferent to your investigation. + +The warmth is the indifference. The bartender's radio doesn't know. + +## Audio Bus Architecture + +5 player-facing buses, each with independent volume slider: + +| Bus | Content | Diegetic source | +|-----|---------|-----------------| +| Music | Future — empty for now | Non-diegetic | +| Ambient | Station hum, zone overlays, global loops | Environment | +| World SFX | NPC footsteps, doors, machinery, conversation murmur | Other entities | +| Player Actions | Player footsteps, combat, weapon sounds | Player character | +| UI Sounds | Cursor, implant, monologue chimes, fog recognition | Neural lattice / cognition | + +## Generation Approach + +### Stable Audio Open (>200ms, organic character) +- Model: ~1.2B parameters, 44.1kHz stereo output, ~47s ceiling +- Prompting: Describe the SPACE, not the sound. "Industrial space station interior, low frequency machinery hum" not "sci-fi ambient drone in D minor." +- Iteration: Generate 4-6 candidates per asset. Test: solo → stack → fatigue (5+ minutes for loops). +- Post-processing: Trim, normalize (LUFS), EQ to carve frequency space, crossfade loops (3-5s overlap, equal-power). + +### Manual Synthesis (<200ms, insert-tech character) +- Tools: Audacity / Python synthesis (sine tone + envelope + harmonic layering) +- The precision IS the design — insert-tech sounds should feel mathematically exact. +- A 50ms cursor tick is a few lines of oscillator + exponential decay. + +### Quality Validation +- **Solo test:** Does it sound right alone? +- **Stack test:** Does it sit in the mix with other layers without masking? +- **Fatigue test:** Can you listen for 5+ minutes without jarring repeat? (loops only) +- **Close-your-eyes test (Ozzie):** Does the sound create a mental image / sensation? + +## Decision References + +- D-018: Three-range sound model (close/medium/long) +- D-038: Audio in v0.1 scope — 8 files via Stable Audio Open +- D-045: Environmental neutrality +- D-048: Neural insert overlay (insert-styled UI aesthetic) +- D-053: Movement stances (acoustic footprint implications) diff --git a/docs/assets/audio/sfx.md b/docs/assets/audio/sfx.md new file mode 100644 index 000000000..c385559ba --- /dev/null +++ b/docs/assets/audio/sfx.md @@ -0,0 +1,41 @@ +# SFX — Audio Assets + +World sound effects: footsteps, environmental events, impacts. Event-driven, often positional (AudioStreamPlayer2D). + +## Generation Approach + +Mixed methods depending on duration and character: +- Footsteps: SAO generation (>200ms) or hybrid (generate longer clip, extract best transient) +- Future environmental SFX (doors, machinery events): SAO or foley recording +- Post-processing: normalize, trim, ensure clean attack/release + +## Assets + +| ID | Filename | Status | Bus | Method | Duration | Prompt/Notes | Sprint | +|----|----------|--------|-----|--------|----------|-------------|--------| +| SFX-001 | `sfx_footstep_metal.ogg` | planned | Player Actions | hybrid | 0.3-0.5s | Single footstep on metal grating. Walk pace. Player character proprioceptive feedback. | S8+ | +| SFX-002 | `sfx_footstep_metal_run.ogg` | planned | Player Actions | hybrid | 0.2-0.3s | Faster footstep, sprint pace. Louder — player is broadcasting position (D-053 acoustic footprint). | S8+ | + +## Detailed Entries + +### SFX-001: sfx_footstep_metal +- **Sonic family:** organic (physical world) +- **Bus rationale:** Player Actions — this is feedback on YOUR movement, not world information. NPC footsteps (future) go on World SFX. +- **Stance implications (D-053):** Walk = normal volume. Sprint variant (SFX-002) = louder. Careful = quieter variant (future asset). Crouch = near-silent variant (future asset). +- **Integration:** Triggered by player movement tick. Positional (AudioStreamPlayer2D at player position) — maps to camera-relative stereo per D-018. +- **Cross-reference:** D-038 (#5), D-053 (movement stances as acoustic decisions) + +## Future Expansion + +SFX will grow significantly with: +- NPC footstep variants (by surface type, stance) → World SFX bus +- Door open/close, machinery activation → World SFX bus +- Combat impacts, weapon sounds → Player Actions bus +- Environmental events per planet/biome +- NPC conversation murmur (event-driven, point-source) → World SFX bus + +When this file exceeds ~50 entries, split by domain: +- `sfx-movement.md` (footsteps, stance variants) +- `sfx-environment.md` (doors, machinery, weather) +- `sfx-combat.md` (weapons, impacts) +- `sfx-conversation.md` (murmur, vocal events) diff --git a/docs/assets/audio/ui.md b/docs/assets/audio/ui.md new file mode 100644 index 000000000..a6544f460 --- /dev/null +++ b/docs/assets/audio/ui.md @@ -0,0 +1,74 @@ +# UI — Audio Assets + +Interface sounds triggered by player interaction, insert systems, and cognitive events. Non-positional (AudioStreamPlayer). Routes to UI Sounds bus. + +## Generation Approach + +- **Insert-tech sounds (<200ms):** Manual synthesis. Sine/square oscillators, exponential decay, harmonic layering. Precision IS the design. +- **Organic cognitive sounds (>200ms):** Stable Audio Open primary. Warm texture, natural decay. +- **Monologue chimes:** Currently PLACEHOLDER (Sprint 7). Redo scheduled Sprint 8 priority #1. Design brief below captures target register. + +## Assets + +| ID | Filename | Status | Bus | Method | Duration | Prompt/Notes | Sprint | +|----|----------|--------|-----|--------|----------|-------------|--------| +| UI-001 | `cursor_hover.ogg` | planned | UI Sounds | synth | 50-100ms | Subtle tick/ping on entity hover (D-056). Insert-tech: clean, precise, synthetic. Almost subliminal — notice if missing, not if present. Sine ~3.2kHz, exponential decay. | S7 #440 | +| UI-002 | `implant_open.ogg` | planned | UI Sounds | SAO+synth | 150-250ms | Rising tone when insert UI opens (radial menu, inventory, stance). Neural lattice powering up. Frequency sweep 800Hz→2kHz, harmonic shimmer. Template for insert-tech family. | S7 #440 | +| UI-003 | `fog_recognition.ogg` | planned | UI Sounds | SAO | 300-400ms | Warm organic chime at onset of cognitive delay (D-060). Character recognizing a person — "those footsteps... that's Kael." Unresolved tone (rises, doesn't land). 300-800Hz, breathy attack, natural tail overlapping delay start. | S7 #440 | +| UI-004 | `weapon_aim.ogg` | planned | UI Sounds | hybrid | 100-150ms | Harder click/lock for weapon aim state. Mechanical, deliberate. 400-800Hz latch sound. SKETCH ONLY — no weapons in Sprint 7, design for consistency. | S7 #440 | +| UI-005 | `sfx_monologue_chime.ogg` | planned | UI Sounds | synth | 500-1000ms | PLACEHOLDER. Soft crystalline tone, neural lattice surfacing a thought. Quiet, non-intrusive. Sprint 8 redo mandatory. See design brief below. | S7 #440 | +| UI-006 | `sfx_monologue_chime_urgent.ogg` | planned | UI Sounds | synth | 500-1000ms | PLACEHOLDER. Sharper variant for contradiction/anomaly. Brighter, 15% louder, shorter. Sprint 8 redo mandatory. See design brief below. | S7 #440 | + +## Mix Specs (not audio files) + +These are AudioBus parameter changes, documented in `docs/audio/dialogue-ambient-dip.md`: + +| Spec | Trigger | Effect | Sprint | +|------|---------|--------|--------| +| Dialogue dip | Dialogue box opens | Ambient -6 to -8dB, 300ms ease-in, 500ms ease-out | S7 #440 | +| Confrontation dip | Confrontation dialogue | Ambient -10 to -12dB + LP (800Hz), World SFX -4 to -6dB, 500ms ease-in, 1000ms ease-out | S7 #440 | + +## Detailed Entries + +### UI-001: cursor_hover +- **Sonic family:** insert-tech +- **Frequency range:** 3-4kHz primary +- **Design principle:** "Like breathing — present, functional, invisible." Player shouldn't describe it if asked, but would notice absence. Fatigue test critical — plays 300+ times per session. +- **Generation:** Pure synthesis. Sine tone at 3.2kHz, exponential decay over 40-50ms. No SAO — precision and purity are the point. +- **Debouncing:** AudioManager enforces 100ms cooldown between plays (rapid mouse movement). +- **Integration:** CursorRenderer.cursor_state_changed signal → AudioManager.play_ui("cursor_hover") +- **Cross-reference:** D-056 (cursor states) + +### UI-003: fog_recognition +- **Sonic family:** organic +- **Frequency range:** 300Hz-1.5kHz +- **Design principle:** "The sound you hear internally when something clicks into place." Not a chime — more like a soft exhalation of tone. Sits BETWEEN insert sounds and ambient — not UI, not world, cognition. +- **Timing (Q-014 resolved):** Fires at ONSET of cognitive delay. Sequence: hear something in fog → chime plays → 0.6s delay → monologue during delay → blob transitions to D-033 color. Chime is "your character is processing," color transition is "recognition complete." +- **Integration:** Cognitive delay onset event → AudioManager.play_ui("fog_recognition") +- **Cross-reference:** D-060 (cognitive delay), D-018 (three-range sound, medium range) + +### UI-005 / UI-006: Monologue Chime Design Brief (PLACEHOLDER) + +**Target emotional register for Sprint 8 redo:** + +The monologue chimes are the two poles of augmented cognition made audible: + +| Variant | Meaning | Feel | Target | +|---------|---------|------|--------| +| Normal | "My lattice surfaced this" | A thought arriving — not a notification. Like your own attention shifting. | Player never consciously notices it. Pavlovian: text appeared, brain registered, moved on. | +| Urgent | "My lattice flagged a contradiction" | Productive discomfort. "Wait, what did I miss?" | Micro-spike of alertness. Not alarm. The delta from normal must be SMALL but unmistakable. | + +**Relationship to fog recognition chime:** +- Fog recognition = organic (biological cognition, warm, 300-800Hz) +- Monologue normal = insert-tech (crystalline, clean, higher register, ~1.2kHz) +- Monologue urgent = insert-tech (sharper, brighter, adds second harmonic ~2.4kHz) +- Same cognitive family, different branches. Cousins, not twins. + +**Quality bar:** If the urgent chime feels like a quest marker ping, it has failed. If it feels like Ubisoft, it has failed. The delta between normal and urgent = "someone thinking quietly" vs "someone's eyes going slightly wide." + +**Placeholder spec (Sprint 7):** +- Normal: pure sine 1.2kHz, 600ms, gentle attack, natural decay. Conservative volume. +- Urgent: sine 1.2kHz + harmonic 2.4kHz, 400ms, sharper attack, 15% louder. +- Deliberately undersized — obviously temporary. Ugly placeholders get replaced. + +**Evaluation gate:** First internal playtest after Sprint 7: "Does the normal chime feel like a thought arriving? Does the urgent chime create a physiological response?" If no → trigger chime redesign. diff --git a/docs/assets/video/README.md b/docs/assets/video/README.md new file mode 100644 index 000000000..865935c8f --- /dev/null +++ b/docs/assets/video/README.md @@ -0,0 +1,18 @@ +# Video Asset Pipeline + +Status: **Stub** — no video assets planned for v0.1. + +## Categories + +| Category | File | Count | Description | +|----------|------|-------|-------------| +| Trailers | [trailers.md](trailers.md) | 0 | Marketing / Steam page trailers | +| Cutscenes | [cutscenes.md](cutscenes.md) | 0 | In-game narrative moments (D-019: deferred to milestones) | + +## Palette + +See [palette.md](palette.md) for motion/editing style guide (to be established). + +## Decision References + +- D-019: 3D cutscenes for key moments — deferred to milestones, not v0.1 diff --git a/docs/assets/video/palette.md b/docs/assets/video/palette.md new file mode 100644 index 000000000..21debf081 --- /dev/null +++ b/docs/assets/video/palette.md @@ -0,0 +1,5 @@ +# Video Palette + +Status: **Stub** — no video production planned for v0.1. + +To be established when cutscene or trailer work begins. diff --git a/docs/assets/visual/README.md b/docs/assets/visual/README.md new file mode 100644 index 000000000..280c04eae --- /dev/null +++ b/docs/assets/visual/README.md @@ -0,0 +1,29 @@ +# Visual Asset Pipeline + +Status: **Stub** — awaiting first visual sprint. + +## Categories + +| Category | File | Count | Description | +|----------|------|-------|-------------| +| Sprites | [sprites.md](sprites.md) | 0 | Entity sprites via 3D render pipeline | +| Furniture | [furniture.md](furniture.md) | 0 | Furniture items by location/type | +| Tilesets | [tilesets.md](tilesets.md) | 0 | Floor/wall tiles by biome/planet | +| Icons | [icons.md](icons.md) | 0 | UI icons, status indicators | +| Effects | [effects.md](effects.md) | 0 | Fog shaders, particles, overlays | + +## Palette + +See [palette.md](palette.md) for art direction, "the angle", color relationships, and render pipeline specs. + +## Pipeline + +- **3D render pipeline:** Blender model → Godot Camera3D at -72.5deg → orthographic render → outline pass → resolution downscale +- **Render skill:** `/render-sprite` produces 12 PNGs (4 directions x 3 resolutions) +- **Art direction workshop:** `docs/workshops/art-direction-mood-board/` + +## Decision References + +- D-019: Top-down camera, 15-20deg from vertical ("the angle") +- D-033: Entity color = relationship to player +- D-045: Environmental neutrality diff --git a/docs/assets/visual/palette.md b/docs/assets/visual/palette.md new file mode 100644 index 000000000..2ee7991c0 --- /dev/null +++ b/docs/assets/visual/palette.md @@ -0,0 +1,16 @@ +# Visual Palette + +Status: **Stub** — reference art direction workshop output for current guidance. + +See `docs/workshops/art-direction-mood-board/` for the established visual identity. + +## Key Decisions + +- **Camera angle:** 15-20deg from vertical ("the angle"), rendered via orthographic Camera3D at -72.5deg from horizontal (D-019) +- **Entity colors:** Relationship-based per D-033 (green = known/friendly, amber = neutral, red = hostile, etc.) +- **Environmental neutrality:** Spaces don't visually shift with narrative state (D-045) +- **Functional warmth:** Industrial infrastructure that people made livable — not military, not luxury + +## Style Guide + +To be populated from art direction workshop synthesis and first visual sprint.