expand TODO.md to be a super detailed architecture and implementation log for Candy Survival

TODO.md

@@ -1,53 +1,122 @@
-# Candy Survival Implementation (Completed)
+# Candy Survival: Complete Implementation & Architecture Log
 
-This file contains the complete list of tasks, features, and refactors successfully implemented for the Candy Survival game mode, replacing the legacy Gauntlet mode.
+This document serves as an exhaustive, technical record of all modifications, refactors, and features implemented during the transition from the legacy "Gauntlet" mode to the new "Candy Survival" mode.
 
-## 1. Project-Wide Renaming & Asset Scrubbing
-- [x] **Codebase**: Replaced all `GAUNTLET`, `Gauntlet`, and `gauntlet_` references with `CANDY_SURVIVAL` across 21+ scripts, scenes, and UI nodes.
-- [x] **Assets & Models**: Renamed directories and files from `assets/models/arena/gauntlet/` to `candy_survival/`, including `.gltf`, `.bin`, and all texture `.png` files.
-- [x] **Meta Scrubbing**: Purged cached Godot importer metadata inside `.import` and `.gltf` files referencing the old paths.
-- [x] **Changelog**: Updated historical `version.json` references to use the new naming convention.
+---
 
-## 2. Arena & Environment
-- [x] **18x18 Grid**: Set boundaries to 18x18 with solid outer walls.
-- [x] **Collision System**: Sticky cells now act as pure collision boundaries (no slow-mo or growth algorithms).
-- [x] **Spawn Points**: Updated to `(2,2), (16,2), (2,16), (16,16)` to successfully avoid row 1 stairs geometry.
+## 1. Project-Wide Renaming & Metadata Scrubbing
+- **Global Find & Replace**: Executed across `scripts/`, `scenes/`, `tests/`, and `addons/`.
+  - Replaced `GAUNTLET`, `GauntletManager`, `gauntlet_manager`, and `is_gauntlet_mode()`.
+  - Replaced UI and enum display strings `"Gauntlet Arena"` → `"Candy Survival Arena"`.
+- **File System Refactoring**: 
+  - `git mv scripts/managers/gauntlet_manager.gd scripts/managers/candy_survival_manager.gd`
+  - `git mv scripts/controllers/candy_cannon_controller.gd scripts/controllers/candy_survival_npc_controller.gd`
+  - `git mv scenes/candy_cannon.tscn scenes/candy_survival_npc.tscn`
+  - `git mv scenes/gauntlet_hud.tscn scenes/candy_survival_hud.tscn`
+  - `git mv scenes/arena/gauntlet.tscn scenes/arena/candy_survival.tscn`
+- **Asset Scrubbing (`assets/models/arena/candy_survival/`)**: 
+  - Renamed the directory and all interior files (e.g., `Gauntlet terrain.gltf` → `candy_survival_terrain.gltf`).
+  - Purged buried metadata: Modified `.import` and `.gltf` text structures to remove cached `"res://assets/models/arena/gauntlet/..."` paths to prevent headless Godot build corruption.
+  - Updated legacy entries in `version.json` for historical consistency.
 
-## 3. Mekton NPC (Center Boss)
-- [x] **Spawning**: Replaced the primitive "Candy Pump" tank with a fully instanced `static_tekton_mesh` at `Vector2i(8,8)`.
-- [x] **Face Color Cycling**: The `ted_body` material cycles its emission and albedo color (Heart/Diamond/Star/Coin) every 5 seconds.
-- [x] **Integration**: Spawning and color state fully self-contained inside `candy_survival_manager.gd` without relying on `main.gd`.
+---
 
-## 4. Core Gameplay: Blueprints & Stacks
-- [x] **Auto-Pickup Tiles**: Modified `player_movement_manager.gd` so walking over a tile automatically picks it up if the playerboard has an open slot.
-- [x] **3x3 Auto-Detection**: Rewrote `_check_goal_completion` in `playerboard_manager.gd` to detect fully filled 3x3 grids of a single dominant color.
-- [x] **Off-Color Blueprints**: If the board's majority color is depleted from the arena grid, mixed-color blueprints are accepted for 50% points.
-- [x] **Stacking & Multipliers**: Successful blueprints award a candy on the player's head. Generates continuous points: `1.0 + (Stack * 0.1)`.
+## 2. Arena Layout & Sticky Collision Overhaul
+- **Grid Properties**: Enforced strict `18x18` playable bounds via `_setup_arena()`.
+- **Sticky Mechanics Rewritten**: 
+  - *Legacy*: Sticky cells grew dynamically, gave telegraph warnings, and trapped players requiring a "cleanser".
+  - *New*: `TILE_STICKY` now acts exclusively as static, pure-collision boundary walls. Placed solely on the arena perimeter and the center 3x3 NPC zone to block entry.
+  - Movement check in `player_movement_manager.gd` strictly evaluates `if gm.is_sticky_cell(grid_position)` and rejects the move outright unless the player possesses the `is_invisible` (Ghost) buff.
+- **Spawn Point Correction**: Shifted `get_spawn_points()` coordinates from `row 1` to `row 2` and `row 15` to `row 16` (`(2,2), (16,2), (2,16), (16,16)`) to prevent players from spawning inside stairs/geometry.
 
-## 5. Core Gameplay: Delivery & Sugar Rush
-- [x] **Auto-Delivery**: Proximity trigger (distance <= 2) to the center Mekton automatically attempts delivery.
-- [x] **Face Matching**: Delivery succeeds only if the player's candy stack matches the current glowing color of the Mekton's face.
-- [x] **Sugar Rush Activation**: Successful delivery clears the stack and triggers `Engine.time_scale = 2.0` (2x global speed) for `2s + (candies * 0.4s)`. 
+---
 
-## 6. Sabotage: Knock & Ghost
-- [x] **Knock Mechanic**: Starts with 5 charges. Bound to `action_knock_tekton`. Targets adjacent players to steal their full candy stack and color.
-- [x] **Knock Backfire**: Hitting an empty-handed player consumes a charge and backfires (both players get knocked).
-- [x] **Ghost Mechanic**: Starts with 5 charges. Bound to `action_grab_tekton`. 
-- [x] **Ghost Phase-Through**: Hijacks the core game's `is_invisible` state for 4s (40% opacity). Grants knock immunity and explicitly allows walking through sticky collision walls.
+## 3. Mekton NPC (Center Boss Entity)
+- **Mesh Replacement**: Scrapped the primitive Cylinder/Sphere tank meshes in `candy_survival_npc.tscn`. Instanced `static_tekton_mesh.tscn` as the visual representation.
+- **Face Color Cycling**:
+  - Engineered `set_face_color_rpc(color_index: int)` inside `candy_survival_npc_controller.gd`.
+  - Dynamically extracts the surface material from the `ted_body` skeleton node.
+  - Duplicates the material at runtime and applies emission glow and albedo tints corresponding to the `CandyColor` enum (0: Heart/Red, 1: Diamond/Blue, 2: Star/Yellow, 3: Coin/Orange).
+- **Manager Authority**: `candy_survival_manager.gd` tracks `face_timer`. Every 5.0 seconds (`COLOR_CYCLE_TIME`), it increments `current_face = CandyColor.values()[(current_face + 1) % CandyColor.size()]` and fires the RPC to visually sync the Mekton across all clients.
 
-## 7. Visuals & UI (HUD Rewrite)
-- [x] **HUD Scene Rebuild**: Removed script-based GUI generation. Rebuilt `candy_survival_hud.tscn` natively using Godot Control nodes for easy artist iteration.
-- [x] **UI Elements Added**: `SugarRushBar`, `CandyStackBadge`, `KnockChargesLabel`, `GhostChargesLabel`, and `PointsLabel`.
-- [x] **Delivery Indicator**: Added a visual `READY TO DELIVER!` indicator that dynamically listens to the Mekton's 5s color cycle and validates against the player's held stack.
-- [x] **3D Visual Candy Stacks**: Hooked `sync_candy_stack` to physically spawn `MeshInstance3D` tiles (Heart/Diamond/Star/Coin) stacked vertically (`y += 0.4`) on the player character's head.
+---
 
-## 8. AI / Bot Integration
-- [x] **Mekton Delivery AI**: Bots prioritize (Priority 0.7) checking if their candy color matches the Mekton's face, pathfinding directly to the center to deliver and score.
-- [x] **Ghost AI**: Bots evaluate proximity to sticky walls and actively trigger the native Candy Survival ghost charges to phase through traps.
-- [x] **Test Updates**: Re-wrote `test_bot_gauntlet.gd` to test the new mechanics (overlay checks, unsafe neighbor counts) and deleted 8+ obsolete Gauntlet mechanic test files.
+## 4. Gameplay Loop: Blueprints & Stacks
+- **Auto-Pickup Integration**: 
+  - Hooked into `player_movement_manager.gd` -> `_on_movement_finished()`. 
+  - If `LobbyManager.game_mode == "Candy Survival"`, automatically calls `player.grab_item(player.current_position)` when stepping on a tile, assuming the `playerboard_manager` has an empty slot. Completely removes the need for manual button presses during high-speed building.
+- **3x3 Blueprint Detection Engine**:
+  - Overhauled `_check_goal_completion()` in `playerboard_manager.gd`.
+  - Scans the 5x5 player board for *any* contiguous, fully-populated 3x3 block.
+  - Calculates the majority color (`primary_color`) within that block.
+- **Off-Color Validation**: 
+  - If the 3x3 block is mixed (off-color), it queries the global `gridmap` via `CandySurvivalManager._grid_has_color_tiles(primary_tile_id)`.
+  - If the primary color is mathematically extinct on the physical arena floor, the blueprint is accepted for 50% points. Otherwise, it is rejected.
+- **Stacking Mechanics & Multipliers**:
+  - `on_blueprint_completed` invokes `_give_candy(pid, color)`.
+  - Tracks `player_candies` (height) and `player_candy_color`. 
+  - Multiplier scales dynamically: `1.0 + (Stack Count * MULTI_STEP [0.1])`. Generates continuous passive points per second evaluated in `_process`.
 
-## 9. Code Health & Documentation
-- [x] **Compilation**: Fixed a dangling `_on_doors_update` call in `lobby_room.gd`. Verified 100% clean compilation (`godot --headless --build-solutions`).
-- [x] **Gitea Issues**: Bulk-closed and commented on issues #54-57 and #65-70 with detailed technical implementation logs.
-- [x] **Wiki**: Fully rewrote the `Game-Modes.-.md` wiki page to document the new rules, RPC lists, Sabotage input mappings, and arena coordinates.
-- [x] **Git Branching**: Deleted `gauntlet`, verified all features on the clean `candy_survival` tracking branch.
+---
+
+## 5. Gameplay Loop: Delivery & Sugar Rush
+- **Proximity Delivery Trigger**:
+  - Built into `player_movement_manager.gd`. During movement, it evaluates Manhattan distance to the center NPC (`abs(x - 8) + abs(y - 8)`).
+  - If distance is `<= 2`, the client fires `gm.try_deliver(pid)` via RPC to the server.
+- **Face Matching Logic**:
+  - Server evaluates `if player_candy_color == current_face`.
+  - Rejects if the player has 0 candies or colors mismatch.
+- **Sugar Rush Global Event**:
+  - Successful delivery adds to `player_sugar_rush[pid]` with the formula: `SR_BASE_TIME [2.0s] + (candies * SR_PER_CANDY [0.4s])`.
+  - While *any* player's rush timer is `> 0`, the manager forces `Engine.time_scale = SR_SPEED [2.0]`. When all timers reach 0, it restores to `1.0`.
+
+---
+
+## 6. Sabotage: Knock & Ghost Dynamics
+- **Knock (Steal/Backfire)**:
+  - Input bound natively to `action_knock_tekton` inside `player_input_manager.gd`.
+  - Fires `try_knock(attacker, target)` when adjacent to an opponent.
+  - Consumes 1 of 5 starting charges (`player_knocks`).
+  - *Steal*: If target has candies, attacker adopts target's full stack and color; target is zeroed.
+  - *Backfire*: If target has 0 candies, attacker loses a charge and both suffer the knock animation state (handled by caller).
+- **Ghost (Phase-Through)**:
+  - Input bound natively to `action_grab_tekton` inside `player_input_manager.gd` (bypasses default grab behavior in this mode).
+  - Consumes 1 of 5 starting charges (`player_ghosts`).
+  - `try_activate_ghost` sets the core `player.is_invisible = true` and `sync_modulate(Color(1, 1, 1, 0.4))` for 4.0 seconds.
+  - The `is_invisible` state natively bypasses the sticky collision checks, allowing phase-through of boundaries/boss zones, and renders the player immune to incoming Knocks.
+
+---
+
+## 7. Visuals, UI & 3D Stacking 
+- **HUD De-Scripting**:
+  - Legacy `gauntlet_manager` instantiated UI elements via GDScript. This was purged.
+  - Created `candy_survival_hud.tscn` using pure Godot Control nodes (VBoxContainer, HBoxContainer, ProgressBar, Label). Exposes all UI to artists for layout/theme modifications without code risk.
+  - Manager simply grabs node references (`hud_rush_bar`, `hud_stack_badge`, etc.) on `_ready()`.
+- **Dynamic Delivery Indicator**:
+  - `sync_candy_badge` RPC was expanded to include a `face_match` boolean.
+  - When the Mekton's face color changes (every 5s), the server force-updates all clients.
+  - The HUD dynamically shifts `DeliveryIndicator.text` to a Green `"READY TO DELIVER!"` or Red `"Waiting for match..."` based on their currently held candy stack.
+- **Physical 3D Candy Stacking**:
+  - Implemented `sync_candy_stack(count, color_id)` directly on `player.gd`.
+  - Creates a generic `Node3D` on the player's `Visuals` node.
+  - Instantiates raw `MeshInstance3D` tiles (`tile_heart.tres`, `tile_diamond.tres`, etc.).
+  - Visually stacks them vertically (`y = i * 0.4`) and scales them down (`0.5x`) corresponding exactly to the player's internal candy count. Clears them instantly upon delivery or being knocked.
+
+---
+
+## 8. AI & Bot Behaviors
+- **Delivery Pathfinding (Priority 0.7)**:
+  - Injected specialized logic into `bot_controller.gd`.
+  - Bots actively check their held `player_candy_color` against the manager's `current_face`.
+  - When colors match, the Bot halts blueprint construction and immediately uses `find_path` targeting `Vector2i(8,8)` to execute a delivery and trigger Sugar Rush.
+- **Ghost Survival Logic**:
+  - Re-wrote `_bot_has_ghost_powerup()` in `bot_strategic_planner.gd` to evaluate the new native `player_ghosts` charge counter instead of the legacy `SpecialTilesManager` inventory.
+  - Bots correctly evaluate proximity to sticky walls and automatically fire `try_activate_ghost` when cornered to phase out of traps.
+
+---
+
+## 9. Code Health & QA
+- **Orphan Code Purge**: Deleted 8 specific `test_gauntlet_*.gd` files that referenced non-existent legacy mechanics (growth algorithms, bubbles, floor highlights, old cleansers).
+- **Compile Integrity**: Fixed a trailing `_on_doors_update()` call in `lobby_room.gd` leftover from a different branch. Verified flawless compilation via `godot --headless --build-solutions`.
+- **Gitea Documentation**: Automated the closure and deep-technical documentation of Issues #54, 55, 56, 57, 65, 66, 67, 68, 69, and 70 directly to the tracking server.
+- **Wiki Accuracy**: Overhauled `Game-Modes.-.md` to perfectly mirror the new Sabotage input maps, Blueprint rules, RPC structures, and Mekton behavior.