# IStalk — Systems Index

## Overview

| Metric | Value |
|--------|-------|
| **Total Systems** | 33 |
| **Categories** | 9 |
| **MVP Systems** | 16 |
| **Alpha Systems** | 6 |
| **Beta Systems** | 6 |
| **Launch Systems** | 5 |
| **Circular Dependencies** | None |
| **High-Risk Bottlenecks** | Relay Transport, FishNet Replication, Match State Machine, Geometric LoS, Weight System |

> **Architecture note (2026-06-23):** The relay server at `/Users/mahmoudaglan/istalk-relay-server/` serves two distinct roles. During the lobby phase it exchanges JSON signals (room create/join/role/start). During the game phase it is a **dumb binary packet forwarder** — the Eye/first-joiner player runs FishNet as a client-host, and all Synapse UDP traffic is tunnelled through the relay WebSocket. There is no dedicated game server. System #20 covers the relay connection and binary protocol; System #33 covers FishNet's patterns on top of it.

---

## Systems Enumeration

### Player Controllers

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 1 | Runner Movement Controller | MVP | Core | **Designed** → [sys-01-runner-movement.md](sys-01-runner-movement.md) |
| 2 | Eye Camera Controller | MVP | Core | **Designed** → [sys-02-eye-camera.md](sys-02-eye-camera.md) |
| 3 | Minion Controller | Beta | Feature | Not Started |

### Core Mechanics

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 4 | Weight/Burden System | MVP | Core | **Designed** → [sys-04-weight-burden.md](sys-04-weight-burden.md) |
| 5 | Geometric LoS (Line of Sight) | MVP | Core | **Designed** → [sys-05-geometric-los.md](sys-05-geometric-los.md) |
| 6 | Eye Laser System | MVP | Feature | **Designed** → [sys-06-eye-laser.md](sys-06-eye-laser.md) |
| 7 | Incarnation System | Alpha | Feature | Not Started |
| 8 | Trap/Dread Economy | Alpha | Feature | Not Started |
| 9 | Loot & Extraction Loop | MVP | Feature | **Designed** → [sys-09-loot-extraction.md](sys-09-loot-extraction.md) |

### Map & Environment

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 10 | Procedural Map Generator | MVP | Core | **Designed** → [sys-10-procedural-map-generator.md](sys-10-procedural-map-generator.md) |
| 11 | Prop System | MVP | Feature | **Designed** → [sys-11-prop-system.md](sys-11-prop-system.md) |
| 12 | Room Prefab Framework | MVP | Feature | **Designed** → [sys-12-room-prefab-framework.md](sys-12-room-prefab-framework.md) |
| 13 | Overtime Collapse | Alpha | Feature | Not Started |

### Economy & Items

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 14 | Item Database (ScriptableObject) | MVP | Foundation | **Designed** → [sys-01-item-database.md](sys-01-item-database.md) |
| 15 | Shrine/Shop System | Alpha | Feature | Not Started |
| 16 | Usable Items System | Alpha | Feature | Not Started |

### Social & Betrayal

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 17 | Betrayal Mechanics | Beta | Polish | Not Started |
| 18 | Minion System | Beta | Feature | Not Started |

### Audio

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 19 | Sound Radius System | Alpha | Core | Not Started |

### Networking

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 20 | Relay Transport Layer | MVP | Foundation | **Designed** → [sys-20-relay-transport.md](sys-20-relay-transport.md) |
| 33 | FishNet Replication Layer | MVP | Foundation | **Designed** → [sys-33-fishnet-replication.md](sys-33-fishnet-replication.md) |
| 21 | Lobby & Matchmaking | MVP | Core | **Designed** → [sys-21-lobby-matchmaking.md](sys-21-lobby-matchmaking.md) |

> **#20 Relay Transport Layer:** Owns the WebSocket connection to the relay server, the binary packet protocol (first-byte target routing), host election (`hostId` from `game_start`), heartbeat/ping-pong, and reconnection handling. This is the plumbing that all game traffic flows through.
>
> **#33 FishNet Replication Layer:** Owns NetworkBehaviour patterns, SyncVar/RPC conventions, client-side prediction strategy for Runner movement, authority model (host = Eye = FishNet server+client, all others = clients), and spawn/despawn contracts. Depends on #20 (the relay is the transport FishNet/Synapse uses).

### Match Management

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 22 | Match State Machine | MVP | Foundation | **Designed** → [sys-22-match-state-machine.md](sys-22-match-state-machine.md) |
| 23 | Scoring & Results | Beta | Polish | Not Started |

### Progression & Meta

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 24 | Persistent Progression | Launch | Meta | Not Started |
| 25 | Cosmetics System | Launch | Meta | Not Started |

### UI

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 26 | Runner HUD | MVP | Presentation | **Designed** → [sys-26-runner-hud.md](sys-26-runner-hud.md) |
| 27 | Eye HUD | MVP | Presentation | **Designed** → [sys-27-eye-hud.md](sys-27-eye-hud.md) |
| 28 | Minion HUD | Beta | Presentation | Not Started |
| 29 | Menu & Lobby UI | Launch | Presentation | Not Started |

### Polish & Onboarding

| # | System | Priority | Layer | Status |
|---|--------|----------|-------|--------|
| 30 | Tutorial System | Launch | Polish | Not Started |
| 31 | Replay System | Launch | Polish | Not Started |
| 32 | VFX & Juice | Beta | Presentation | Not Started |

---

## Dependency Map

### Layer 1: Foundation (Zero Dependencies)

```
[14] Item Database (SO)
[20] Relay Transport Layer          ← WebSocket+binary protocol, host election
[33] FishNet Replication Layer      ← NetworkBehaviour patterns, authority model (depends on [20])
[22] Match State Machine
```

> Note: #33 depends on #20 (relay is the transport), but both are Foundation because their
> design contracts must be locked before any gameplay NetworkBehaviour is written.

### Layer 2: Core (Depends on Foundation only)

```
[1]  Runner Movement Controller    → [33]         (FishNet NetworkBehaviour + prediction)
[2]  Eye Camera Controller         → [33]         (camera position sync)
[4]  Weight/Burden System          → [14, 33]     (item weights + sync)
[5]  Geometric LoS                 → [33]         (visibility state sync)
[10] Procedural Map Generator      → [14]         (room/prop data definitions)
[19] Sound Radius System           → [33]         (sound events networked)
[21] Lobby & Matchmaking           → [20, 22]     (relay JSON signaling + match phase)
```

### Layer 3: Feature (Depends on Core)

```
[6]  Eye Laser System              → [2, 5, 11]
[7]  Incarnation System            → [2, 5, 12]
[8]  Trap/Dread Economy            → [19, 22]
[9]  Loot & Extraction Loop        → [4, 14, 22]
[11] Prop System                   → [5, 10]
[12] Room Prefab Framework         → [10]
[15] Shrine/Shop System            → [9, 14]
[16] Usable Items System           → [4, 5, 7, 14]
[3]  Minion Controller             → [1, 33, 22]
[18] Minion System                 → [3, 8, 22]
[13] Overtime Collapse             → [10, 22]
```

### Layer 4: Presentation

```
[26] Runner HUD                    → [1, 4, 9, 16]
[27] Eye HUD                       → [6, 8, 18, 19]
[28] Minion HUD                    → [3, 18]
[29] Menu & Lobby UI               → [21, 24]
[32] VFX & Juice                   → [1, 6, 7, 11]
```

### Layer 5: Polish & Meta

```
[17] Betrayal Mechanics            → [9, 19, 5]
[23] Scoring & Results             → [9, 18, 22]
[24] Persistent Progression        → [23]
[25] Cosmetics System              → [33, 24]     (cosmetic sync via FishNet)
[30] Tutorial System               → [1, 2, 4, 6]
[31] Replay System                 → [33, 22]     (position logging via FishNet)
```

---

## Bottleneck Analysis

Systems with the most dependents (highest risk — poor design here cascades):

| System | Direct Dependents | Risk Level |
|--------|-------------------|-----------|
| FishNet Replication Layer (#33) | 10 | CRITICAL |
| Relay Transport Layer (#20) | 3 direct + all via #33 | CRITICAL |
| Match State Machine (#22) | 9 | HIGH |
| Item Database (#14) | 6 | HIGH |
| Geometric LoS (#5) | 6 | HIGH |
| Weight/Burden System (#4) | 5 | MEDIUM |
| Runner Movement Controller (#1) | 4 | MEDIUM |
| Procedural Map Generator (#10) | 4 | MEDIUM |

---

## Recommended Design Order

The order GDDs should be authored in (dependency-first within each priority tier):

### MVP Tier (Design First)

| Order | System | Layer | Rationale |
|-------|--------|-------|-----------|
| 1 | Item Database (SO) | Foundation | Pure data definitions — everything references these. Design the schema first so all systems agree on item/room/trap shape. |
| 2 | Relay Transport Layer | Foundation | The actual pipe all game traffic flows through. Documents the WebSocket protocol, binary packet format, host election via `hostId`, and reconnection rules — must be agreed before FishNet is wired up. |
| 3 | FishNet Replication Layer | Foundation | Authority model (host = Eye = FishNet server), SyncVar/RPC conventions, client-side prediction contract for Runner movement. Every NetworkBehaviour in the codebase follows these patterns — lock them first. |
| 4 | Match State Machine | Foundation | Phase flow (grace → hunt → extraction → overtime) defines WHEN every other system activates. Lock the timeline and transition triggers. |
| 5 | Runner Movement Controller | Core | The game IS the movement (Pillar 1). Physics model, input mapping, momentum rules, and FishNet prediction integration. |
| 6 | Weight/Burden System | Core | Core tension mechanic (Pillar 2). Tier thresholds, ability gating, drop/stash rules, and sync with movement controller. |
| 7 | Eye Camera Controller | Core | Pan bounds, zoom levels, scroll speed, input model. Shapes all LoS and laser geometry. |
| 8 | Geometric LoS | Core | Binary visibility state. Raycasting strategy, anatomical sockets, culling tiers, layer masks, performance budget. |
| 9 | Lobby & Matchmaking | Core | Relay JSON protocol (create/join/ready/start), room lifecycle, role assignment, `game_start` → FishNet host handoff, scene transition. |
| 10 | Procedural Map Generator | Core | Room stitching algorithm, connector matching, seed-based determinism, server generates + syncs layout to clients. No static maps — this IS the level. |
| 11 | Room Prefab Framework | Feature | Editor tools for room authoring: connector placement, spawn nodes, prop slots, boundary gizmos, validation. Tools-first approach. |
| 12 | Prop System | Feature | Static/dynamic/destructible prop categories, physics interaction rules, LoS blocking interface. |
| 13 | Eye Laser System | Feature | Charge/release timing, telegraph visuals, SphereCast parameters, prop destruction, Runner elimination. |
| 14 | Loot & Extraction Loop | Feature | Item spawning, pickup/drop, extraction threshold, altar channeling, win condition resolution. Completes the loop. |
| 15 | Runner HUD | Presentation | Weight meter, loot counter, ability availability, extraction progress. Minimal essential feedback. |
| 16 | Eye HUD | Presentation | Laser charge, detection indicators, Dread preview, altar alerts. Minimal Eye feedback. |

### Alpha Tier

| Order | System | Layer | Rationale |
|-------|--------|-------|-----------|
| 17 | Sound Radius System | Core | Noise propagation, Dread feed, Eye indicators, Runner spatial audio. New information channel. |
| 18 | Incarnation System | Feature | Prop possession, camera transition, micro-laser, visual tells. Eye strategic depth. |
| 19 | Trap/Dread Economy | Feature | Dread accumulation/spend, trap placement rules, area-denial effects. Eye economy. |
| 20 | Shrine/Shop System | Feature | Shrine placement, UI flow, loot-spending, item delivery. Runner economy. |
| 21 | Usable Items System | Feature | Per-item activation logic: Smoke Bomb, Mirror, Decoy, Ocular Paint, Grapple Hook. |
| 22 | Overtime Collapse | Feature | Room sealing logic, timing, visual/audio warning, forced confrontation. |

### Beta Tier

| Order | System | Layer | Rationale |
|-------|--------|-------|-----------|
| 22 | Minion Controller | Feature | Ghost movement, wall-pass physics, ability input, perspective setup. |
| 23 | Minion System | Feature | Death → role switch flow, ability definitions (Mark/Noise/Block/Haunt), Eye coordination. |
| 24 | Betrayal Mechanics | Polish | Noise Bait, Loot Theft, Sacrifice Ping rules and networking. Social tension layer. |
| 25 | Minion HUD | Presentation | Cooldowns, proximity sense, coordination UI. |
| 26 | Scoring & Results | Polish | Kill/extraction/betrayal tracking, currency conversion, results screen data. |
| 27 | VFX & Juice | Presentation | Particle specs, shader requirements, animation triggers per system. |

### Launch Tier

| Order | System | Layer | Rationale |
|-------|--------|-------|-----------|
| 28 | Persistent Progression | Meta | Currency banking, unlock trees, mastery tracks, stat persistence. |
| 29 | Cosmetics System | Meta | Skin loading, networked sync, unlock gating, equip flow. |
| 30 | Menu & Lobby UI | Presentation | Full menu flow, settings, matchmaking browser, cosmetic equip. |
| 31 | Tutorial System | Polish | Guided sequences, AI Eye, gate logic. Requires all MVP systems to teach. |
| 32 | Replay System | Polish | Position recording, playback, death-cam, ghost runs. |

---

## High-Risk Systems

These require extra design attention due to their dependency count or technical complexity:

| System | Risk Factor | Mitigation |
|--------|-------------|-----------|
| **Relay Transport Layer** | All game traffic flows through the relay WebSocket. Wrong protocol design = broken multiplayer end-to-end. The host election mechanism (`hostId`) determines who runs FishNet server. | Document the full binary packet format and JSON message protocol explicitly. Test relay connectivity independently before wiring FishNet on top. |
| **FishNet Replication Layer** | 10 systems depend on its NetworkBehaviour patterns. Wrong authority model = rewrite everything. The host = Eye client-hosted model has implications for authority on every synced system. | Lock the authority contract (what server owns, what clients predict) before writing any NetworkBehaviour. Pay special attention to what happens when the Eye-host disconnects mid-match. |
| **Match State Machine** | 9 systems gate their behavior on match phase. Unclear phase boundaries = integration hell. | Define every phase transition trigger explicitly. Make phases observable via events so systems can subscribe cleanly. |
| **Runner Movement Controller** | If movement doesn't feel great, no amount of content saves the game. This IS the game. | Prototype week 1-2. Iterate until buttery smooth. Decouple from weight system initially — add weight gating after movement feels perfect alone. |
| **Geometric LoS** | Performance-critical (runs every frame). Wrong approach = either false positives (unfair) or frame drops. | Budget: max N raycasts/frame. Pre-cull aggressively (frustum + sqrMagnitude). Profile early on target hardware. |
| **Procedural Map Generator** | Can produce unplayable layouts. Hard to debug. Combinatorial explosion of edge cases. No static maps — procgen IS the level. | Extensive validation passes + designer override tools. Seed-based for determinism (server picks seed, sends to clients). Start with simple linear stitching, add branching later. |

---

## Progress Tracker

| Phase | Designed | Total | Completion |
|-------|----------|-------|------------|
| MVP | 16 | 16 | 100% |
| Alpha | 0 | 6 | 0% |
| Beta | 0 | 6 | 0% |
| Launch | 0 | 5 | 0% |
| **Total** | **16** | **33** | **48%** |

---

*Created: 2026-06-23*
*Last updated: 2026-06-23*
*Status: Index complete — ready for individual system GDD authoring*
