# Update 01: Code Architecture Plan

**All paths relative to:** `Assets/Scripts/`

---

## New Scripts to Create

### Eye System (6 new files)

| File | Class | Purpose |
|------|-------|---------|
| `Data/EyeType_SO.cs` | `EyeType_SO : ScriptableObject` | Defines eye type: name, icon, hasEyelids, ability flags, stat overrides |
| `Eye/EyeTypeController.cs` | `EyeTypeController : NetworkBehaviour` | Master controller — reads EyeType_SO at spawn, enables/disables ability scripts, applies stat overrides to DreadEconomy/Laser |
| `Eye/EyeEyelidController.cs` | `EyeEyelidController : NetworkBehaviour` | Eyelid input (right-click toggle), SyncVar<bool> closed state, black overlay rendering, flash dodge validation |
| `Eye/EyeFlashReceiver.cs` | `EyeFlashReceiver : NetworkBehaviour` | Receives flash events from server, checks eyelid state, applies/skips blind overlay + ability lockout |
| `Data/WearableData_SO.cs` | `WearableData_SO : ScriptableObject` | Defines wearable: abilityType enum, cooldown, icon, description, isPassive, throwRange |
| `Runner/WearableAbilityType.cs` | `enum WearableAbilityType` | Dash, WallRun, AirDash, Slide, Vault, Grapple |

### Runner Co-op System (4 new files)

| File | Class | Purpose |
|------|-------|---------|
| `Runner/RunnerWearableManager.cs` | `RunnerWearableManager : NetworkBehaviour` | Manages 2 wearable slots (SyncList), enables/disables abilities on equip/unequip, handles drops on down |
| `Runner/RunnerCoopActions.cs` | `RunnerCoopActions : NetworkBehaviour` | Ledge boost (ServerRpc), bag throw (ServerRpc), anti-AFK vote ritual |
| `Runner/RunnerBuffSystem.cs` | `RunnerBuffSystem : NetworkBehaviour` | Active buff tracking (SyncList), timed expiry, proximity checks for aura effects |
| `Runner/GrappleController.cs` | `GrappleController : NetworkBehaviour` | Grapple hook physics — aim, fire, swing, detach. Separate script due to complexity. |

### Extraction Rework (2 new files)

| File | Class | Purpose |
|------|-------|---------|
| `Core/ExtractionRoom.cs` | `ExtractionRoom : NetworkBehaviour` | Room trigger zone, tracks runners inside, manages 30s timer, incarnation prop density |
| `Core/AntiAfkRitual.cs` | `AntiAfkRitual : NetworkBehaviour` | Vote kick logic — tracks voters, timer, kills target, removes from alive count |

---

## Existing Scripts to Modify

### Heavy Modifications (significant logic changes)

| File | Changes |
|------|---------|
| `Runner/RunnerController.cs` | **Strip all advanced movement.** Remove: dash, wall-run, air-dash, slide, vault logic. Keep: run, sprint, jump, crouch, coyote time, jump buffer, gravity. Add: public methods `EnableAbility(WearableAbilityType)` / `DisableAbility(WearableAbilityType)` that re-enable the stripped code paths conditionally. Each movement ability becomes a guarded block: `if (_dashEnabled) { /* existing dash code */ }` |
| `Runner/PlayerInventory.cs` | **Add wearable slot system.** New `SyncList<string> _wearableIds` (max 2). New methods: `TryEquipWearable(string id)`, `TryUnequipWearable(string id)`, `DropAllWearables(Vector3 pos)`. Modify `DropAll()` to also call `DropAllWearables()`. Add `OnWearableChanged` event. |
| `Core/ExtractionManager.cs` | **Replace per-player extraction with room-based.** Remove `_extractedPlayerIds` SyncList and `TryExtract(NetworkObject)`. Add: `SyncVar<bool> _roomUnlocked`, `SyncVar<float> _extractionTimer`, method `UnlockRoom()` (called when threshold met), server Update that ticks timer when all alive in room. Fire `OnAllExtracted` event. |
| `Core/GameManager.cs` | **Update win condition.** Subscribe to `ExtractionManager.OnAllExtracted` instead of individual `OnPlayerExtracted`. Remove individual extraction counting. Add Eye type selection relay from lobby. Update GracePeriod: Eye places traps (unchanged). |
| `Runner/RunnerInteraction.cs` | **Add co-op interactions.** Add: boost detection (scan for crouching runners near walls), throw targeting (aim at teammate while holding G), extraction room entry logic. Remove: any betrayal-related checks if they exist. |
| `Core/Shrine.cs` | **Expand stock categories.** Add wearable items and co-op buffs to `PopulateStock()`. Split UI display into categories: Loot Items / Wearables / Co-op Buffs. Add purchase validation for wearable slot availability. |
| `Data/GlobalRules_SO.cs` | **Add all new tuning constants** from Part E of design doc (eye type multipliers, wearable cooldowns, co-op values, extraction room timers). |
| `Runner/ShrineItemEffect.cs` | **Add Flash Orb effect.** When activated, fires `[ServerRpc] ServerTriggerFlash()` which broadcasts to Eye's `EyeFlashReceiver`. Add team cooldown check. |
| `Eye/EyeLaserController.cs` | **Accept stat overrides.** Add `public void ApplyTypeModifiers(float cooldownMult, float radiusMult)` called by `EyeTypeController` at spawn. Use modified values instead of raw `GlobalRules_SO` values. |
| `Eye/EyeScanAbility.cs` | **Accept stat overrides + disable capability.** Add `public void ApplyTypeModifiers(float cooldownMult, float radiusMult)`. Add `enabled` toggle driven by `EyeTypeController`. |
| `Eye/EyeTrapPlacer.cs` | **Accept stat overrides.** Add `public void ApplyTypeModifiers(float costMult, int maxActiveBonus)`. |

### Light Modifications (small additions)

| File | Changes |
|------|---------|
| `Eye/DreadEconomy.cs` | Add `public void ApplyStartOverride(float amount)` and `public void ApplyRegenOverride(float rate)` for eye type stat customization. |
| `Eye/EyeIncarnationController.cs` | No changes needed — works as-is in extraction room (just needs dense props placed by MapGenerator). |
| `Runner/RunnerHealth.cs` | On `_isDown` change: call `RunnerWearableManager.DropAllWearables()`. Add reference to wearable manager. |
| `Core/MapGenerator.cs` | Add extraction room generation: a locked room with dense `IncarnationProp` spawns, unlocked via `ExtractionManager`. |
| `Core/LobbyManager.cs` | Add Eye type selection UI hook. Sync selected `EyeType_SO` ID to all clients before match start. Pass to `PlayerSpawner`. |
| `Core/PlayerSpawner.cs` | When spawning Eye: read selected type, pass to `EyeTypeController` initialization. |
| `Runner/RunnerAnimator.cs` | Add animation triggers for: boost (being boosted up), throw (lobbing item), receiving item. |
| `UI/RunnerHUD.cs` | Add: wearable slot display (2 slots with icons + cooldown overlays), active buff indicators, extraction room timer. |
| `UI/EyeHUD.cs` | Add: eyelid state indicator, flash incoming warning, eye type ability display. |
| `UI/ShrineUI.cs` | Add: tabbed categories (Loot / Wearables / Buffs), wearable slot preview. |
| `Data/ItemDatabase.cs` | Add: `GetWearable(string id)` method, `WearableData_SO[]` cache loaded from Resources. |
| `Shared/WeightComponent.cs` | No changes — wearables are weightless by design. |
| `Runner/RunnerVisibility.cs` | No changes needed. |

---

## Scripts to Remove / Deprecate

None. All existing code is preserved — advanced movement code in `RunnerController` is guarded behind flags, not deleted. This allows wearables to re-enable the exact same physics code.

---

## New Prefab Requirements

| Prefab | Path | Components |
|--------|------|------------|
| Eye_Watcher | `Assets/Resources/Prefabs/Eye_Watcher.prefab` | All existing Eye scripts + EyeTypeController + EyeEyelidController + EyeFlashReceiver. Scan enabled, Laser weak, Traps standard. |
| Eye_Predator | `Assets/Resources/Prefabs/Eye_Predator.prefab` | All Eye scripts + EyeTypeController + EyeFlashReceiver (NO EyeEyelidController). Laser strong, NO Scan. |
| Eye_Trapper | `Assets/Resources/Prefabs/Eye_Trapper.prefab` | All Eye scripts + EyeTypeController + EyeEyelidController + EyeFlashReceiver. Traps buffed, NO Laser. |
| WorldItem_Wearable | `Assets/Resources/Prefabs/WorldItem_Wearable.prefab` | WorldItem + mesh/icon display for wearable ground pickups |
| ExtractionRoom | `Assets/Resources/Prefabs/Rooms/ExtractionRoom.prefab` | Room with trigger zone, locked door, 8-12 IncarnationProp slots, visual "eye" theming |

**Alternative to 3 prefabs:** Single Eye prefab with `EyeTypeController` that enables/disables scripts at runtime based on the `EyeType_SO`. This is cleaner — one prefab, dynamic configuration.

**Recommended approach:** Single Eye prefab. `EyeTypeController.OnStartServer()` reads the assigned `EyeType_SO` and:
- Sets `EyeScanAbility.enabled = hasAbility("Scan")`
- Sets `EyeLaserController.enabled = hasAbility("Laser")`
- Sets `EyeEyelidController.enabled = hasEyelids`
- Calls `ApplyTypeModifiers()` on each enabled ability

---

## Implementation Order (Dependencies)

### Phase 1: Data Foundation (no gameplay changes yet)
1. `EyeType_SO.cs` — define the ScriptableObject
2. `WearableData_SO.cs` — define the ScriptableObject
3. `WearableAbilityType.cs` — enum
4. `GlobalRules_SO.cs` — add new fields
5. `ItemDatabase.cs` — add wearable lookup
6. Create .asset files for all 3 eye types and 6 wearables

### Phase 2: Runner Movement Refactor
7. `RunnerController.cs` — strip advanced movement behind flags
8. `RunnerWearableManager.cs` — create, manages equip/unequip
9. `PlayerInventory.cs` — add wearable SyncList
10. `RunnerHealth.cs` — drop wearables on down
11. Test: runner spawns with basic movement only, equipping a wearable enables dash

### Phase 3: Eye Types
12. `EyeTypeController.cs` — master controller
13. `EyeEyelidController.cs` — eyelid input + blackscreen
14. `EyeFlashReceiver.cs` — flash blind logic
15. `EyeLaserController.cs` — accept modifiers
16. `EyeScanAbility.cs` — accept modifiers + disable
17. `EyeTrapPlacer.cs` — accept modifiers
18. `DreadEconomy.cs` — accept overrides
19. `ShrineItemEffect.cs` — add Flash Orb
20. `LobbyManager.cs` — eye type selection
21. `PlayerSpawner.cs` — pass type to controller
22. Test: each eye type spawns with correct abilities, flash/eyelid works

### Phase 4: Co-op Mechanics
23. `RunnerCoopActions.cs` — boost + throw
24. `RunnerInteraction.cs` — integrate boost/throw detection
25. `RunnerBuffSystem.cs` — proximity buff auras
26. `GrappleController.cs` — grapple physics
27. `RunnerAnimator.cs` — new animation triggers
28. Test: two runners can boost, throw items, linked sprint works

### Phase 5: Extraction Rework
29. `ExtractionRoom.cs` — room logic + timer
30. `ExtractionManager.cs` — rewrite to room-based
31. `AntiAfkRitual.cs` — vote kick
32. `GameManager.cs` — new win condition
33. `MapGenerator.cs` — extraction room generation
34. Test: team deposits loot, room unlocks, all gather, 30s countdown, extract

### Phase 6: UI + Polish
35. `RunnerHUD.cs` — wearable slots + buff indicators
36. `EyeHUD.cs` — eyelid indicator + type display
37. `ShrineUI.cs` — categories
38. `UI/EyeTypeSelectionUI.cs` (new) — lobby eye type picker

---

## Network Considerations

| Concern | Solution |
|---------|----------|
| Eye type must be known before spawn | Sync eye type ID in lobby phase via `LobbyManager` relay message. `PlayerSpawner` reads it. |
| Wearable equip/unequip must be server-authoritative | All equip/unequip via `[ServerRpc]`. Client sends request, server validates slot availability. |
| Flash must be validated server-side | `ShrineItemEffect` fires `ServerRpc` → server checks team cooldown → server fires flash to Eye's `EyeFlashReceiver` |
| Eyelid state must be checked server-side | `EyeFlashReceiver` checks `EyeEyelidController._eyelidsClosed` SyncVar on server when flash arrives |
| Extraction room presence must be server-authoritative | `ExtractionRoom` uses server-side trigger colliders (`OnTriggerEnter/Exit` with `[Server]` guard) |
| Boost/throw must prevent exploits | Server validates distance, state (crouching/alive), and cooldowns before executing |
| Anti-AFK must prevent abuse | Server requires majority vote (2+ of remaining alive runners), 20s uninterruptible channel |

---

## Editor Tooling Additions

| Tool | Purpose |
|------|---------|
| `Editor/EyeTypeEditor.cs` | Custom inspector for `EyeType_SO` — preview which abilities are enabled, stat modifiers visualized |
| `Editor/WearableDataEditor.cs` | Custom inspector for `WearableData_SO` — shows ability type, cooldown, weight (always 0), placement preview |
| `Editor/ExtractionRoomValidator.cs` | Validates extraction room prefab has enough IncarnationProp slots, trigger zone, locked door reference |
| `Editor/AnimatorSetupWizard.cs` | Guides setup of Runner Animator Controller — adds required states, transitions, parameters for new animations (boost, throw, receive, grapple) |

---

## Migration Notes

- No data loss — existing loot items, trap data, shrine items all remain valid
- `RunnerController` keeps ALL movement code — just wrapped in ability flags
- Existing `ExtractionManager` altar deposit flow is preserved (deposit loot → meet threshold)
- The change is what happens AFTER threshold: room unlocks instead of individual extraction
- Shrines expand their stock (additive, not destructive)
- Eye prefab gains scripts (additive)
