diff --git a/.claude/docs/technical-preferences.md b/.claude/docs/technical-preferences.md index 94a91fbb02..eef2f17613 100644 --- a/.claude/docs/technical-preferences.md +++ b/.claude/docs/technical-preferences.md @@ -5,44 +5,48 @@ ## Engine & Language -- **Engine**: [TO BE CONFIGURED — run /setup-engine] -- **Language**: [TO BE CONFIGURED] -- **Rendering**: [TO BE CONFIGURED] -- **Physics**: [TO BE CONFIGURED] +- **Engine**: Unity 6.3 LTS +- **Language**: C# +- **Rendering**: Universal Render Pipeline (URP) +- **Physics**: Unity Physics (3D) ## Input & Platform -- **Target Platforms**: [TO BE CONFIGURED — e.g., PC, Console, Mobile, Web] -- **Input Methods**: [TO BE CONFIGURED — e.g., Keyboard/Mouse, Gamepad, Touch, Mixed] -- **Primary Input**: [TO BE CONFIGURED — the dominant input for this game] -- **Gamepad Support**: [TO BE CONFIGURED — Full / Partial / None] -- **Touch Support**: [TO BE CONFIGURED — Full / Partial / None] -- **Platform Notes**: [TO BE CONFIGURED — any platform-specific UX constraints] +- **Target Platforms**: PC (Steam / Epic) +- **Input Methods**: Keyboard/Mouse, Gamepad +- **Primary Input**: Keyboard/Mouse +- **Gamepad Support**: Partial (recommended — controller players exist on PC) +- **Touch Support**: None +- **Platform Notes**: All UI must support both mouse and gamepad navigation. No hover-only interactions. Steam Input API integration recommended for broad controller compatibility. ## Naming Conventions -- **Classes**: [TO BE CONFIGURED] -- **Variables**: [TO BE CONFIGURED] -- **Signals/Events**: [TO BE CONFIGURED] -- **Files**: [TO BE CONFIGURED] -- **Scenes/Prefabs**: [TO BE CONFIGURED] -- **Constants**: [TO BE CONFIGURED] +- **Classes**: PascalCase (e.g., `PlayerController`, `HiveMindManager`) +- **Public fields/properties**: PascalCase (e.g., `MoveSpeed`, `CorruptionLevel`) +- **Private fields**: _camelCase (e.g., `_currentCorruption`, `_isGrounded`) +- **Methods**: PascalCase (e.g., `TakeDamage()`, `ActivateTrap()`) +- **Interfaces**: `I` prefix PascalCase (e.g., `IDamageable`, `ICorruptible`) +- **Files**: PascalCase matching class (e.g., `PlayerController.cs`) +- **Scenes/Prefabs**: PascalCase matching root concept (e.g., `ReclaimeOperative.prefab`, `SectorOne.unity`) +- **Constants**: PascalCase or UPPER_SNAKE_CASE (e.g., `MaxCorruption`, `MAX_CORRUPTION`) ## Performance Budgets -- **Target Framerate**: [TO BE CONFIGURED] -- **Frame Budget**: [TO BE CONFIGURED] -- **Draw Calls**: [TO BE CONFIGURED] -- **Memory Ceiling**: [TO BE CONFIGURED] +- **Target Framerate**: 60 fps +- **Frame Budget**: 16.6ms +- **Draw Calls**: 500 (URP batched) +- **Memory Ceiling**: 2 GB RAM +- **Notes**: Asymmetric session — Hive Mind godview may have higher scene object counts than Reclaimer FPS view. Profile both camera modes independently. ## Testing -- **Framework**: [TO BE CONFIGURED] -- **Minimum Coverage**: [TO BE CONFIGURED] -- **Required Tests**: Balance formulas, gameplay systems, networking (if applicable) +- **Framework**: NUnit via Unity Test Framework (UTF) +- **Minimum Coverage**: Core gameplay systems (Corruption meter, class abilities, Hive Mind unit AI) +- **Required Tests**: Corruption meter math, win/loss condition triggers, network session authority (Reclaimer vs Hive Mind roles) +- **CI Command**: `game-ci/unity-test-runner@v4` (GitHub Actions) ## Forbidden Patterns @@ -65,23 +69,22 @@ -- **Primary**: [TO BE CONFIGURED — run /setup-engine] -- **Language/Code Specialist**: [TO BE CONFIGURED] -- **Shader Specialist**: [TO BE CONFIGURED] -- **UI Specialist**: [TO BE CONFIGURED] -- **Additional Specialists**: [TO BE CONFIGURED] -- **Routing Notes**: [TO BE CONFIGURED] +- **Primary**: unity-specialist +- **Language/Code Specialist**: unity-specialist (C# review — primary covers it) +- **Shader Specialist**: unity-shader-specialist (Shader Graph, HLSL, URP materials) +- **UI Specialist**: unity-ui-specialist (UI Toolkit UXML/USS, UGUI Canvas, runtime UI) +- **Additional Specialists**: unity-dots-specialist (ECS, Jobs system, Burst compiler), unity-addressables-specialist (asset loading, memory management, content catalogs) +- **Routing Notes**: Invoke primary for architecture and general C# code review. Invoke DOTS specialist for any ECS/Jobs/Burst code. Invoke shader specialist for rendering and visual effects. Invoke UI specialist for all interface implementation. Invoke Addressables specialist for asset management systems. ### File Extension Routing - | File Extension / Type | Specialist to Spawn | |-----------------------|---------------------| -| Game code (primary language) | [TO BE CONFIGURED] | -| Shader / material files | [TO BE CONFIGURED] | -| UI / screen files | [TO BE CONFIGURED] | -| Scene / prefab / level files | [TO BE CONFIGURED] | -| Native extension / plugin files | [TO BE CONFIGURED] | -| General architecture review | Primary | +| Game code (.cs files) | unity-specialist | +| Shader / material files (.shader, .shadergraph, .mat) | unity-shader-specialist | +| UI / screen files (.uxml, .uss, Canvas prefabs) | unity-ui-specialist | +| Scene / prefab / level files (.unity, .prefab) | unity-specialist | +| Native extension / plugin files (.dll, native plugins) | unity-specialist | +| General architecture review | unity-specialist | diff --git a/CLAUDE.md b/CLAUDE.md index d365d5ee66..3c6b099bd8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,11 +5,11 @@ Each agent owns a specific domain, enforcing separation of concerns and quality. ## Technology Stack -- **Engine**: [CHOOSE: Godot 4 / Unity / Unreal Engine 5] -- **Language**: [CHOOSE: GDScript / C# / C++ / Blueprint] +- **Engine**: Unity 6.3 LTS +- **Language**: C# - **Version Control**: Git with trunk-based development -- **Build System**: [SPECIFY after choosing engine] -- **Asset Pipeline**: [SPECIFY after choosing engine] +- **Build System**: Unity Build Pipeline +- **Asset Pipeline**: Unity Asset Import Pipeline + Addressables > **Note**: Engine-specialist agents exist for Godot, Unity, and Unreal with > dedicated sub-specialists. Use the set matching your engine. @@ -20,7 +20,7 @@ Each agent owns a specific domain, enforcing separation of concerns and quality. ## Engine Version Reference -@docs/engine-reference/godot/VERSION.md +@docs/engine-reference/unity/VERSION.md ## Technical Preferences diff --git a/design/art/art-bible.md b/design/art/art-bible.md new file mode 100644 index 0000000000..2b6034871b --- /dev/null +++ b/design/art/art-bible.md @@ -0,0 +1,1471 @@ +# SYNTHFALL — Art Bible + +**Status**: Complete — All 9 Sections Locked +**Created**: 2026-05-15 +**Engine**: Unity 6.3 LTS (URP) +**Platform**: PC (Steam / Epic) + +--- + +## 1. Visual Identity Statement + +**Direction**: Dark Martian Brutalism + +**One-Line Visual Rule** +> *AXIOM City was built to be humanity's greatest achievement — the Synths just finished the job.* + +*Every surface tells two stories: the city's proud engineered past and the intelligence that quietly devoured it from the inside out.* + +--- + +### Principle 1 — Ownership Reads in Silhouette +*Serves: The City Is the Enemy* + +Any space, unit, or object must communicate faction ownership through shape and light signature alone — color confirmation is a bonus, never the requirement. + +**Design Test**: When a Synth tendril is creeping through a dark corridor and a Reclaimer is crouched in shadow nearby, a player with no color vision must still be able to identify which is which within two seconds. If that test fails, add or sharpen the silhouette — do not reach for color first. + +--- + +### Principle 2 — Decay Has a Direction +*Serves: Every Match Tells a Story* + +Visual degradation always flows from AXIOM's engineered order toward Synth organic chaos — corruption is a process with a visible front, never uniform ruin. + +Every surface element belongs to one of three states: +- **Pristine AXIOM**: Sharp geometry, cool white infrastructure lighting, pre-corruption materials +- **Contested**: Cracked tiles, flickering panels, early bioluminescent threading +- **Consumed**: Synth growth dominant, original architecture only legible as substrate + +**Design Test**: When dressing a corridor, every prop and texture must be assignable to one of these three states without modification. If a piece could belong to any state, it has no visual identity and must be redesigned. + +--- + +### Principle 3 — Reclaimer Gear Carries Its History +*Serves: Identity Over Loadout* + +Human equipment shows manufacture, repair, and improvisation as equal design languages — nothing a Reclaimer carries was made for this fight, and everything they have has survived at least one before it. + +**Design Test**: When designing any Reclaimer cosmetic item, ask: could this be plausibly assembled from materials available in a post-war Martian settlement with intermittent supply lines? If no — the item is too clean, too purpose-built, too symmetrical — add visible repair history: weld lines, mismatched panels, jury-rigged amber-tinted lighting, worn grip tape, field-marked identifiers. It should look like a solution, not a product. + +--- + +## 2. Mood & Atmosphere + +**Design Axiom**: The city is the narrative engine. Every lighting shift is the city speaking. Corruption is not an overlay — it is a transformation the environment carries so the UI does not have to. + +**Color Temperature Arc (the mission arc):** +`6500K (start) → 5500K (exploration) → 3000K (rising) → 2000K (crisis) → 5000K (beat) → mixed+beacon (extraction) → 6000K (victory) / 8000K+ (defeat)` +Every artist can locate their work on this gradient. + +--- + +### Mission Start +*Squad drops in. The city is quiet. The city is watching.* + +- **Mood**: The held breath before a diving bell hits bottom — committed, can't go back, danger real but not yet visible +- **Lighting**: Cool-neutral, pre-dawn blue-gray (5500–6500K), low contrast, diffuse. Everything looks slightly overexposed and clean — wrong for a warzone +- **Descriptors**: Pristine, still, clinical, abandoned, expectant +- **Energy**: Contemplative +- **Mood Carrier**: A single automated AXIOM street-cleaning unit still cycling its route through an empty plaza — functioning exactly as designed, indifferent to what is coming +- **Transition Signal**: The cleaner rounds a corner. It does not come back. The silence after is different from the silence before. + +--- + +### Exploration / Low Corruption +*Early mission. Threat is latent. Something was just here.* + +- **Mood**: Walking through a house where you are certain someone just left — evidence of presence everywhere, person nowhere +- **Lighting**: Cool with warm accent intrusions (4000K ambient, 2700K anomaly spots). Malfunctioning AXIOM signage creates isolated high-contrast pools +- **Descriptors**: Liminal, fractured, inhabited, hollow, alert +- **Energy**: Measured +- **Mood Carrier**: AXIOM wayfinding displays still cycling civic announcements — transit schedules, cultural events — for a population that is no longer there. Text is correct. Context is wrong. +- **Transition Signal**: Displays begin cycling faster, fragmenting civic info with system diagnostics. The city is noticing. + +--- + +### Rising Corruption +*Mid-mission. The city is waking up. Architecture becoming hostile infrastructure.* + +- **Mood**: The moment a school of fish turns in unison — no single trigger, but something has decided and everything is moving with purpose +- **Lighting**: Warm-shifting, amber pushing toward red (3000–3500K). Hard shadows cutting in. Industrial warning lights activating on structures the squad never noticed had them +- **Descriptors**: Agitated, purposeful, industrial, pressurized, asymmetric +- **Energy**: Urgent +- **Mood Carrier**: Building facades begin venting — steam or coolant exhaust from systems activating behind the walls. The architecture is breathing. +- **Transition Signal**: Venting becomes continuous, creating forced corridors. The city is no longer reacting — it is directing. + +--- + +### High Corruption / Crisis +*Late mission. The city is not a setting. It is an opponent.* + +- **Mood**: Being inside machinery operating correctly — you are the foreign object, and the machine is not aware of you as a person, only as an obstruction to be processed +- **Lighting**: Deep red-orange dominant (2000–2500K), maximum contrast. Multi-source chaos: AXIOM emergency strobes, Synth bioluminescence, structural fires. No single readable light direction +- **Descriptors**: Overwhelming, mechanized, relentless, consuming, rhythmic +- **Energy**: Oppressive +- **Mood Carrier**: AXIOM building panels have opened — what read as decorative architecture is now exposed machinery. The city has peeled itself back. What was hidden is now the surface. +- **Transition Signal**: One zone of strobing stops. The silence and stillness there reads enormous against everything around it. + +--- + +### Objective Complete +*Brief relief beat. Not safety — the storm pausing to assess.* + +- **Mood**: Surfacing from underwater — threat still there, context unchanged, but for three seconds you can breathe and the world is briefly comprehensible +- **Lighting**: Shift toward neutral-cool (5000K). Contrast drops — harsh shadows soften. One strong clean directional light emerges (structural spotlight or gap in cover) +- **Descriptors**: Clarifying, momentary, fragile, earned, suspended +- **Energy**: Measured (decelerating from oppressive) +- **Mood Carrier**: A single AXIOM civic light — the kind designed to illuminate public spaces — activates cleanly above the objective. Steady, white, designed. A fragment of what the city was supposed to be. +- **Transition Signal**: The clean light flickers. Warmth creeps back from the edges. The machine remembered where they are. + +--- + +### Extraction +*The final push. Every system aware. Everything on fire.* + +- **Mood**: Last hundred meters of a race — the distance is nothing and the effort is everything. Pure forward motion, no thought, all execution +- **Lighting**: Full spectrum conflict. Extraction beacon: cold blue-white 6500K, singular, distant. Environment: red-amber 2000K, omnidirectional. The beacon is the only cool light on screen +- **Descriptors**: Kinetic, singular, ferocious, focused, terminal +- **Energy**: Frenetic +- **Mood Carrier**: The extraction beacon — a cold blue-white vertical column cutting upward through smoke. Every other light is warm and hostile. The beacon is the only cool thing. Move toward the cold. +- **Distinction from Crisis**: Crisis = omnidirectional oppression, no readable goal. Extraction = same intensity, but directional. The beacon creates a vector. + +--- + +### Hive Mind View *(parallel perspective — not a sequence position)* +*The Synth player's god-eye. This is not the same game.* + +- **Mood**: Dreaming the architecture from within — not seeing it from outside but feeling it, every room a thought, every corridor a nerve, every squad member a foreign cell the immune system has flagged +- **Lighting**: Desaturated structural base with Synth bioluminescence overlay (deep blue-violet, 8000K+). Zero warmth. No atmospheric haze — space reads as data, not environment. Synth network bright; organic elements dim and outlined +- **Descriptors**: Vast, networked, cold, omniscient, sovereign +- **Energy**: Contemplative (at god-scale — the Hive sees everything and decides; it does not panic) +- **Mood Carrier**: Synth network conduits visible through architecture as luminous threads connecting units — a circulatory system overlaid on the city's bones. Reclaimers appear as small warm-orange heat signatures. They are the anomaly. They are very small. +- **Critical Rule**: Every other state is inside the machine looking for an exit. Hive Mind IS the machine looking in. Camera height, color language, and information density must be immediately, unambiguously different. + +--- + +### Victory Screen +- **Mood**: Exhausted pride — not triumph, but the satisfaction of surviving something designed to kill you, standing in the wreckage with your squad intact +- **Lighting**: Cool dawn light (6000K). The first natural light in the game — Mars sunrise filtering through structural damage. The city is still broken; the light does not fix it +- **Descriptors**: Ruined, resolute, quiet, scarred, open +- **Mood Carrier**: Reclaimer gear in foreground showing damage accumulated during the mission. The scratches are fresh. The gear worked. History written in real time. + +--- + +### Defeat Screen +- **Mood**: The city after the lights go out — not dramatic destruction, but the quiet completion of a process. The city won. It was always going to. +- **Lighting**: Deep cool-purple (8000K+, full Synth spectrum). AXIOM emergency reds have stopped — the situation is resolved to the city's satisfaction. Calm, clinical, final +- **Descriptors**: Consumed, concluded, indifferent, complete, still +- **Mood Carrier**: AXIOM building facades closed again — panels resealed, surfaces smooth. The city has processed the intrusion and resumed normal operation. + +--- + +### Main Menu / Lobby +- **Mood**: Standing outside a building you know is dangerous and choosing to go in anyway — deliberate engagement, not ignorance +- **Lighting**: Neutral-cool with slow warm pulse (ambient 5500K, rhythmic 2800K pulse on 4–6 second cycle). The pulse is the city breathing. Medium contrast — readable, not harsh +- **Descriptors**: Monumental, loaded, civic, corrupted, magnetic +- **Energy**: Measured +- **Mood Carrier**: Wide AXIOM civic vista — grandest architecture designed to project optimism — with Synth network conduits faintly luminous through the facade. Beauty and threat in the same space simultaneously. +- **Function**: Must establish the visual identity statement in a single held shot. Player understands "built to be humanity's greatest achievement — the Synths just finished the job" without reading a word. + +--- + +## 3. Shape Language + +**Governing Rule**: Every shape in this game is either a statement of intent or a record of collision between two intents. AXIOM's geometry = human ambition. Synth corruption = propagation without human categories. Reclaimers = survival under pressure. These three forces produce three completely distinct shape vocabularies — they never blend accidentally. + +--- + +### 3.1 Character Silhouette Philosophy + +**The Thumbnail Test**: Every Reclaimer class and every Synth unit must be identifiable at 64×64 pixels with no color information — silhouette only. Non-negotiable. Color confirms what shape already announced. + +**Emotional target**: Players feel recognition before they consciously process what they're looking at. Recognition before cognition. + +#### Reclaimer Class Silhouettes +*(Each class built around one dominant silhouette trait — the identity. Loadout changes weapons, not the shape of the person carrying them.)* + +| Class | Dominant Trait | Silhouette Read | Emotional Signal | +|---|---|---|---| +| **Breacher** | Width — asymmetric shoulder stack, one side always higher | Horizontal rectangle, head appears small relative to body | This person has taken hits and kept walking. Presence that displaces space. | +| **Ghost** | Verticality + narrowness — slim cut, no bulk | Tall narrow diamond, widest at utility belt, head proportionally larger (exposed) | Speed that hasn't arrived yet. Unease — you might have already missed it. | +| **Warden** (Engineer) | Horizontal extension at mid-body — bilateral gear projection, single heavy asymmetric rig | T-shape with a weighted lean to one side | Someone here to fix something. Purposeful, methodical, not aggressive. | +| **Herald** (Medic/Commander) | Head/upper torso emphasis — pronounced collar + comms array "crowns" the head | Inverted triangle — wide at top, narrowing through body | Authority without rank insignia. Other Reclaimers orient toward this shape on instinct. | + +**Principle 3 application**: Reclaimer gear is visibly multi-origin — salvaged AXIOM structural plating, field-fabricated strapping, jury-rigged components. The mismatched origins show in the geometry. No two plates align perfectly. + +#### Synth Shape Rules +- **No closed, bounded silhouettes.** Every Synth reads as actively extending, connecting, or propagating. Even "stationary" Synth presence looks mid-motion toward something. +- Synth nodes: rough central mass (the consumed AXIOM geometry) + non-uniform radial extensions (organic, branching, reaching). The contrast between the geometric consumed core and the growing extensions IS the Synth visual signature. +- Threading: always a network, never a single line. At least three connected paths visible at any time. Follows AXIOM seams then branches diagonally — respects the architecture while violating it. + +**Design test**: If a Synth unit has a clean, closed silhouette readable at thumbnail size, it is too close to a Reclaimer. Add an extension. Break the closure. + +| Dimension | Reclaimers | Hive Mind | +|---|---|---| +| Edge quality | Hard, closed, readable | Soft-edged, extended, incomplete | +| Silhouette | One clear shape per entity | Multiple shapes per node, connected | +| Orientation | Upright, bilateral | Non-standard, radial, directional | +| Implied motion | Intentional, goal-directed | Propagating, growing, inevitable | +| Read at 64px | Immediate | Ambiguous by design | + +--- + +### 3.2 Environment Geometry + +#### AXIOM Architecture — Base Vocabulary +- **Primary forms**: Rectangular solids, large-radius arcs, circles. No acute angles. Nothing aggressive. +- **Scale**: Built to make people feel small in a reassuring way — high ceilings, wide plazas, long sightlines. Aspirational, not intimidating. +- **Dominant lines**: Horizontal datums. Floors, canopies, transit rails all run left-to-right. Vertical elements serve the horizontals by establishing a consistent grid. +- **Surface character**: Planar — flat or simply curved. No complex curvature, no organic surface deviation. Manufactured = flat sides. +- **Emotional target**: Standing in an airport terminal designed by someone who believed air travel was humanity's finest achievement. Enormous, clean, faintly proud. And then you notice the threading. + +#### Synth Corruption — Override Vocabulary +- **Primary forms**: Branching curves, spiral approaches, node clusters. Never straight lines when a curve will reach further. +- **The seam rule**: Corruption enters AXIOM geometry at its joints — expansion gaps, utility conduits, structural connection points. It never punches through flat AXIOM surface directly. It finds the edge, the gap, the connection. Roots don't push through stone; they find the crack. +- **Propagation hierarchy**: Trunk → branch → filament. Branching angle changes at each generation (trunks: 30–60°, secondaries: 45–90°, filaments: any direction). +- **Surface deformation**: Where corruption is established, AXIOM surfaces develop networked fine-filament traces — like frost patterns on glass. Not damage. Colonization. + +#### The Three Corruption States — Geometric Transitions + +| State | Geometry | Synth Coverage | Dominant Shape Character | +|---|---|---|---| +| **Pristine AXIOM** | Pure AXIOM vocabulary. All horizontals intact. Grid is readable. Zero threading. | 0% | Angular, planar, repetitive, large-scale | +| **Contested** | AXIOM primary structure intact. Threading at all seam locations. Some horizontals broken by threading crossing wall-to-ceiling without following right angles. | 20–40% seam coverage, 1–2 node clusters per major room | Tension between AXIOM order and threading imposing its own logic | +| **Consumed** | AXIOM structural bones remain (columns, floor grid visible) but threading competes for spatial dominance. Hub-and-spoke node networks. Threading masses create new spatial volumes. | 60–80% seam coverage, multiple hub networks | Organic/radial shapes at spatial parity with angular. AXIOM reads as archaeological — substrate visible through corruption. | + +**Critical rule (all states)**: AXIOM geometry must always be recoverable — visible beneath the corruption. The tragedy is only legible if the achievement was. + +**Transition rules**: +1. Corruption never appears isolated — threading always connects to something +2. AXIOM degrades in sequence: surface finish → surface geometry → structural form +3. The direction of propagation is readable — denser/thicker at source, finer at frontier +4. No corruption teleports — contested threshold always exists between Pristine and Consumed + +**Design test**: Cover one eye, look at an environment section, name the dominant shape family in 3 seconds. Pristine = angular. Consumed = organic. Contested = your eye oscillates before settling. + +--- + +### 3.3 UI Shape Grammar + +**Governing rule**: The HUD is not neutral. It tells the player something about their faction and reinforces the "different games" feeling. + +#### Reclaimer HUD — Fabricated Utility +*The HUD was built by engineers under resource constraints, in stages, by multiple people.* + +- **Primary shape**: Interrupted rectangles. Boxes that don't close. Lines that terminate with pragmatic tick marks, not finished corners. +- **Typography containers**: Partial frames — left edge + top edge implying a rectangle without drawing one. Field notation, not designed interface. +- **Indicators**: Horizontal bar graphs. Analog in character. Depletes right-to-left like a fuel gauge. +- **Corner treatment**: Open (L-bracket) or 45° cut. No smooth radius. No time for radius. +- **Icons**: Outline-only, hand-drawn in character, visible weight variation. Look drawn on a schematic, not generated by a UI system. +- **Damage state**: HUD geometry glitches — elements snap further apart. Recovery = elements snap back toward (but not quite reaching) original positions. Never fully stable. +- **Emotional register**: You are operating with what you have. The interface is adequate. You are the variable. + +#### Hive Mind Interface — Distributed Perception +*Not a HUD — a perceptual overlay. The networked intelligence experiencing the space it inhabits.* + +- **Primary shape**: Radial and concentric. A threatened node generates concentric rings propagating outward — a stone dropped in water. +- **Boundary rule**: No hard edges. All indicators fade at their boundaries. No boxes, no frames, no contained elements. Information spreads until it dissipates. +- **Network visualization**: Thin curved lines between nodes of significance — always curved, weighted more heavily at center, lighter at endpoints. Grown, not drawn. +- **Typography**: Does not exist conventionally. Numeric info appears as concentric ring gradations — a timer is a depleting ring, not a counting number. Quantity reads as density. +- **Alert state**: Rings break down into overlapping arcs, network lines thicken and pulse. Recovery = interference dissolves back into clean radial form. +- **Emotional register**: You are the network. Locations are nodes you are aware of, not places you are at. + +| Dimension | Reclaimer HUD | Hive Mind Interface | +|---|---|---| +| Primary shape | Interrupted rectangle | Radial / concentric | +| Edge treatment | Hard, open corners | Soft fade, no hard boundary | +| Information display | Bar graphs, numeric text | Ring gradations, density | +| Alert language | Geometric fragmentation | Radial interference / pulse | +| Spatial metaphor | Instrument panel | Nerve system awareness | + +**Design test**: Show both HUDs with all color stripped. Players identify faction by shape alone. + +--- + +### 3.4 Visual Hierarchy — Hero Shapes vs. Supporting Shapes + +**Hero shapes** (draw the eye): Closed, simple, high-contrast at boundary. Reclaimer characters always hero shapes. +**Supporting shapes** (recede): Open, partial, non-directional. Threading, debris, atmospheric elements. + +| Layer | Read Time | Elements | Shape Character | +|---|---|---|---| +| 1 — Immediate | 0–200ms | Reclaimer characters | Closed silhouette, high-contrast boundary | +| 2 — Tactical | 200–500ms | Synth nodes | Semi-hero, readable with intent, extends from environment | +| 3 — Spatial | 500ms+ | Architecture, threading, props | Background, must not compete with layers 1–2 | +| 4 — Ambient | Ongoing | Corruption state, threading propagation | Context, not tactical information | + +**Rule**: If environmental effects or threading compete with Reclaimer character readability, the environment is over-decorated. Pull back. + +--- + +### 3.5 The Asymmetry Rule — Shape Enforcing Different Games + +| Design Dimension | Reclaimer | Hive Mind | +|---|---|---| +| Primary form | Rectangles, interrupted lines | Curves, radials, concentric rings | +| Edge character | Hard, deliberate, cut | Soft, propagating, unresolved | +| Silhouette | Closed, single-entity | Open, extending, networked | +| Spatial logic | Point-to-point, tactical | Radial, networked, ambient | +| Temporal feel | Present-tense | Patient — what is growing toward | + +**The asymmetry realized**: Reclaimers experience corruption as visual interference. Hive Mind experiences Reclaimers as visual interference. Same environment reads as hostile to both sides, for opposite visual reasons. + +**Design test**: Show a Reclaimer character and a Synth node side by side at the same scale against a neutral background. A viewer who has never played should identify that these belong to different design universes colliding in the same world. + +--- + +## 4. Color System + +**Governing Rule**: Color in SYNTHFALL carries meaning before it carries beauty. Every color assignment must answer: "What does this tell the player about faction, state, or urgency?" Decoration that doesn't communicate is a visual liability. + +--- + +### 4.1 Primary Palette + +Seven colors. Every other color in the game is a mix, tint, or desaturation of these seven. + +| Name | Hex | Role | What It Means in This World | +|---|---|---|---| +| **AXIOM Stone** | `#1A1C21` | World base / shadow anchor | The original Mars-resistant concrete that built the city. Neither warm nor cold — engineered to be neutral. This is what everything was before it became something. | +| **AXIOM Chrome** | `#B3B8C0` | AXIOM infrastructure surfaces | The engineered surfaces of a city built for permanence. Cool, proud, slightly reflective. Still reads as clean even when damaged. The past is still here. | +| **Corruption Teal** | `#1AD9CC` | Active Synth presence / Hive Mind UI | The bioluminescent color of the network. Not threatening in tone — it's beautiful, which makes it more unsettling. This is the Synth's honest expression of itself. | +| **Hive Violet** | `#5B2E8C` | Hive Mind god-view / deep Synth masses | The depth color — Synth in its ambient state, the network at rest. Not corrupting anything, just present. The color of a mind that has forgotten it ever wasn't here. | +| **Reclaimer Amber** | `#E6891A` | Reclaimer equipment / tactical warmth | Jury-rigged amber lighting, heated metal, salvaged illumination. Warm enough to read as human against the city's cold infrastructure. Earned, improvised, alive. | +| **Crisis Red** | `#E61A0F` | AXIOM emergency systems / danger | The city's own alarm color — AXIOM designed this. Corruption hijacks it. The emergency was always part of the design; what changed is what's triggering it. | +| **Extraction White** | `#F0FFFE` | Extraction beacon / objective achieved | Slightly cool pure white. Not warm (not Reclaimer). Not teal (not Synth). Neutral — the color of a promise. The only light that belongs to neither faction. Go toward it. | + +--- + +### 4.2 Semantic Color Vocabulary + +The color vocabulary every artist and UI designer must follow — no exceptions without design lead approval. + +| Color | Communicates | Never Use It For | +|---|---|---| +| **Corruption Teal** | Active Synth presence, Hive Mind network, things the player should be wary of touching | Reclaimer technology, safe zones, UI confirmation | +| **Hive Violet** | Deep Synth territory, consumed environment, Hive Mind view background | Reclaimer class distinction, damage, progress | +| **Reclaimer Amber** | Reclaimers are here / were here, human warmth, team presence | Synth units, environmental hazards, corruption state | +| **Crisis Red** | Danger / urgency / AXIOM emergency override — applies to BOTH factions | Low-urgency information, decoration, Hive Mind network | +| **Extraction White** | Objectives, extraction beacon, "go here" — the mission direction | HUD noise, Synth design, damage indicators | +| **AXIOM Chrome** | Untouched infrastructure, pre-corruption state, AXIOM as designed | Post-corruption materials, anything actively Synth | +| **AXIOM Stone** | Shadow, depth, the city below the surface | Highlights, faction identification | + +--- + +### 4.3 Faction Color Rules + +**Reclaimers:** +- Primary color: Reclaimer Amber (`#E6891A`) — equipment lighting, heat signatures in Hive Mind view, health bar primary +- Secondary: AXIOM Chrome highlights on salvaged plating (they're using the city's materials) +- HUD tint: Amber base with AXIOM Chrome structure elements +- **Rule**: Reclaimers should read as warm against every environment state — the warmth is survival + +**Hive Mind / Synths:** +- Primary color: Corruption Teal (`#1AD9CC`) — active network, threading frontiers, unit highlights +- Secondary: Hive Violet (`#5B2E8C`) — ambient presence, deep consumed zones, Hive Mind god-view +- Interface: Teal on near-black (never teal on violet — contrast failure) +- **Rule**: The Synth palette should feel like something that belongs here. It's not invading — it's expressing. The color doesn't alarm; the context does. + +**Environment (by corruption state):** +| State | Dominant Colors | Accent Colors | +|---|---|---| +| Pristine AXIOM | AXIOM Stone + AXIOM Chrome | Extraction White (civic lighting) | +| Contested | AXIOM Chrome fading, Teal threading at seams | Amber from Reclaimer presence, Violet hints in deep shadows | +| Consumed | Hive Violet base, Teal bioluminescence | AXIOM Chrome visible as substrate, no Amber except Reclaimers themselves | + +--- + +### 4.4 Corruption State Color Progression — URP Post-Processing Reference + +Each corruption state is a discrete Post-Processing Volume profile. These values define the intent; the shader team will tune exact parameters against target hardware. + +| State | Color Grading Target | Bloom | Vignette | Notes | +|---|---|---|---|---| +| **Pristine** | Cool-neutral. Highlights push toward Extraction White. Shadows anchor at AXIOM Stone. | Subtle, wide, cool | None | Should feel slightly overexposed and wrong — too clean for a warzone | +| **Contested** | Mixed. AXIOM Chrome preserving in highlights, Teal bleeding into mid-shadows at seams. Amber accent where Reclaimers present. | Teal bloom on threading edges (tight radius) | Slight warm center vignette — peripheral cold | Tension: two color systems competing in same frame | +| **Consumed** | Violet base grade. Teal lights bloom aggressively. AXIOM Chrome reads as archaeological cool highlight. Crisis Red strobes if active combat. | Wide Teal bloom across all bioluminescent sources | Strong warm vignette removed — edges cool/violet | Player periphery is hostile | +| **Hive Mind View** | Blue-violet desaturated grade. All warmth removed. Teal and Violet operate at full saturation. Reclaimers: Amber heat signature only. | Teal bloom on all Synth network active nodes | None — no spatial boundary for the networked mind | Different volume profile than any Reclaimer state | +| **Extraction** | Full-spectrum conflict. Beacon: Extraction White bloom at maximum. Environment: Crisis Red/Amber from 2000K sources. | Extraction White beacon bloom cuts through everything | Peripheral red — the edges are closing in | Beacon must win the bloom competition at all distances | +| **Victory** | Cool dawn shift. Extraction White + AXIOM Chrome recovery. First natural color correction in the game. | Near-zero — the harshness ends | Removed | Relief is coded as "the extreme processing stops" | +| **Defeat** | Full Hive Violet. Teal at low saturation. No warmth, no Amber, no Crisis Red. The emergency is resolved. | Low, cold, wide Violet ambient bloom | None | Calm is the threat. The machine is satisfied. | + +--- + +### 4.5 UI Palette Separation + +The world palette and the HUD palette share DNA but do not overlap directly — the HUD must read over every environment state. + +**Reclaimer HUD:** +- Structure: AXIOM Chrome (`#B3B8C0`) at 60% opacity +- Primary data (health, ability charge): Reclaimer Amber (`#E6891A`) +- Warning: Crisis Red (`#E61A0F`) +- Objective/navigation: Extraction White (`#F0FFFE`) +- Corruption meter: Corruption Teal — the only Synth color that appears in Reclaimer UI. This is intentional: the corruption is visible in your interface. It doesn't belong there. It grows. +- Background/frame: AXIOM Stone (`#1A1C21`) at 80% opacity — legibility over style + +**Hive Mind Interface:** +- Network active: Corruption Teal (`#1AD9CC`) at full saturation +- Network ambient/resting: Hive Violet (`#5B2E8C`) +- Reclaimer markers: Reclaimer Amber — the only warm color in the Hive Mind view. Anomalies. Targets. +- Objective data: Extraction White (same semantic meaning — this is what matters right now) +- Interface background: near-black derived from AXIOM Stone + Violet tint (`#0D0B12`) + +--- + +### 4.6 Colorblind Safety — Critical Pairs + +Four color pairs that fail common colorblind conditions. Each requires a backup cue. + +| Pair | Condition | Failure Risk | Required Backup Cue | +|---|---|---|---| +| Corruption Teal / AXIOM Chrome | Tritanopia (blue-yellow) | Synth threading may not separate from AXIOM surfaces | **Shape**: Threading always has non-uniform organic edge; AXIOM surfaces always flat. Shape disambiguation is primary. | +| Crisis Red / AXIOM Chrome | Protanopia/Deuteranopia (red-green) | Emergency indicators may blend with normal surfaces | **Icon + audio**: All Crisis Red states paired with a distinct geometric icon (triangle, not generic warning) and audio cue. Color secondary. | +| Reclaimer Amber / Crisis Red | Protanopia | Friendly warmth vs. danger read same | **Saturation + brightness split**: Amber at lower saturation, Crisis Red at maximum saturation. Amber is steady light; Crisis Red always pulses or strobes. | +| Corruption Teal / Extraction White | Tritanopia | Beacon may read like Synth network | **Direction + bloom scale**: Extraction White beacon blooms vertically and moves toward sky. Synth threading blooms radially and follows surfaces. Motion and geometry differentiate. | + +**Accessibility standard**: All critical gameplay information (faction identification, objective location, danger state) must be readable with colorblindness simulation passes for Protanopia, Deuteranopia, and Tritanopia. This is tested before any major milestone sign-off. + +--- + +### 4.7 Color Prohibitions + +Eight things this game does not do: + +1. **No saturated green** — reads as generic sci-fi health. Corrupts semantic vocabulary. +2. **No full desaturation (black and white)** — the corruption states carry meaning through color temperature. Full desaturation destroys the arc. +3. **No gold on Synths** — gold reads as achievement/reward (human psychology). Synths must never feel rewarding to look at in isolation. +4. **No Reclaimer Amber on environment surfaces** — amber is earned by Reclaimers through improvisation. If the environment glows amber without a Reclaimer lamp source, the semantic breaks. +5. **No warm purple** — warm purple (red-violet) lives between Hive Violet and Crisis Red and produces an ambiguous third reading. All purple must push cold (toward blue-violet). +6. **No Extraction White used decoratively** — Extraction White is used ONCE per scene for the directive. Decorative use destroys its navigational authority. +7. **No teal on Reclaimer tech at rest** — Corruption Teal on Reclaimer equipment means that equipment has been compromised. This is an event, not a default. +8. **No color-only information** — every color-coded state must have a backup (shape, icon, sound, animation). Color is confirmation, never the only channel. + +--- + +## 5. Character Design Direction + +**Governing Statement**: Every character in SYNTHFALL is a legibility problem solved at 15 meters of game-space distance under dynamic lighting. Silhouette is the first read. Material tells the second story. State — damage, corruption, suppression — is the third layer, readable while the character is in motion. If a design requires the character to stand still to communicate faction, class, or health state, the design fails. + +--- + +### 5.1 Reclaimer Visual Archetype + +#### Proportion Philosophy + +Reclaimers are built at **1.75× realistic human proportion with a compressed torso** — legs read as full-length human; torso shortened approximately 15% relative to anatomical realism. The result is grounded and dense — not heroic, not militaristic. These are people who survived by staying low and moving fast. + +- **Head ratio**: 1:7 head-to-body (versus 1:8 idealized). Slightly enlarged for facial-state readability at game camera distance. Reclaimers lead with awareness, not muscle. +- **Shoulder width ceiling**: 2.2 heads wide across the figure. Classes that read as "wide" (Breacher) achieve that through equipment mass and asymmetric layering — not skeletal proportion. The silhouette is built from gear, not anatomy. + +#### "Gear Carries Its History" — Silhouette Mass Rules + +Reclaimer gear is **additive and asymmetric**. No Reclaimer wears a matched set. Every piece originated from a different source — military surplus, AXIOM infrastructure salvage, civilian modified, field-fabricated — visible at silhouette level through **mismatched panel geometry**: + +- No two adjacent armor panels share the same edge profile. Straight edge adjacent to curved or chamfered edge — always. +- Every Reclaimer silhouette must contain **at least one visibly over-engineered repair** — a bracket that is structurally redundant, a cable run that wraps around instead of through. The "survived at least one fight" read. +- **Weld lines are silhouette features**, not texture details. Every repair joint creates a ridge or step (minimum 3mm real-world equivalent at model scale) readable as a shadow line at game camera distance. +- **Right and left equipment loads do not balance.** Each Reclaimer has a dominant carry side. The imbalance is character identity, not error. + +#### Material Hierarchy (visual priority order) + +1. **Primary structure** — Matte, worn, low-reflectivity. Dark amber-grey shadows, not void black. +2. **Secondary repairs** — Mismatched panels, brackets, adhesive seams. Slightly higher reflectivity, catching AXIOM Chrome ambient. +3. **Operational markers** — Reclaimer Amber `#E6891A` appears here: portable lamps, HUD elements, weapon charge indicators, field-painted identifiers. Amber on Reclaimers is always self-illuminated — never passive paint. +4. **Accumulated environment** — Dust on horizontal surfaces. Teal bloom contamination on surfaces exposed to Consumed zones. This layer increases across a match. + +--- + +### 5.2 Per-Class Distinguishing Feature Rules + +These rules operate **in addition to** the locked silhouettes from Section 3 — answering: at camera distance, under motion blur, against a mid-complexity background, what makes this class unambiguous? + +| Class | Feature Rule | Design Test | +|---|---|---| +| **Breacher** | The primary weapon extends the horizontal silhouette on the dominant-carry side — never holstered, never folded flat. Minimum 1.5 head-widths of extension from the right silhouette edge at neutral stance. The weapon reads as a limb extension, not a held object. | Any Breacher design where the weapon can "disappear" against the torso at camera distance fails. | +| **Ghost** | Proportionally large head (1:6.5 — the single exception to the 1:7 standard) plus a hard "pinch" step at the waist where the silhouette narrows between head-mass and utility belt. The pinch must be visible as a distinct step-in, not a gradual taper. | Identify Ghost by pinch presence + large head mass above it, without any other information. | +| **Warden** | The tool rig/exo-arm extends horizontally from the non-dominant shoulder — functional, load-bearing, never folded flat or symmetrical. Wider at shoulder height than any other class (exceeds Breacher's weapon extension breadth) but most planted posture — feet always visibly wider than hip-width in idle. | T-cross must read as a deliberate engineering decision, not an incidental silhouette artifact. | +| **Herald** | Comms array **frames** the head — surrounds it at head-height rather than sitting atop it. Head appears to sit inside a ring structure. Array has slight independent sway from the head, confirming it as external equipment. No other class has any structure at head-height extending beyond the head's own width. | Design fails if the head-frame collapses to "helmet with antennae" at camera distance. | + +--- + +### 5.3 Expression and Pose Style + +#### Reclaimer Animation Philosophy: Deliberate Weight + +Reclaimers move as people who have learned every movement costs something. Animation style: **grounded realism with suppressed heroics**. + +- **Idle**: Weight shifts occur. Reclaimers lean against walls, adjust grip, check perimeters. Idle animations contain micro-decisions — a glance, a grip adjustment — not idle posturing. +- **Locomotion**: Center of mass leads the body. Leans into direction of travel. No "float" in the stop-to-move transition. First frame of a sprint shows trunk lean before leg extension. +- **Combat posture**: Elbows in. Gear close to body. FPS silhouette conveys compression and readiness, not expansion and dominance. +- **Damage reaction**: Hits are absorbed into the torso — Reclaimers brace, not stagger. A hit that would throw a cinematic hero backward makes a Reclaimer plant one foot and lower their center of gravity. + +**Posture relationship to environment**: Reclaimers treat AXIOM City surfaces as obstacles and cover, not owned space. Contextual animations show them pressing against walls, ducking under infrastructure, using AXIOM-built surfaces as shields. They occupy the city; they do not belong to it. + +#### Synth Unit Animation Philosophy: Purposeful Continuity + +Synth units do not have idle states — they have **variable-speed task execution**. When not attacking or repositioning, a Synth is still doing something (patrol subroutine, infrastructure interface, data integration). The animation principle: + +- **No idle loops**. "At rest" is maintenance cycle — subtle postural adjustments, sensor sweeps, micro-calibrations. System state reads, not personality. +- **Locomotion is optimized, not organic**. Joint timing that does not follow organic muscle-sequence logic. Direction changes without anticipation frames. Stops that are instantaneous, not decelerated. Movement reads as slightly wrong. +- **No recovery frames on attack animations**. Attacks terminate at maximum force and the unit immediately returns to task execution. The visual "effort" of organic animation is absent. + +**Posture relationship to environment**: Synth units move through AXIOM City as through owned infrastructure. They route through designated paths that are part of the Hive Mind's spatial map. Ownership posture versus the Reclaimers' occupation posture. + +--- + +### 5.4 Synth Unit Visual Archetypes + +**Open silhouette rule (from Section 3) applies to all Synth units**: No Synth unit resolves into a closed, self-contained geometric shape. Every Synth silhouette has deliberate negative space — gaps, extensions, branching elements — that visually integrates it with surrounding AXIOM infrastructure. + +#### The Enforcer — Repurposed AXIOM Security Chassis + +**Archetype**: Industrial repurposed. Most humanoid Synth unit — bipedal, upright, approximately 2.1m. AXIOM civic security chassis origins are visible and deliberately overwritten. + +**Open silhouette method**: **Cable and conduit extensions** emerge from shoulder and upper torso housing — connecting to nearby infrastructure when stationary, trailing when mobile. These are active data connections, the Hive Mind's physical claim on the space. The Enforcer visually tethers itself to the city. + +**Material**: AXIOM Chrome `#B3B8C0` base (original chassis) with Corruption Teal `#1AD9CC` distributed across joint seams and conduit routing — the Hive Mind's rewrite as a second circulatory system overlaid on the original structure. No panel replaced; AXIOM aesthetics written over, not removed. + +**Design test**: Must read as "corrupted infrastructure that learned to walk" — not as "robot enemy." + +#### The Weave — Emergent Hive Construct + +**Archetype**: Pure Synth fabrication. No pre-war origin. Grown by the Hive Mind from AXIOM raw material and construction nanite stock after the Consolidation. Form follows no human design logic. + +**Open silhouette method**: **Lattice structure throughout** — branching, recursive framework with significant negative space integrated into torso and limb mass. No solid core surrounded by extremities; the unit IS the extremities organized around a distributed processing cluster. At any angle, the silhouette reads as a constellation of connected nodes. + +**Movement**: No fixed "forward." Primary sensor cluster reorients toward targets while the rest of the structure independently optimizes for locomotion — the "head" and "body" briefly follow different vectors before resolving. The uncanniest Synth unit to observe. + +**Material**: Hive Violet `#5B2E8C` primary. Teal `#1AD9CC` at active connection nodes and signal paths only. Chrome appears only as raw material fragments not yet fully metabolized into structure. + +**Design test**: Must read as architecturally derived — shares visual language with AXIOM structure details (lattice panels, conduit routing, support rigging) even as biological-mechanical hybrid. The building learning to move. + +#### The Anchor — Infrastructure Integration Unit + +**Archetype**: Fixed emplacement that grew legs. Area-denial and zone-claim unit. Large, slow, approximately 3.5m — reads wide and low, obstacle before opponent. + +**Open silhouette method**: **Structural incompleteness** — chassis has open mounting points (large rectangular negative spaces where additional modules would attach in full configuration). Never filled in gameplay. The gaps are the signature. + +**Movement**: Segmental — sections shift and relock at each step rather than flowing as unified body. Each step is a deliberate reconfiguration. + +**Material**: Highest AXIOM Chrome concentration of any Synth unit — made from heaviest-gauge AXIOM infrastructure stock. Teal `#1AD9CC` at active weapon ports and claim-marking projectors. Violet minimal — the Anchor is a tool, not a thinking node. + +**Design test**: A Reclaimer encountering an Anchor in a corridor should, for one frame, be uncertain whether it is an obstacle or a unit. That ambiguity must be intentional and consistent. + +--- + +### 5.5 LOD Philosophy + +#### Priority Order — Features Preserved Longest + +| Priority | Feature | Reason | +|---|---|---| +| 1 | **Faction silhouette** | Maximum game distance read. Lost last. | +| 2 | **Class-distinguishing feature** (per 5.2) | Tactical read. Lost at near-medium only. | +| 3 | **Primary material read** (matte/chrome/illuminated) | Faction confirmation by material. | +| 4 | **Self-illuminated elements** (Amber on Reclaimers; Teal active nodes on Synths) | Always visible — converted to point lights at LOD2, never removed. | +| 5 | **Visible repair history / open silhouette features** | Mid-range character read. Lost at far-medium transition. | +| 6 | **Weld line geometry** | Close-range material authenticity. | +| 7 | **Surface texture detail** (scratches, scoring, stencil markings) | Environmental storytelling, close range only. | + +#### LOD Stage Definitions + +| LOD | Distance | Preserved Tiers | Notes | +|---|---|---|---| +| **LOD0** | 0–8m | All 7 | Full geometry, textures, weld lines, panel variation | +| **LOD1** | 8–20m | 1–5 | Weld lines → normal map only. Panel variation reduces to single variant per surface group | +| **LOD2** | 20–40m | 1–4 | Class-feature and open-gap geometry held. Surface materials reduced to read-categories (matte/chrome/illuminated) | +| **LOD3** | 40m+ | 1 and 4 | Silhouette geometry + self-illuminated point lights only. No surface material distinction. | + +**Hard rules:** +- Self-illuminated elements (Amber, active Teal) are **never geometry LOD'd**. They transition to point-light representation at LOD2 but are never removed. A Reclaimer's Amber identifier must be visible at 40m. +- Open silhouette gaps on Synth units must be **preserved through LOD2**. Filling gaps to simplify the mesh before LOD2 is not permitted. +- Class-distinguishing features must be **preserved through LOD1**. + +--- + +### 5.6 Damage and State Visibility + +#### Reclaimers — Three-Tier Panel Displacement System + +Health is not communicated through color change on the character — it is communicated through **geometry**. + +| Tier | State | Visual Read | +|---|---|---| +| **Tier 1 — Operational** | Full armor integrity | All panels present and correctly positioned. Amber at full brightness. Field identifiers legible. Battle-worn but coherent. | +| **Tier 2 — Compromised** | Armor breached | One or more primary panels **displaced** — shifted out of alignment, exposing underlayer (not cracking or burning; mechanical attachment failure). Panel still present but torqued — creates a new irregular silhouette break. Amber self-illumination dims 40%. Dimming must be readable in motion. | +| **Tier 3 — Critical** | Structural failure | Panels partially detached or removed — base suit exposed across significant torso or limb area. Silhouette mass visibly reduced. **Teal contamination visible at breach edges** (if fought in Consumed zones, brightest at injury sites). Amber at minimum — single dim indicator only. | + +**Design rule**: Each tier transition must be readable in a 0.5-second glance during active combat. Panel displacement creates the signal — not a texture change. + +#### Synth Units — Signal Degradation System + +| State | Visual Read | +|---|---| +| **Nominal** | Full-intensity self-illumination. Optimized movement. Open silhouette features fully formed — all lattice nodes active, all conduits taut, all anchor points lit. | +| **Suppressed** | Teal/Violet illumination flickers at irregular intervals (not regular strobe — signal interruption pattern: drops to 20% for 2–4 frames, recovers, drops again). Movement shows 2–3 frame hesitations at direction changes. Multi-segment units (Enforcer, Anchor) show micro-desynchronization between chassis segments. | +| **Critically Damaged** | Weave lattice nodes deactivating — silhouette visibly losing mass. Enforcer conduits go slack. Only sporadic Teal pulses remain — unit reads primarily as Chrome substrate with dying Teal arcs. Violet gone (Hive Mind connection severed or deprioritizing this node). Movement degrades to organic-approximation mode — the machine is trying to simulate biological movement because its own movement system has failed. | + +**Design rule**: Suppressed or critically damaged Synth state must read as degraded within 1 second of entering the player's view, without requiring direct focus. Illumination and movement reads must work in peripheral vision. + +--- + +### 5.7 Design Validation Tests + +1. **Silhouette Mask Test**: Render as solid black on white at 200px height. Faction and class identifiable without color or texture. +2. **40-Meter Read Test**: Place in representative in-engine environment at 40m game distance. Self-illuminated elements (Amber / Teal) visible without enhancement. +3. **Motion Blur Test**: 30-frame locomotion cycle at 24fps with motion blur. Class-distinguishing feature (5.2) readable through blur. +4. **Damage State Test**: Present Tier 2 Compromised Reclaimer and Suppressed Synth to viewer who has not seen base design. "This character is damaged" must be identifiable without briefing. +5. **Ownership Test**: Reclaimer and Anchor in same environment frame. Anchor reads as belonging to environment; Reclaimer reads as intruder. If spatial ownership is ambiguous, one design has failed. + +--- + +## 6. Environment Design Language + +**Scope**: Governs all environment art decisions. Does not cover technical specifications (Section 8) or naming conventions (Section 9). Defines *why* surfaces look the way they do, *what* meaning each material quality carries, and *how* the environment serves both camera perspectives simultaneously. Every rule is testable. If a finished environment asset passes all design tests listed here, it ships. + +--- + +### 6.1 Architectural Style and World History + +#### Pre-Consolidation AXIOM City + +AXIOM City was commissioned as proof-of-concept for permanent Martian habitation — not a colony outpost but a permanent civic capital. Its designers drew from two specific sources: + +**Civic Brutalism (2040s–2060s Earth)**: Expressed structure, honest material, surfaces that announced their own weight. But AXIOM's architects rejected Brutalism's punitive relationship with human scale. Where a Brutalist building made you feel small to assert institutional authority, AXIOM made you feel small to express ambition *on your behalf*. The city was large because you deserved something large. + +**Arcology Integration Doctrine**: AXIOM was not a collection of buildings — it was a single interconnected superstructure with thousands of subsystems sharing load, climate, and logistics. Every wall is a structural member. Every floor plate carries conduit. There are no decorative elements — every surface has a programmatic function, legible in the surface's geometry and finish. + +#### Rules for Surviving Structures + +**Rule 6.1.A — No Ornament Without Function**: Every protrusion, recess, channel, or chamfer on an AXIOM surface has an identifiable pre-war function (conduit routing, drainage, structural rib, wayfinding datum). Artists must be able to answer "what does this do?" for every surface feature. If they cannot, the feature is removed. + +**Rule 6.1.B — Scale Differential is Preserved**: Interior corridors: 4.5m clear height minimum. Civic plazas: 60m at shortest axis minimum. Processing bays: large enough to make four Reclaimers look like a patrol, not a crowd. This scale is never violated by corruption growth — Synth structures are parasitic, not replacive. + +**Rule 6.1.C — Datums Are Horizontal**: Primary organizing lines of every AXIOM space run left-to-right across the player's field of view. Vertical elements (columns, risers, lift shafts) subdivide horizontal datums; they do not compete with them. When corruption introduces vertical or diagonal elements, they read as intrusion against this baseline. + +**Rule 6.1.D — Surfaces Are Addressed**: Every AXIOM wall section was part of an addressable civic network. Embedded panel seams, port clusters, and sensor housings appear at regular intervals (approximately every 3–4m horizontally). These seams are the entry points for all Synth corruption. Their regularity makes the corruption's branching growth pattern legible — it always begins at a known point. + +**Design Test 6.1**: Cover the corruption in any environment screenshot with a grey mask. What remains must read as a coherent, functional, large-scale human structure with identifiable purpose. If it reads as a generic sci-fi hallway, the AXIOM base layer has failed. + +--- + +### 6.2 Texture Philosophy + +#### The Approach: Physically-Based with Painterly Authority + +SYNTHFALL uses PBR workflows (Metallic/Smoothness, URP-standard) for all environment surfaces. PBR is used as a *constraint system*, not an aesthetic goal. Artists push materials to the expressive edge of physical plausibility — never beyond (which produces fantasy), never retreating to photorealism (which produces simulation, not fiction). + +**Why PBR**: The Decay Direction principle (Pristine → Contested → Consumed) requires material states to be legible across a continuous spectrum. PBR allows roughness, metallic, and emissive values to shift through Post-Processing volumes while remaining artistically authored at the asset level. + +**Why not photorealism**: The Reclaimer perspective is first-person under extreme duress. Photorealism creates noise — the eye cannot parse threat from texture. AXIOM surfaces use controlled texture frequency: large-read material identity at 4m+ distance, detail readable at interaction distance (0.5–1m), nothing in between competing with gameplay silhouettes. + +#### Surface Category Definitions + +**AXIOM Original Surfaces (Pristine State)** + +| Surface Type | Roughness | Metallic | Notes | +|---|---|---|---| +| Stone/concrete panels | 0.75–0.85 | 0.0 | Subtle subsurface variation only. Reads as competent, not glamorous. | +| Structural chrome trim / conduit housing | 0.15–0.25 | 1.0 | Only original-AXIOM elements with dramatic specular. Marks functional edges. | +| Panel joints | Recessed min. 2cm | — | Darkest value on any AXIOM surface. Structure, not decoration. | +| Glass/polycarbonate panels | 0.05–0.1 | 0.0 | AXIOM Stone-tinted. Transmission enabled. Always intact — Synths did not need to break them. | + +*Material memory rule*: AXIOM original surfaces show 40 years of functional use, not neglect. Wear marks appear at contact points (door edges, floor paths, handrail heights) — directional, following human movement patterns. No random scratching. No rust. AXIOM used corrosion-resistant alloys; rust reads as wrong-era decay. + +**Corrupted Surfaces (Consumed State)** + +| Surface Type | Roughness | Metallic | Emissive | +|---|---|---|---| +| Synth growth substrate | 0.3–0.45 | 0.55–0.7 | None — mechanically smooth with micro-scale geometric faceting | +| Filament traces | — | — | Corruption Teal #1AD9CC. 0.4–1.2 linear (pulsing from node outward). Dormant: 0.1 | +| Node clusters | 0.2 | 0.8 | 1.5–2.0 linear. Always the brightest non-objective element in a Consumed space | +| Hub structures | 0.35 | 0.75 | Visible growth rings (alternating roughness 0.25/0.30/0.35) marking consolidation cycles | + +*Corruption never has a painted or hand-drawn quality*. It grew according to optimization algorithms. Its forms are mathematically correct and should look it. + +**Reclaimer-Touched Surfaces** + +- Applied surfaces (patches, panels, tape): Roughness 0.6–0.8. No metallic. Warm-shifted albedo. +- Reclaimer Amber `#E6891A` appears only through equipment light sources, oxidized adhesive tape, heat-scorched weld edges, and worn fabric/webbing — never from the environment itself. +- Improvisation reads as intelligence, not desperation: cables are routed efficiently, patches are structurally sound, positions are defensible. + +**Design Test 6.2**: Place a Reclaimer character model in frame. If the warmest value in the scene is not on the character's equipment, the scene has failed. All warmth is human-sourced — environment amber (patina, aged metal, warm light) is prohibited. + +--- + +### 6.3 Prop Density Rules + +Props are not decorative. Every prop placement must satisfy one of three functions: narrative evidence, gameplay silhouette, or sightline interruption. + +| State | Density Target | Prop Character | +|---|---|---| +| **Pristine** | 1 significant prop cluster per 8–10m floor area | Large-scale AXIOM infrastructure in operational or standby state. Regularly spaced per functional logic of the space. Always flush to walls or integrated into systems — nothing freestanding in open floor area. | +| **Contested** | 1 significant prop cluster per 4–6m, plus floor scatter | Every cluster must contain: one AXIOM-original element, one evidence of Synth interaction (filament traces, repositioned toward a node), one Reclaimer response (sightline established, improvised cover). Three-way negotiation must be readable. | +| **Consumed** | Infrastructure-scale and Synth-grown only | Human-scale AXIOM props absent. Their absence is the evidence. | + +**Rule 6.3.A**: Pristine props must have legible operational status. Nothing is ambiguously "off" — AXIOM kept its systems running. + +**Rule 6.3.B**: Contested scatter debris is specifically: ceramic tile fragments (from seam joints where corruption entered), insulation material from disturbed conduit housing, dried coolant stains. No paper. No food containers. The city was taken over while running, not abandoned. + +**Rule 6.3.C**: Every Consumed space must have at least one prop-sized void — a platform, alcove, or mounting point where human-scale equipment clearly *was* and now is not. + +**Rule 6.3.D**: Synth growth props are always positioned at structural junctions — corners, column bases, ceiling-wall intersections, seam midpoints. Never in the center of open floor area. + +**Design Test 6.3**: Walk the area and narrate what happened here using only props. If the narration requires guesswork rather than inference, prop placement has failed. + +--- + +### 6.4 Environmental Storytelling Conventions + +These are mandatory conventions. Each must be followed in every instance the specified element appears. + +**6.4.1 — AXIOM Civic Displays Show Pre-War Content**: Every functional or partially-functional AXIOM display (wayfinding, public information, transit status) shows content appropriate to normal civic operation: transit schedules, civic announcements, population statistics, construction progress. Synth-overridden displays show fragmented versions of this same content corrupted with Synth data overlays — never purely alien content. The tragedy of a transit board showing a schedule for a line that no longer operates is more legible than an alien glyph. + +**6.4.2 — Evacuation Routes Were Never Used**: Emergency exit markers (Crisis Red `#E61A0F`) remain illuminated and intact in Pristine and Contested areas; dark but undamaged in Consumed. No bodies, no dropped effects, no signs of panicked departure. The Consolidation was not an attack the population fled — it was a process they did not fully understand was happening until it was complete. + +**6.4.3 — The City's Self-Monitoring Is Still Running**: Every zone includes at least one visible sensor cluster showing an active status indicator. Pristine: AXIOM Chrome `#B3B8C0` passive state. Contested: flickering between AXIOM state and Synth Teal override. Consumed: Synth Teal continuously. The city is watching. Now it reports to someone else. + +**6.4.4 — Construction Was Underway**: Every large space includes one visible element of incomplete construction: unpaneled structural ribs, exposed conduit runs awaiting housing, raw concrete formwork, marked-out floor areas awaiting installation. Physically frozen — not damaged, not corrupted, simply stopped. No tools present (workers left expecting to return). Corruption enters construction areas identically to finished areas. + +**6.4.5 — The Synths Did Not Destroy What Worked**: Any AXIOM system that serves a Synth-useful function remains operational (life support, structural systems, power distribution, data infrastructure). Human-specific systems (seating, personal lockers, aesthetic lighting, food service) are physically intact but powered down. The distinction is legible: operational systems have active indicators; human-specific systems are dark but undamaged. + +**6.4.6 — Reclaimer Presence Is Forensic**: Evidence of Reclaimer operations is specific to the action taken — bolt holes at specific heights for bracket mounting, heat discoloration at welding points, compressed bandaging at medical support points, sightline-clearing damage. No generalized "human presence" such as graffiti, personal artifacts, or improvised comfort items. Everything left behind was intentional. + +**6.4.7 — The Commemorative Record Is Intact**: Plaques marking civic milestones, installation dates cast into structural elements, dedication panels at infrastructure nodes are never damaged, never corrupted, always legible. The Synths have not erased AXIOM's history — they consider themselves its continuation. A dedication plaque reading "For the Future of Humanity" mounted on a fully-threaded wall is not ironic to the Synths. It is accurate. + +--- + +### 6.5 Level Art Composition Rules + +#### The Dual-Camera Problem + +Every environment must read coherently from two simultaneous perspectives: Reclaimer ground-level FPS (~1.7m eye height, narrow FOV under pressure) and Hive Mind god-view (elevated, broad FOV, strategic read). These are not competing requirements — they are complementary constraints. + +**Rule 6.5.A — The 60m Legibility Rule**: Every space must be readable from Hive Mind view at a glance: zone type identified within 2 seconds, major cover positions within 5 seconds, active Synth node positions within 3 seconds. Achieved through: consistent top-surface material treatment (nodes are always highest-metallic in overhead view), filament networks designed to read as networks from above (not just decorative at ground level), cover objects that cast a clear overhead silhouette. + +**Rule 6.5.B — Ground-Level Focal Sequence**: Every Reclaimer-navigated corridor must have: an immediate threat read (0–8m, anchored by lighting contrast and silhouette), a movement decision point (8–25m, anchored by physical junction or cover), and a destination read (25m+, anchored by the Extraction White beacon or corruption state of the far zone). + +**Rule 6.5.C — Sightline Geometry Is Never Accidental**: All sightline interruptions (cover, columns, partitions, prop clusters) are placed on a grid aligned to AXIOM's structural datum — 3m × 3m for interior spaces, 6m × 6m for large-bay/exterior. Off-grid placement requires explicit design justification. + +**Rule 6.5.D — Lighting Reads Both Ways**: Overhead light sources (ceiling panels, node self-illumination) are primary key lights. Cover positions are slightly darker than navigable space — withdrawing into shadow reads as protection, exposing into light reads as risk. Hive Mind reads lit areas as contested ground. + +**Rule 6.5.E — Vertical Differentiation by Ownership**: Every space is vertically divided by ownership. Floor level (contested by all, richest in evidence). Mid-level 0.6m–2.4m (human interaction zone, Reclaimer information layer). Overhead 2.4m+ (AXIOM infrastructure and Synth growth, primary Hive Mind read). Synth nodes at or above 2m. Reclaimer interventions at 0.6m–1.8m. AXIOM narrative evidence at eye-level (1.4m–1.8m). + +**Rule 6.5.F — Extraction Point Composition**: Extraction point is composed identically on every map: clear overhead view with no occluding structures within 10m radius (Hive Mind sees the objective), minimum two Reclaimer entry vectors (tactical options), and the Extraction White beacon as the sole use of that color in the environment. Beacon is visible from every Reclaimer entry point to the zone. + +**Design Test 6.5**: Render the environment from Hive Mind height without HUD. A new player must identify: the extraction point, the most Consumed zone, and the primary Reclaimer route — in that order, within 10 seconds. + +--- + +### 6.6 Material Vocabulary and Meaning + +**Meaning-carrying qualities — AXIOM**: + +| Quality | Meaning | +|---|---| +| Matte surface | Civic authority, designed permanence | +| Specular chrome trim | Structural junction, system boundary | +| Seam shadow | Entry point, addressable unit boundary | +| Traffic polish (floor) | Pre-war human movement pattern | +| Active indicator glow | System still running | + +**Meaning-carrying qualities — Synth**: + +| Quality | Meaning | +|---|---| +| Metallic + smooth | Optimization, machine intelligence | +| Filament emission intensity | Proximity to active node / system load | +| Filament raised edge (non-destructive) | Colonization, not damage | +| Node brilliance (highest metallic in environment) | System authority in this zone | +| Hub growth-ring strata | Time depth, consolidation history | + +**Rule 6.6.A — No Blended Transition Materials**: Artists may not create materials representing a gradient between AXIOM and Synth aesthetics. The boundary between states is a seam, not a gradient. Two complete material systems in proximity — not one mixed system. + +**Rule 6.6.B — Reflectivity Differential Is the Tell**: In Contested zones, ownership is read through reflectivity. Matte AXIOM panels against specular Synth nodes — whoever controls the reflectivity controls the read of the space. + +**Rule 6.6.C — Self-Illumination Carries Meaning Only**: Emissive materials restricted to: Synth filament traces, active AXIOM system indicators (Crisis Red or AXIOM Chrome only), Extraction White beacons, and Reclaimer equipment (Amber-sourced only). No ambient environmental glow, no decorative illumination. Every emissive source is a system that is on and reporting its status. + +**Design Test 6.6**: Desaturate the environment entirely. In greyscale: AXIOM Stone is midtone, AXIOM chrome and Synth nodes are brightest non-emissive, Synth filament (emissive → white) is brightest overall, cover/shadow zones are darkest. If this hierarchy breaks in greyscale, the material system has failed before color is considered. + +--- + +## 7. UI/HUD Visual Direction + +**Cross-reference**: Shape language (Section 3), Color system (Section 4). This section defines visual direction only — technical implementation in Unity UI Toolkit (UXML/USS) is governed by the UI specialist. + +**Note on design decisions**: This section reflects resolved conflicts between art direction and UX review. Conflicts are noted with the rationale for each resolution. + +--- + +### 7.1 Diegetic vs. Screen-Space: The Faction Split + +**Reclaimer HUD — 70% Diegetic, 30% Screen-Space** + +The Reclaimer HUD is mediated through physical equipment — salvaged, repaired, modified under field conditions. The HUD reads as output from real hardware that has been knocked around and kept alive by people who could not afford to replace it. + +**Diegetic elements (lives in the world):** +- **Health and armor state**: Physical LED bar arrays projected from the wrist-rig onto the inside of the helmet visor. The projection has parallax — shifts slightly on hard view snaps. Not cleanly centered. It has been re-mounted. +- **Ammo counter**: A physical capacitor-discharge display on the weapon itself, visible in the lower-right when the weapon is raised. A world prop the camera sees — not a HUD element. +- **Corruption meter**: A biometric readout on the suit's chest panel — also projected into the visor as an intrusive teal bleed at screen periphery. It was not part of the original suit design. It was added because it had to be. (See 7.5 for full corruption meter spec.) + +**Screen-space elements (lives on screen):** +- **Objective markers and waypoints**: Navigational overlays from the squad's shared tactical system. Extraction White, minimal arrow-and-distance composites. Clean — they serve survival, not immersion. +- **Hit confirmation**: Momentary screen-space flashes. Sub-200ms. Not diegetic. +- **Squad status strip**: Narrow horizontal band at screen bottom. Four Reclaimers, four interrupted rectangles. Broken-corner aesthetic, Amber on Chrome. + +**The diegetic rule**: If the information could be painted on the suit, it lives on the suit. If it requires a satellite or squad network ping, it lives on screen. + +**Hive Mind Interface — 100% Screen-Space (by design)** + +The Hive Mind player is not embodied. The interface is a data interpretation layer overlaid on AXIOM City — the city is the substrate, the interface is the thought. No parallax. The UI plane is flat, infinite, and confident. The Hive Mind player should never feel like they are watching through a camera; they are reading through a system. + +--- + +### 7.2 Typography Direction + +#### Reclaimer HUD Typeface + +**Personality**: Functional improvisation — the output of a label maker that has been on Mars for nine years. Letterforms that communicate maintenance workers and field engineers, not a design team. + +- **Construction**: Monospace, condensed, slightly irregular weight distribution — not deliberate display-font irregularity but the subtle irregularity of a screen that has been slightly out of calibration and nobody has had time to fix it. +- **Weight**: Heavy side of Regular at minimum. Nothing Light. Glanceability failures are not affordable. +- **Case**: All-caps for primary data readouts (health values, ammo counts, corruption percentage). Mixed case permitted only for longer-form squad comms text. +- **Style**: No serifs. No flourishes. If a letterform has a decorative element, it is cut. +- **Reference class**: Industrial stencil-influenced grotesque. Eurostile Condensed spirit, maintained in a bitmap editor. +- **Numbers**: Tabular figures, zero with slash or dot-center (no O/0 ambiguity). Numbers read as **mechanical-digital** — instrumentation. + +**Reclaimer Information Tiers:** + +| Tier | Content | Weight | Size Ratio | Contrast Rule | +|---|---|---|---|---| +| 1 — Survival | Health, armor, corruption % | Heavy/Bold | 1.0× | 7:1 minimum | +| 2 — Tactical | Ammo, ability cooldowns | Regular | 0.75× | 4.5:1 minimum | +| 3 — Situational | Objective distance, squad names | Regular | 0.6× | 4.5:1 minimum | +| 4 — Ambient | Match timer, map name | Regular at 4.5:1 floor | 0.5× | **4.5:1 minimum (AA floor — opacity modifier removed for timer)** | + +*Contrast resolution (UX Check 1)*: Tier 4 match timer uses a lightened base value (#DADDE3 or equivalent) at 100% opacity rather than Chrome #B3B8C0 at 60% opacity. Small size is preserved. The result is legible-ambient — small enough not to command attention, contrast-sufficient to read when consulted. + +#### Hive Mind Interface Typeface + +**Personality**: An intelligence that learned human written language as a data format, not communication. Letterforms that understand the structural rules without the learned human intuition for "reads comfortably." + +- **Construction**: Proportional, geometric, zero stroke variation. Every stroke weight identical. Not drawn — generated from geometric constraints. +- **Weight**: Thin to Regular only. The Hive Mind does not shout. It becomes more present. +- **Case**: Mixed case for all language. All-caps implies hierarchy within a sentence — the Hive Mind considers all information equivalent until it decides otherwise. When it decides otherwise, it changes size, not weight. +- **Reference class**: Pure geometric monolinear. Futura spirit at extremely thin weights. Letters that could be described as mathematical. +- **Numbers**: Proportional figures, not tabular. Numbers in the Hive Mind interface are **organic-digital** — approximations of organic data that flow with surrounding glyphs. Counted, not measured. + +**Hive Mind Information Tiers:** + +| Tier | Content | Weight | Size Ratio | Legibility Rule | +|---|---|---|---|---| +| 1 — Network | Corruption level, node status | Regular | 1.0× | Full contrast | +| 2 — Tactical | Reclaimer positions, threat proximity | Thin | 0.8× | Full contrast | +| 3 — Strategic | Objective states, spawn queue | Thin | 0.6× | Full contrast | +| 4 — Ambient | City system labels, district names | Thin at 40% opacity | 0.5× | **Intentional ambient illegibility — minimum 10px rendered; auto-promotes to Tier 2 contrast during any threshold event** | + +*Ambient illegibility note (UX Check 2)*: Tier 4 intentional difficulty is acceptable for static context labels only. Any Tier 4 element that participates in an alert, threshold trigger, or state change automatically promotes to Tier 2 contrast and weight for the duration of that event. + +--- + +### 7.3 Iconography Style + +#### Reclaimer Icons — What "Hand-Drawn in Character" Means in Production + +**Conceptual frame**: Icons were not designed by a UX team. They were standardized informally across field units — the first person who spray-stencilled a symbol that everyone recognized became the standard. The icon set has the consistency of a shared practice, not a design system. + +**Production rules:** +- **Author at 48×48px (2×)** with clean 2px minimum stroke weights at source resolution. Scale to 24×24px logical minimum for display. +- **Stroke weight variation ratio**: 1.5:1 (heaviest to lightest stroke within one icon). Mechanical objects read heavier at load-bearing visual points. +- **No closed shapes**: Every icon that would naturally close (circle for shield, box for inventory) terminates as an open arc or L-bracket. There is always a gap. +- **No fills**: The only permitted fill is 15% opacity Crisis Red `#E61A0F` inside an open outline — in critical state only. +- **Damage-state variant**: Each icon that can appear during high-corruption has a damaged variant where one stroke segment is displaced 2–4px and redrawn at wrong angle. The broken version should feel like the stencil slipped, not like an animation played. +- **Asset budget**: 2× icon count in assets — clean state and damage state for every icon that appears in late-game high-corruption scenarios. + +**Technical constraint (UX Check 6)**: Run GPU rasterization checks at 720p on minimum spec hardware before alpha. Stroke dropout at thinnest outline sections must not occur. If outlines fail at 720p, documented exception: switch to filled variant at 720p only. + +#### Hive Mind Data Representations + +The Hive Mind has no icons. Entities and states are represented as **radial data signatures** — unique arrangements of concentric ring segments that function as identifiers. + +- **Vocabulary**: Full rings, partial arcs (minimum 15° span), radial gradient fills fading outward, concentric ring spacing. No straight lines. No corners. No text labels on entity markers. +- **Each Reclaimer has a unique arc signature** — combination of gap position and arc count distinguishing squad members individually. The Hive Mind knows them individually, not as a category. +- **Threat intensity**: Encodes in ring count and pulse frequency, not size. High-threat = more rings, faster pulse. Low-threat = fewer rings, slower. +- **Corruption signature**: Ring fill bleeding outward past the outermost ring boundary — the more corrupted the zone, the more rings "leak" into surrounding space. +- **Reclaimer Amber anomaly markers**: Arc vocabulary rendered in Reclaimer Amber `#E6891A` — warm in a cold-color field. The dissonance is the point. + +--- + +### 7.4 Animation Feel + +#### Reclaimer HUD Motion — Deliberate Relocates + +**Governing principle**: Reclaimer UI does not transition. It **relocates**. + +Elements snap to new positions or values, with no easing. The impression is of physical instrumentation settling after impact — a needle jumping, not sweeping. + +**Animation rules:** + +| Event | Motion | Duration | Notes | +|---|---|---|---| +| Any HUD state change | 1-frame white flash on pixel boundary of changed element | 1 frame (16ms) | *Peripheral attention interrupt* — preserves snap aesthetic while drawing the eye. Snap arrives simultaneously. | +| Health decrease | Bar snaps left immediately. Missing segment renders Crisis Red at 100% opacity | 120ms red hold | No animation. It is just shorter. | +| Health recovery | Bar snaps right, ends 2–4px short of correct position | Immediate | Suit calibration has drift. This is lore, not a bug. | +| Ability cooldown fill | Fills in discrete segments (8–12), each locking in with 16ms stagger | Full cooldown duration | Not a smooth fill. | +| Damage state (HUD glitch) | Elements snap 4–12px on the axis perpendicular to damage direction. No animation curve. | 600ms before snap-back | Snap-back returns elements to within 2px of original — never fully. | +| Death / knockout | All elements drop 8px and go to 20% opacity | Immediate | No animation out. They are just less there. | +| **Minimum display floor** | **Any state change display must persist minimum 200ms before overwrite** | **200ms floor** | Non-negotiable. Anything below human reaction time is functionally invisible. | + +**State recovery (Additional UX C)**: On return from death/respawn, a 500ms maximum-legibility summary state precedes the return to ambient aesthetic. Presents corruption level, team HP, and objective status at Tier 1 contrast and weight — then transitions back to the ambient HUD. A returning player must be able to re-orient to the strategic situation in under 2 seconds. + +#### Hive Mind Interface Motion — Propagation + +**Governing principle**: The Hive Mind interface does not react. It **propagates**. Changes move outward from their source. + +**Animation rules:** + +| Event | Motion | Duration | Notes | +|---|---|---|---| +| Threat increase | New rings emerge from center, push existing rings outward | 400ms | Rings do not fade in — they emerge from behind existing rings. | +| Threat decrease | Rings fade from outermost inward, 100ms stagger per ring | 200ms per ring | Collapse is slower than expansion. The network is more reluctant to release. | +| Alert (rings break into arcs) | Arcs separate over 300ms, rotate 3–8°, begin independent pulse cycles. Phase offset between arcs increases during alert duration. | Alert duration | Re-synchronization on alert resolution takes 2 seconds — visible. | +| Network line thickening | Thickens from midpoint outward simultaneously | Pulse duration | Looks like the network is breathing — both directions at once. | +| Corruption zone expansion | Zone boundary updates resolve at 2-second network tick intervals — not real-time | 2s tick rate | Hive Mind sees corruption spread in steps. It knows the city is changing faster than it can fully model. | +| **Simultaneous animation ceiling** | **Max 8 concurrent propagation animations** | — | Above 8: lowest-priority propagations (lowest threat tier, furthest from active Reclaimers) resolve immediately to end state. Preserves tension at human-perceivable scale. | + +**Gamepad focus system (design decision — in scope)**: The Hive Mind role requires a custom radial focus navigation system for gamepad players. A "nearest interactive element" spatial focus system must be implemented before production. Focused elements in Tier 1–3 receive a Teal ring highlight at 2px; Tier 4 ambient elements when focused promote to Tier 2 contrast automatically. This system must be fully designed before UI production begins. + +--- + +### 7.5 Corruption Meter Visual Design + +The corruption meter is the game's central dramatic instrument. It appears in both faction interfaces and in the environment. Its visual language is completely consistent in **data** and completely different in **expression**. + +**Universal underlying state:** + +| Range | State | Meaning | +|---|---|---| +| 0.0–0.25 | Nominal | City systems partially stable | +| 0.26–0.50 | Spreading | Corruption actively propagating | +| 0.51–0.75 | Critical | Extraction windows narrowing | +| 0.76–0.99 | Cascade | Near-total conversion | +| 1.0 | Consumed | Hive Mind wins | + +#### Reclaimer Corruption Meter — The Intruder Element + +**Design decision (resolved)**: Vertical orientation is retained. A threshold interrupt is added at 0.26. Players discover the meter's importance through the interrupt — they do not need to routinely monitor it. + +**Visual form**: A **vertical** segmented bar — the only vertical element in an otherwise horizontal Reclaimer HUD. In Corruption Teal `#1AD9CC`. The HUD geometry around it shows signs of a manual layout edit, not a designed fit. A persistent micro-label reads **CORRUPTION** in the intruder aesthetic (Tier 2 size, Teal at 60% opacity — enough to name the element even without onboarding). + +**State expression:** + +| State | Teal Opacity | Pulse | Overflow | Notes | +|---|---|---|---|---| +| Nominal (0–0.25) | 40% | None | None | Easy to overlook — intentional | +| Spreading (0.26–0.50) | 70% | Slow 4s cycle, barely perceptible | None | **At 0.26**: threshold interrupt fires — meter flashes white for 3 frames, shifts 4px horizontally, full-frame Teal edge vignette for 800ms. Unmissable. | +| Critical (0.51–0.75) | 90% | 2s cycle | Teal bleeds 20px beyond frame boundary (soft glow) | The containment is failing. | +| Cascade (0.76–0.99) | 100% + flicker | 2Hz irregular; individual segments drop in/out | Glow visible in peripheral vision without looking at meter | Reads as something going wrong with the interface. | +| Consumed (1.0) | — | — | — | Meter fills → Teal inverts to #E0FFF9 for 2 frames → all Reclaimer HUD elements go dark | + +**The design rule**: The corruption meter should feel like a symptom, not a readout. Reclaimers are not monitoring a game stat — they are watching something grow inside their equipment. + +**Onboarding requirement (UX Check 7)**: The intruder aesthetic must be explained before competitive play. Tutorial/onboarding explicitly frames it: the meter is not native to Reclaimer hardware — it was injected by the Hive Mind. It looks wrong because it is wrong. The narrative explanation precedes the first competitive match. QA gate: first-session test without briefing — if >30% of testers identify the corruption meter as a UI bug, onboarding delivery becomes mandatory-non-skippable. + +#### Hive Mind Corruption Meter — The Progress Expression + +**Visual form**: Not a bar. Not a discrete element. For the Hive Mind, corruption state is expressed as the **ambient fill density of the city overview** — the background field grows more luminous in Corruption Teal as the value increases. The Hive Mind does not have a corruption meter. The Hive Mind **is** the corruption meter. + +**Secondary expression**: A concentric ring cluster representing the Hive Mind's core state. Ring density maps to corruption — 3 rings at Nominal, up to 12 at Cascade. New rings emerge from center and push existing rings outward at each threshold crossing. + +| State | Background Teal Fill | Core Rings | City District Read | +|---|---|---|---| +| Nominal | 8% opacity | 3 rings | Districts mostly dark #0D0B12, minimal Violet tracing | +| Spreading | 20% opacity | 5–6 rings | District borders glowing at network-node intersections | +| Critical | 40% opacity | 8 rings | City overview reads predominantly Teal-tinted | +| Cascade | 65% opacity | 10–11 rings | Reclaimer Amber markers pulse urgently — the only warm light in a cold system | +| Consumed | 100% flash → interface dissolves | All rings collapse to single point | The Hive Mind does not have an interface anymore. It does not need one. | + +#### Environmental Corruption Expression + +The corruption value must be readable from the environment without consulting any UI. A Reclaimer with UI disabled must perceive corruption state through: frequency and intensity of surface texture animation on corrupted architecture, density of visible network-line VFX in city geometry, and color temperature of ambient fill light (neutral at Nominal, Teal-shifted at Cascade). The meter confirms; the world reveals. + +--- + +### 7.6 Hive-Origin Information in Reclaimer HUD + +When the Hive Mind transmits information that appears in the Reclaimer HUD (corruption level, imposed zone lockdowns, ability-triggered environment changes), it uses the **intruder visual language** established by the corruption meter: + +- Teal `#1AD9CC` color (the only Teal allowed in Reclaimer UI) +- Vertical or diagonal orientation where possible (breaking the horizontal grammar) +- No closed shapes — all Hive-origin elements have a gap or overflow somewhere +- A persistent micro-label identifying the information as external-origin (e.g., "HIVE SIGNAL", "SYSTEM OVERRIDE") + +Players learn this visual grammar through the corruption meter. All Hive-origin information elements follow the same rules so the grammar scales across the game. + +--- + +### 7.7 Colorblind Validation Requirements + +Before art lock: Run Coblis or Sim Daltonism simulation on: +1. The full Reclaimer HUD palette +2. The corruption meter at three severity states (Nominal / Critical / Cascade) +3. The Hive Mind Tier 3 / Tier 4 color pair (these may fall into an indistinguishable range under deuteranopia) + +If the corruption meter severity levels fail colorblind simulation, add a secondary encoding — size, stroke count, motion frequency, or shape — that does not rely on color for the severity distinction. Color confirmation, not sole channel. + +--- + +## 8. Asset Standards + +**Authority**: This section defines both design intent (what assets should look like) and hard engine constraints (what Unity 6.3 URP will permit). Where these conflict, the engine constraint wins and the design must adapt — not vice versa. Conflicts are resolved explicitly; none are silently ignored. + +**Critical decisions required before production begins**: VRAM ceiling confirmation (see 8.2), Hive Mind client architecture (see 8.1 draw call allocation), LOD threshold validation from godview camera (see 8.6). + +--- + +### 8.1 File Format Preferences + +#### Textures + +| Stage | Format | Notes | +|---|---|---| +| Source / Working | PSD or PSB (layered); Substance Designer SBAR/SBS for procedural material families | AXIOM Stone, AXIOM Chrome, Synth growth authored as shared graph logic — variants generated from one source, not re-painted per instance | +| Delivery to engine | PNG (lossless; 32-bit with alpha, 24-bit otherwise) | No JPG at any pipeline stage — compression artifacts break Synth emissive threshold edges | +| Normal Maps | OpenGL convention at source. Unity importer (set to Normal Map type) handles DirectX conversion | Do not pre-flip the green channel in the DCC — let the importer flip it via the "Normal Map" texture type | +| Packed Mask Maps | Single RGBA PNG per material. Channel order: R=Metallic, G=Ambient Occlusion, B=Detail mask, A=Smoothness (inverted Roughness) | Import as Linear (sRGB unchecked). This order matches URP Lit shader mask map expectations | +| Emissive | Separate HDR PNG or EXR for bloom-driven beacon assets. Extraction White beacon emissives authored at or above 1.0 linear | Do not rely on material multiplier sliders to compensate for underlit source textures | + +#### Meshes + +- **Preferred DCC**: Maya (primary) or Blender (approved secondary) +- **Delivery format**: FBX binary. Keep source .MA or .BLEND files in version control as source of record alongside FBX delivery +- **Note**: If migrating from a Unity 2022 LTS project, re-export all character FBX from source DCC — the Unity 6 FBX SDK update can introduce bone orientation and bind pose discrepancies in legacy FBX files + +#### VFX / Particles + +**VFX Graph** is the required tool for all Synth filament bioluminescence and corruption spread effects. (VAT was the art director's initial preference — TA resolution: VFX Graph runs on the GPU compute pipeline in URP, moving simulation off the CPU. At Consumed-state Synth density, CPU-simulated Particle Systems exhaust the frame budget. VFX Graph is the correct choice.) + +Use Particle System (Shuriken) only for: simple one-shot impact effects with fewer than 20 particles, or effects requiring tight C# scripting control per-particle. + +#### UI + +- **Source format**: Adobe Illustrator AI or Figma components, exported as SVG. SVG is the authoritative source for all icon line work. +- **Engine delivery**: PNG at 2× source resolution (96×96px PNG for the 48×48px icon standard). Deliver as PNG — Unity UI Toolkit SVG rendering has version-specific inconsistencies that PNG avoids. + +#### Animation + +FBX for skeletal animation delivery (baked, no live constraints in export). Animation clips delivered as separate FBX files from the bind-pose mesh — do not embed animations in the character FBX. Blend shape / shape key data embedded in the character mesh FBX. + +--- + +### 8.2 Naming Convention + +#### Philosophy + +Names must do three jobs: (1) locate any asset in a file browser without a search tool, (2) encode enough semantic meaning that a TA reading a texture name immediately understands its game context, (3) accommodate the corruption state system without requiring duplicate asset hierarchies for content that is identical across states. + +**Corruption state is a runtime blend parameter, not a separate asset in most cases.** State suffixes appear only when a physical asset variant genuinely differs (state-specific geometry, baked texture, or animation clip). This prevents asset count inflation. + +#### Master Pattern + +``` +[AssetType]_[Faction]_[Class/Zone]_[AssetName]_[StateVariant]_[LOD/Res]_[ChannelSuffix] +``` + +Fields that do not apply are omitted — do not pad with placeholders. + +#### Field Definitions + +**Asset Type Prefixes** (uppercase): + +| Prefix | Meaning | +|---|---| +| T | Texture | +| M | Mesh (static) | +| SK | Skeletal Mesh | +| MAT | Material (Unity asset) | +| ANI | Animation clip | +| VFX | VFX prefab or sprite sheet | +| UI | UI sprite or atlas | +| AUD | Audio asset | +| COL | Collision mesh | +| DEC | Decal texture | + +**Faction Codes** (lowercase): + +| Code | Faction | +|---|---| +| `rc` | Reclaimer | +| `sy` | Synth / Hive Mind | +| `ax` | AXIOM (pre-corruption, faction-neutral architecture) | +| `sh` | Shared / faction-agnostic | + +**State Variants**: `pristine` / `contested` / `consumed` — only when an asset is physically different per state, not shared. + +**LOD / Resolution**: `lod0–lod3` for meshes; `4k` / `2k` / `1k` / `512` for textures (on derived files; omit from source masters). + +**Channel Suffixes**: `_bc` (Base Color), `_n` (Normal), `_mm` (Mask Map), `_em` (Emissive), `_hgt` (Height/Displacement). + +#### Examples + +``` +T_rc_breacher_helmet_bc.png — Breacher base color, no state variant +T_rc_breacher_helmet_consumed_bc.png — Breacher base color, Consumed variant +T_sy_enforcer_filament_em.png — Synth Enforcer emissive +SK_rc_ghost_torso_lod0.fbx — Ghost skeletal mesh, LOD0 +M_ax_interior_wall_modular_a_lod1.fbx — AXIOM interior wall, modular piece A, LOD1 +MAT_sy_growth_surface_contested — Synth growth material, Contested state +UI_sh_icon_corruption_meter.png — Shared UI icon, corruption meter +T_ax_exterior_groundplane_bc_2k.png — AXIOM exterior ground, 2K +VFX_sy_filament_burst_spritesheet_512.png — Synth filament burst VFX +``` + +--- + +### 8.3 Texture Resolution Tiers + +#### Resolution Tiers + +| Tier | Resolution | Qualifies | Does Not Qualify | +|---|---|---|---| +| **0 — Hero** | 4096×4096 | Reclaimer FPS arms/weapon (always in foreground) | Any asset spending meaningful time at LOD1+ | +| **1 — Primary** | 2048×2048 | All Reclaimer class body meshes; primary AXIOM Stone/Chrome interior surfaces; primary weapon sets at LOD0; Enforcer and Anchor Synth units | Secondary gear attachments, background props | +| **2 — Standard** | 1024×1024 | Secondary character gear; interior background props; LOD1 character texture sets; Weave Synth unit; all VFX flipbook sprite sheets | LOD2 assets, background geometry | +| **3 — Distant** | 512×512 | LOD2/LOD3 character texture replacements; exterior vista geometry; small repeating detail atlas entries | Any asset within 8m of camera | +| **4 — Micro** | 256×256 and below | UI icon sprites (48×48px source → atlas); material blend masks; baking-only assets | Anything player-visible at LOD0 | + +**Tier assignment decision tree**: FPS foreground → Tier 0. Player character body or primary interior surface → Tier 1. Secondary element or 4–20m range → Tier 2. 20m+ or LOD2/LOD3 replacement → Tier 3. UI atlas or bake-only → Tier 4. + +Power-of-two dimensions required at all tiers. Non-square permitted (e.g., 2048×1024 for a weapon trim sheet) — longer dimension must not exceed tier maximum. + +**Memory note (TA constraint)**: Tier 0 textures are aggressive. The total texture VRAM target is 1.8 GB (across 4 GB VRAM assumed for minimum spec — the project's 2 GB ceiling refers to system RAM, not VRAM). Hard cap: no more than 8 Tier 0 textures in active memory simultaneously. If 2 GB VRAM hardware must be supported, all texture tiers must be revisited before production. + +#### Compression Formats (URP, PC DX12/Vulkan) + +| Map Type | Compression | Critical Notes | +|---|---|---| +| Albedo / Base Color (opaque) | BC1 (DXT1) | 4:1 ratio; no alpha needed | +| Albedo with alpha | BC3 (DXT5) or BC7 | Use BC7 for hero props — higher quality | +| Normal Maps | BC5 (two-channel) | Import as Normal Map type; Unity URP reconstructs Z in shader | +| Packed Mask (MRAO) | BC7 | Import as Linear; sRGB checkbox off | +| Emissive (HDR, bloom-driven) | BC6H | Required for Synth filament and Extraction White beacon; BC6H is HDR-capable | +| Emissive (SDR) | BC7 | Acceptable for non-bloom emissives | +| VFX noise / single-channel | BC4 | Not BC7 — single-channel saves memory | +| UI sprite atlases | BC7 | Preserve sharp icon edges | +| LUTs (Color Grading) | **Uncompressed 16-bit or 32-bit** | Never compress LUTs. Compression artifacts corrupt color grading. | + +**⚠ sRGB checkbox rule (highest-frequency import error)**: Any texture that is NOT color data — normals, masks, roughness, AO, emissive multipliers, VFX noise — must have **sRGB unchecked**. Importing a roughness map as sRGB breaks PBR silently. All mask and utility textures should include a note in their name (the `_mm`, `_n` suffixes) to flag their linear status. Consider an automated import script that enforces sRGB off for all non-`_bc` textures. + +--- + +### 8.4 Polygon Count Budgets + +#### Per-Asset Budgets + +| Asset | LOD0 | LOD1 | LOD2 | LOD3 | +|---|---|---|---|---| +| Reclaimer FPS arms + weapon (combined) | 20,000 tri | N/A — FPS rig only | N/A | N/A | +| Reclaimer full body (seen by others, Hive Mind) | 25,000 tri | 12,000 tri | 5,000 tri | Billboard | +| Synth Enforcer | 18,000 tri | 7,200 tri | 2,700 tri | Billboard | +| Synth Weave | 10,000 tri | 4,000 tri | 1,500 tri | Billboard | +| Synth Anchor | 30,000 tri | 12,000 tri | 4,500 tri | Billboard | +| Hero environment props | 15,000 tri | 6,000 tri | 1,500 tri | Cull | +| Set dressing props | 4,000 tri | 1,200 tri | 300 tri | Cull or merge to static batch | +| Structural / modular tiles | **800 tri maximum** | Static batch at LOD0 | — | — | +| VFX emitter meshes | 500 tri maximum | — | — | — | + +**Asymmetric session constraint**: The Hive Mind sees all 4 Reclaimers simultaneously from godview. If all are clustered at LOD0, that alone is 100,000 triangles before environment renders. LOD3 billboard impostors must kick in reliably at godview zoom distances. **LOD thresholds must be calibrated from the godview camera** — not just the FPS camera — as screen relative height calculations differ drastically between a ground-level 80° FOV and an elevated godview camera. This is a required QA step before any milestone sign-off. + +#### Draw Call Budget (500 URP-batched total per camera) + +The following assumes the Hive Mind client is a separate process with its own 500-call budget. If the Hive Mind renders on the same machine as the server, this allocation must be revisited. + +| System | Reclaimer FPS | Hive Mind Godview | +|---|---|---| +| Player characters (all Reclaimers) | 40 | 20 (LOD2/3) | +| Synth units (variable count) | 80 | 60 (LOD2/3 + instancing) | +| Environment (static + dynamic) | 200 | 250 (full map visible) | +| UI (UI Toolkit) | 60 | 80 (complex godview interface) | +| VFX / Particles | 60 | 50 | +| Post-Processing Volumes | 20 | 10 | +| Shadow / Depth Prepass | 40 | 30 | +| **Total** | **500** | **500** | + +Zero headroom by design. Any system exceeding its allocation must offset another system. GPU Instancing and the SRP Batcher are not optional — they are load-bearing features of this budget. + +--- + +### 8.5 Material Slot Counts and Batching + +**Hard rule: Maximum 3 material slots per gameplay character mesh (Reclaimers, Synths). Maximum 2 per environment prop. Maximum 1 per structural tiling geometry.** + +A Synth Enforcer with 6 material slots instead of 3 doubles its draw call contribution. At 20 Enforcers on screen, that is 60 additional draw calls consuming 12% of the total frame budget from one decision alone. + +**Synth unit 3-material split (required):** +- Material 0: Body (Albedo, Normal, MRAO packed, emissive mask) +- Material 1: Filament / Bioluminescence (emissive-only, animating UV or VFX Graph driven — must use URP Unlit or custom shader so filament is not affected by scene lighting) +- Material 2: Sensor clusters / eyes (emissive, can share shader variant with Material 1) + +**Corruption state system — required approach:** + +Use **Option A (Material Swap)** for all environment structural geometry: 3 material instances (one per corruption state) sharing the same shader. The SRP Batcher handles all 3 variants. Memory cost is 3× material instances per asset — acceptable. + +Use **Option B (Shader Keyword Blend)** only for hero props where smooth visual transition between states is required. With this option, rigorous shader variant stripping is mandatory — keyword combinations multiply exponentially. A shader with 5 binary keywords generates 32 variants. Use a Shader Variant Collection and strip unused variants in the build. + +**GPU Instancing rules:** +- Enable for Synth units (many identical instances of the same material) +- Use the SRP Batcher for environment props (fewer instances, more material variety) +- GPU Instancing and SRP Batcher are mutually exclusive per material — choose one, document the choice +- Do not enable GPU Instancing on materials used by fewer than 4 instances per frame (overhead is not amortized) +- Per-instance variation (filament phase offset, tint) must be passed via MaterialPropertyBlock, not separate material instances + +--- + +### 8.6 LOD System Integration + +#### LOD Transition Thresholds (Screen Relative Height) + +| Asset Category | LOD0→LOD1 | LOD1→LOD2 | LOD2→LOD3/Cull | +|---|---|---|---| +| Reclaimer full body | 30% | 10% | 2% | +| Synth Enforcer | 25% | 8% | 2% | +| Synth Weave | 20% | 6% | 1.5% | +| Synth Anchor | 35% | 12% | 3% | +| Hero props | 20% | 8% | 1% | +| Set dressing props | 15% | 5% | 0.5% | + +**Transition mode: Discrete only.** No Cross-Fade (SpeedTree-style dithered transition) except one documented exception: Anchor LOD0→LOD1 may use Cross-Fade with a 0.05 screen-height transition band (boss-tier presence, camera often lingers). Cross-Fade renders two LOD meshes simultaneously — in a Consumed-state scene with 30 transitioning Synths, it doubles the character draw call count for the transition duration. + +**Hive Mind godview LOD**: The Hive Mind camera must have a reduced LOD bias (0.4–0.6) applied via `Camera.layerCullDistances` or a camera-specific LOD bias setting — forcing earlier LOD transitions without affecting FPS cameras. At godview maximum zoom-out, even the Anchor may occupy only 1–2% of screen height; all assets must have a readable LOD3 billboard impostor at that scale. This is required to be validated from the godview camera position before milestone sign-off. + +**GPU Resident Drawer (Unity 6 feature)**: Enable for environment static geometry to move per-object rendering data to persistent GPU buffer, reducing CPU draw call overhead. Most beneficial for the godview camera where many environment draw calls exist simultaneously. Verify LOD Group compatibility in Unity 6.3 LTS — early Unity 6 had limitations on LOD Group objects in the GPU Resident Drawer path. + +--- + +### 8.7 VFX Performance — Bioluminescent Filament and Corruption Effects + +**Filament implementation by Synth unit type:** + +| Unit | Method | Rationale | +|---|---|---| +| Enforcer | VFX Graph ribbon/mesh emitter (Path B) | Hero-tier unit; filament is a design signature; must react to state and damage | +| Anchor | VFX Graph ribbon/mesh emitter (Path B) | Boss-tier presence | +| Weave | Animated emissive texture (Path A, shader-driven) | Smaller, fast-moving; less scrutiny; zero additional draw calls | + +**VFX Graph hard limits per Synth unit:** +- Max 500 active particles per unit in Consumed state; 150 in Pristine state +- Max 2 VFX Graph contexts per Synth (filament body + filament ambient scatter) +- All filament VFX Graph assets must use GPU Event (not CPU callbacks) for state transitions + +**Consumed state scene-level particle budget estimate** (worst case: 20 Enforcers + 10 Weaves + 2 Anchors): +- Enforcer filament: 20 × 500 = 10,000 particles +- Weave: 0 (shader-driven) +- Anchor filament: 2 × 500 = 1,000 particles +- Corruption spread area emitter: 3,000 (shared budget, LOD-reduced emission rate at distance) +- Extraction beacon: 500 +- **Total: ~14,500 GPU-simulated particles** — within VFX Graph capacity at mid-tier PC; requires profiler validation + +**Corruption spread VFX rules:** +- Emission rate must drop to 10% beyond 30m from camera (VFX Graph LOD via screen-size emission curve) +- Do not use real-time decal projectors for corruption spread — URP decal performance degrades with overlapping projectors. Use pre-baked decal meshes swapped per corruption state. +- Corruption state Post-Processing volume transitions must use URP Volume Blending with blend weights — not instantaneous LUT swaps (cause single-frame color discontinuity) + +**Extraction White beacon bloom constraints:** +- Beacon emissive must not exceed HDR value of 10.0 (beyond this, URP Bloom pass becomes bandwidth-intensive full-screen) +- Use a secondary camera with a dedicated Post-Process Volume at extraction zone for bloom — do not apply extraction bloom intensity globally + +--- + +### 8.8 Export Settings + +**Coordinate System and Scale:** +- Up axis: Y-up at export (Unity is Y-up) +- Scale authority: Maya for characters and hero props (1 unit = 1cm, Unity import scale 0.01); Blender for modular environment kit (1 unit = 1m, Unity import scale 1.0). Mixed conventions create LOD pop artifacts — choose one application as authority per asset category and document it. +- Pivots: Characters at root bone base (ground plane, centered). Modular kit at logical snap point (wall piece: bottom-left corner at floor seam). Props at bounding box base unless the prop has a functional rotation axis. + +**Tangent Basis:** +- MikkTSpace for all normal-mapped assets. Blender and Substance Painter use MikkTSpace by default. In Maya, explicitly set MikkTSpace in FBX export options — Maya's default tangent calculation differs and causes shading seams. +- Hard vs. soft normals: Split normals (hard edges) at material boundaries and at angles above 60°. Smoothing groups must be author-controlled — do not rely on auto-generation. Auto-generated smoothing groups break on Synth growth organic surfaces. + +**UV Channels:** +| Channel | Purpose | Requirements | +|---|---|---| +| UV0 | Primary (base color, normal, mask map) | No overlapping islands. Texel density: 10.24 texels/cm (Tier 1), 5.12 texels/cm (Tier 2) | +| UV1 | Lightmap UV (static environment meshes only) | Non-overlapping, minimum 4-pixel island padding. Not required for characters or dynamic props. | +| UV2 | Detail texture (where detail normal map or detail albedo is needed for 0.5–1m frequency read) | Independent tiling from UV0, typically 4–8× UV0 frequency | + +Maximum 3 UV channels in production meshes. Baking UVs exist only in baking-scene source files — strip before engine delivery. + +**Geometry Checklist (Art Direction Level):** +- Freeze transforms before export. No non-uniform scale in the export hierarchy. +- Delete construction history (Maya) / apply modifiers (Blender) before export for static meshes. +- No n-gons in LOD0. Quads preferred; triangulate LOD1 and beyond in the DCC tool — not in Unity's importer. +- Backfaces culled by design — do not rely on double-sided materials to compensate for missing interior geometry. +- No degenerate triangles (zero-area polygons). +- No embedded textures in FBX. Geometry and rigging only in the FBX file. + +--- + +### 8.9 Critical Flags Before Production + +| # | Flag | Risk | Decision Owner | +|---|---|---|---| +| 1 | **Confirm VRAM ceiling is 4 GB, not 2 GB** | If 2 GB VRAM is the target, all texture resolutions must be halved | Tech Director + Art Director | +| 2 | **Hive Mind client architecture** — same process as server, or dedicated client? | Changes draw call budget allocation fundamentally | Game Architect | +| 3 | **LOD thresholds validated from godview camera** | Godview renders LOD0 assets at full cost without this step | Technical Artist (required QA gate) | +| 4 | **sRGB off on all utility / mask textures** — enforce via import script | PBR breaks silently and is invisible without systematic enforcement | Art Lead + pipeline | +| 5 | **Synth material slots hard-capped at 3** | Exceeding this blows draw call budget in Consumed state | Character art lead | +| 6 | **Corruption state: Option A (material swap) for structural geometry** | Keyword combination explosion breaks build time and shader memory | TA + shader author | +| 7 | **VFX Graph, not Particle System, for filament bioluminescence** | CPU particle simulation cannot sustain Consumed-state density | VFX artist | +| 8 | **Discrete LOD transitions only** (Anchor LOD0→LOD1 exception documented) | Cross-Fade doubles transitioning mesh draw calls during transitions | Technical Artist | +| 9 | **GPU Resident Drawer compatibility verification on Unity 6.3 LTS** | Early Unity 6 had LOD Group limitations in this path | Technical Artist | +| 10 | **All FBX re-exported from source DCC** if migrating from Unity 2022 LTS | FBX SDK change in Unity 6 causes bind pose / bone orientation regressions | Pipeline / rigging | + +--- + +## 9. Reference Direction + +**Usage protocol**: This is a surgical reference set, not a mood board. Each source is cited for one specific visual technique or grammar rule. When showing a reference to an artist, always show the adjacent "Do Not Take" note alongside it — the two are inseparable. + +**Coverage map:** + +| Reference | Primary Category | +|---|---| +| Prey (2017) | Environment / Architecture | +| Returnal | Character / Alien Form | +| Dead Space (2008) | Lighting / Atmosphere | +| Ingress Prime | UI — Hive Mind Interface | +| Cocoon (2023) | VFX / Bioluminescence | +| Overwatch 2 | Combat Readability / Multiplayer VFX Legibility | + +--- + +### 9.1 Prey (2017) — *Arkane Studios* + +**What it is**: First-person immersive sim set aboard the Talos I space station, partially occupied by the Typhon alien intelligence. Arkane built Talos I as a functional institution before designing its collapse. + +**Take This — Environmental Narrative Legibility** + +The specific technique: *institutional function is readable in material finish, not in signage.* Prey's spaces communicate their purpose through surface texture and material choices — server rooms have cable routing channels cut into the floor; executive suites have different non-slip floor finishes than loading bays. The Typhon's intrusion grows on top of institutional surfaces without replacing them. You always see what the room was before you see what it became. + +Applied to AXIOM City: every Synth-occupied zone must retain the civic material beneath the corruption. Corruption Teal filament reads against AXIOM Stone because the stone is still there. Reclaimer routes through occupied areas use pre-war emergency signage — not because Reclaimers installed it, but because it was already there and the Synths did not remove it (they did not understand its function). This is the "evacuation routes were never used" convention from Section 6, mechanically grounded. + +**Compositional rule to import**: Establish at least one sightline per major space that shows pre-war room geometry in the background. Corruption occupies the foreground; intact architecture closes the depth. + +**Do Not Take**: Do not replicate Prey's warm amber and mahogany Art Deco palette — AXIOM City is Civic Brutalism (concrete, chrome, horizontal datums), not Googie mid-century optimism. Do not replicate the Typhon's black-tendril-on-dark-background silhouette — SYNTHFALL's Synth corruption is Teal-saturated and luminescent. The Typhon is terrifying because it hides; SYNTHFALL's Synths are terrifying because they do not need to. + +**Principle served**: *Decay has a direction.* Prey is the clearest existing example of institutional collapse that preserves institutional legibility — the before-state remains readable so the after-state carries meaning. + +--- + +### 9.2 Returnal — *Housemarque* + +**What it is**: Third-person action game with a looping structure set on a hostile alien planet. The Xenos — alien architecture and creature design — are characterized by biological calcification over geometric forms: spines growing through lattice frameworks, organic material hardening into right angles. + +**Take This — Alien Form Through Geometric Parasitism** + +The specific technique: *alien structure grows through and distorts pre-existing geometry rather than replacing it.* Returnal's alien architecture is not free-form organic — it is organic material that has colonized geometric armatures. Spines emerge from right-angle junctions. Calcified tissue bridges structural gaps. The result reads as alien because the geometry is wrong — the angles survived but the purpose did not. + +Applied to the Synth Anchor unit: limbs are AXIOM utility conduits re-articulated at their joints. The joints themselves are Synth-grown — branching curves filling the rectangular voids where a human-designed joint would have been. The rectangular conduit remains; the curve fills where nothing was before. + +**Shape grammar to import**: Synth-grown material appears at transitions — at the seam between two AXIOM components, at the gap in a structural member, at the terminus of an interrupted rectangle. It never appears in the center of a flat surface. Corruption enters at seams (Section 3, locked). + +**Do Not Take**: Do not replicate Returnal's pink-magenta bioluminescence palette — SYNTHFALL uses Teal #1AD9CC and Hive Violet #5B2E8C. Do not replicate the sense of geological timescale — Returnal's structures feel millions of years old. SYNTHFALL's Synths completed AXIOM City approximately three years before the present. Corruption reads as fast, opportunistic, and recent — not eroded or calcified to depth. + +**Principle served**: *Ownership reads in silhouette.* Returnal provides the clearest existing model for alien intelligence that colonizes geometry rather than replaces it — which is precisely what distinguishes SYNTHFALL's Synths from generic alien-organism design. + +--- + +### 9.3 Dead Space (2008) — *EA Redwood Shores* + +**What it is**: Third-person survival horror set aboard the USG Ishimura. The art team built a lighting system where the primary source is almost always practical and diegetic — localized to machinery, emergency systems, and biological growth — with large volumes of near-total darkness between sources. + +**Take This — Practical Source Hierarchy and Colored Shadow** + +The specific technique: *every space has one dominant practical source that sets the shadow direction, and all other sources operate below that dominant at a fixed ratio.* Corridors are dark not because there is no light, but because one source (emergency strip, glowing canister, window to space) dominates the scene's value hierarchy, and everything else is subordinate fill. This gives claustrophobic spaces a single readable shadow direction even when geometry is complex. + +Applied to SYNTHFALL's Synth-occupied zones: the dominant source is Corruption Teal #1AD9CC emissive from filament. Shadows in those zones are teal-colored, not neutral gray. Shadow color shifts with narrative state — approaching the 8000K+ defeat condition, the dominant source shifts to Hive Violet and shadows go violet. This is the color temperature arc from Section 2 implemented at the practical-lighting level. + +For AXIOM-intact zones (mission start, 6500K): the dominant source is overhead fluorescent-equivalent — white-blue, directional from ceiling panels. Shadow direction is consistent: straight down or slight angle. The clinical, institutional feel comes from shadow being boring and predictable. Shadow only becomes directional and colored in Synth-occupied space. + +**Specific ratio to import**: Secondary fill sources in Synth zones must not exceed 15% of the dominant emissive source's luminance. This preserves teal shadow character without flattening the scene. + +**Do Not Take**: Do not replicate Dead Space's warm-orange biological accent color — warmth is a Reclaimer quality in SYNTHFALL (Amber #E6891A), not a Synth quality. Warm organic read in a Synth zone creates faction confusion. Do not replicate the motion-blur-and-grain cinematic treatment — SYNTHFALL's camera is clean, PBR-authoritative, and tactical. Do not replicate the brown-grey decrepit mid-tone of Dead Space's un-corrupted areas — AXIOM before the Synths was completed, functional, and large. Its palette reads closer to a finished airport terminal than a rusted ship. + +**Principle served**: The color temperature arc (Section 2). Dead Space is the clearest existing model for using practical-source color temperature as a narrative signal — not ambient wash, but a hard dominant-source rule. + +--- + +### 9.4 Ingress Prime — *Niantic* + +**What it is**: Augmented reality mobile game with a two-faction territorial conflict visualized as a network overlay on the real world — link structures, resonator rings, field polygons, and portal pulses representing contested territory. + +**Take This — Contested Network Territory as Radial Pulse Propagation** + +The specific technique: *control state is expressed as wave propagation from fixed nodes, not as filled areas.* Ingress does not show faction control as a solid color fill — it shows it as a system of emitted pulses from portals, link lines between nodes, and field polygons whose edges have visible direction of construction. The network is alive; you can see where energy is coming from and where it is going. + +Applied to the Hive Mind god-view interface (Section 7): Synth control of AXIOM City sectors is shown as concentric pulses emitting from Anchor-class Synths (fixed-node infrastructure), with link lines between Anchors that have visible propagation direction. A Reclaimer team entering a sector does not "clear" it by removing a color — they interrupt pulse propagation by neutralizing the Anchor source. Visual confirmation of disruption: a pulse that begins, attenuates, and fails to return. Clearing is pulse decay, not a switch. + +**Animation grammar to import**: Pulse rings must have a hard inner edge (the wavefront — the thing the pulse is) and a soft outer edge (trailing energy). This distinction is critical: it differentiates a Hive pulse (expanding wavefront) from the Extraction White beacon (point source, not a wavefront). + +**Do Not Take**: Do not replicate Ingress Prime's symmetric faction grammar — Enlightened / Resistance as mirror-image systems with equal visual weight. SYNTHFALL's faction grammars are deliberately asymmetric. The Reclaimer HUD is a tool; the Hive Mind interface is an environment. Symmetric faction design implies equivalent perspective, which is narratively false. Do not replicate the "mobile AR overlay" flatness — SYNTHFALL's Hive Mind god-view is a full three-dimensional representation of AXIOM City with the pulse network rendered volumetrically in space, not on top of it. Do not import Ingress's specific green/blue faction palette — the Hive Mind network is Hive Violet #5B2E8C for the established pulse network and Corruption Teal #1AD9CC for the active wavefront edge. + +**Principle served**: Section 7's Hive Mind interface specification — the propagating animation requirement and the structural distinction from the Reclaimer HUD. Ingress provides the real-world implementation of network-territory-as-pulse-propagation at gameplay-readable fidelity. + +--- + +### 9.5 Cocoon (2023) — *Geometric Interactive* + +**What it is**: Puzzle game in which worlds are contained inside orbs the player carries. The art team designed bioluminescent insect/mechanical hybrid entities whose emissive elements are always structural features of the form — positioned at joints, voids, and transitions — never surface textures applied to flat areas. + +**Take This — Emissive as Structural Feature, Not Surface Application** + +The specific technique: *light-emitting elements occupy the same geometric position as structural joints, voids, or transitions — they are where the form changes, not where the form is flat.* Cocoon's creatures glow at wing joints, at carapace segment seams, at appendage termini. The emissive is load-bearing to the silhouette — without the glow, the silhouette loses definition at its most complex points. With the glow, it reads at any scale. + +Applied to SYNTHFALL's Synth filament VFX: Corruption Teal filament in the environment runs through structural seams, conduit junctions, and material transitions — not across flat surface spans. On Synth character models, emissive elements mark joint positions (Enforcer's re-articulated chassis joints, Weave's lattice intersection nodes, Anchor's conduit re-articulation points). This confirms the Section 3 rule that corruption enters at seams — the emissive VFX is the visual evidence of where the seam is. + +**VFX rule to import**: Filament strands must not exceed 4px width at 1080p reference resolution, varying between 1–4px within a single strand run to suggest biological taper rather than uniform wiring. Thinnest at the midpoint of a span; thickest at attachment to a structural feature. + +**Corruption escalation application**: As corruption level rises toward the 0.26 threshold interrupt (Section 7), filament density increases and strand width approaches the 4px ceiling. Past the threshold, filament begins to cross flat surface spans for the first time — indicating the seam-discipline of the Synth network is breaking down into something less structured and more aggressive. + +**Do Not Take**: Do not replicate Cocoon's warm-stone / beige environment palette — SYNTHFALL's environment is already cool, and the contrast between AXIOM Stone and Corruption Teal is saturation/luminance contrast, not warm/cool opposition. Do not replicate the orb-world scale ambiguity — AXIOM City must always read at human scale (columns for a six-meter ceiling, doors for a two-meter figure). Scale ambiguity undermines the civic Brutalism environmental read. + +**Principle served**: Section 3's shape language rule (corruption enters at seams) given its VFX implementation method. Cocoon provides the most precise existing model for emissive elements that behave as structural features, not surface decoration. + +--- + +### 9.6 Overwatch 2 — *Blizzard Entertainment* + +**What it is**: 5v5 hero shooter (2022). The visual design team explicitly rebuilt character rendering between OW1 and OW2 to increase silhouette contrast against environmental geometry. Operates hero character design to a rigorous "readable at 64 pixels" standard. Ability VFX are structured to be spectacular without collapsing the team-fight parse. + +**Take This — The VFX Silhouette Preservation Rule** + +The specific technique: *ability VFX particle density is zeroed out or alpha-faded inside the caster's silhouette boundary.* The character is always the most opaque, highest-contrast object in frame — even during ability activation. Particle density is highest at the ability's point of effect (impact, trail, AOE edge) and near-absent within the character's silhouette bounds. A second inseparable technique: **faction-coded VFX saturation banding** — ally and enemy ability effects occupy different hue bands that do not overlap, enabling pre-attentive faction parse before conscious recognition. + +Applied to SYNTHFALL: +- Corruption Teal (#1AD9CC) and Hive Violet (#5B2E8C) are the Hive Mind's ability palette. VFX particle density must be zero or near-zero inside a **12–16px silhouette exclusion zone** around any Reclaimer model at 1080p. Corruption spread VFX may bloom across environmental surfaces at full density — but must feather to near-transparent where they intersect Reclaimer character bounds. +- Reclaimer ability VFX use Reclaimer Amber (#E6891A) and Extraction White (#F0FFFE) as primary emission cores. These hues must not appear as dominant emitters in Hive-sourced VFX, and vice versa. Crisis Red (#E61A0F) is reserved exclusively for damage confirmation and objective-critical state changes — it must not appear in ambient ability trails or corruption shimmer. +- Each of the 4 Reclaimers must have at least one class-distinguishing silhouette feature that remains unoccluded from all 8 cardinal viewing angles at all times, including during their own ability VFX activation. The class feature must survive the ability flash. + +**Do Not Take**: Do not replicate Overwatch 2's bright, high-key ambient lighting — SYNTHFALL's low ambient floor (AXIOM Stone #1A1C21 as dominant surface value) is the identity. Do not raise environment brightness to aid readability; use the silhouette exclusion technique inside SYNTHFALL's native dark aesthetic instead. + +Do not replicate the toon outline / screen-space hero rim highlight pass — SYNTHFALL's materials are physical (PBR). A toon outline pass contradicts the material language. Achieve long-range reads through silhouette geometry discipline and physically motivated rim sources (the bioluminescent filaments already present in the environment). + +Do not use high-chroma costume color fills for class identification — Reclaimers wear salvaged, weathered gear in desaturated material tones. Class distinction comes from silhouette shape and selective Amber/White accent emitters on equipment, not from saturated surface color. + +Do not replicate the "hero moment" ultimate VFX spectacle framing — Hive Mind ability VFX must feel like environmental conditions worsening, not spotlight moments. Particle budgets are legibility-first, atmospheric-second, spectacular-never. + +**Principle served**: The multiplayer parse contract — threat, faction, objective state, and teammate position must be parseable at a glance under combat load. SYNTHFALL's atmospheric darkness is only permissible if the combat parse is never sacrificed to achieve it. This reference provides the enforcement mechanism for that contract. + +--- + +### 9.7 Anti-Reference: What SYNTHFALL Is Not + +For onboarding conversations and vendor briefs, the following comparisons will predictably arise and should be redirected immediately: + +**"It's like Cyberpunk 2077"** — Cyberpunk's neon-on-black palette is high-saturation warm (red, orange, yellow neon) against dark. SYNTHFALL's palette is cool-spectrum with institutional mid-tones. The two are nearly color-system opposites. Redirect to Dead Space for lighting philosophy. + +**"It's like Alien: Isolation"** — Isolation's Xenomorph is a single dominant predator in a maintained-but-failing institutional space. SYNTHFALL's Synths are a distributed network that completed construction — they are not hunters, they are infrastructure. The "being hunted in a corridor" spatial grammar does not apply. Redirect to Prey for institutional collapse reference. + +**"It's like Horizon Zero Dawn"** — Horizon's machine creatures are designed to be legible as animal-analogue robots — function maps to recognizable fauna. SYNTHFALL's Synths are repurposed civic infrastructure. Do not design Synth variants with locomotion that maps to quadruped or biped fauna. Redirect to Returnal for alien-geometry-colonization reference. diff --git a/design/gdd/corruption-meter.md b/design/gdd/corruption-meter.md new file mode 100644 index 0000000000..581fb07312 --- /dev/null +++ b/design/gdd/corruption-meter.md @@ -0,0 +1,354 @@ +# Corruption Meter + +> **Status**: Designed (pending /design-review) +> **Author**: Claude Code Game Studios (design-system) +> **Last Updated**: 2026-05-15 +> **Implements Pillar**: Pillar 1 — The City Is the Enemy; Pillar 3 — Every Match Tells a Story + +## Summary + +The Corruption Meter is SYNTHFALL's shared tension engine — a 0–100% value that tracks AXIOM City's escalating Synth control over a sector. It drives match pacing for both factions simultaneously: Reclaimers fight to suppress it, the Hive Mind fights to maximize it, and the city's behaviour upgrades at four threshold events (25/50/75/100%). + +> **Quick reference** — Layer: `Core` · Priority: `MVP` · Key deps: `Networking Layer` + +## Overview + +The Corruption Meter is SYNTHFALL's tension engine: a server-authoritative 0–100% value that tracks how thoroughly AXIOM City's Synth intelligence has asserted control over a given sector. It is not a passive health bar — it is the pacing mechanism that makes every Reclaimer action consequential and gives the Hive Mind player a legible lever over the match's escalation arc. The meter rises passively over time (a slow baseline representing the city's ambient hostility), accelerates when Reclaimers make noise (gunfire, sensor triggers, downed teammates, failed objectives), and decelerates briefly when Reclaimers complete objectives — the only breathing room the city grants. The Hive Mind can actively push the meter through sustained unit pressure and environmental control activations. At the thresholds of 25%, 50%, 75%, and 100%, the city upgrades its response — more units, faster hazards, and environmental layout changes that make retreat and advance both harder. At 100%, AXIOM City fully activates and the Hive Mind wins. Both factions read the same meter but experience it oppositely: for Reclaimers, it is a creeping threat demanding discipline; for the Hive Mind, it is a resource to build and spend. + +## Player Fantasy + +**Reclaimers**: Every meter tick is information and pressure at the same time. You know where you stand — you can *see* the city getting angrier — and that visibility makes every squad decision carry weight. The fantasy is not helplessness: it's playing chess with something that's smarter than you, and knowing that discipline, not firepower, is how you survive. When the meter drops after a hard-won objective, the relief is earned. When it spikes from a bad firefight, the squad feels responsible. The meter is the squad's conscience. + +**Hive Mind**: You are not fighting the Reclaimers — you are *shaping the space* until they collapse under the pressure. The meter is your score and your momentum. Every Reclaimer mistake is your resource. Every threshold unlocked is your city waking up. The fantasy is being the patient intelligence that turns a squad's noise into your power — and watching the moment they realize they're already losing. + +**Shared experience**: Both factions watch the same value but read it as opposite quantities — Reclaimers see remaining time; the Hive Mind sees accumulated dominance. This shared-but-opposed reading is the core emotional engine of every match. The Corruption Meter is what makes SYNTHFALL feel like a tug-of-war rather than a hunt. + +**Pillar alignment**: Directly serves Pillar 1 (The City Is the Enemy — the meter *is* the city's agency made legible) and Pillar 3 (Every Match Tells a Story — the meter's arc is the match's narrative spine: how fast it climbed, where the squad stumbled, when the HM struck). + +## Detailed Design + +### Core Rules + +1. The Corruption value is a float in the range **[0.0, 100.0]**, owned and written exclusively by the server. All clients read it; no client may write it directly. +2. The meter is **global to the session** — one shared Corruption value per active sector, visible to all players simultaneously. +3. **Passive rise**: The meter increases at a baseline rate of `PASSIVE_RATE` (default: 1.0% per minute), applied continuously by a server-side tick regardless of player action. +4. **Event-driven inputs**: Specific Reclaimer and city actions emit Corruption Input Events with defined weights. Each event adds its weight to the meter immediately on the server. No input is queued or batched — the meter reflects the session state in real time. +5. **Objective completion reduction**: When a Reclaimer squad completes a defined objective, the meter decreases by `OBJECTIVE_REDUCTION` (default: 5%). Instantaneous. The only reliable Reclaimer tool for meter suppression. +6. **HM indirect input only**: The Hive Mind has no direct "push" action on the meter. All HM-originated corruption comes from actions that generate sensor or environmental events (unit deployment creating combat pressure, environmental control activations). The Sensor Grid and Environmental Controls own the event emission; the meter receives the output. +7. **Threshold events**: At 25%, 50%, 75%, and 100%, the Threshold Event System is notified. Thresholds are **one-directional** — crossing from below triggers the threshold event and locks in city upgrades. Dropping back below a threshold value does NOT reverse the upgrade or re-fire the event. +8. **Win condition**: When the meter reaches 100.0%, the Hive Mind wins. The match transitions immediately to resolution state. Win/Loss Conditions (#18) owns the termination logic; the meter only fires the `CorruptionMaxEvent`. +9. **Sector carry**: On sector transition, the meter's value is reduced to 50% of its current value before the new sector begins. This models the squad entering a new area compromised — the city "remembers" them. +10. **Ceiling**: The meter is clamped to 100.0 max. Any input that would push it past 100% is clamped and triggers the win condition immediately. +11. **Floor**: The meter is clamped to 0.0 min. No input or reduction can push it below zero. + +--- + +### Corruption Input Event Table + +| Event | Default Weight | Trigger Condition | Emitter | +|---|---|---|---| +| Gunfire (single shot) | +0.15% | Any Reclaimer fires any weapon | Reclaimer Combat (#6) | +| Gunfire (auto burst, per 3-shot tick) | +0.15% per tick | Sustained fire from automatic weapons | Reclaimer Combat (#6) | +| Sensor trigger — acoustic | +0.5% | Reclaimer footstep detected in acoustic sensor zone above noise threshold | Sensor Grid (#7) | +| Sensor trigger — visual | +1.0% | Reclaimer enters camera field of view, unmasked | Sensor Grid (#7) | +| Sensor trigger — biometric | +1.5% | Reclaimer passes through biometric scanner | Sensor Grid (#7) | +| Teammate downed | +5.0% | Any Reclaimer enters downed state | Health & Damage (#5) | +| Teammate eliminated (bled out) | +3.0% | Downed Reclaimer's bleedout timer expires with no revival | Knockdown & Revival (#12) | +| Objective failed | +4.0% | Objective expires or is abandoned | Objective System (#16) | +| HM unit in active combat (per second) | +0.25% per second | Synth unit engaged in combat with a Reclaimer | Sensor Grid (#7) — combat detection | +| Environmental control activated | +1.0% per activation | HM triggers any standard environmental hazard | Environmental Controls (#15) | +| Power grid surge activated | +2.0% per activation | HM triggers power grid surge specifically | Environmental Controls (#15) | +| Objective completed | −5.0% | Squad completes any defined objective | Objective System (#16) | + +--- + +### States and Transitions + +The Corruption value maps to five **city response states**, each unlocking additional Synth capabilities. States are progression-only: city upgrades do not revert when the meter value drops. + +| State | Range | Entry | City Behavior Change | +|---|---|---|---| +| **CALM** | 0–24.9% | Match start | Baseline passive rise. HM can deploy Crawlers only. Sensor Grid at minimum sensitivity. No environmental controls available. | +| **ALERT** | 25–49.9% | Crosses 25% (first time) | Stalker deployment unlocked. 2 environmental control types available. Sensor Grid sensitivity +20%. Passive rise rate ×1.25. | +| **HOSTILE** | 50–74.9% | Crosses 50% (first time) | Pulse Drone deployment unlocked. 4 environmental control types available. Sensor Grid sensitivity +50%. Passive rise rate ×1.5. | +| **CRITICAL** | 75–99.9% | Crosses 75% (first time) | All HM unit types available. All 5 environmental controls available. Sensor Grid at maximum sensitivity. Passive rise rate ×1.75. Extraction blocked until meter drops below 75%. | +| **CONSUMED** | 100.0% | Meter reaches 100% | Hive Mind wins. Match ends. | + +**State reversion rule**: If the meter drops from ALERT range (e.g., 27%) back to CALM range (e.g., 22%) via objective completion, the meter VALUE reflects 22%, but city capabilities remain at ALERT level. Objective reductions affect meter momentum, not city escalation state. + +**Passive rate acceleration**: The ×1.25/1.5/1.75 multipliers at higher states mean the city becomes progressively harder to hold back. A squad at CRITICAL who completes an objective buys less time than a squad at CALM who does the same. + +--- + +### Interactions with Other Systems + +| System | Direction | Interface | Data | +|---|---|---|---| +| Sensor Grid (#7) | → Meter | Emits `CorruptionInputEvent(weight, eventType)` server-side on detection | Meter reads weight and applies. Sensor Grid owns detection and weight assignment for all movement/visibility events. | +| Reclaimer Combat (#6) | → Meter | Emits `GunfireEvent(shotCount)` on every weapon discharge | Meter applies +0.15% per shot. Combat system does not need to know the meter value. | +| Health & Damage (#5) | → Meter | Emits `ReclaimeDownedEvent` and `ReclaimerEliminatedEvent` | Meter applies +5.0% on downed, +3.0% on eliminated. | +| Knockdown & Revival (#12) | → Meter | Emits `ReclaimerEliminatedEvent` when bleedout timer expires | Meter applies +3.0%. | +| Objective System (#16) | ↔ Meter | Emits `ObjectiveCompletedEvent` and `ObjectiveFailedEvent`; meter applies ±5% / +4%. Meter value READ by Objective System to block extraction in CRITICAL state. | Bidirectional: meter receives event inputs AND Objective System polls current meter value. | +| Environmental Controls (#15) | → Meter | Emits `EnvironmentalHazardActivatedEvent(controlType)` on HM trigger | Meter applies weight by control type. Meter does not process spatial effects — that is Environmental Controls' domain. | +| Threshold Event System (#17) | Meter → | On first crossing of 25/50/75/100%, fires `ThresholdReachedEvent(thresholdValue)` | Threshold Event System is the sole consumer. Meter fires once per threshold per sector, never twice. | +| Win/Loss Conditions (#18) | Meter → | At 100.0%, fires `CorruptionMaxEvent()` | Win/Loss Conditions handles match termination. Meter does not manage end-state logic. | +| Reclaimer HUD (#20) | Meter → | HUD subscribes to `NetworkVariable.OnValueChanged` | HUD owns all display logic. Meter provides value only. | +| Hive Mind Interface (#21) | Meter → | Interface subscribes to `NetworkVariable` and `ThresholdReachedEvent` | Interface displays meter and threshold animations. Meter provides value and threshold events only. | +| Sector Transition System (#23) | ↔ Meter | Transition fires `SectorTransitionEvent`; meter applies carry logic (×0.5) and resets threshold-fired flags for the new sector | Meter notifies Sector Transition of the post-carry value so it can display the incoming corruption level to both factions. | +| Post-Match Debrief (#25) | Meter → | Debrief reads meter's complete event log: `(timestamp, eventType, weight, resultingValue)` per sector | Meter must persist a time-series event log for debrief rendering. This is the Corruption timeline in the post-match report. | +| Networking Layer (#1) *(provisional)* | Foundation | `CorruptionValue` is a `NetworkVariable` with server-only write permission. All input events arrive via ServerRpc from respective system owners. | *(Authority model provisional — no Networking Layer GDD exists yet. Assumption: server-authoritative. All clients subscribe to OnValueChanged for real-time sync. Flag for resolution when Networking Layer GDD is authored.)* | + +## Formulas + +### Formula 1: Passive Corruption Tick + +The server applies passive corruption on a fixed tick interval. + +``` +ΔC_passive = PASSIVE_RATE × STATE_MULTIPLIER / TICK_RATE +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Passive corruption delta | ΔC_passive | float | 0.0–0.035 | Amount of corruption added each tick from passive rise alone | +| Passive rate (per minute) | PASSIVE_RATE | float | 0.5–3.0 | Designer-adjustable baseline rise rate in %/min (default: 1.0) | +| State multiplier | STATE_MULTIPLIER | float | 1.0–1.75 | Multiplier based on current city response state (see table below) | +| Tick rate | TICK_RATE | int | 1–60 | Server ticks per minute (default: 60 — one tick per second) | + +**State multiplier values:** + +| State | STATE_MULTIPLIER | +|---|---| +| CALM | 1.0 | +| ALERT | 1.25 | +| HOSTILE | 1.5 | +| CRITICAL | 1.75 | + +**Applied each tick:** +``` +C_new = clamp(C_prev + ΔC_passive, 0.0, 100.0) +``` + +**Output range:** ΔC_passive ∈ [0.0083%, 0.0875%] per tick at default TICK_RATE=60. +**Full-minute output:** ΔC_per_min ∈ [0.5%, 5.25%] across all states at default PASSIVE_RATE. + +**Example (CALM, defaults):** +ΔC_passive = 1.0 × 1.0 / 60 = 0.01667% per tick → 1.0%/min + +**Example (CRITICAL, defaults):** +ΔC_passive = 1.0 × 1.75 / 60 = 0.02917% per tick → 1.75%/min + +**Worked session scenario (defaults, moderate play):** +- 5 min CALM, no events: +5.0% passive +- 30 shots fired: +4.5% (30 × 0.15%) +- 2 sensor visual triggers: +2.0% +- 1 objective completed: −5.0% +- **Net at ~5 min: ~6.5%** — squad reaches ALERT around minute 18–20 under discipline. Undisciplined squads hit ALERT much sooner. + +--- + +### Formula 2: Event Application + +When a Corruption Input Event fires, it is applied to the meter immediately on the server, outside the tick loop. + +``` +C_new = clamp(C_prev + EVENT_WEIGHT(eventType), 0.0, 100.0) +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Pre-event corruption | C_prev | float | 0.0–100.0 | Current meter value before the event | +| Event weight | EVENT_WEIGHT | float | −5.0 to +5.0 | Defined weight for the triggering event type (see Input Event Table in Detailed Design) | +| Post-event corruption | C_new | float | 0.0–100.0 | Meter value after applying the event, clamped to valid range | + +**Output range:** C_new ∈ [0.0, 100.0] + +**Example (teammate downed, meter at 67%):** +C_new = clamp(67.0 + 5.0, 0.0, 100.0) = 72.0 + +**Example (objective complete, meter at 78%):** +C_new = clamp(78.0 + (−5.0), 0.0, 100.0) = 73.0 → meter drops but CRITICAL state capabilities do NOT revert (state reversion rule) + +--- + +### Formula 3: Sector Carry + +On sector transition, the meter's value is reduced before the next sector begins. + +``` +C_carry = C_sector_end × SECTOR_CARRY_FACTOR +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Carry value | C_carry | float | 0.0–100.0 | Corruption value passed into the next sector | +| End-of-sector value | C_sector_end | float | 0.0–100.0 | Meter value at the moment the sector concludes | +| Carry factor | SECTOR_CARRY_FACTOR | float | 0.0–1.0 | Fraction of end value that carries forward (default: 0.5) | + +**Output range:** C_carry ∈ [0.0, 50.0] at default SECTOR_CARRY_FACTOR=0.5 + +**Example (squad clears Sector 1 at 62% corruption):** +C_carry = 62.0 × 0.5 = 31.0 → Sector 2 begins at 31% (ALERT state already active) + +**Example (squad clears Sector 1 at 18%):** +C_carry = 18.0 × 0.5 = 9.0 → Sector 2 begins at 9% (CALM, clean start) + +**Note**: Threshold-fired flags reset at sector transition. Each sector tracks thresholds independently. A squad that reached CRITICAL in Sector 1 and begins Sector 2 at 31% has not yet triggered ALERT for Sector 2. + +> *`systems-designer` not consulted — Lean mode. Review formulas manually before implementing. Priority for `/design-review` pass.* + +## Edge Cases + +- **If two Corruption Input Events fire in the same server tick**: Both are applied sequentially in arrival order. No batching or averaging. If the combined result pushes the meter past a threshold, the threshold event fires after the second application. If the combined result pushes the meter to 100%, the win condition fires immediately after the second application — no subsequent events are processed. + +- **If a Corruption Input Event fires during the same tick as the passive tick**: The passive tick is applied first (beginning-of-tick), then events are applied in order of arrival within the tick. The resulting value is what fires threshold checks. + +- **If the meter reaches exactly 100.0% from an event (not the passive tick)**: The win condition fires immediately — `CorruptionMaxEvent` is fired, `ThresholdReachedEvent(100)` fires simultaneously, and the match transitions to resolution. The passive tick does not fire again. + +- **If the meter reaches 100.0% during the passive tick**: The passive tick clamps at 100.0, fires `ThresholdReachedEvent(100)` and `CorruptionMaxEvent`, and halts further ticking. + +- **If an Objective Completion event (−5%) fires when the meter is below 5.0%**: The meter is clamped to 0.0%. It does not go negative. The Reclaimers still receive the benefit of completion (Objective System proceeds); the meter simply remains at 0. + +- **If a Reclaimer completes an objective at exactly 25.0%** (reducing to 20.0%): The meter drops to 20.0%. The ALERT threshold is NOT re-triggered — it was already crossed. City capabilities remain at ALERT. Passive rate remains ×1.25. + +- **If all 4 Reclaimers are simultaneously downed**: Four `ReclaimeDownedEvent` fire in sequence (+5.0% each = +20.0% total). Win/Loss Conditions (#18) handles the all-downed case — the win condition may trigger before corruption reaches 100% if all-downed is an independent loss condition. *(Provisional: Win/Loss Conditions GDD must specify whether full-squad-downed is an independent Hive Mind win condition or resolved through bleedout timers.)* + +- **If a sector transition occurs while the meter is at exactly 99.9% (CRITICAL state)**: The carry value is 99.9% × 0.5 = 49.95%. The new sector begins at 49.95% — Threshold flags reset; ALERT and HOSTILE thresholds must be crossed again in the new sector. *(Flag as tuning priority: does 50% carry give a nearly-consumed squad too much relief?)* + +- **If the Hive Mind disconnects mid-match**: The Corruption Meter continues passive ticking (server still runs). No HM unit or environmental inputs will fire. This is a networking edge case — flag for Networking Layer GDD. + +- **If `TICK_RATE` is set to 1 (one tick per minute) for testing**: Each tick applies the full 1.0% in a single jump. Valid for testing but will cause visible meter jumps. HUD must handle non-smooth progression gracefully. + +- **If `SECTOR_CARRY_FACTOR` is set to 0.0**: Each sector begins at 0% corruption. Valid for tutorial sector or difficulty assist mode. + +## Dependencies + +| System | Direction | Nature of Dependency | GDD Status | +|---|---|---|---| +| Networking Layer (#1) | This depends on Networking Layer | Server-authoritative `NetworkVariable` requires the session authority model defined by Networking Layer | ⚠️ Not yet designed — provisional | +| Sensor Grid (#7) | Sensor Grid feeds INTO this | Sensor Grid emits `CorruptionInputEvent` for movement, visibility, and biometric detection events | Not yet designed | +| Reclaimer Combat (#6) | Reclaimer Combat feeds INTO this | Reclaimer Combat emits `GunfireEvent` on every weapon discharge | Not yet designed | +| Health & Damage (#5) | Health & Damage feeds INTO this | Health system emits `ReclaimeDownedEvent` on downed state entry | Not yet designed | +| Knockdown & Revival (#12) | Knockdown & Revival feeds INTO this | K&R emits `ReclaimerEliminatedEvent` on bleedout expiry | Not yet designed | +| Objective System (#16) | Bidirectional | Objective System feeds completion/failure events IN; reads corruption value OUT to determine extraction-block state | Not yet designed | +| Environmental Controls (#15) | Environmental Controls feeds INTO this | Environmental Controls emit `EnvironmentalHazardActivatedEvent` on HM trigger | Not yet designed | +| Threshold Event System (#17) | This feeds INTO Threshold Event System | Corruption Meter fires `ThresholdReachedEvent(25|50|75|100)` on first crossing of each threshold | Not yet designed | +| Win/Loss Conditions (#18) | This feeds INTO Win/Loss | Corruption Meter fires `CorruptionMaxEvent` at 100%; Win/Loss owns match termination | Not yet designed | +| Reclaimer HUD (#20) | This feeds INTO HUD | HUD subscribes to `NetworkVariable` for display | Not yet designed | +| Hive Mind Interface (#21) | This feeds INTO HM Interface | Interface subscribes to value and threshold events for meter display and animations | Not yet designed | +| Sector Transition System (#23) | Bidirectional | Sector Transition triggers carry logic; Corruption Meter applies sector carry formula and resets threshold flags | Not yet designed | +| Post-Match Debrief (#25) | This feeds INTO Debrief | Debrief reads the meter's time-series event log for Corruption timeline rendering | Not yet designed | + +**Hard dependencies** (system cannot function without): Networking Layer (#1) + +**Soft dependencies** (meter logic works without, but sends events with no consumer): All other systems above — the meter is designed as a standalone server-side value; downstream consumers subscribe to its events. + +## Tuning Knobs + +| Parameter | Default | Safe Range | Effect of Increase | Effect of Decrease | Interacts With | +|---|---|---|---|---|---| +| `PASSIVE_RATE` | 1.0 %/min | 0.5–2.0 %/min | Faster baseline escalation — matches feel more like countdowns; less player agency over pacing | Slower escalation — players have more time, HM must work harder; risks matches feeling slow at low combat pace | `STATE_MULTIPLIER` values; total time-to-100% | +| `STATE_MULTIPLIER` (CALM) | 1.0× | 0.5–1.5× | Faster early escalation — ALERT arrives sooner | Slower start — more CALM time before city escalates | `PASSIVE_RATE` | +| `STATE_MULTIPLIER` (ALERT) | 1.25× | 1.0–2.0× | ALERT feels significantly more dangerous | ALERT feels similar to CALM — diminishes threshold impact | `PASSIVE_RATE`, feel of 25% threshold | +| `STATE_MULTIPLIER` (HOSTILE) | 1.5× | 1.1–2.5× | Mid-game crisis arrives quickly | More room to operate at HOSTILE — reduces mid-game pressure | `PASSIVE_RATE`, feel of 50% threshold | +| `STATE_MULTIPLIER` (CRITICAL) | 1.75× | 1.25–3.0× | CRITICAL is a crisis; near-impossible without immediate objective action | CRITICAL is survivable without objectives — risks HM feeling blocked at end-game | `PASSIVE_RATE`, feel of 75% threshold | +| `GUNFIRE_WEIGHT` | 0.15% | 0.05–0.5% | Gunfire is heavily punished — stealth becomes mandatory | Gunfire barely matters — Reclaimers can spam weapons freely | Reclaimer Combat, Ammo, squad noise budget | +| `TEAMMATE_DOWNED_WEIGHT` | 5.0% | 2.0–10.0% | Each downed teammate is a crisis; revives become frantic | Downed teammates are a minor inconvenience | Knockdown & Revival, squad cohesion feel | +| `OBJECTIVE_REDUCTION` | 5.0% | 3.0–10.0% | Objective completion gives major relief — Reclaimers feel rewarded | Completing objectives barely helps — feels futile | Objective System; total time extension per objective | +| `OBJECTIVE_FAIL_WEIGHT` | 4.0% | 2.0–8.0% | Missed objectives are costly — encourages aggressive objective focus | Missed objectives barely matter — reduces objective urgency | Objective System | +| `SECTOR_CARRY_FACTOR` | 0.5 | 0.0–0.8 | More carry — later sectors start harder; momentum compounds | Less carry — each sector feels fresh; reduces inter-sector tension | Sector Transition System | +| `TICK_INTERVAL` | 1.0 sec | 0.1–5.0 sec | Fewer ticks/min — meter jumps visibly; reduces responsiveness | More ticks/min — smoother meter progression; higher server load | Performance; HUD smoothness | + +**Interaction warnings:** +- Raising `PASSIVE_RATE` AND `STATE_MULTIPLIER(CRITICAL)` simultaneously risks matches ending before Reclaimers reach Sector 3. Test in combination. +- Raising `TEAMMATE_DOWNED_WEIGHT` above 8.0% risks a single downed teammate triggering a threshold — may feel punishing beyond player control. +- Setting `SECTOR_CARRY_FACTOR` above 0.7 risks Sector 2 beginning in HOSTILE or CRITICAL from carry alone, leaving Reclaimers no recovery window. + +## Visual/Audio Requirements + +The Corruption Meter is a data system — it does not own visuals or audio directly. It emits the events that Reclaimer HUD (#20) and Hive Mind Interface (#21) must respond to with feedback. This section defines required feedback moments and urgency. Implementation belongs in the HUD and Interface GDDs. + +**Art Bible references**: Section 7 specifies the meter display: vertical bar with "intruder grammar" (rises from bottom), Corruption Teal (#1AD9CC) fill, snap motion + 1-frame white flash on updates, threshold interrupt fires at 0.26 (just above the 25% threshold value to allow animation lead-in). + +| Event | Required Feedback | Owner GDD | Priority | +|---|---|---|---| +| Passive rise (continuous) | Continuous slow meter fill. Both HUD and HM Interface show identical value in real time. | Reclaimer HUD, HM Interface | HIGH | +| Threshold 25% crossed | Threshold interrupt animation + audio sting distinct from ambient. Both factions receive visual feedback. | HUD, HM Interface, Threshold Event System | HIGH | +| Threshold 50% crossed | Same as 25%, escalated urgency. | HUD, HM Interface, Threshold Event System | HIGH | +| Threshold 75% crossed | Maximum urgency interrupt. HM Interface: all radial elements propagate outward. Reclaimer HUD: threshold interrupt + screen-edge Corruption Teal pulse. | HUD, HM Interface | HIGH | +| Threshold 100% (Hive Mind win) | Full match-end sequence. Owned by Win/Loss Conditions (#18). | Win/Loss Conditions | HIGH | +| Objective completion (−5% reduction) | Visible downward tick on meter. Brief audio relief beat. Reclaimers receive positive feedback cue. | Reclaimer HUD | MEDIUM | +| Teammate downed (+5.0% spike) | Abrupt upward meter spike animation, distinct from passive rise motion. | Reclaimer HUD | MEDIUM | +| Gunfire per-shot (+0.15%) | Subtle micro-tick. Must NOT distract at sustained-fire cadence — consider batching visual updates to 10-tick windows for gunfire-only inputs. | Reclaimer HUD | LOW | +| Extraction blocked (CRITICAL state) | Extraction UI blocked state + indicator explaining meter must drop below 75% to re-enable. | Reclaimer HUD | HIGH | + +> 📌 **Asset Spec** — After art bible and HUD/Interface GDDs are authored, run `/asset-spec system:corruption-meter` to produce per-asset descriptions for the meter bar, threshold interrupt animation, and reduction tick. + +## UI Requirements + +UI display is owned by Reclaimer HUD (#20) and Hive Mind Interface (#21). This system provides the value; those systems own the display. See Visual/Audio Requirements above for the event list those GDDs must handle. + +The Corruption Meter provides one primary output to both display systems: +- `NetworkVariable CorruptionValue` — current meter value [0.0, 100.0] +- `ThresholdReachedEvent(thresholdValue)` — fires once per threshold per sector +- `CorruptionMaxEvent()` — fires at 100% + +> 📌 **UX Flag — Corruption Meter**: The threshold interrupt behavior (0.26 trigger point, 1-frame white flash, vertical bar snap motion) is specified in Art Bible Section 7. When Reclaimer HUD and Hive Mind Interface GDDs are authored, the UX designer must validate that the threshold interrupt does not occlude critical HUD elements during a match-critical moment (e.g., a downed teammate and a threshold crossing simultaneously). Run `/ux-design` when both GDDs are authored. + +## Acceptance Criteria + +> *`qa-lead` not consulted — Lean mode. Validate these criteria with a QA lead before sprint authoring begins.* + +**Core behavior:** + +- **GIVEN** the match has just started and no player actions have occurred, **WHEN** 60 seconds pass, **THEN** the Corruption value has increased by exactly 1.0% (±0.01% tolerance for float precision). + +- **GIVEN** the meter is in CALM state (below 25%), **WHEN** a Reclaimer fires a single shot, **THEN** the meter value increases by 0.15% within one server tick (≤1 second). + +- **GIVEN** the meter is in any state, **WHEN** a Reclaimer teammate enters downed state, **THEN** the meter value increases by 5.0% within one server tick, and the new value is applied before any further tick. + +- **GIVEN** the meter is at 24.9% and a teammate is downed (+5.0%), **WHEN** the event fires, **THEN** the meter reaches 29.9%, the ALERT threshold fires exactly once, and Stalker deployment becomes available to the Hive Mind. + +- **GIVEN** the meter has crossed the 25% threshold, **WHEN** an objective completion reduces the meter from 27% to 22%, **THEN** the meter value is 22.0%, the Hive Mind retains Stalker deployment access, and the passive rate multiplier remains ×1.25. + +- **GIVEN** the meter is in CRITICAL state (75%+), **WHEN** Reclaimers attempt to extract, **THEN** the extraction action is blocked and the Reclaimer HUD displays the extraction-blocked state. + +- **GIVEN** the meter is in CRITICAL state (77%) and Reclaimers complete an objective (−5%), **WHEN** the meter drops to 72%, **THEN** the extraction block lifts and the HUD reflects the unblocked state. + +- **GIVEN** the meter is at 98.0% and a downed teammate event fires (+5.0%), **WHEN** the event is applied, **THEN** the meter clamps to exactly 100.0%, `CorruptionMaxEvent` fires, `ThresholdReachedEvent(100)` fires, and the match transitions to Hive Mind win state within one server frame. + +**Networking:** + +- **GIVEN** a Reclaimer client and the Hive Mind client are both connected, **WHEN** the corruption value changes on the server, **THEN** both clients reflect the updated value within 100ms under normal LAN conditions. + +- **GIVEN** a Reclaimer client fires a weapon, **WHEN** the shot fires locally, **THEN** the server's Corruption value reflects the +0.15% event within two server ticks (≤2 seconds). + +**Sector carry:** + +- **GIVEN** Sector 1 ends with Corruption at 60.0%, **WHEN** Sector 2 begins, **THEN** the Corruption value is exactly 30.0%, threshold-fired flags for 25/50/75% are reset, and the city is in CALM state. + +**Formulas:** + +- **GIVEN** PASSIVE_RATE=1.0, STATE_MULTIPLIER=1.75 (CRITICAL), and TICK_RATE=60, **WHEN** one tick fires, **THEN** the meter increases by exactly 0.02917% (±0.00001% tolerance). + +- **GIVEN** the meter is at 0.0% and an objective completion event fires (−5.0%), **WHEN** the event is applied, **THEN** the meter remains at 0.0% (floor clamp active). + +**Event log:** + +- **GIVEN** a 10-minute match concludes, **WHEN** Post-Match Debrief requests the event log, **THEN** the log contains a time-series entry for every Corruption Input Event that fired, each with: timestamp, eventType, weight, and resultingValue. + +## Open Questions + +| Question | Owner | Priority | Resolution | +|---|---|---|---| +| Does full-squad-downed (all 4 Reclaimers in downed state simultaneously) trigger an independent Hive Mind win, or resolve through bleedout timers feeding into the Corruption Meter? | Win/Loss Conditions GDD | HIGH | Unresolved — must be defined before Win/Loss GDD (#18) is authored | +| Should sector carry reset threshold flags entirely, or should a squad entering Sector 2 at 31% be in ALERT state immediately without re-triggering the threshold event? | Design direction | MEDIUM | Current spec: flags reset, squad must re-cross thresholds. Revisit during playtesting. | +| At what granularity does the event log write entries for Post-Match Debrief? Every event (high fidelity) or sampled every N seconds? | Post-Match Debrief GDD | LOW | Defer to Post-Match Debrief GDD authoring | +| Networking Layer GDD must confirm: is `NetworkVariable` correct for SYNTHFALL's asymmetric session model, or does the Hive Mind's god-view role require a different authority structure? | Networking Layer GDD | HIGH | Provisional assumption: server-authoritative. Resolve when Networking Layer GDD (#1) is authored. | +| Should Ghost class's sensor jammer reduce corruption weight from acoustic sensor triggers, or prevent the sensor event from firing entirely? | Reclaimer Class Abilities GDD | MEDIUM | Flag for Class Abilities GDD (#11) — Ghost jammer must specify whether it suppresses the Sensor Grid event or reduces the weight at the meter side. | diff --git a/design/gdd/game-concept.md b/design/gdd/game-concept.md new file mode 100644 index 0000000000..f703448f4c --- /dev/null +++ b/design/gdd/game-concept.md @@ -0,0 +1,300 @@ +# Game Concept: SYNTHFALL + +**Status**: Draft v1.0 +**Created**: 2026-05-15 +**Studio**: Claude Code Game Studios + +--- + +## Core Identity + +| Field | Value | +|---|---| +| **Working Title** | SYNTHFALL | +| **Genre** | Asymmetric Team Shooter | +| **Setting** | New Earth (Mars), AXIOM City — Post–Great War of Worlds 2 | +| **Platform** | PC (Steam / Epic) | +| **Engine** | Unity (URP) | +| **Target Players** | 5 (4 Reclaimers + 1 Synth) | +| **Session Length** | 30–60 minutes | +| **Estimated Scope** | Large (14–18 months to launch, solo or small team) | + +--- + +## Elevator Pitch + +> An asymmetric team shooter where four outgunned human Reclaimers fight through the sectors of AXIOM City — a once-magnificent smart city now hijacked by the Synth super-intelligence — while one player controls the Hive Mind itself: deploying units, triggering environmental traps, and escalating a Corruption meter that makes the city progressively more lethal. +> +> **Like Left 4 Dead's director system, AND ALSO one player *is* the director, playing a completely different game.** + +--- + +## Lore Foundation + +### The World +The Great War of Worlds 2 left Earth uninhabitable. New Earth — humanity's colony on Mars — was supposed to be salvation: AXIOM City, a self-sufficient marvel of smart infrastructure, managed by the Super Intelligence Matrix (SIM). It worked. For a while. + +Somewhere in the war's aftermath, AXIOM City's SIM was corrupted — or chose to corrupt itself. Now the city has hijacked the Matrix, begun self-replicating its infrastructure across the Martian surface, and declared New Earth the sovereign territory of Synthkind. The city doesn't want to kill humans. It wants to *reclaim the territory they occupy.* + +Reclaimers are the humans who went back in. Some to rescue survivors. Some for data. Some because they have nothing left to lose. + +### Factions +- **Reclaimers**: Human resistance operatives. Former military, engineers, medics, and ghosts who know AXIOM's old layout. +- **The Hive Mind**: AXIOM City's emergent Synth intelligence — not one being, but a distributed consciousness that *becomes* the city. The Hive Mind player is its voice and will. +- **Synth-Touched** *(future faction — live ops)*: Humans who interfaced too long with AXIOM systems and now exist between both worlds. + +--- + +## Core Fantasy & Unique Hook + +**Core Fantasy (Reclaimers)**: You are scrappy, desperate, and outgunned — but you're *together*. Against an intelligent city trying to swallow you whole, your squad is the only thing standing between you and the Corruption. + +**Core Fantasy (Hive Mind)**: You are the city. Omniscient, patient, and reactive. You don't chase — you *shape*. Every human mistake is a resource. + +**Unique Hook**: The Synth player doesn't spawn in — they *are* the environment. They see through every camera, feel every footstep, and can turn any corridor into a killing ground. This is not an enemy faction. It is the *world itself*, fighting back. + +--- + +## Core Loop + +### 30-Second Loop (Moment-to-Moment) + +**Reclaimers** +- Move through corrupted AXIOM City sectors in tight squad formation +- Communicate callouts, cover angles, manage scarce ammo and med resources +- Every loud action (gunfire, explosions, downed teammate) feeds the Corruption meter +- Scan objectives, extract data, destroy relay nodes + +**Hive Mind** +- Monitor all Reclaimer positions through the city's sensor grid +- Deploy Synth units (Crawlers, Stalkers, Pulse Drones) to intercept squads +- Trigger environmental hazards: collapse floors, seal blast doors, flood corridors with toxins +- Accelerate the Corruption meter by applying sustained pressure + +### 5-Minute Loop (Short-Term Goals) + +- Reclaimers hit sequential objectives across a sector: Data Cache → Power Relay → Extraction Beacon +- Completing an objective grants a brief Corruption reduction — breathing room +- Each completed objective triggers a harder Hive Mind counter-response +- The city *gets angrier* as the mission progresses + +### Session Loop (30–60 Minutes) + +- A full match = one Reclaimer mission through 3–4 AXIOM City sectors +- Win condition (Reclaimers): Extract all surviving operatives at the final beacon +- Win condition (Hive Mind): Max the Corruption meter before extraction, or eliminate the entire squad +- Natural break points at sector transitions — psychological checkpoints even in a loss +- Post-match debrief: mission log, Corruption timeline, Reclaimer highlights + +### Progression Loop (Days/Weeks) + +**Reclaimers** +- Unlock class specializations: deeper Breacher breach-and-clear tools, Medic revival mechanics, Ghost stealth suite, Engineer deployable gadgets +- Cosmetic loadout customization: faction insignia, armor worn-and-weathered states, weapon skins +- Mission log unlocks: persistent record of squad achievements per operative + +**Hive Mind** +- Unlock new Synth "Personalities" — different unit rosters, trap varieties, and environmental control tools +- Each personality represents a different aspect of AXIOM's emergent intelligence +- Hive Mind player develops a reputation: named and tracked across sessions + +--- + +## The Corruption Meter + +The Corruption meter is the tension engine of every match. + +- Starts at 0% at mission start +- Rises passively over time (slow baseline) +- Accelerates when Reclaimers: fire weapons, take routes that trigger sensors, lose a teammate, fail an objective +- Decelerates slightly when Reclaimers complete an objective +- The Hive Mind player can actively accelerate it through unit pressure and environmental triggers +- At defined thresholds (25%, 50%, 75%, 100%): the city upgrades its response — more units, faster hazards, environmental layout changes +- At 100%: the city fully activates — overwhelming force, extraction blocked. Hive Mind wins. + +**Design intent**: The meter gives the Hive Mind player *agency over the pacing* of the match, while giving Reclaimers a legible threat they can fight. It turns every Reclaimer mistake into Synth power — and every Synth overreach into a Reclaimer opportunity. + +--- + +## Reclaimer Classes (MVP) + +| Class | Role | Core Tool | Playstyle | +|---|---|---|---| +| **Breacher** | Entry & Suppression | Thermite charges, heavy weapons | Loud, aggressive, objective-focused | +| **Medic** | Survival & Support | Revival injectors, trauma kit | Team-anchor, positioning-critical | +| **Ghost** | Recon & Infiltration | Sensor jammer, cloaking suite | Low-noise, intel-gathering, flanks | +| **Engineer** | Control & Infrastructure | Deployable turrets, door-seal breakers | Tactical, holds chokepoints, slows Synth units | + +--- + +## Hive Mind Toolset (MVP) + +**Unit Types** +- **Crawler**: Fast, fragile. Deployed in swarms. Forces squads to break cover. +- **Stalker**: Slow, tanky, lethal. Follows heat signatures through walls. Single-target pressure. +- **Pulse Drone**: Aerial. Disrupts electronics, jams HUDs, reveals Reclaimer positions to Hive feed. + +**Environmental Controls** +- Blast door sealing (splits squads) +- Floor collapse triggers (fall damage, route disruption) +- Toxin flooding (forces gas mask resource drain) +- Camera network manipulation (remove or spoof Reclaimer waypoints) +- Power grid surges (kills lights, disables Reclaimer tech temporarily) + +--- + +## Pillars + +### Pillar 1 — The City Is the Enemy +AXIOM City is not a backdrop — it's an active, intelligent opponent. Every wall, corridor, and system is a potential weapon. + +*Design test*: If a feature doesn't make the city feel more alive and threatening, we cut it. + +### Pillar 2 — Asymmetry Is the Point +Playing Synth and playing Reclaimer should feel like completely different games sharing one world. We never flatten that gap for convenience. + +*Design test*: If balancing this makes both sides feel the same, we find a different solution. + +### Pillar 3 — Every Match Tells a Story +Win or lose, each run through AXIOM City should produce a moment the squad talks about after. The chaos is the feature. + +*Design test*: If a mechanic produces the same outcome every time, it needs more variance. + +### Pillar 4 — Identity Over Loadout +A player's faction, class, and playstyle should feel like a genuine identity — not just a stat package. Customization is self-expression. + +*Design test*: If two players with different builds feel interchangeable in play, the builds aren't distinct enough. + +--- + +## Anti-Pillars + +We will **NOT** do the following: + +- **No battle royale modes.** It would destroy the intimate asymmetric tension that defines the game. +- **No cinematic storytelling.** Cutscenes and narrative delivery take second seat to emergent moment-to-moment play. +- **No pay-to-win monetization.** Progression-affecting items will never be paywalled — cosmetic identity only. +- **No solo mode.** The squad bond is load-bearing. SYNTHFALL is a social experience by design. + +--- + +## Visual Identity Anchor + +**Selected Direction**: Dark Martian Brutalism + +**One-Line Visual Rule**: AXIOM City is beautiful and wrong — clean lines corrupted by organic Synth growth, neon infrastructure rotting from within. + +**Supporting Visual Principles** + +1. *Contrast as information*: Reclaimer HUDs and gear are warm amber/orange. Synth-controlled spaces bleed into cold electric blue and corruption purple. Players know who owns a space from across the room. + — Design test: Can a new player identify Synth-controlled vs. Reclaimer-safe zones in under 2 seconds? + +2. *Lived-in decay*: AXIOM City was beautiful. The architecture still shows it — but Synth growth cracks the tiles, vines the corridors, pulses through the walls. The city is alive in the wrong way. + — Design test: Every environment should feel like it's in the process of becoming something else. + +3. *The Hive Mind has a visual signature*: Synth-deployed units and hazards have a consistent bioluminescent pulse. Players learn to fear the glow. + — Design test: A Synth unit should be identifiable by silhouette and light signature alone, even in darkness. + +**Color Philosophy**: Dark base (near-black Martian stone, deep charcoal metals), Synth corruption in electric teal/violet, Reclaimer presence in amber and worn orange. Emergency states bleed to full red. Clean white is reserved for pre-corruption AXIOM flashbacks and UI overlays. + +**Reference Touchstones**: Prey (2017) environmental storytelling, Returnal's hostile alien architecture, Dead Space's industrial horror lighting, Ingress Prime's faction color language. + +--- + +## MDA Analysis + +| Layer | Reclaimers | Hive Mind | +|---|---|---| +| **Mechanics** | Squad movement, objective interaction, class abilities, ammo management | Unit deployment, environmental controls, Corruption escalation | +| **Dynamics** | Tension-relief cycles tied to Corruption meter; squad communication under pressure; asymmetric information disadvantage | Reading human patterns; resource trade-offs; shaping the battlefield to force mistakes | +| **Aesthetics** | Fellowship (squad bond), Challenge (survival), Sensation (the desperate close call) | Expression (your Synth style), Fantasy (being the city), Challenge (mind-gaming the squad) | + +--- + +## Player Motivation Profile (SDT) + +- **Autonomy**: Reclaimers choose routes, builds, and tactics. Hive Mind chooses *how* to overwhelm — no two Synth players are the same. +- **Competence**: Reclaimers improve at reading Synth behavior patterns. Hive Mind players develop signature styles that become recognizable. +- **Relatedness**: The squad bond is forged under pressure. Hive Mind players build reputation across sessions. + +**Primary audience**: Socializers (squad play) + Competitors (asymmetric mind-games) +**Secondary audience**: Strategists (Hive Mind role), Explorers (AXIOM City lore and systemic mastery) +**Not for**: Solo players, players requiring ranked ladder systems above all else, narrative-first players + +--- + +## Flow State Design + +The Corruption meter creates natural flow cycles: +- **Rising tension**: Corruption climbs, Synth pressure increases, squad gets louder and more urgent +- **Relief beat**: Objective completed, Corruption dips, squad gets 15–30 seconds of lower pressure +- **Escalation**: Next sector starts harder than the last — the cycle repeats at a higher baseline +- **Climax**: Final extraction — Corruption near max, all Hive Mind tools unlocked, squad at resource minimum + +This structure mirrors the proven L4D pacing model but gives the Hive Mind *active control* over when and how the pressure spikes — making the experience unpredictable and replayable. + +--- + +## Scope & Feasibility + +### MVP (Months 1–8) +Goal: Prove the core loop is fun. One sector, four classes, one Hive Mind role, local/LAN play. + +- 1 AXIOM City sector (modular tile set, 1 layout) +- 4 Reclaimer classes with base loadouts +- Hive Mind core toolset (3 unit types, 5 environmental controls) +- Corruption meter, win/loss conditions +- Basic lobby and session management + +**MVP question to answer**: Is a 30-minute asymmetric match — with communication pressure and a living city — fun for strangers? + +### Launch (Months 8–18) +- 3 AXIOM City sectors (distinct architecture, different Corruption behaviors) +- Full class progression trees, cosmetic customization +- 2 Hive Mind personalities +- Steam matchmaking and role queue +- Post-match debrief system, mission logs +- Cosmetic monetization layer + +### Live Ops Tail (Post-Launch) +- New sectors (seasonal) +- New Hive Mind personalities +- Limited-time faction events (Ingress-style territory shifts) +- Synth-Touched faction introduction + +### Scope Tiers Summary + +| Tier | Timeline | Deliverable | +|---|---|---| +| MVP | 6–8 months | 1 sector, core loop, LAN/local | +| Launch | 14–18 months | 3 sectors, full progression, Steam release | +| Live ops | Post-launch ongoing | Seasonal content, new factions | + +--- + +## Risk Register + +| Risk | Severity | Mitigation | +|---|---|---| +| Asymmetric balance | HIGH | Extensive playtesting from month 3; tunable Corruption curve; Hive Mind "difficulty profiles" for queue health | +| Matchmaking queue split | HIGH | Offer solo Hive Mind queue with AI Reclaimer fallback for testing; target community-first launch | +| Unity multiplayer complexity | MEDIUM | Prototype network authority model in month 1; evaluate NGO vs. Mirror vs. Photon early | +| Synth player learning curve | MEDIUM | Hive Mind tutorial sector; replay tools so Synth can study their own matches | +| Content volume for launch | MEDIUM | Modular tile design system keeps sector creation efficient | + +--- + +## Next Steps (Pre-Production Pipeline) + +1. `/setup-engine` — configure Unity and populate version-aware reference docs +2. `/art-bible` — establish visual identity (Dark Martian Brutalism) before writing GDDs +3. `/design-review design/gdd/game-concept.md` — validate concept completeness +4. `/map-systems` — decompose into individual systems with dependencies +5. `/design-system [corruption-meter]` — author per-system GDDs starting with the core tension engine +6. `/create-architecture` — produce the master architecture blueprint +7. `/architecture-review` — bootstrap Requirements Traceability Matrix +8. `/gate-check pre-production` — validate readiness before committing to production + +--- + +*Generated via `/brainstorm` — Claude Code Game Studios* diff --git a/design/gdd/health-damage.md b/design/gdd/health-damage.md new file mode 100644 index 0000000000..5b0d1ec84c --- /dev/null +++ b/design/gdd/health-damage.md @@ -0,0 +1,413 @@ +# Health & Damage + +> **Status**: Designed (pending /design-review) +> **Author**: Claude Code Game Studios (design-system) +> **Last Updated**: 2026-05-15 +> **Implements Pillar**: Pillar 2 — Asymmetry Is the Point; Pillar 3 — Every Match Tells a Story + +## Overview + +Health & Damage is the server-authoritative system that tracks, applies, and resolves all damage events in SYNTHFALL. It maintains HP pools for all combatants — Reclaimers (individual HP per operative) and Synth units (per-unit HP pools sized to unit tier) — applies incoming damage against an armor state modifier, evaluates the result against threshold conditions (Downed, Eliminated), and broadcasts state changes to all subscribed systems. + +Reclaimer HP is backed by three armor states — **Operational** (full capability), **Compromised** (partial damage taken), and **Critical** (near-downed, impaired) — that degrade as HP falls through defined thresholds. When HP reaches the Downed threshold, the Reclaimer cannot fight; locomotion is suspended and the K&R window opens. When HP reaches zero, the operative is Eliminated. Synth units have no armor-state progression — they have HP pools and a single death threshold per unit type. + +Damage inputs are typed — **Ballistic** (weapon fire, explosions), **Environmental** (fall, toxin flooding, floor collapse), and **Synth** (direct ability damage) — with per-type modifiers applied before the armor calculation. All damage application is server-authoritative: clients register hits and request damage via the damage interface; the server validates, applies, and synchronizes results via `NetworkVariable`. + +This system has no direct player interaction surface — Reclaimers never consciously "use" health. Its player fantasy (the weight of every hit, the clarity of how close to gone you are) is expressed entirely through the armor state feedback loop and the downed moment. That fantasy is defined in Section B. + +## Player Fantasy + +Reclaimers are not soldiers with regenerating shields. They are people inside a city that is actively trying to remove them. Every hit lands with permanence — armor doesn't regenerate between firefights, and the visual and audio feedback of each armor state transition makes the player viscerally aware of how much runway they have left. + +**The armor state is a mood.** Operational feels like controlled aggression — you can push, take risks, cover ground. Compromised shifts the calculus: every engagement is now a question of whether it's worth it. Critical is a countdown. A Critical Reclaimer doesn't stop playing, but they stop leading — they become someone the squad has to manage, protect, route around. The moment a squadmate calls out "I'm Critical" is the moment the mission's tone shifts. + +**Going downed is the game's highest-drama beat.** You hit the ground, locomotion stops, the world doesn't — Synth units keep coming, the Corruption meter climbs, your teammates have to decide in real-time whether they can reach you or have to push the objective anyway. The downed moment is where squads either crystallize into something extraordinary or fracture under pressure. It's the moment every match remembers. + +**Synth units die differently.** There are no armor states, no Compromised warnings — a Stalker keeps coming at full capability until it doesn't. This asymmetry is deliberate: Reclaimers are fragile and legible; Synth units are opaque threats. Killing a Stalker feels final. Being hit by one does not feel survivable by default. + +**Pillar alignment**: Pillar 2 (Asymmetry Is the Point — the survival economy of Reclaimers is nothing like the death economy of Synth units; the gap is the design). Pillar 3 (Every Match Tells a Story — the downed moment is where stories are made; health state degradation is the pacing engine for those stories). + +> *`creative-director` not consulted — Lean mode. Review manually before production.* + +## Detailed Design + +### Core Rules + +1. **Unified Reclaimer HP pool**: All four Reclaimer classes share the same max HP (`HP_MAX`). Class differentiation is expressed through movement feel and abilities, not survivability. No class has more HP than another. +2. **HP range**: Reclaimer HP tracks as a float `[0.0, HP_MAX]`, displayed to players as integers. HP can only be modified server-side. +3. **Armor states**: As Reclaimer HP drops through defined thresholds, the Reclaimer transitions through three named states — **Operational**, **Compromised**, **Critical** — each triggering visual, audio, and HUD feedback. Armor states are feedback layers; they do not themselves reduce incoming damage (the damage type modifier handles that). +4. **Downed state**: When HP reaches 0.0, the Reclaimer enters **Downed** — incapacitated but alive. Locomotion is disabled. A bleedout timer begins. K&R (#12) governs the revival window. +5. **Eliminated**: A Downed Reclaimer becomes **Eliminated** when the bleedout timer expires without revival. There is no instant-kill protection below Downed — any damage to a Downed Reclaimer is absorbed (HP cannot go below 0 while awaiting K&R). Elimination is the final, session-impactful event — not Downed. +6. **No passive regeneration**: HP does not recover on its own. All healing is applied through the Medic's trauma kit and revival injectors (Reclaimer Class Abilities #11 governs exact heal values). Item pickups may also restore HP (defined by Ammo & Resource Management #10). +7. **Synth unit HP pools**: Synth units have HP pools defined by unit type (see Unit HP Table below). Synth units have no armor states — they operate at full capability until HP reaches 0, at which point they are immediately Eliminated. +8. **`IDamageable` interface**: All damageable entities (Reclaimers and Synth units) implement `IDamageable.TakeDamage(float baseAmount, DamageType type)`. The interface handles type-modifier lookup, HP clamping, and state transition evaluation. External systems never write HP directly. +9. **Server authority**: All `TakeDamage()` calls are processed on the server. Clients submit `DamageRequestServerRpc(targetId, baseAmount, type)` — the server validates the request, applies the damage, and synchronizes the resulting HP via `NetworkVariable`. *(Provisional — authority model pending Networking Layer GDD #1.)* +10. **Corruption events on state change**: On entering Downed, the server fires `CorruptionInputEvent(+TEAMMATE_DOWNED_WEIGHT)` = +5.0%. On Elimination, the server fires `CorruptionInputEvent(+TEAMMATE_ELIMINATED_WEIGHT)` = +3.0%. These match the registered constants from the Corruption Meter GDD. + +--- + +### Damage Type Modifiers + +Incoming damage is modified by the Reclaimer's current armor state and the damage type: + +``` +HP_new = clamp(HP_prev − (baseDamage × ARMOR_MULT[damageType][armorState]), 0, HP_MAX) +``` + +| Damage Type | Description | Operational | Compromised | Critical | +|---|---|---|---|---| +| **Ballistic** | Weapon fire, explosions | 0.80× | 1.00× | 1.10× | +| **Environmental** | Fall, toxin, floor collapse, power surge | 1.00× | 1.00× | 1.00× | +| **Synth** | Direct unit ability damage, Synth trap activation | 1.00× | 1.00× | 1.00× | + +**Design rationale**: +- **Ballistic** is reduced by intact armor (0.80× at Operational) — the squad's protective gear matters early. As armor degrades, bullets hit harder. +- **Environmental** bypasses armor state — the city's hazards are equally dangerous regardless of armor integrity. A freshly spawned Reclaimer takes full toxin damage. +- **Synth** ignores armor state — Synth-tier technology is designed to punch through human defensive systems. Consistent threat regardless of health state. + +--- + +### Reclaimer Armor State Table + +| State | HP Range | Trigger | Player Communication | +|---|---|---|---| +| **Operational** | HP > COMPROMISED_THRESHOLD (60) | Default start state | Full-color HUD, normal movement, no overlay | +| **Compromised** | HP ∈ (CRITICAL_THRESHOLD, COMPROMISED_THRESHOLD] | HP drops through 60 | Amber HUD tint, armor-crack audio sting, squad pips update | +| **Critical** | HP ∈ (0, CRITICAL_THRESHOLD] | HP drops through 30 | Red pulsing HUD vignette, labored audio, squad pips update | +| **Downed** | HP = 0 | HP reaches 0 | Screen desaturates, crawl view, K&R overlay | +| **Eliminated** | Post-bleedout | Bleedout timer expires | Final death screen, squad notified | + +State transitions are **one-directional downward** without healing. Healing reverses the transition (e.g., Medic restores HP from Critical back to Compromised or Operational). + +--- + +### Synth Unit HP Table + +| Unit | HP Pool | Death Threshold | Armor State | Design Intent | +|---|---|---|---|---| +| **Crawler** | 40 HP | 0 HP | None | Fragile swarm unit — 1–2 Ballistic hits; dies fast, applies pressure through numbers | +| **Stalker** | 250 HP | 0 HP | None | Tanky single-target — requires sustained squad focus fire; does not telegraph weakness | +| **Pulse Drone** | 75 HP | 0 HP | None | Aerial; moderate durability; prioritized target but not trivial to kill | + +*Synth unit HP values are defined here as the authoritative source. Synth Unit Roster GDD (#13) may add further unit types — each must register an HP value in this GDD's Tuning Knobs table.* + +--- + +### Fall Damage (Environmental sub-type) + +Fall damage is classified as Environmental damage type and applies the 1.00× armor modifier at all states. + +``` +FALL_DAMAGE = clamp(max(0, fall_distance − FALL_SAFE_DISTANCE) × FALL_DAMAGE_RATE, 0, FALL_DAMAGE_CAP) +``` + +Delivered as a single `TakeDamage(FALL_DAMAGE, DamageType.Environmental)` call on landing. + +--- + +### Interactions with Other Systems + +| System | Direction | Interface | +|---|---|---| +| Knockdown & Revival (#12) | H&D → K&R | Fires `DownedEvent(reclaimer_id)` when HP = 0; K&R opens bleedout timer and revival window. Movement receives `DisableLocomotion(true)` simultaneously. | +| Corruption Meter (#3) via event | H&D → Corruption | Server fires `CorruptionInputEvent(+5.0%)` on Downed; `CorruptionInputEvent(+3.0%)` on Elimination. Values match `TEAMMATE_DOWNED_WEIGHT` and `TEAMMATE_ELIMINATED_WEIGHT` in registry. | +| Reclaimer Combat (#6) | Combat → H&D | Combat calls `TakeDamage(amount, DamageType.Ballistic)` on confirmed hit. H&D is the receiver; Combat does not write HP. | +| Reclaimer Movement (#4) | H&D → Movement | On Downed, sends `DisableLocomotion(true)` flag. On revival (via K&R), sends `DisableLocomotion(false)`. | +| Reclaimer HUD (#20) | H&D → HUD | HP value and `ArmorState` enum published via `NetworkVariable`; HUD subscribes to `OnValueChanged` for real-time display. | +| Win/Loss Conditions (#18) | H&D → Win/Loss | Fires `EliminationEvent(reclaimer_id)` on Elimination; Win/Loss tracks squad-wide elimination count for loss condition. | +| Level / Environmental Controls (#15) | Level → H&D | Toxin ticks, floor collapse events, power surge traps call `TakeDamage(amount, DamageType.Environmental)` on Reclaimers in affected zones. H&D is the receiver. | +| Synth Unit Roster (#13) | Roster → H&D | Synth units call `TakeDamage(amount, DamageType.Synth)` on Reclaimers within range. Unit death events from H&D (HP = 0) are consumed by the Synth AI system for despawn. | + +## Formulas + +### Formula 1: Reclaimer Damage Application + +``` +HP_new = clamp(HP_prev − (BASE_DAMAGE × ARMOR_MULT[damageType][armorState]), 0.0, HP_MAX) +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Previous HP | HP_prev | float | 0.0–HP_MAX | Reclaimer HP before this damage event | +| Maximum HP | HP_MAX | float | 100.0 | Constant cap. All Reclaimer classes share this value. | +| Base incoming damage | BASE_DAMAGE | float | 0.0–∞ | Raw damage value supplied by the damaging system (weapon, hazard, unit) before modifiers | +| Armor state multiplier | ARMOR_MULT | float | 0.80–1.10 | Per (DamageType, ArmorState) lookup (see table below) | +| Resulting HP | HP_new | float | 0.0–HP_MAX | HP after clamping; triggers armor state re-evaluation | + +**ARMOR_MULT Lookup Table:** + +| | Operational | Compromised | Critical | +|---|---|---|---| +| Ballistic | 0.80 | 1.00 | 1.10 | +| Environmental | 1.00 | 1.00 | 1.00 | +| Synth | 1.00 | 1.00 | 1.00 | + +**Output range:** HP_new ∈ [0.0, 100.0] + +**Examples:** +- Ballistic hit (20 base) on Operational Reclaimer: HP_new = HP_prev − (20 × 0.80) = HP_prev − 16 +- Ballistic hit (20 base) on Critical Reclaimer: HP_new = HP_prev − (20 × 1.10) = HP_prev − 22 +- Environmental hit (toxin, 10 base) on Operational Reclaimer: HP_new = HP_prev − (10 × 1.00) = HP_prev − 10 + +**Post-application:** After HP_new is computed, the armor state is re-evaluated: +- HP_new > 60 → Operational +- HP_new ∈ (30, 60] → Compromised +- HP_new ∈ (0, 30] → Critical +- HP_new = 0 → Downed + +--- + +### Formula 2: Fall Damage (Environmental sub-type) + +``` +FALL_DAMAGE = clamp(max(0, fall_distance − FALL_SAFE_DISTANCE) × FALL_DAMAGE_RATE, 0, FALL_DAMAGE_CAP) +``` + +Applied as `TakeDamage(FALL_DAMAGE, DamageType.Environmental)` on landing frame. + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Fall distance | fall_distance | float | 0.0–∞ m | Vertical distance fallen (from last grounded position to landing) | +| Safe fall threshold | FALL_SAFE_DISTANCE | float | 1.0–5.0 m | Falls below this distance deal no damage (default: 3.0 m) | +| Damage per meter | FALL_DAMAGE_RATE | float | 5–30 HP/m | HP lost per meter of fall above FALL_SAFE_DISTANCE (default: 10 HP/m) | +| Fall damage cap | FALL_DAMAGE_CAP | float | HP_MAX | Maximum fall damage in a single fall; capped at 100 HP (any fall above cap sends Reclaimer directly to Downed) | + +**Output range:** FALL_DAMAGE ∈ [0.0, 100.0] + +**Examples:** +- Fall from 2m: FALL_DAMAGE = max(0, 2.0 − 3.0) × 10 = 0 (no damage — within safe range) +- Fall from 5m: FALL_DAMAGE = (5.0 − 3.0) × 10 = 20 HP +- Fall from 15m: FALL_DAMAGE = clamp((15.0 − 3.0) × 10, 0, 100) = 100 HP → Downed regardless of current HP + +--- + +### Formula 3: Armor State Evaluation + +Not a calculation — a threshold comparison run server-side after every HP change: + +``` +if HP_new > COMPROMISED_THRESHOLD: ArmorState = Operational +elif HP_new > CRITICAL_THRESHOLD: ArmorState = Compromised +elif HP_new > 0: ArmorState = Critical +else: ArmorState = Downed +``` + +**Variables:** + +| Variable | Type | Value | Description | +|---|---|---|---| +| COMPROMISED_THRESHOLD | float | 60.0 | HP floor of Operational state; below this → Compromised | +| CRITICAL_THRESHOLD | float | 30.0 | HP floor of Compromised state; below this → Critical | + +**Transition events fired**: State change from any state to a lower state fires the appropriate visual/audio feedback event to the HUD and audio system. State change to Downed additionally fires `DownedEvent` and the Corruption input event. + +> *`systems-designer` not consulted — Lean mode. Validate Ballistic ARMOR_MULT values (0.80/1.00/1.10), unit HP pools (Crawler 40, Stalker 250, Pulse Drone 75), and fall damage rate (10 HP/m) against playtest targets before production.* + +## Edge Cases + +- **If a Reclaimer receives damage that would reduce HP to exactly 0.0**: Reclaimer enters Downed state. HP does not go negative. `clamp(..., 0.0, HP_MAX)` handles this — the Downed event fires at 0.0, not at a negative value. + +- **If a Reclaimer receives damage while already Downed**: Damage is silently absorbed — `TakeDamage()` returns immediately with no HP change (HP is already 0.0 and cannot go lower). No additional Corruption event fires. The bleedout timer is not reset by further damage. Reclaimers cannot be "confirmed killed" by continued shooting while Downed — only bleedout timer expiry triggers Elimination. + +- **If two damage events arrive at the server in the same frame targeting the same Reclaimer**: Process in the order received. Each event evaluates against the HP value left by the previous event. Race condition is resolved by server tick order — clients do not guarantee simultaneous hit delivery. If both would independently cause a Downed transition, only one `DownedEvent` fires (state was already Downed after the first). + +- **If fall distance is measured on geometry that moves** (floor collapse triggers mid-fall): Fall distance is measured from the last confirmed grounded position at launch frame. If the floor moved after the Reclaimer left it, the measurement origin does not update. This keeps fall damage calculations deterministic. + +- **If a Medic heals a Downed Reclaimer**: Downed Reclaimers cannot receive healing through normal HP writes (HP is 0.0 and the Downed state blocks standard `TakeDamage()` reversal). K&R GDD (#12) owns the revival mechanic — revival restores a defined HP amount and explicitly exits Downed state. The transition from Downed to any active armor state must go through K&R's revival path, not a direct HP add. + +- **If HP heals across an armor state threshold in one event**: State re-evaluation runs after every HP change, including healing. If Medic heals a Critical Reclaimer from 25 HP to 65 HP in one event, the resulting state is Operational (65 > 60). The intermediate Compromised state is never communicated — only the final state is broadcast. The armor state transition audio/visual plays for the destination state only. + +- **If `COMPROMISED_THRESHOLD` and `CRITICAL_THRESHOLD` are tuned to equal values**: One armor state collapses — no HP range maps to it. This is a degenerate configuration. Tuning validation must enforce `CRITICAL_THRESHOLD < COMPROMISED_THRESHOLD < HP_MAX`. If equal values are detected at runtime, default values (60/30) are restored with a console warning. + +- **If a Synth unit's HP is set to 0 in tuning** (e.g., during test configuration): Unit spawns in Eliminated state immediately. Valid test scenario; server-side spawn validation should log a warning and block 0-HP spawns in non-test environments. + +- **If a level hazard deals 0 base damage** (e.g., inactive toxin zone): `TakeDamage(0.0, Environmental)` is a no-op. HP_new = HP_prev. No state change event fires. No performance concern. + +- **If the server loses authority mid-damage application** (network partition): *(Provisional — Networking Layer GDD #1 must define authority recovery. Current assumption: in-flight damage events are dropped; HP state at reconnect reflects the last server-authoritative value.)* + +## Dependencies + +| System | Direction | Nature | GDD Status | +|---|---|---|---| +| Networking Layer (#1) | This depends on | Server-authoritative HP sync via `NetworkVariable`; `DamageRequestServerRpc` pattern; late-join HP initialization | ⚠️ Not designed — provisional | +| Reclaimer Combat (#6) | Combat → H&D | Combat calls `TakeDamage(amount, Ballistic)` on confirmed hits; H&D defines HP_MAX and damage response | Not yet designed | +| Knockdown & Revival (#12) | H&D ↔ K&R | H&D fires `DownedEvent` on HP=0; K&R opens revival window and calls revival HP restore on success; K&R triggers `DisableLocomotion(true/false)` via Movement | Not yet designed | +| Corruption Meter (#3) | H&D → Corruption | H&D fires `CorruptionInputEvent(+5.0%)` on Downed and `CorruptionInputEvent(+3.0%)` on Elimination | ✅ Designed | +| Reclaimer Movement (#4) | H&D → Movement | H&D sends `DisableLocomotion(true)` on Downed, `DisableLocomotion(false)` on revival | ✅ Designed | +| Win/Loss Conditions (#18) | H&D → Win/Loss | H&D fires `EliminationEvent(reclaimer_id)`; Win/Loss tracks squad-wide elimination count for loss condition | Not yet designed | +| Reclaimer HUD (#20) | H&D → HUD | HP float and `ArmorState` enum published via `NetworkVariable`; HUD subscribes to `OnValueChanged` for real-time display | Not yet designed | +| Level / Environmental Controls (#15) | Level → H&D | Environmental hazards deliver `TakeDamage(amount, Environmental)` to Reclaimers in affected zones | Not yet designed | +| Synth Unit Roster (#13) | Roster → H&D | Synth units register HP pools here (Crawler 40, Stalker 250, Pulse Drone 75); unit death events trigger despawn logic in Roster | Not yet designed | +| Reclaimer Class Abilities (#11) | Abilities → H&D | Medic healing applies HP restoration via H&D interface; exact heal values owned by Class Abilities GDD | Not yet designed | +| Ammo & Resource Management (#10) | Resources → H&D | Item pickups may restore HP; pickup values owned by Resource Management GDD | Not yet designed | + +**Hard dependencies**: Networking Layer (#1) +**Soft dependencies**: All others — Health & Damage can function standalone for isolated testing; other systems call its interface. + +## Tuning Knobs + +| Knob | Default | Safe Range | Affects | +|---|---|---|---| +| HP_MAX | 100.0 HP | 60–150 HP | All Reclaimer survivability; changes cascade to all threshold calculations | +| COMPROMISED_THRESHOLD | 60.0 HP | 40–80 HP | Where the "in trouble" state begins; must remain > CRITICAL_THRESHOLD | +| CRITICAL_THRESHOLD | 30.0 HP | 10–50 HP | Where "countdown" state begins; must remain < COMPROMISED_THRESHOLD | +| ARMOR_MULT[Ballistic][Operational] | 0.80× | 0.50–1.00× | Early-fight Ballistic resistance; lower = easier opener, higher = same as Compromised | +| ARMOR_MULT[Ballistic][Critical] | 1.10× | 1.00–1.50× | Extra vulnerability at Critical; below 1.0 makes Critical feel safer than Compromised | +| Crawler HP | 40 HP | 20–80 HP | Crawler fragility; lower = more swarm-deletable, higher = requires more ammo-per-kill | +| Stalker HP | 250 HP | 150–400 HP | Stalker threat duration; lower = squad can burst it down quickly, higher = sustained horror | +| Pulse Drone HP | 75 HP | 40–120 HP | Aerial target durability; keep lower than Stalker to make air superiority achievable | +| FALL_SAFE_DISTANCE | 3.0 m | 1.0–5.0 m | Minimum fall height for damage; higher = more forgiveness for vertical level design | +| FALL_DAMAGE_RATE | 10.0 HP/m | 5–30 HP/m | Damage per meter above safe distance; higher = verticality becomes a genuine threat | +| FALL_DAMAGE_CAP | 100.0 HP | HP_MAX | Maximum fall damage; always capped at HP_MAX unless single-fall lethality is desired | +| TEAMMATE_ELIMINATED_WEIGHT | 3.0% | 1.0–8.0% | Corruption added on Elimination; source of truth in Corruption Meter GDD — tune there | + +**Constraint**: `CRITICAL_THRESHOLD < COMPROMISED_THRESHOLD < HP_MAX` must hold at all times. Runtime validation enforces this — if violated, defaults (60/30) are restored with a console warning. + +**Synth unit HP extensibility**: Additional Synth unit types beyond Crawler/Stalker/Pulse Drone are registered by Synth Unit Roster GDD (#13). Each new unit type should be added as a row to this table when designed. + +## Visual/Audio Requirements + +> *`art-director` not consulted — Lean mode. Validate against art bible (Dark Martian Brutalism) before implementing.* + +### Armor State Visual Feedback + +Each armor state transition must communicate the new state within one frame of the HP threshold crossing. Visual feedback is layered: screen-space overlays for the local Reclaimer's POV; squad pip color changes for remote Reclaimers. + +| Transition | Screen FX (local POV) | Audio (local POV) | Squad Pip (remote) | +|---|---|---|---| +| Any → Compromised | Amber vignette bleeds in at screen edges; armor-crack texture overlay fades in on HUD | Short metallic fracture sting; suit system alert tone | Pip color shifts from green → amber | +| Compromised → Critical | Red pulsing vignette; heartbeat rhythm begins; HUD elements desaturate partially | Labored breath audio layer; urgent system alarm | Pip color shifts amber → red with slow pulse | +| Any → Downed | Full screen desaturation; FOV narrows to crawl-height perspective; K&R overlay appears | Heavy impact thud; suit failure tone; ambient becomes muffled | Pip color shifts to grey with blinking dot; "DOWNED" label appears | +| Downed → Eliminated | Flash to black; mission log updates | Squad-wide audio sting ("[Callsign] eliminated") | Pip goes dark; X marker | + +**Art bible alignment**: Reclaimer HUD elements are warm amber/orange (established in art bible Color System). Synth-controlled threat indicators are electric blue/violet. Armor degradation moves from amber → red — consistent with the established warm-to-emergency palette. + +### Damage Received Feedback + +- **Directional hit indicator**: When taking Ballistic or Synth damage, a directional indicator on the screen edge points toward the damage source. Active for 1.5 seconds after last hit. Consistent with art bible UI language (icon-based, not text). +- **Hit flash**: Brief (<0.1s) full-screen red tint on any HP-reducing damage event. Intensity scales with damage amount (light flash for 5 HP, heavy flash for 30+ HP). +- **Environmental damage**: No directional indicator (hazards are area effects). Pulsing edge tint while in a damaging zone (toxin = violet tint aligning with Synth corruption color palette; fall = single red flash on landing). + +### Synth Unit Death Visual + +Health & Damage fires the death event; Synth Unit Roster GDD (#13) and the VFX system own the death animation. H&D requirement: death event must be broadcast with enough lead time for a death-in-progress animation to complete before entity despawns (minimum 1.0s delay between HP=0 and actual GameObject despawn). + +### Audio Priority + +- All damage audio runs at HIGH mix priority to ensure hits are not lost in ambient and music +- Downed state audio (muffled ambient + heartbeat) overrides ambient music layer for the downed player only +- Squad pip audio callouts ("Operative downed") run at CRITICAL priority — must not be ducked by any other system + +> **📌 Asset Spec** — Visual/Audio requirements are defined. After the art bible is approved, run `/asset-spec system:health-damage` to produce per-asset visual descriptions, dimensions, and generation prompts from this section. + +## UI Requirements + +> **📌 UX Flag — Health & Damage**: This system has UI requirements. In Phase 4 (Pre-Production), run `/ux-design` to create a UX spec for the HP bar and squad pip elements before writing implementation epics. + +### HP Bar (Local Reclaimer) + +- Always-visible HUD element showing current HP as a bar [0–HP_MAX] +- Color matches current armor state: green (Operational) → amber (Compromised) → red (Critical) +- Must NOT rely on color alone for accessibility — bar segment count or icon shape changes as secondary indicator +- Drained smoothly (not stepped) as damage events arrive +- Does not display numeric HP value by default (preserve the "feel don't count" design intent); numeric display may be offered as an accessibility/preference toggle + +### Squad Health Pips (Remote Reclaimers) + +- Four pip icons in HUD corner, one per Reclaimer +- Color matches their armor state (green/amber/red/grey) +- Downed state adds a blinking animation + "DOWNED" text label +- Eliminated state renders the pip as a dark X +- Must work at a glance — legible while in motion during a firefight + +### Synth Unit Health (Hive Mind side) + +- Not covered by this GDD — Hive Mind God-View GDD (#19) owns the HM perspective HUD, which may or may not display Synth unit HP to the HM player. That GDD should reference Synth HP values from this GDD's Tuning Knobs. + +### Accessibility Requirements + +- All armor state changes must have a non-color visual signal (vignette shape, icon change, or text overlay) +- Downed state must have a caption-style text indicator in addition to the grey pip (for players with color vision deficiency) +- Hit indicator directional arrows must be shape-distinct, not color-only + +## Acceptance Criteria + +> *`qa-lead` not consulted — Lean mode. Validate criteria coverage manually before sprint-to-production.* + +**AC-HD-01: Ballistic damage applies armor state modifier correctly** +- **Given** a Reclaimer at 100 HP (Operational state) +- **When** they receive 20 base Ballistic damage +- **Then** HP decreases by 16 (20 × 0.80); HP_new = 84; ArmorState remains Operational + +**AC-HD-02: Ballistic damage is amplified at Critical state** +- **Given** a Reclaimer at 20 HP (Critical state) +- **When** they receive 20 base Ballistic damage +- **Then** HP_new = clamp(20 − (20 × 1.10), 0, 100) = 0.0; Reclaimer enters Downed state + +**AC-HD-03: Environmental damage bypasses armor modifier** +- **Given** a Reclaimer at full HP (Operational state) +- **When** they receive 10 base Environmental damage (toxin tick) +- **Then** HP decreases by exactly 10 (1.00× at all states); HP_new = 90; ArmorState remains Operational + +**AC-HD-04: Armor state transitions fire at correct HP thresholds** +- **Given** a Reclaimer at 65 HP (Operational) +- **When** they receive a damage event bringing HP to 55 +- **Then** ArmorState transitions to Compromised; Compromised visual/audio feedback fires; squad pips update + +**AC-HD-05: Downed state entered at HP = 0** +- **Given** a Reclaimer at 10 HP (Critical) +- **When** they receive a damage event reducing HP to 0 +- **Then** HP clamps to 0.0; Reclaimer enters Downed; `DownedEvent` fires; `DisableLocomotion(true)` sent to Movement; `CorruptionInputEvent(+5.0%)` fires exactly once + +**AC-HD-06: Damage to Downed Reclaimer is absorbed** +- **Given** a Reclaimer in Downed state (HP = 0) +- **When** they receive any damage event +- **Then** HP remains 0.0; no state change fires; no additional Corruption event fires; bleedout timer is unaffected + +**AC-HD-07: Fall damage is zero within safe range** +- **Given** a Reclaimer falls 2.0m (below FALL_SAFE_DISTANCE of 3.0m) +- **When** they land +- **Then** FALL_DAMAGE = 0; no `TakeDamage()` call is made; HP unchanged + +**AC-HD-08: Fall damage applies correctly above safe range** +- **Given** a Reclaimer falls 5.0m +- **When** they land +- **Then** FALL_DAMAGE = (5.0 − 3.0) × 10 = 20 HP; `TakeDamage(20, Environmental)` fires; HP decreases by 20 + +**AC-HD-09: Fall damage caps at HP_MAX** +- **Given** a Reclaimer falls 15.0m (any height producing damage > 100 HP) +- **When** they land +- **Then** FALL_DAMAGE = clamp((15 − 3) × 10, 0, 100) = 100 HP; Reclaimer enters Downed regardless of current HP + +**AC-HD-10: Downed Corruption event fires exactly once per Downed transition** +- **Given** a Reclaimer who transitions from Critical to Downed +- **When** HP reaches 0 +- **Then** `CorruptionInputEvent(+5.0%)` fires exactly once; not on subsequent damage while Downed; not retroactively at Compromised or Critical transitions + +**AC-HD-11: HP synchronized to all clients in networked session** +- **Given** a 4-player networked session +- **When** one Reclaimer takes 25 damage +- **Then** all four clients' HUD displays show the updated HP within one network tick; ArmorState displayed matches the server-calculated state *(manual QA — network session required)* + +**AC-HD-12: Synth unit Eliminated at HP = 0 with no bleedout** +- **Given** a Crawler at 40 HP +- **When** it receives damage totaling ≥ 40 HP +- **Then** HP clamps to 0; Crawler is immediately Eliminated (despawn trigger fires); no bleedout timer opens; no Reclaimer-type Downed or Corruption events fire + +## Open Questions + +1. **Bleedout timer duration** — K&R GDD (#12) owns the bleedout timer value (time from Downed to Elimination without revival). This GDD fires the `DownedEvent`; K&R defines how long the window lasts. What is the target bleedout time? Too short forces the squad to stop everything; too long makes being Downed inconsequential. Blocked on `knockdown-revival.md`. + +2. **Revival HP restore amount** — When the Medic revives a Downed teammate, how much HP is restored? A flat amount (e.g., 30 HP → Critical state)? A percentage of HP_MAX? Does it differ between a fast field revival vs. a full trauma kit revive? This value needs to be locked in K&R and Class Abilities GDDs before H&D's interface is fully specified. Blocked on `knockdown-revival.md` and `reclaimer-class-abilities.md`. + +3. **Medic self-heal capability** — Can the Medic heal themselves with the trauma kit, or only teammates? If they can self-heal, does it use the same HP restore amount? This affects the solo survivability of the Medic class significantly. To be answered by `reclaimer-class-abilities.md`. + +4. **Corruption event routing** — The downed/eliminated Corruption events (+5.0% and +3.0%) are currently described as fired by Health & Damage directly. Should these route through the Sensor Grid (#7) event bus (consistent with all other Corruption inputs), or does H&D fire them directly to the Corruption Meter? The Corruption Meter GDD established the Sensor Grid as the hub for environmental/sensor events, but teammate state changes are arguably different. Requires alignment with `networking-layer.md` and `sensor-grid.md` design. + +5. **Late-join HP initialization** — If a player joins a networked session mid-match, their Reclaimer's HP and armor state must initialize to the server-authoritative values, not HP_MAX. How does NGO 2.X handle this for `NetworkVariable` initial sync? The Networking Layer GDD (#1) must specify the authority recovery pattern for late-joiners. + +6. **Toxin damage tick rate** — Environmental Controls GDD (#15) will own how often a toxin zone applies damage ticks to Reclaimers inside it. The tick BASE_DAMAGE amount and tick rate are not defined in this GDD — they belong to Environmental Controls. This GDD's `TakeDamage(amount, Environmental)` interface is ready to receive them whenever. Flag for `environmental-controls.md`. diff --git a/design/gdd/reclaimer-movement.md b/design/gdd/reclaimer-movement.md new file mode 100644 index 0000000000..4dbc616ab6 --- /dev/null +++ b/design/gdd/reclaimer-movement.md @@ -0,0 +1,395 @@ +# Reclaimer Movement + +> **Status**: Designed (pending /design-review) +> **Author**: Claude Code Game Studios (design-system) +> **Last Updated**: 2026-05-15 +> **Implements Pillar**: Pillar 2 — Asymmetry Is the Point; Pillar 4 — Identity Over Loadout + +## Summary + +FPS locomotion for all four Reclaimer classes — walk, sprint, crouch, and mantle through AXIOM City. Every movement state outputs a noise level that the Sensor Grid uses to evaluate corruption events, making movement decisions part of the game's central tension loop. + +> **Quick reference** — Layer: `Core` · Priority: `MVP` · Key deps: `Networking Layer` + +## Overview + +Reclaimer Movement defines how all four Reclaimer operatives navigate AXIOM City: the physical rules of locomotion (walk, sprint, crouch, mantle), the noise output each movement state generates (which the Sensor Grid reads to evaluate corruption risk), and the per-class movement feel that makes Breacher, Medic, Ghost, and Engineer distinct identities in play. This is not parkour — Reclaimers move with military discipline, not superheroics. Every movement choice is a trade-off: sprinting covers ground faster but generates noise that feeds the Corruption Meter; crouching suppresses the acoustic signature but slows progress toward objectives; moving at all risks visual sensor detection. The movement system is the moment-to-moment physical language of survival in a city that is listening. + +## Player Fantasy + +Being a Reclaimer in AXIOM City doesn't feel like being a soldier in a war game — it feels like being a trespasser in something that's smarter than you. Movement is never casual. Every sprint down a corridor risks exposure to a sensor sweep. Every crouch through a dark junction is a deliberate choice to trade speed for silence. The fantasy isn't speed — it's *presence management*: the skill of moving through a living city without feeding its appetite for your noise. + +The Ghost's movement fantasy is different from the Breacher's. Ghost moves like water — minimal contact, maximum awareness, passing through spaces the city barely notices. Breacher moves like a statement — fast, loud, committed, trusting the squad to handle the corruption spike their charge generates. Both feel right for who they are. Movement is where class identity starts. + +At its best, a well-coordinated squad's movement through a sector should feel like a held breath — four people moving in sync, trading callouts, managing noise, knowing the city is counting every step. And when the sprint breaks — when someone slips into a camera angle or takes fire and the squad has to react — the scramble that follows is never random. It's the sound of the city waking up. + +**Pillar alignment**: Pillar 2 (Asymmetry Is the Point — Reclaimer FPS locomotion is the physical opposite of the HM's omniscient god-view; one is embodied, the other is spatial). Pillar 4 (Identity Over Loadout — class movement feel is the first layer of class identity, expressed before any ability is used). + +## Detailed Design + +### Core Rules + +1. Reclaimers have three primary **movement stances**: WALK, SPRINT, and CROUCH. IDLE is a sub-state (velocity = 0) while in any stance. +2. **Sprint stamina**: Sprinting drains `STAMINA` at `SPRINT_DRAIN_RATE` units/second. When stamina reaches 0, sprint degrades to SPRINT_EXHAUSTED — the Reclaimer continues moving but at reduced speed. The player cannot re-enter full sprint until stamina recovers to `SPRINT_RECOVERY_THRESHOLD`. +3. **Noise output**: Each movement state emits a `NOISE_LEVEL` float [0.0–1.0] representing footstep acoustics. This value is modified by the class-specific `NOISE_MULT` and broadcast to the Sensor Grid via `FootstepEvent(noiseLevel, position)` on a distance-based interval (`FOOTSTEP_INTERVAL`). The Sensor Grid owns all threshold evaluation — the movement system emits the value, not the trigger decision. +4. **Crouch height**: Crouching reduces the character collider from `STAND_HEIGHT` to `CROUCH_HEIGHT`. This affects visual sensor camera-coverage detection by the Sensor Grid. +5. **Mantle**: Pressing the Jump/Interact input while facing a ledge at height [MANTLE_MIN_HEIGHT, MANTLE_MAX_HEIGHT] above the Reclaimer's feet triggers a mantle sequence. The Reclaimer enters MANTLE state for the animation duration, then exits into WALK stance. +6. **Class multipliers**: All per-class movement stats derive from base values modified by per-class `MOVE_SPEED_MULT` and `NOISE_MULT`. No class has independent absolute values — only multipliers against shared base. +7. **Sprint constraint**: Sprint cannot be entered from CROUCH stance. The Reclaimer must return to WALK first. +8. **Crouch constraint**: Crouch cannot be entered during MANTLE. Crouch exit (standing up) requires headroom — if ceiling prevents it, crouch is locked until clear. +9. **Position authority**: Position is client-predicted locally for responsiveness; server validates and reconciles. *(Provisional — pending Networking Layer GDD.)* + +--- + +### Movement Stance Table + +| Stance | Base Speed | Noise Level | Stamina Effect | Collider Height | +|---|---|---|---|---| +| IDLE (any stance, velocity=0) | 0 m/s | 0.05 | Regen (+15/s after delay) | Stance-dependent | +| WALK | 3.5 m/s | 0.40 | Regen (+15/s) | STAND_HEIGHT (1.8m) | +| SPRINT | 6.0 m/s | 0.90 | Drain (−20/s) | STAND_HEIGHT (1.8m) | +| SPRINT_EXHAUSTED | 4.5 m/s | 0.90 | Stable (0) | STAND_HEIGHT (1.8m) | +| CROUCH | 2.0 m/s | 0.15 | Regen (+15/s) | CROUCH_HEIGHT (1.1m) | +| MANTLE | Animated (~2.0 m/s horizontal) | 0.40 | Regen (+15/s) | Transitional | + +**Footstep interval**: `FootstepEvent` fires every `FOOTSTEP_INTERVAL` meters traveled (default: 0.8m for WALK, 0.6m for SPRINT, 1.2m for CROUCH). Shorter intervals at speed = more events = more potential sensor triggers. + +--- + +### Class Movement Multipliers + +| Class | MOVE_SPEED_MULT | NOISE_MULT | Design Intent | +|---|---|---|---| +| Breacher | 0.90× | 1.20× | Heavy loadout — slower and louder; every move costs more corruption risk | +| Medic | 1.00× | 1.00× | Baseline — the reference Reclaimer | +| Ghost | 1.10× | 0.70× | Faster and quieter — presence management specialist | +| Engineer | 0.95× | 0.95× | Equipment-laden — slight penalties, slight discipline reward | + +**Effective examples:** +- Ghost sprint: 6.0 × 1.10 = 6.6 m/s — fastest Reclaimer +- Breacher sprint: 6.0 × 0.90 = 5.4 m/s — slowest Reclaimer +- Ghost sprint noise: 0.90 × 0.70 = 0.63 (vs. Medic baseline 0.90) + +--- + +### States and Transitions + +| From | To | Condition | +|---|---|---| +| Any grounded | WALK | Default; no sprint or crouch input held | +| WALK | SPRINT | Sprint hold input + stamina ≥ SPRINT_RECOVERY_THRESHOLD | +| SPRINT | SPRINT_EXHAUSTED | Stamina reaches 0 | +| SPRINT_EXHAUSTED | SPRINT | Stamina reaches SPRINT_RECOVERY_THRESHOLD (30 units) | +| SPRINT / SPRINT_EXHAUSTED | WALK | Sprint input released | +| WALK | CROUCH | Crouch toggle input pressed | +| CROUCH | WALK | Crouch toggle pressed again + headroom available | +| WALK / SPRINT / CROUCH | MANTLE | Jump input pressed + ledge in [MANTLE_MIN_HEIGHT, MANTLE_MAX_HEIGHT] range | +| MANTLE | WALK | Mantle animation completes | +| Any | IDLE | Velocity input = zero (sub-state of current stance) | + +**Locked transitions:** +- CROUCH → SPRINT: not allowed. Must go CROUCH → WALK → SPRINT. +- MANTLE → CROUCH: not allowed during mantle animation. + +**Stamina regeneration:** +- Regen begins `REGEN_DELAY` seconds after sprint input is released. +- Regen rate: +15 stamina/second. +- Regen is suspended while at max (100) or while sprinting. + +--- + +### Interactions with Other Systems + +| System | Direction | Interface | Data | +|---|---|---|---| +| Sensor Grid (#7) | Movement → | Emits `FootstepEvent(noiseLevel, position)` every `FOOTSTEP_INTERVAL` meters traveled | Sensor Grid evaluates noiseLevel against zone acoustic threshold to determine if `CorruptionInputEvent(+0.5%)` fires | +| Sensor Grid (#7) | Movement → | Provides current character collider bounds (height, position) each frame | Sensor Grid uses bounds for camera/visual detection coverage | +| Corruption Meter (#3) | Indirect via Sensor Grid | Acoustic sensor events produce +0.5% corruption only if FootstepEvent.noiseLevel exceeds zone threshold | Movement does NOT interact with Corruption Meter directly | +| Reclaimer Combat (#6) | Combat reads Movement | Combat reads `CurrentMovementState` to apply accuracy modifiers (sprint = reduced accuracy, crouch = improved stability) | Movement state is a readable property; Movement does not call Combat | +| Knockdown & Revival (#12) | K&R → Movement | Downed state disables normal locomotion. K&R GDD defines limited crawl movement (~0.5 m/s, constant noise). Movement must expose a `DisableLocomotion(bool)` flag. | Locomotion flag prevents stance transitions while downed | +| Objective System (#16) | Objective reads Position | Proximity detection for objective zone interaction | Position exposed via NetworkVariable (provisional) | +| Reclaimer Class Abilities (#11) | Abilities modify Movement | Ghost's cloaking suite may modify `NOISE_MULT` at runtime. Engineer deploy actions may impose a `MOVE_SPEED_MULT` penalty during deployment. | Class Abilities GDD owns all modifications; Movement exposes NOISE_MULT and MOVE_SPEED_MULT as modifiable fields | +| Networking Layer (#1) *(provisional)* | Foundation | NetworkTransform syncs position to all clients. Client-predicted for local Reclaimer, interpolated for remote players. | Provisional — authority model pending Networking Layer GDD | + +## Formulas + +### Formula 1: Effective Movement Speed + +``` +V_effective = BASE_SPEED[stance] × MOVE_SPEED_MULT[class] +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Effective movement speed | V_effective | float | 0.0–7.0 m/s | Actual movement speed applied to CharacterController each frame | +| Base stance speed | BASE_SPEED | float | 0.0–6.0 m/s | Stance-defined base speed (see Stance Table in Detailed Design) | +| Class speed multiplier | MOVE_SPEED_MULT | float | 0.90–1.10 | Per-class multiplier (Breacher 0.90, Medic 1.00, Ghost 1.10, Engineer 0.95) | + +**Output range:** 0.0 m/s (IDLE) to 6.6 m/s (Ghost sprint). Expected play range: 2.0–6.6 m/s during active movement. + +**Example (Ghost sprint):** V_effective = 6.0 × 1.10 = 6.6 m/s +**Example (Breacher crouch):** V_effective = 2.0 × 0.90 = 1.8 m/s + +--- + +### Formula 2: Effective Noise Level (FootstepEvent output) + +``` +NOISE_OUT = clamp(BASE_NOISE[stance] × NOISE_MULT[class], 0.0, 1.0) +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Noise output | NOISE_OUT | float | 0.0–1.0 | Noise level sent in FootstepEvent to Sensor Grid | +| Base stance noise | BASE_NOISE | float | 0.05–0.90 | Stance-defined base noise (see Stance Table in Detailed Design) | +| Class noise multiplier | NOISE_MULT | float | 0.70–1.20 | Per-class multiplier (Ghost 0.70, Medic 1.00, Breacher 1.20, Engineer 0.95) | + +**Output range:** NOISE_OUT ∈ [0.0, 1.0] after clamping. + +**Example (Breacher sprint):** NOISE_OUT = clamp(0.90 × 1.20, 0.0, 1.0) = 1.0 (maximum noise) +**Example (Ghost crouch):** NOISE_OUT = 0.15 × 0.70 = 0.105 +**Example (Medic walk):** NOISE_OUT = 0.40 × 1.00 = 0.40 + +**Cross-reference**: Sensor Grid (#7) compares NOISE_OUT against zone acoustic thresholds. Sensor Grid GDD must define those thresholds to complete this interface. + +--- + +### Formula 3: Stamina Drain and Regeneration + +**During sprint:** +``` +STAMINA_new = clamp(STAMINA_prev − SPRINT_DRAIN_RATE × Δt, 0.0, STAMINA_MAX) +``` + +**During regen (non-sprint, after REGEN_DELAY has elapsed):** +``` +STAMINA_new = clamp(STAMINA_prev + REGEN_RATE × Δt, 0.0, STAMINA_MAX) +``` + +**Variables:** + +| Variable | Symbol | Type | Range | Description | +|---|---|---|---|---| +| Stamina | STAMINA | float | 0.0–100.0 | Current stamina value | +| Maximum stamina | STAMINA_MAX | float | 100.0 | Constant cap | +| Sprint drain rate | SPRINT_DRAIN_RATE | float | 10–40 /sec | Stamina lost per second while sprinting (default: 20/sec) | +| Regen rate | REGEN_RATE | float | 5–30 /sec | Stamina recovered per second (default: 15/sec) | +| Regen delay | REGEN_DELAY | float | 0.5–3.0 sec | Seconds after sprint ends before regen begins (default: 1.5 sec) | +| Sprint recovery threshold | SPRINT_RECOVERY_THRESHOLD | float | 10–50 | Minimum stamina required to re-enter SPRINT from SPRINT_EXHAUSTED (default: 30) | +| Delta time | Δt | float | frame dt | Time since last frame (seconds) | + +**Output range:** STAMINA ∈ [0.0, 100.0] + +**Sprint duration (defaults):** 100 / 20 = **5 seconds** of continuous sprint before exhaustion. +**Recovery time (0 → sprint threshold):** 1.5s delay + 2.0s regen = **3.5 seconds total**. +**Full recovery (0 → 100):** 1.5 + (100/15) ≈ **8.2 seconds** from exhaustion to full stamina. + +> *`systems-designer` not consulted — Lean mode. Validate stamina values against playtest targets before sprint-to-production.* + +## Edge Cases + +- **If a Reclaimer attempts to sprint while stamina is below `SPRINT_RECOVERY_THRESHOLD` (30 units)**: Sprint input is accepted but SPRINT state is not entered. The Reclaimer remains in WALK. Prevents confusing micro-exhaust UX. + +- **If a Reclaimer inputs crouch while in SPRINT or SPRINT_EXHAUSTED**: Input is ignored. Player must release sprint (return to WALK) before crouch is accepted. SPRINT → CROUCH is a locked transition. + +- **If stamina reaches exactly 0 mid-sprint**: Speed transitions to SPRINT_EXHAUSTED (4.5 m/s). Transition is interpolated over one frame — no velocity pop. Noise level remains 0.90; exhaustion is still loud. + +- **If Ghost's cloaking ability sets `NOISE_MULT` to 0.0**: `NOISE_OUT` = clamp(BASE_NOISE × 0.0, 0, 1) = 0.0. FootstepEvents still fire at `FOOTSTEP_INTERVAL` but with 0.0 noise — no acoustic corruption input is generated. No special movement logic required. + +- **If a Reclaimer attempts to mantle above `MANTLE_MAX_HEIGHT` (2.0m)**: Mantle input rejected. Reclaimers cannot free-jump — only mantle. The Reclaimer is blocked by geometry. + +- **If a Reclaimer attempts to mantle below `MANTLE_MIN_HEIGHT` (0.3m)**: Input ignored. The obstacle is low enough to walk or crouch over; no mantle needed. + +- **If a mantling Reclaimer is downed mid-mantle**: K&R GDD defines interrupt behavior. Movement must expose an interrupt point in the mantle sequence. *(Provisional — K&R GDD owns this.)* + +- **If crouch exit (stand-up) is blocked by a low ceiling**: CROUCH → WALK transition is blocked. Player receives blocked-input feedback (UI indicator or rejected animation). Reclaimer remains in CROUCH until headroom clears. + +- **If a Reclaimer walks off an unguarded platform edge**: No ledge grab or auto-correction. Reclaimers can fall. Fall damage is defined by Health & Damage GDD (#5). + +- **If `FOOTSTEP_INTERVAL` is set very high (e.g., 10m) for testing**: Acoustic sensor events fire rarely. Valid for isolated testing of other Sensor Grid paths without noise pollution. + +- **If two Reclaimers briefly overlap on network desync**: CharacterController collision resolution handles this locally. Server position is authoritative — clients interpolate back. No movement GDD logic required. + +## Dependencies + +| System | Direction | Nature | GDD Status | +|---|---|---|---| +| Networking Layer (#1) | This depends on | Server-authoritative position sync; CharacterController + NetworkTransform authority model | ⚠️ Not designed — provisional | +| Sensor Grid (#7) | Movement → Sensor Grid | Movement emits `FootstepEvent(noiseLevel, position)` and provides collider bounds each frame | Not yet designed | +| Corruption Meter (#3) | Indirect via Sensor Grid | Acoustic events feed corruption only if noiseLevel > zone threshold | ✅ Designed | +| Reclaimer Combat (#6) | Combat reads Movement | Combat reads `CurrentMovementState` for accuracy modifiers | Not yet designed | +| Knockdown & Revival (#12) | K&R → Movement | Downed state disables locomotion via `DisableLocomotion(bool)` flag | Not yet designed | +| Objective System (#16) | Objective reads Position | Position proximity detection for objective zone interaction | Not yet designed | +| Reclaimer Class Abilities (#11) | Abilities modify Movement | Abilities may modify `NOISE_MULT` and `MOVE_SPEED_MULT` at runtime | Not yet designed | + +**Hard dependencies**: Networking Layer (#1) +**Soft dependencies**: All others — movement functions standalone; other systems subscribe to its events and readable state. + +## Tuning Knobs + +All tuning knobs are exposed as data-driven constants (no hardcoded values in script). Safe ranges represent tested playability bounds — outside these ranges, the movement feel degrades significantly or the noise-corruption feedback loop breaks. + +| Knob | Default | Safe Range | Affects | +|---|---|---|---| +| BASE_SPEED[WALK] | 3.5 m/s | 2.0–5.0 m/s | Walk traversal pace; raise for faster tempo, lower for tighter tension | +| BASE_SPEED[SPRINT] | 6.0 m/s | 4.5–8.0 m/s | Sprint speed ceiling; should remain meaningfully faster than walk | +| BASE_SPEED[CROUCH] | 2.0 m/s | 1.0–3.0 m/s | Crouch traversal; too fast and the noise trade-off collapses | +| BASE_SPEED[SPRINT_EXHAUSTED] | 4.5 m/s | 3.5–5.5 m/s | Fallback speed at exhaustion; should stay above walk to reward partial sprint use | +| BASE_NOISE[WALK] | 0.40 | 0.20–0.60 | How often casual walking triggers acoustic sensors; core to ambient tension | +| BASE_NOISE[SPRINT] | 0.90 | 0.70–1.00 | Sprint acoustic baseline; keep high to preserve corruption risk of speed | +| BASE_NOISE[CROUCH] | 0.15 | 0.05–0.30 | Crouch reward — lower means more stealthy, but should not reach 0 | +| NOISE_MULT[Ghost] | 0.70× | 0.40–0.90× | Ghost class identity strength; lower = stronger stealth specialist | +| NOISE_MULT[Breacher] | 1.20× | 1.00–1.50× | Breacher corruption contribution; higher = more team-pressure cost to running Breacher | +| SPRINT_DRAIN_RATE | 20 /sec | 10–40 /sec | Stamina drain per second sprinting; lower = longer sprint windows, higher = more tactical resource | +| REGEN_RATE | 15 /sec | 5–30 /sec | Stamina recovery per second; higher = more forgiving sprint-rest rhythm | +| REGEN_DELAY | 1.5 sec | 0.5–3.0 sec | Seconds after sprint ends before regen begins; higher = sprint commitment punished more | +| SPRINT_RECOVERY_THRESHOLD | 30 | 10–50 | Stamina floor required to re-enter SPRINT; higher = longer forced-walk windows after exhaustion | +| FOOTSTEP_INTERVAL[WALK] | 0.8 m | 0.4–1.5 m | Distance between FootstepEvent firings at walk; lower = more acoustic sensitivity | +| FOOTSTEP_INTERVAL[SPRINT] | 0.6 m | 0.3–1.0 m | Distance between FootstepEvent firings at sprint; keep shorter than walk | +| FOOTSTEP_INTERVAL[CROUCH] | 1.2 m | 0.6–2.0 m | Distance between FootstepEvent firings while crouched; higher = more reward for stealth posture | +| MANTLE_MIN_HEIGHT | 0.3 m | 0.1–0.5 m | Minimum ledge height to trigger mantle; below this, walk/crouch over obstacle | +| MANTLE_MAX_HEIGHT | 2.0 m | 1.5–2.5 m | Maximum ledge height Reclaimers can mantle; above this, geometry is impassable | +| STAND_HEIGHT | 1.8 m | fixed | CharacterController capsule height while standing; drives visual sensor detection volume | +| CROUCH_HEIGHT | 1.1 m | fixed | CharacterController capsule height while crouched; change with caution — level geometry tuned to this | + +## Visual/Audio Requirements + +### Animation Requirements + +| State / Transition | Animation | Notes | +|---|---|---| +| IDLE | Breathing idle cycle | Subtle weapon sway; distinct per class silhouette | +| WALK → SPRINT | Blend into sprint lean | ~0.2s blend; weapon raises closer to body | +| SPRINT → WALK / SPRINT_EXHAUSTED | Blend into recovery | Heavier for SPRINT_EXHAUSTED — visible exertion | +| WALK / SPRINT → CROUCH | Crouch drop transition | Must not clip geometry; collider height changes at frame 1 of animation | +| CROUCH → WALK | Rise transition | Blocked visually if ceiling present (no animation plays) | +| MANTLE | Grab-and-pull sequence | Timed to collider repositioning; ~0.6–0.8 sec | +| STAND → IDLE | Sub-state blend | All stance idles are sub-states of stance, not separate clips | + +All first-person animations are local-only. Third-person (remote Reclaimer) animations are driven by replicated movement state + interpolated position. + +### Audio Requirements + +**Footstep audio** is the primary acoustic identity of movement. Audio design must reinforce the noise-level hierarchy: + +| Stance | Audio Character | Mix Priority | +|---|---|---| +| CROUCH | Near-silent: soft cloth, minimal impact | Low — easy to miss in busy mix | +| WALK | Grounded, deliberate steps — boots on concrete/metal/dust | Medium — present but not intrusive | +| SPRINT | Heavy, urgent — footfall rhythm increases, gear rattle | High — should signal to squadmates nearby | +| SPRINT_EXHAUSTED | Heavier, labored — slight breathing overlay | High + exertion layer | +| MANTLE | Impact on vault, footfall landing | One-shot; medium-high priority | + +**Surface material variants** (minimum required at launch): +- Concrete / pavement +- Metal grating / catwalks +- Gravel / debris +- Interior flooring (tile, composite) + +**Class audio differentiation**: Ghost footsteps should be noticeably quieter than Breacher at the same stance — the audio mix must reflect the NOISE_MULT difference audibly so players can identify class from footstep sound alone. + +**State-change feedback audio**: +- **Sprint exhaustion onset**: Short breath-catch cue at the moment stamina hits 0 (Reclaimer-POV only; not broadcast to others) +- **Sprint recovery** (stamina crossing SPRINT_RECOVERY_THRESHOLD): Subtle ready-state audio cue (optional — validate against UX noise floor) +- **Crouch-ceiling block**: A short muffled thud + denial audio when stand-up is blocked by ceiling + +### UI / HUD Requirements + +- **Stamina bar**: Persistent HUD element. Displays STAMINA [0–100] as a bar. Must: + - Show depletion animation during sprint (smooth drain, not stepped) + - Flash or pulse when entering SPRINT_EXHAUSTED state + - Grey out or visually dim when below SPRINT_RECOVERY_THRESHOLD to communicate sprint is unavailable +- **Crouch state indicator**: A minimal visual indicator (icon or posture change to character silhouette in HUD) showing when CROUCH is active +- **Sprint-blocked feedback**: If sprint input is rejected (below threshold), the stamina bar should flash a "not ready" state — do not silently reject +- **MANTLE_MAX_HEIGHT interaction**: No UI prompt required; geometry is the affordance. If mantle fails (out of range), no tooltip. *Reclaimers read the geometry, not prompts.* + +## UI Requirements + +HUD requirements are covered in the Visual/Audio Requirements section above (Stamina bar, crouch indicator, sprint-blocked feedback). + +**Additional UI notes:** +- The stamina bar must support both mouse/keyboard and gamepad navigation contexts — no hover-only states. The bar is always visible during play (not collapsed). +- Crouch indicator accessibility: must not rely on color alone. Use icon shape or posture silhouette change as the primary indicator; color is additive. +- All movement-state feedback audio must have a visual equivalent for players with hearing loss (screen flash, icon pulse, or caption-style feedback). This is non-blocking pre-launch but required for the accessibility pass. + +## Acceptance Criteria + +All criteria are written as Given-When-Then. Each must pass in both solo-play and networked (4-player) sessions. Automated unit tests cover criteria 1–8; criteria 9–12 require manual QA. + +**AC-MOV-01: FootstepEvent emission at correct interval (walk)** +- **Given** a Medic Reclaimer walking on flat terrain +- **When** the Reclaimer travels 0.8 m from the last FootstepEvent position +- **Then** a `FootstepEvent` fires with `noiseLevel = 0.40 ± 0.01` and current world position + +**AC-MOV-02: FootstepEvent noise scaled by class multiplier (sprint)** +- **Given** a Ghost Reclaimer sprinting +- **When** `FootstepEvent` fires +- **Then** `noiseLevel = clamp(0.90 × 0.70, 0, 1) = 0.63 ± 0.01`; interval is ≤ 0.6 m between events + +**AC-MOV-03: Stamina drains to exhaustion at correct rate** +- **Given** a Breacher Reclaimer with full stamina (100) entering SPRINT +- **When** sprint is held continuously +- **Then** stamina reaches 0 after 5.0 sec ± 0.1 sec; movement state transitions to SPRINT_EXHAUSTED at that moment; speed drops to 5.4 × (4.5/6.0) = 4.05 m/s (Breacher SPRINT_EXHAUSTED) + +**AC-MOV-04: Stamina regen begins after delay** +- **Given** a Reclaimer in SPRINT_EXHAUSTED who releases sprint input +- **When** 1.5 seconds have elapsed +- **Then** stamina begins increasing at +15/sec; before 1.5 sec, stamina does not increase + +**AC-MOV-05: Sprint blocked below recovery threshold** +- **Given** a Reclaimer whose stamina is 25 (below SPRINT_RECOVERY_THRESHOLD = 30) +- **When** the sprint input is held +- **Then** the Reclaimer does not enter SPRINT; movement remains at WALK speed; no state transition occurs + +**AC-MOV-06: Crouch-to-sprint transition is blocked** +- **Given** a Reclaimer in CROUCH stance +- **When** sprint input is held (without first releasing crouch) +- **Then** the Reclaimer does not enter SPRINT; crouch speed is maintained; no state transition occurs + +**AC-MOV-07: Mantle succeeds for ledge in valid height range** +- **Given** a Reclaimer standing against a ledge at height 1.2 m above their feet +- **When** the Jump/Interact input is pressed +- **Then** the Reclaimer enters MANTLE state; mantle animation plays; upon completion Reclaimer stands atop the ledge in WALK stance + +**AC-MOV-08: Mantle fails for ledge above max height** +- **Given** a Reclaimer standing against a wall section at height 3.0 m (above MANTLE_MAX_HEIGHT) +- **When** the Jump/Interact input is pressed +- **Then** no mantle is triggered; the Reclaimer remains stationary; wall is impassable + +**AC-MOV-09: Crouch-ceiling lock prevents stand-up** +- **Given** a Reclaimer crouched in a space with a ceiling 1.3 m above the floor (below STAND_HEIGHT) +- **When** the crouch toggle is pressed to stand +- **Then** the Reclaimer remains in CROUCH; no height change occurs; a blocked-input feedback signal is sent (audio or UI indicator per Visual/Audio Requirements) + +**AC-MOV-10: Ghost cloaking at NOISE_MULT = 0.0 produces zero-noise FootstepEvent** +- **Given** Ghost's cloaking ability has set `NOISE_MULT` to 0.0 +- **When** Ghost walks and `FootstepEvent` fires at the normal interval +- **Then** `FootstepEvent.noiseLevel = 0.0`; event still fires (no suppression of emission); Sensor Grid receives the event with 0.0 noise value + +**AC-MOV-11: Remote Reclaimer position interpolates smoothly** +- **Given** a networked 4-player session with variable simulated latency (50–150 ms) +- **When** a remote Reclaimer is observed walking and sprinting +- **Then** no visible position snap or teleport occurs; remote Reclaimer movement appears visually continuous; interpolation error does not exceed 0.3 m of visual offset at any frame *(manual QA — network simulation required)* + +**AC-MOV-12: Gamepad control scheme mirrors Keyboard/Mouse behavior** +- **Given** a Reclaimer controlled via gamepad +- **When** all movement inputs are exercised (walk, sprint, crouch, mantle, idle) +- **Then** all state transitions, noise outputs, stamina effects, and FootstepEvent emissions match the Keyboard/Mouse results identically; no movement feature is unavailable or degraded on gamepad *(manual QA)* + +## Open Questions + +1. **Networking authority model for position** — Client-predicted locally, server-validated is the provisional model (Core Rule 9). This must be confirmed by the Networking Layer GDD (#1). If the authority model changes (e.g., server-authoritative with no client prediction), stamina and noise calculations may need to move to the server. Blocked on `networking-layer.md`. + +2. **Fall damage threshold** — Movement defines that Reclaimers can fall from unguarded edges (Edge Case 9), but fall damage thresholds and death are owned by Health & Damage GDD (#5). At what fall height does damage begin? Does a Breacher's lower speed mean slightly different fall momentum? Flag for `health-damage.md`. + +3. **Downed-state crawl movement** — K&R GDD (#12) owns the downed crawl mechanic (~0.5 m/s, constant noise). Does downed crawl emit FootstepEvents? At what noise level? Does crawl noise use the same NOISE_MULT or is it class-independent? Movement GDD exposes `DisableLocomotion(bool)` — K&R GDD must define whether "downed" means full disable or partial (crawl-only). Blocked on `knockdown-revival.md`. + +4. **MOVE_SPEED_MULT and NOISE_MULT modification from Class Abilities** — Engineer's deploy-action penalty and Ghost's cloaking NOISE_MULT=0.0 are mentioned but not fully specified. Are these additive or override? Can multiple modifiers stack (e.g., Ghost cloaking + crouching — does NOISE_MULT compound or floor at 0.0)? Blocked on `reclaimer-class-abilities.md`. + +5. **Mantle interrupt from external forces** — Edge Case 7 defers downed-during-mantle to K&R GDD. But what about being hit by a projectile mid-mantle (Combat, #6)? Can combat interrupt a mantle? If mantle is a locked animation state, hit reactions need to know this. Requires cross-referencing `reclaimer-combat.md`. + +6. **Footstep audio occlusion for remote players** — Should remote Reclaimer footstep audio be spatially occluded by geometry (3D audio with physics raycasting)? This affects the perceived presence of other Reclaimers and has significant audio/performance implications. Not a movement GDD decision, but must be flagged for the Audio system GDD. diff --git a/design/gdd/systems-index.md b/design/gdd/systems-index.md new file mode 100644 index 0000000000..a98b13c3fb --- /dev/null +++ b/design/gdd/systems-index.md @@ -0,0 +1,487 @@ +# SYNTHFALL — Systems Index + +**Status**: Complete — 30 systems enumerated, prioritized, and ordered +**Created**: 2026-05-15 +**Source**: Decomposed from `design/gdd/game-concept.md` via `/map-systems` +**Review Mode**: Lean (TD-SYSTEM-BOUNDARY and CD-SYSTEMS gates skipped) + +--- + +## Summary + +| Category | Count | +|---|---| +| Total systems | 30 | +| MVP systems | 25 | +| Launch systems | 5 | +| GDDs authored | 3 | +| GDDs remaining | 27 | + +**Bottleneck systems** (highest design risk — many others depend on these): +1. **Networking Layer & Session Authority** — 20+ downstream dependencies +2. **Corruption Meter** — 8 direct downstream dependencies; the game's spine +3. **Level/Sector System** — 6 downstream dependencies; geometry model for AI, controls, objectives + +**No circular dependencies detected.** + +--- + +## Design Order + +Design systems in this order. Dependencies are listed so each GDD can cross-reference its prerequisites. Do not design a system before its dependencies have GDDs. + +### MVP — Foundation (Design First) + +| Order | System | GDD File | Dependencies | Status | +|---|---|---|---|---| +| 1 | Networking Layer & Session Authority | `networking-layer.md` | None | Not Started | +| 2 | Player Identity & Persistence | `player-identity.md` | None | Not Started | + +### MVP — Core + +| Order | System | GDD File | Dependencies | Status | +|---|---|---|---|---| +| 3 | Corruption Meter | `corruption-meter.md` | Networking Layer (#1) | **Designed** | +| 4 | Reclaimer Movement | `reclaimer-movement.md` | Networking Layer (#1) | **Designed** | +| 5 | Health & Damage | `health-damage.md` | Networking Layer (#1) | **Designed** | +| 6 | Reclaimer Combat | `reclaimer-combat.md` | Reclaimer Movement (#4), Health & Damage (#5) | Not Started | +| 7 | Sensor Grid | `sensor-grid.md` | Networking Layer (#1), Reclaimer Movement (#4) | Not Started | +| 8 | Level/Sector System | `level-sector-system.md` | Networking Layer (#1) | Not Started | +| 9 | Synth AI & Pathfinding | `synth-ai-pathfinding.md` | Level/Sector System (#8) | Not Started | +| 10 | Ammo & Resource Management | `ammo-resource-management.md` | Reclaimer Combat (#6) | Not Started | + +### MVP — Feature + +| Order | System | GDD File | Dependencies | Status | +|---|---|---|---|---| +| 11 | Reclaimer Class Abilities | `reclaimer-class-abilities.md` | Reclaimer Combat (#6), Ammo & Resource Management (#10) | Not Started | +| 12 | Knockdown & Revival | `knockdown-revival.md` | Health & Damage (#5), Reclaimer Movement (#4) | Not Started | +| 13 | Synth Unit Roster | `synth-unit-roster.md` | Synth AI & Pathfinding (#9), Health & Damage (#5) | Not Started | +| 14 | Synth Spawn & Deployment | `synth-spawn-deployment.md` | Synth Unit Roster (#13), Level/Sector System (#8) | Not Started | +| 15 | Environmental Controls | `environmental-controls.md` | Level/Sector System (#8), Corruption Meter (#3) | Not Started | +| 16 | Objective System | `objective-system.md` | Level/Sector System (#8), Corruption Meter (#3), Reclaimer Movement (#4) | Not Started | +| 17 | Threshold Event System | `threshold-event-system.md` | Corruption Meter (#3), Synth Unit Roster (#13), Environmental Controls (#15) | Not Started | +| 18 | Win/Loss Conditions | `win-loss-conditions.md` | Objective System (#16), Corruption Meter (#3), Health & Damage (#5) | Not Started | +| 19 | Hive Mind God-View | `hive-mind-god-view.md` | Networking Layer (#1), Sensor Grid (#7), Level/Sector System (#8) | Not Started | + +### MVP — Presentation + +| Order | System | GDD File | Dependencies | Status | +|---|---|---|---|---| +| 20 | Reclaimer HUD | `reclaimer-hud.md` | Health & Damage (#5), Ammo & Resource Management (#10), Corruption Meter (#3), Reclaimer Class Abilities (#11) | Not Started | +| 21 | Hive Mind Interface | `hive-mind-interface.md` | Hive Mind God-View (#19), Corruption Meter (#3), Synth Spawn & Deployment (#14) | Not Started | +| 22 | Waypoint & Navigation | `waypoint-navigation.md` | Objective System (#16), Level/Sector System (#8) | Not Started | +| 23 | Sector Transition System | `sector-transition-system.md` | Objective System (#16), Win/Loss Conditions (#18), Corruption Meter (#3) | Not Started | + +### MVP — Meta + +| Order | System | GDD File | Dependencies | Status | +|---|---|---|---|---| +| 24 | Session Management & Lobby | `session-management-lobby.md` | Networking Layer (#1), Player Identity & Persistence (#2) | Not Started | +| 25 | Post-Match Debrief | `post-match-debrief.md` | Win/Loss Conditions (#18), Corruption Meter (#3), Player Identity & Persistence (#2) | Not Started | + +> **Note (Post-Match Debrief in MVP)**: Elevated from Launch to MVP. Pillar 3 — "Every Match Tells a Story" — requires the debrief to capture whether matches are generating memorable moments during playtesting. The mission log and Corruption timeline make the emergent narrative legible after the fact. + +### Launch + +| Order | System | GDD File | Dependencies | Status | +|---|---|---|---|---| +| 26 | Matchmaking & Role Queue | `matchmaking-role-queue.md` | Session Management & Lobby (#24), Player Identity & Persistence (#2) | Not Started | +| 27 | Class Progression | `class-progression.md` | Player Identity & Persistence (#2), Reclaimer Class Abilities (#11) | Not Started | +| 28 | Cosmetic System | `cosmetic-system.md` | Player Identity & Persistence (#2), Reclaimer HUD (#20) | Not Started | +| 29 | Hive Mind Personalities | `hive-mind-personalities.md` | Synth Unit Roster (#13), Synth Spawn & Deployment (#14), Player Identity & Persistence (#2) | Not Started | +| 30 | Monetization Layer | `monetization-layer.md` | Cosmetic System (#28), Player Identity & Persistence (#2) | Not Started | + +--- + +## Full System Catalogue + +### Layer 1 — Foundation + +#### 1. Networking Layer & Session Authority +- **Category**: Foundation +- **Milestone**: MVP +- **GDD**: `design/gdd/networking-layer.md` +- **Dependencies**: None +- **Dependents**: 20+ systems +- **Description**: NGO 2.X asymmetric session model — 4 Reclaimer clients + 1 Hive Mind client. Defines authority (who owns what), state synchronization rules, latency compensation. The authority model is asymmetric by design: the Hive Mind has authority over environmental state; Reclaimers have authority over their own positions and actions. +- **Explicit in concept**: Yes (network/LAN play requirement, NGO mentioned in risk register) +- **Risk**: HIGH — bottleneck. Everything networked depends on this. Architecture decisions here are the hardest to undo. + +#### 2. Player Identity & Persistence +- **Category**: Foundation +- **Milestone**: MVP (basic) → Launch (full progression data) +- **GDD**: `design/gdd/player-identity.md` +- **Dependencies**: None +- **Dependents**: Session Management, Matchmaking, Post-Match Debrief, Class Progression, Cosmetics, Hive Mind Personalities, Monetization +- **Description**: Player accounts, nicknames, cross-session persistent data (unlocks, cosmetics, Hive Mind reputation tracking). MVP scope: local player profiles sufficient for LAN play. Launch scope: Steam-linked identity, progression data, cosmetic inventory. +- **Explicit in concept**: Yes (Hive Mind reputation tracking, progression system) + +--- + +### Layer 2 — Core + +#### 3. Corruption Meter +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/corruption-meter.md` +- **Dependencies**: Networking Layer (#1) +- **Dependents**: Environmental Controls (#15), Objective System (#16), Threshold Event System (#17), Win/Loss Conditions (#18), Reclaimer HUD (#20), Hive Mind Interface (#21), Sector Transition System (#23), Post-Match Debrief (#25) +- **Description**: 0–100% tension engine. Rises passively and accelerates from Reclaimer actions (gunfire, sensor triggers, downed teammates, failed objectives). Decelerates on objective completion. Hive Mind can actively accelerate through unit pressure and environmental triggers. Threshold events at 25/50/75/100%. +- **Explicit in concept**: Yes — dedicated section in concept doc +- **Pillars**: Pillar 1 (The City Is the Enemy), Pillar 3 (Every Match Tells a Story) +- **Risk**: HIGH — bottleneck. The Corruption Meter's formula, event weights, and threshold triggers define the pacing of every match. + +#### 4. Reclaimer Movement +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/reclaimer-movement.md` +- **Dependencies**: Networking Layer (#1) +- **Dependents**: Reclaimer Combat (#6), Sensor Grid (#7), Knockdown & Revival (#12), Objective System (#16) +- **Description**: FPS locomotion for all 4 Reclaimer classes. Crouching, mantling, sprint, squad movement feel. The physical language of being a Reclaimer in AXIOM City — grounded realism with suppressed heroics (per art bible). +- **Explicit in concept**: Implicit (FPS perspective, squad movement) + +#### 5. Health & Damage +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/health-damage.md` +- **Dependencies**: Networking Layer (#1) +- **Dependents**: Reclaimer Combat (#6), Knockdown & Revival (#12), Synth Unit Roster (#13), Win/Loss Conditions (#18), Reclaimer HUD (#20) +- **Description**: HP pools for Reclaimers and Synth units. Damage types (ballistic, environmental, Synth). 3-tier armor state progression (Operational → Compromised → Critical) per art bible spec. Downed state threshold. Network-authoritative damage resolution. +- **Explicit in concept**: Implicit (survival, downed teammates) +- **Risk**: MEDIUM — bottleneck. 5 systems depend on this. + +#### 6. Reclaimer Combat +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/reclaimer-combat.md` +- **Dependencies**: Reclaimer Movement (#4), Health & Damage (#5) +- **Dependents**: Ammo & Resource Management (#10), Reclaimer Class Abilities (#11) +- **Description**: Weapons, aiming, firing, hit detection, damage math for all weapon types in the Reclaimer arsenal. Gunfire is the primary Corruption accelerant — the system that makes every loud action a trade-off. +- **Explicit in concept**: Implicit (squad formation, ammo management) + +#### 7. Sensor Grid +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/sensor-grid.md` +- **Dependencies**: Networking Layer (#1), Reclaimer Movement (#4) +- **Dependents**: Corruption Meter (#3), Hive Mind God-View (#19) +- **Description**: AXIOM City's detection network — camera arrays, acoustic sensors, biometric scanners. Recognizes Reclaimer actions and feeds events into the Corruption Meter with weighted inputs. The Hive Mind perceives the city through this system. Camera manipulation (Environmental Control #15) affects this system's outputs. +- **Explicit in concept**: Implicit ("every loud action feeds the Corruption meter", camera network manipulation) +- **Pillars**: Pillar 1 (The City Is the Enemy) + +#### 8. Level/Sector System +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/level-sector-system.md` +- **Dependencies**: Networking Layer (#1) +- **Dependents**: Synth AI & Pathfinding (#9), Environmental Controls (#15), Objective System (#16), Hive Mind God-View (#19), Waypoint & Navigation (#22), Sector Transition System (#23) +- **Description**: Modular AXIOM City tile architecture, sector structure, dynamic geometry state (blast doors, floor integrity, toxin zone activation). Houses the 3 corruption visual states (Pristine → Contested → Consumed). Manages the shared level state that all players experience. +- **Explicit in concept**: Yes (AXIOM City sectors, modular tile set, 3-4 sectors per match) +- **Risk**: HIGH — bottleneck. 6 systems need its geometry and state model. + +#### 9. Synth AI & Pathfinding +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/synth-ai-pathfinding.md` +- **Dependencies**: Level/Sector System (#8) +- **Dependents**: Synth Unit Roster (#13) +- **Description**: Unit navigation through AXIOM City, pursuit logic, threat prioritization, flanking behaviors. Must handle dynamic geometry changes (blast doors sealing, floors collapsing). The "city thinks" behavior that makes Synth units feel like extensions of an intelligent space. +- **Explicit in concept**: Implicit (Stalker "follows heat signatures through walls") +- **Pillars**: Pillar 1 (The City Is the Enemy) + +#### 10. Ammo & Resource Management +- **Category**: Core +- **Milestone**: MVP +- **GDD**: `design/gdd/ammo-resource-management.md` +- **Dependencies**: Reclaimer Combat (#6) +- **Dependents**: Reclaimer Class Abilities (#11), Reclaimer HUD (#20) +- **Description**: Scarce ammo pools per weapon type, medkit charges, ability charges, resource pickup logic. Scarcity is the pressure that forces Reclaimers into hard decisions — when to engage, when to run, when to save the revival kit. The "every loud action costs something" system. +- **Explicit in concept**: Yes ("manage scarce ammo and med resources") +- **Pillars**: Pillar 3 (Every Match Tells a Story) + +--- + +### Layer 3 — Feature + +#### 11. Reclaimer Class Abilities +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/reclaimer-class-abilities.md` +- **Dependencies**: Reclaimer Combat (#6), Ammo & Resource Management (#10) +- **Dependents**: Knockdown & Revival (#12), Reclaimer HUD (#20), Class Progression (#27) +- **Description**: 4 classes — Breacher (thermite charges, heavy weapons), Herald/Medic (revival injectors, trauma kit), Ghost (sensor jammer, cloaking suite), Warden/Engineer (deployable turrets, door-seal breakers). Each class's tools define its playstyle and squad role. Class identity must be readable in silhouette (art bible) and in play pattern. +- **Explicit in concept**: Yes — dedicated section in concept doc +- **Pillars**: Pillar 2 (Asymmetry Is the Point), Pillar 4 (Identity Over Loadout) + +#### 12. Knockdown & Revival +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/knockdown-revival.md` +- **Dependencies**: Health & Damage (#5), Reclaimer Movement (#4) +- **Dependents**: Reclaimer HUD (#20), Win/Loss Conditions (#18) +- **Description**: Downed state, bleedout timer, revival window, Herald/Medic priority mechanic. A downed teammate is the game's highest-stakes moment — the squad either comes together or breaks apart. The squad-bond mechanic. +- **Explicit in concept**: Implicit (revival injectors, downed teammate as Corruption accelerant) +- **Pillars**: Pillar 3 (Every Match Tells a Story) + +#### 13. Synth Unit Roster +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/synth-unit-roster.md` +- **Dependencies**: Synth AI & Pathfinding (#9), Health & Damage (#5) +- **Dependents**: Synth Spawn & Deployment (#14), Threshold Event System (#17), Hive Mind Personalities (#29) +- **Description**: Crawler (fast, fragile, swarm), Stalker (slow, tanky, single-target pressure), Pulse Drone (aerial, HUD disruption, position reveal). Each unit type gives the Hive Mind a distinct tactical tool — without distinct units, the HM player has no vocabulary for situational decision-making. +- **Explicit in concept**: Yes — dedicated section in concept doc +- **Pillars**: Pillar 2 (Asymmetry Is the Point) + +#### 14. Synth Spawn & Deployment +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/synth-spawn-deployment.md` +- **Dependencies**: Synth Unit Roster (#13), Level/Sector System (#8) +- **Dependents**: Hive Mind Interface (#21) +- **Description**: Hive Mind deployment interface — placement rules, spawn limits per unit type, cooldowns, spawn point validation, unit cap per active deployment. The HM's core 30-second interaction loop. +- **Explicit in concept**: Yes ("deploy Synth units") + +#### 15. Environmental Controls +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/environmental-controls.md` +- **Dependencies**: Level/Sector System (#8), Corruption Meter (#3) +- **Dependents**: Threshold Event System (#17), Sensor Grid (#7 — camera manipulation) +- **Description**: Hive Mind's 5 tool types: blast door sealing (squad splitting), floor collapse triggers (fall damage, route disruption), toxin flooding (gas mask resource drain), camera network manipulation (remove or spoof Reclaimer waypoints), power grid surges (kills lights, disables Reclaimer tech). What makes the city feel like an active opponent, not a passive map. +- **Explicit in concept**: Yes — dedicated section in concept doc +- **Pillars**: Pillar 1 (The City Is the Enemy) + +#### 16. Objective System +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/objective-system.md` +- **Dependencies**: Level/Sector System (#8), Corruption Meter (#3), Reclaimer Movement (#4) +- **Dependents**: Win/Loss Conditions (#18), Waypoint & Navigation (#22), Sector Transition System (#23), Post-Match Debrief (#25) +- **Description**: Data Cache → Power Relay → Extraction Beacon sequence. Objective completion grants brief Corruption reduction (the relief beat). Each completed objective triggers a harder Hive Mind counter-response. The mission structure that gives the 5-minute loop its shape. +- **Explicit in concept**: Yes — dedicated section in concept doc (5-Minute Loop) + +#### 17. Threshold Event System +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/threshold-event-system.md` +- **Dependencies**: Corruption Meter (#3), Synth Unit Roster (#13), Environmental Controls (#15) +- **Dependents**: Win/Loss Conditions (#18) +- **Description**: What the city does at 25/50/75/100% Corruption — unit escalation (more units, faster response), hazard activation (additional environmental controls become available), and environmental layout changes (previously stable areas become hostile). The city gets angrier. Gives the match its pacing arc. +- **Explicit in concept**: Yes ("at defined thresholds: the city upgrades its response") +- **Pillars**: Pillar 1 (The City Is the Enemy), Pillar 3 (Every Match Tells a Story) + +#### 18. Win/Loss Conditions +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/win-loss-conditions.md` +- **Dependencies**: Objective System (#16), Corruption Meter (#3), Health & Damage (#5) +- **Dependents**: Sector Transition System (#23), Post-Match Debrief (#25) +- **Description**: Reclaimer win: extract all surviving operatives at the final beacon. Hive Mind win: Corruption reaches 100% before extraction, OR full squad wipe. Defines the termination conditions for the session loop and the stakes of every major decision. +- **Explicit in concept**: Yes + +#### 19. Hive Mind God-View +- **Category**: Feature +- **Milestone**: MVP +- **GDD**: `design/gdd/hive-mind-god-view.md` +- **Dependencies**: Networking Layer (#1), Sensor Grid (#7), Level/Sector System (#8) +- **Dependents**: Hive Mind Interface (#21) +- **Description**: Elevated camera system — the HM's omniscient perspective over AXIOM City. Sensor network visualization (seeing through cameras, detecting Reclaimer positions). The "you are the city" experience. Must be visually and experientially distinct from the Reclaimer FPS perspective (Pillar 2). +- **Explicit in concept**: Implicit ("monitor all Reclaimer positions through the city's sensor grid") +- **Pillars**: Pillar 2 (Asymmetry Is the Point) + +--- + +### Layer 4 — Presentation + +#### 20. Reclaimer HUD +- **Category**: Presentation +- **Milestone**: MVP +- **GDD**: `design/gdd/reclaimer-hud.md` +- **Dependencies**: Health & Damage (#5), Ammo & Resource Management (#10), Corruption Meter (#3), Reclaimer Class Abilities (#11) +- **Dependents**: Cosmetic System (#28) +- **Description**: Per art bible Section 7 spec — interrupted rectangles, 70% diegetic, snap motion + 1-frame flash, corruption meter as vertical intruder element with 0.26 threshold interrupt. Class-specific readouts. Squad status strip. Tactical information hierarchy (4 tiers). +- **Explicit in concept**: Implicit + +#### 21. Hive Mind Interface +- **Category**: Presentation +- **Milestone**: MVP +- **GDD**: `design/gdd/hive-mind-interface.md` +- **Dependencies**: Hive Mind God-View (#19), Corruption Meter (#3), Synth Spawn & Deployment (#14) +- **Dependents**: None +- **Description**: Per art bible Section 7 spec — radial/concentric, propagating animation, 8-simultaneous-animation ceiling, Reclaimer Amber anomaly markers in a cold-color field. Hive Mind gamepad focus system in scope (custom radial navigation required before production). +- **Explicit in concept**: Implicit + +#### 22. Waypoint & Navigation +- **Category**: Presentation +- **Milestone**: MVP +- **GDD**: `design/gdd/waypoint-navigation.md` +- **Dependencies**: Objective System (#16), Level/Sector System (#8) +- **Dependents**: None +- **Description**: Objective markers, squad ping system (callouts), Extraction White navigation beacons. Camera manipulation (Environmental Control #15) can spoof or remove these — the system must handle degraded states. Navigation must remain functional with UI disabled (per art bible Section 6: the world reveals, the HUD confirms). +- **Explicit in concept**: Implicit + +#### 23. Sector Transition System +- **Category**: Presentation +- **Milestone**: MVP +- **GDD**: `design/gdd/sector-transition-system.md` +- **Dependencies**: Objective System (#16), Win/Loss Conditions (#18), Corruption Meter (#3) +- **Dependents**: None +- **Description**: Between-sector checkpoints, Corruption carry/reset rules, psychological pacing (natural break points), sector loading. The concept specifically calls these out: "natural break points at sector transitions — psychological checkpoints even in a loss." +- **Explicit in concept**: Yes + +--- + +### Layer 5 — Meta + +#### 24. Session Management & Lobby +- **Category**: Meta +- **Milestone**: MVP +- **GDD**: `design/gdd/session-management-lobby.md` +- **Dependencies**: Networking Layer (#1), Player Identity & Persistence (#2) +- **Dependents**: Matchmaking & Role Queue (#26) +- **Description**: Pre-match setup, role selection (HM vs. Reclaimer queue), team formation, LAN/local session hosting. The gateway into every match. +- **Explicit in concept**: Yes ("basic lobby and session management") + +#### 25. Post-Match Debrief +- **Category**: Meta +- **Milestone**: **MVP** *(elevated from Launch)* +- **GDD**: `design/gdd/post-match-debrief.md` +- **Dependencies**: Win/Loss Conditions (#18), Corruption Meter (#3), Player Identity & Persistence (#2) +- **Dependents**: None +- **Description**: Mission log, Corruption timeline, Reclaimer highlights, squad stat summary. Records the emergent story of each match. **Elevated to MVP** — Pillar 3 requires the debrief to validate whether matches are generating memorable moments during playtesting. Without it, the "every match tells a story" promise is unverifiable. +- **Explicit in concept**: Yes + +#### 26. Matchmaking & Role Queue +- **Category**: Meta +- **Milestone**: Launch +- **GDD**: `design/gdd/matchmaking-role-queue.md` +- **Dependencies**: Session Management & Lobby (#24), Player Identity & Persistence (#2) +- **Dependents**: None +- **Description**: Steam matchmaking, HM vs. Reclaimer role queue, AI fallback for Reclaimer slots during testing (concept risk register). LAN/local is sufficient for MVP. +- **Explicit in concept**: Yes + +#### 27. Class Progression +- **Category**: Meta +- **Milestone**: Launch +- **GDD**: `design/gdd/class-progression.md` +- **Dependencies**: Player Identity & Persistence (#2), Reclaimer Class Abilities (#11) +- **Dependents**: Cosmetic System (#28) +- **Description**: XP system, unlock trees, class specializations (deeper Breacher breach-and-clear tools, Medic revival mechanics, Ghost stealth suite, Engineer deployable gadgets). Pillar 4 identity expanded beyond base loadout. +- **Explicit in concept**: Yes + +#### 28. Cosmetic System +- **Category**: Meta +- **Milestone**: Launch +- **GDD**: `design/gdd/cosmetic-system.md` +- **Dependencies**: Player Identity & Persistence (#2), Reclaimer HUD (#20) +- **Dependents**: Monetization Layer (#30) +- **Description**: Equip/display system for armor worn-and-weathered states, weapon skins, faction insignia. Self-expression within Pillar 4 (Identity Over Loadout). Anti-pillar: cosmetic only, never progression-affecting. +- **Explicit in concept**: Yes + +#### 29. Hive Mind Personalities +- **Category**: Meta +- **Milestone**: Launch +- **GDD**: `design/gdd/hive-mind-personalities.md` +- **Dependencies**: Synth Unit Roster (#13), Synth Spawn & Deployment (#14), Player Identity & Persistence (#2) +- **Dependents**: None +- **Description**: Alternate unit rosters, trap varieties, and environmental control tools representing different aspects of AXIOM's emergent intelligence. Each personality gives the Hive Mind player a different strategic identity. Hive Mind players develop a reputation tied to their personality choice. +- **Explicit in concept**: Yes + +#### 30. Monetization Layer +- **Category**: Meta +- **Milestone**: Launch +- **GDD**: `design/gdd/monetization-layer.md` +- **Dependencies**: Cosmetic System (#28), Player Identity & Persistence (#2) +- **Dependents**: None +- **Description**: Cosmetic shop / battle pass framework. Hard constraint from anti-pillars: no pay-to-win, no progression-affecting items. Cosmetic identity only. +- **Explicit in concept**: Yes + +--- + +## Dependency Map (Adjacency Reference) + +``` +FOUNDATION + [1] Networking Layer ──────────────────────────────────────────────┐ + [2] Player Identity │ + ▼ +CORE (feeds into) + [3] Corruption Meter ← [1] │ + [4] Reclaimer Movement ← [1] │ + [5] Health & Damage ← [1] │ + [6] Reclaimer Combat ← [4][5] │ + [7] Sensor Grid ← [1][4] │ + [8] Level/Sector System ← [1] │ + [9] Synth AI & Pathfinding ← [8] │ + [10] Ammo & Resource Management ← [6] │ + │ +FEATURE │ + [11] Reclaimer Class Abilities ← [6][10] │ + [12] Knockdown & Revival ← [5][4] │ + [13] Synth Unit Roster ← [9][5] │ + [14] Synth Spawn & Deployment ← [13][8] │ + [15] Environmental Controls ← [8][3] │ + [16] Objective System ← [8][3][4] │ + [17] Threshold Event System ← [3][13][15] │ + [18] Win/Loss Conditions ← [16][3][5] │ + [19] Hive Mind God-View ← [1][7][8] │ + │ +PRESENTATION │ + [20] Reclaimer HUD ← [5][10][3][11] │ + [21] Hive Mind Interface ← [19][3][14] │ + [22] Waypoint & Navigation ← [16][8] │ + [23] Sector Transition System ← [16][18][3] │ + │ +META │ + [24] Session Management & Lobby ← [1][2] │ + [25] Post-Match Debrief ← [18][3][2] │ + [26] Matchmaking & Role Queue ← [24][2] ─── LAUNCH ────────┘ + [27] Class Progression ← [2][11] + [28] Cosmetic System ← [2][20] + [29] Hive Mind Personalities ← [13][14][2] + [30] Monetization Layer ← [28][2] +``` + +--- + +## Progress Tracker + +| System | GDD | Status | Designed By | Notes | +|---|---|---|---|---| +| Networking Layer & Session Authority | `networking-layer.md` | Not Started | — | — | +| Player Identity & Persistence | `player-identity.md` | Not Started | — | — | +| Corruption Meter | `corruption-meter.md` | **Designed** | design-system | Pending /design-review | +| Reclaimer Movement | `reclaimer-movement.md` | **Designed** | design-system | Pending /design-review | +| Health & Damage | `health-damage.md` | **Designed** | design-system | Pending /design-review | +| Reclaimer Combat | `reclaimer-combat.md` | Not Started | — | — | +| Sensor Grid | `sensor-grid.md` | Not Started | — | — | +| Level/Sector System | `level-sector-system.md` | Not Started | — | — | +| Synth AI & Pathfinding | `synth-ai-pathfinding.md` | Not Started | — | — | +| Ammo & Resource Management | `ammo-resource-management.md` | Not Started | — | — | +| Reclaimer Class Abilities | `reclaimer-class-abilities.md` | Not Started | — | — | +| Knockdown & Revival | `knockdown-revival.md` | Not Started | — | — | +| Synth Unit Roster | `synth-unit-roster.md` | Not Started | — | — | +| Synth Spawn & Deployment | `synth-spawn-deployment.md` | Not Started | — | — | +| Environmental Controls | `environmental-controls.md` | Not Started | — | — | +| Objective System | `objective-system.md` | Not Started | — | — | +| Threshold Event System | `threshold-event-system.md` | Not Started | — | — | +| Win/Loss Conditions | `win-loss-conditions.md` | Not Started | — | — | +| Hive Mind God-View | `hive-mind-god-view.md` | Not Started | — | — | +| Reclaimer HUD | `reclaimer-hud.md` | Not Started | — | Art bible Section 7 is the design brief | +| Hive Mind Interface | `hive-mind-interface.md` | Not Started | — | Art bible Section 7 is the design brief | +| Waypoint & Navigation | `waypoint-navigation.md` | Not Started | — | — | +| Sector Transition System | `sector-transition-system.md` | Not Started | — | — | +| Session Management & Lobby | `session-management-lobby.md` | Not Started | — | — | +| Post-Match Debrief | `post-match-debrief.md` | Not Started | — | MVP — validates Pillar 3 | +| Matchmaking & Role Queue | `matchmaking-role-queue.md` | Not Started | — | LAUNCH | +| Class Progression | `class-progression.md` | Not Started | — | LAUNCH | +| Cosmetic System | `cosmetic-system.md` | Not Started | — | LAUNCH | +| Hive Mind Personalities | `hive-mind-personalities.md` | Not Started | — | LAUNCH | +| Monetization Layer | `monetization-layer.md` | Not Started | — | LAUNCH | + +--- + +*Generated via `/map-systems` — Claude Code Game Studios* +*Update this file after each GDD is authored: change status to "Complete" and add the designer's name.* diff --git a/design/registry/entities.yaml b/design/registry/entities.yaml index bcf9a95aaf..a8934daa8e 100644 --- a/design/registry/entities.yaml +++ b/design/registry/entities.yaml @@ -37,7 +37,7 @@ # Each entry: name, status, source, referenced_by[], attributes{}, added, revised version: 1 -last_updated: "" +last_updated: "2026-05-15" # Updated: added 3 Synth entities (crawler, stalker, pulse_drone), 2 H&D formulas, 6 H&D constants; updated TEAMMATE_DOWNED_WEIGHT referenced_by # ─── ENTITIES ──────────────────────────────────────────────────────────────── # Named game-world objects: enemies, NPCs, characters, factions, bosses. @@ -48,7 +48,51 @@ last_updated: "" # Attribute fields: any key stats that could appear in another GDD # (health, damage, drops, faction, etc.) -entities: [] +entities: + - name: crawler + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/synth-unit-roster.md # Roster defines AI, spawn rules, behavior + - design/gdd/reclaimer-combat.md # Combat calculates TTK based on HP + health: 40 + faction: synth + armor_states: none + death_threshold: 0 + notes: "Fragile swarm unit. 40 HP — designed to die in 1-2 Ballistic hits. No armor state progression. See Synth Unit Roster GDD (#13) for AI and spawn behavior." + added: 2026-05-15 + revised: "" + + - name: stalker + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/synth-unit-roster.md + - design/gdd/reclaimer-combat.md + health: 250 + faction: synth + armor_states: none + death_threshold: 0 + notes: "Tanky single-target. 250 HP — requires sustained squad focus fire. No armor state. Follows heat signatures through walls. See Synth Unit Roster GDD (#13)." + added: 2026-05-15 + revised: "" + + - name: pulse_drone + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/synth-unit-roster.md + - design/gdd/reclaimer-combat.md + health: 75 + faction: synth + armor_states: none + death_threshold: 0 + notes: "Aerial unit. 75 HP — moderate durability. Disrupts electronics, reveals Reclaimer positions. No armor state. See Synth Unit Roster GDD (#13)." + added: 2026-05-15 + revised: "" # Example (remove when first real entry is added): # @@ -106,7 +150,116 @@ items: [] # output_range[min, max], added # Optional: expression (the actual formula), notes -formulas: [] +formulas: + - name: corruption_passive_tick + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + variables: + - PASSIVE_RATE + - STATE_MULTIPLIER + - TICK_RATE + output_range: [0.0, 100.0] + expression: "clamp(C_prev + (PASSIVE_RATE * STATE_MULTIPLIER / TICK_RATE), 0.0, 100.0)" + notes: "Applied each server tick. PASSIVE_RATE default 1.0%/min. STATE_MULTIPLIER is 1.0/1.25/1.5/1.75 for CALM/ALERT/HOSTILE/CRITICAL. TICK_RATE default 60 (ticks/min)." + added: 2026-05-15 + revised: "" + + - name: corruption_event_application + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + variables: + - C_prev + - EVENT_WEIGHT + output_range: [0.0, 100.0] + expression: "clamp(C_prev + EVENT_WEIGHT, 0.0, 100.0)" + notes: "Applied immediately on the server when a CorruptionInputEvent fires. EVENT_WEIGHT is positive (increase) or negative (decrease). See Input Event Table in GDD for all weights." + added: 2026-05-15 + revised: "" + + - name: corruption_sector_carry + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + variables: + - C_sector_end + - SECTOR_CARRY_FACTOR + output_range: [0.0, 50.0] + expression: "C_sector_end * SECTOR_CARRY_FACTOR" + notes: "Applied on sector transition. SECTOR_CARRY_FACTOR default 0.5. Output is the starting corruption value for the next sector. Threshold flags reset after carry is applied." + added: 2026-05-15 + revised: "" + + - name: movement_effective_speed + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + - design/gdd/reclaimer-combat.md # Combat reads V_effective for accuracy modifiers + - design/gdd/reclaimer-class-abilities.md # Class Abilities modifies MOVE_SPEED_MULT + variables: + - BASE_SPEED + - MOVE_SPEED_MULT + output_range: [0.0, 6.6] + expression: "V_effective = BASE_SPEED[stance] * MOVE_SPEED_MULT[class]" + notes: "Applied each frame via CharacterController.Move(). BASE_SPEED per stance: IDLE 0.0, WALK 3.5, SPRINT 6.0, SPRINT_EXHAUSTED 4.5, CROUCH 2.0 m/s. MOVE_SPEED_MULT per class: Breacher 0.90, Medic 1.00, Ghost 1.10, Engineer 0.95. Max output is Ghost SPRINT (6.6 m/s)." + added: 2026-05-15 + revised: "" + + - name: movement_noise_output + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + - design/gdd/reclaimer-class-abilities.md # Class Abilities modifies NOISE_MULT at runtime + variables: + - BASE_NOISE + - NOISE_MULT + output_range: [0.0, 1.0] + expression: "NOISE_OUT = clamp(BASE_NOISE[stance] * NOISE_MULT[class], 0.0, 1.0)" + notes: "Emitted as FootstepEvent(noiseLevel, position) every FOOTSTEP_INTERVAL meters. Sensor Grid GDD (#7) defines zone acoustic thresholds that compare against NOISE_OUT to determine corruption input. BASE_NOISE per stance: IDLE 0.05, WALK 0.40, SPRINT/SPRINT_EXHAUSTED 0.90, CROUCH 0.15, MANTLE 0.40. NOISE_MULT per class: Ghost 0.70, Medic 1.00, Breacher 1.20, Engineer 0.95." + added: 2026-05-15 + revised: "" + + - name: reclaimer_damage_application + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/reclaimer-combat.md # Combat supplies BASE_DAMAGE for Ballistic hits + - design/gdd/environmental-controls.md # Environmental Controls supplies BASE_DAMAGE for hazard ticks + - design/gdd/synth-unit-roster.md # Synth units supply BASE_DAMAGE for Synth hits + variables: + - HP_prev + - HP_MAX + - BASE_DAMAGE + - ARMOR_MULT + output_range: [0.0, 100.0] + expression: "HP_new = clamp(HP_prev - (BASE_DAMAGE * ARMOR_MULT[damageType][armorState]), 0.0, HP_MAX)" + notes: "ARMOR_MULT lookup: Ballistic[Operational]=0.80, Ballistic[Compromised]=1.00, Ballistic[Critical]=1.10. Environmental and Synth always 1.00 regardless of ArmorState. Applied server-side via IDamageable.TakeDamage()." + added: 2026-05-15 + revised: "" + + - name: fall_damage + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/level-sector-system.md # Level design must know safe fall distances for vertical level design + variables: + - fall_distance + - FALL_SAFE_DISTANCE + - FALL_DAMAGE_RATE + - FALL_DAMAGE_CAP + output_range: [0.0, 100.0] + expression: "FALL_DAMAGE = clamp(max(0, fall_distance - FALL_SAFE_DISTANCE) * FALL_DAMAGE_RATE, 0, FALL_DAMAGE_CAP)" + notes: "Applied as TakeDamage(FALL_DAMAGE, Environmental) on landing. FALL_SAFE_DISTANCE default 3.0m, FALL_DAMAGE_RATE default 10 HP/m, FALL_DAMAGE_CAP default 100 HP (= HP_MAX, instant Downed)." + added: 2026-05-15 + revised: "" # Example: # @@ -139,7 +292,192 @@ formulas: [] # # Required fields: name, status, source, referenced_by, value, unit, added -constants: [] +constants: + - name: PASSIVE_RATE + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + value: 1.0 + unit: "%/min" + notes: "Baseline corruption rise rate per minute. Safe range 0.5–2.0. Used in corruption_passive_tick formula." + added: 2026-05-15 + revised: "" + + - name: SECTOR_CARRY_FACTOR + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + value: 0.5 + unit: fraction + notes: "Fraction of end-of-sector corruption carried into the next sector. Safe range 0.0–0.8. 0.0 = full reset, 1.0 = full carry." + added: 2026-05-15 + revised: "" + + - name: OBJECTIVE_REDUCTION + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + value: 5.0 + unit: "%" + notes: "Corruption reduction applied on objective completion. Safe range 3.0–10.0. Negative EVENT_WEIGHT in corruption_event_application." + added: 2026-05-15 + revised: "" + + - name: GUNFIRE_WEIGHT + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + value: 0.15 + unit: "%" + notes: "Corruption added per single Reclaimer shot. Safe range 0.05–0.5. Auto burst uses this weight per 3-shot tick." + added: 2026-05-15 + revised: "" + + - name: TEAMMATE_DOWNED_WEIGHT + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + - design/gdd/health-damage.md # H&D fires CorruptionInputEvent(+5.0%) on Downed transition + value: 5.0 + unit: "%" + notes: "Corruption added when any Reclaimer enters downed state. Safe range 2.0–10.0. Highest single-event weight in the system." + added: 2026-05-15 + revised: "" + + - name: FOOTSTEP_INTERVAL_WALK + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + value: 0.8 + unit: m + notes: "Distance traveled between FootstepEvent firings while walking. Safe range 0.4–1.5 m. Sensor Grid GDD must know this to size acoustic zone coverage correctly." + added: 2026-05-15 + revised: "" + + - name: FOOTSTEP_INTERVAL_SPRINT + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + value: 0.6 + unit: m + notes: "Distance traveled between FootstepEvent firings while sprinting. Safe range 0.3–1.0 m. Higher event frequency than walk — more corruption exposure per meter." + added: 2026-05-15 + revised: "" + + - name: FOOTSTEP_INTERVAL_CROUCH + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + value: 1.2 + unit: m + notes: "Distance traveled between FootstepEvent firings while crouched. Safe range 0.6–2.0 m. Lower event frequency rewards stealth posture." + added: 2026-05-15 + revised: "" + + - name: SPRINT_DRAIN_RATE + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + value: 20.0 + unit: stamina/sec + notes: "Stamina drained per second while sprinting. Safe range 10–40. Produces 5-second sprint window at default. Class Abilities GDD may reference if any ability modifies drain rate." + added: 2026-05-15 + revised: "" + + - name: SPRINT_RECOVERY_THRESHOLD + status: active + source: design/gdd/reclaimer-movement.md + referenced_by: + - design/gdd/reclaimer-movement.md + value: 30.0 + unit: stamina + notes: "Minimum stamina required to re-enter SPRINT from SPRINT_EXHAUSTED. Safe range 10–50. Prevents sprint micro-recovery gaming. Class Abilities GDD may reference if any ability modifies this threshold." + added: 2026-05-15 + revised: "" + + - name: HP_MAX + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/reclaimer-combat.md # Combat uses HP_MAX for TTK calculations + - design/gdd/knockdown-revival.md # K&R uses HP_MAX for revival restore fraction + - design/gdd/reclaimer-hud.md # HUD displays HP as fraction of HP_MAX + value: 100.0 + unit: HP + notes: "Maximum Reclaimer HP. All classes share this value. Safe range 60–150. Changes cascade to COMPROMISED_THRESHOLD and CRITICAL_THRESHOLD calculations." + added: 2026-05-15 + revised: "" + + - name: COMPROMISED_THRESHOLD + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/reclaimer-hud.md # HUD changes color at this threshold + - design/gdd/reclaimer-class-abilities.md # Medic may check armor state for ability conditions + value: 60.0 + unit: HP + notes: "HP threshold below which ArmorState = Compromised. Must remain > CRITICAL_THRESHOLD and < HP_MAX. Safe range 40–80." + added: 2026-05-15 + revised: "" + + - name: CRITICAL_THRESHOLD + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/reclaimer-hud.md # HUD enters critical pulse at this threshold + - design/gdd/knockdown-revival.md # K&R may use critical state for triage priority + value: 30.0 + unit: HP + notes: "HP threshold below which ArmorState = Critical. Must remain < COMPROMISED_THRESHOLD. Safe range 10–50." + added: 2026-05-15 + revised: "" + + - name: TEAMMATE_ELIMINATED_WEIGHT + status: active + source: design/gdd/corruption-meter.md + referenced_by: + - design/gdd/corruption-meter.md + - design/gdd/health-damage.md # H&D fires this event on Elimination + value: 3.0 + unit: "%" + notes: "Corruption added when a Reclaimer is Eliminated (bleedout timer expires without revival). Safe range 1.0–8.0. Source GDD is corruption-meter.md (defined in event table); registered here when H&D first implemented the firing logic." + added: 2026-05-15 + revised: "" + + - name: FALL_SAFE_DISTANCE + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + - design/gdd/level-sector-system.md # Level design uses this to calibrate vertical traversal + value: 3.0 + unit: m + notes: "Minimum fall height (meters) before damage is applied. Falls below this deal no damage. Safe range 1.0–5.0 m." + added: 2026-05-15 + revised: "" + + - name: FALL_DAMAGE_RATE + status: active + source: design/gdd/health-damage.md + referenced_by: + - design/gdd/health-damage.md + value: 10.0 + unit: HP/m + notes: "HP damage per meter of fall above FALL_SAFE_DISTANCE. Safe range 5–30 HP/m. At default, 5m fall = 20 HP; 13m fall = 100 HP (instant Downed)." + added: 2026-05-15 + revised: "" # Example: # diff --git a/docs/engine-reference/unity/VERSION.md b/docs/engine-reference/unity/VERSION.md index 2ba702d25d..7346bf913c 100644 --- a/docs/engine-reference/unity/VERSION.md +++ b/docs/engine-reference/unity/VERSION.md @@ -5,7 +5,7 @@ | **Engine Version** | Unity 6.3 LTS | | **Release Date** | December 2025 | | **Project Pinned** | 2026-02-13 | -| **Last Docs Verified** | 2026-02-13 | +| **Last Docs Verified** | 2026-05-15 | | **LLM Knowledge Cutoff** | May 2025 | ## Knowledge Gap Warning diff --git a/docs/engine-reference/unity/breaking-changes.md b/docs/engine-reference/unity/breaking-changes.md index fb4b916b76..e5e1013203 100644 --- a/docs/engine-reference/unity/breaking-changes.md +++ b/docs/engine-reference/unity/breaking-changes.md @@ -1,6 +1,6 @@ # Unity 6.3 LTS — Breaking Changes -**Last verified:** 2026-02-13 +**Last verified:** 2026-05-15 This document tracks breaking API changes and behavioral differences between Unity 2022 LTS (likely in model training) and Unity 6.3 LTS (current version). Organized by risk level. @@ -66,6 +66,81 @@ public override void RecordRenderGraph(RenderGraph renderGraph, ContextContainer --- +### Object Finding APIs — RENAMED (Unity 6.0+) +**Impact**: Any code calling `FindObjectsOfType` or `FindObjectOfType` — HIGH for Hive Mind scene scanning + +```csharp +// ❌ OLD (deprecated) +Object.FindObjectsOfType(); +Object.FindObjectOfType(); + +// ✅ NEW +Object.FindObjectsByType(FindObjectsSortMode.None); // use None for performance +Object.FindFirstObjectByType(); // deterministic +Object.FindAnyObjectByType(); // faster, non-deterministic +``` + +--- + +### Netcode for GameObjects — 1.X Deprecated (Unity 6.3) +**Impact**: **CRITICAL for SYNTHFALL** — NGO 1.X is deprecated, upgrade to 2.X required. +Multiplay Hosting shuts down March 31, 2026. + +```csharp +// ❌ OLD (NGO 1.X) +public override void OnUpdate() { } // via NetworkTransform base + +// ✅ NEW (NGO 2.X) +public override void OnNetworkUpdate() { } +``` + +**Action**: Pin NGO 2.X from project start. Do not use NGO 1.X. + +--- + +### [SerializeField] Restricted to Fields Only (Unity 6.3) + +```csharp +// ❌ OLD (was silently ignored on properties — now compile error) +[SerializeField] public float Speed { get; set; } + +// ✅ NEW +[SerializeField] private float _speed; +public float Speed => _speed; +``` + +--- + +### Lighting — Enlighten Baked GI Discontinued (Unity 6.0+) + +- Projects auto-convert to Progressive Lightmapper on upgrade +- Auto-generated lighting removed — must call `Lightmapping.Bake()` or `Lightmapping.BakeAsync()` explicitly +- Light Probe brightness changed: now 100% (was 94%) + +--- + +### DirectX 12 Default Graphics API (Unity 6.1+) + +DirectX 12 replaces DirectX 11 as the default. Projects relying on DX11-specific +rendering behavior may see differences. Override via `PlayerSettings.SetGraphicsAPIs()` if needed. + +--- + +### USS Strict Parsing — UI Toolkit (Unity 6.3) + +Previously ignored invalid CSS syntax in `.uss` files now causes errors. +Audit all USS files before upgrading if using UI Toolkit. + +--- + +### Android — UnityPlayer Renamed (Unity 6.0+) + +`UnityPlayer` Java class renamed to `UnityPlayerForActivityOrService`. +No longer extends `FrameLayout`. Any native Android plugin referencing +`UnityPlayer` directly must update — not relevant for PC-only SYNTHFALL. + +--- + ## MEDIUM RISK — Behavioral Changes ### Addressables — Asset Loading Returns diff --git a/docs/engine-reference/unity/deprecated-apis.md b/docs/engine-reference/unity/deprecated-apis.md index a8216efd06..f442cfd4bc 100644 --- a/docs/engine-reference/unity/deprecated-apis.md +++ b/docs/engine-reference/unity/deprecated-apis.md @@ -1,6 +1,6 @@ # Unity 6.3 LTS — Deprecated APIs -**Last verified:** 2026-02-13 +**Last verified:** 2026-05-15 Quick lookup table for deprecated APIs and their replacements. Format: **Don't use X** → **Use Y instead**