danchie/tekton
3
1
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects 10 Releases 2 Wiki Activity

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

Browse Source
This commit is contained in:
god
2026-07-06 03:42:46 +08:00
parent 7699146811
commit 9747f91b20
1 changed files with 112 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TODO.md
+112 -43
View File
@@ -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 ## 1. Project-Wide Renaming & Metadata Scrubbing
- [x] **18x18 Grid**: Set boundaries to 18x18 with solid outer walls. - **Global Find & Replace**: Executed across `scripts/`, `scenes/`, `tests/`, and `addons/`.
- [x] **Collision System**: Sticky cells now act as pure collision boundaries (no slow-mo or growth algorithms). - Replaced `GAUNTLET`, `GauntletManager`, `gauntlet_manager`, and `is_gauntlet_mode()`.
- [x] **Spawn Points**: Updated to `(2,2), (16,2), (2,16), (16,16)` to successfully avoid row 1 stairs geometry. - 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 ## 2. Arena Layout & Sticky Collision Overhaul
- [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. - **Grid Properties**: Enforced strict `18x18` playable bounds via `_setup_arena()`.
- [x] **3x3 Auto-Detection**: Rewrote `_check_goal_completion` in `playerboard_manager.gd` to detect fully filled 3x3 grids of a single dominant color. - **Sticky Mechanics Rewritten**:
- [x] **Off-Color Blueprints**: If the board's majority color is depleted from the arena grid, mixed-color blueprints are accepted for 50% points. - *Legacy*: Sticky cells grew dynamically, gave telegraph warnings, and trapped players requiring a "cleanser".
- [x] **Stacking & Multipliers**: Successful blueprints award a candy on the player's head. Generates continuous points: `1.0 + (Stack * 0.1)`. - *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 ## 3. Mekton NPC (Center Boss Entity)
- [x] **Knock Mechanic**: Starts with 5 charges. Bound to `action_knock_tekton`. Targets adjacent players to steal their full candy stack and color. - **Mesh Replacement**: Scrapped the primitive Cylinder/Sphere tank meshes in `candy_survival_npc.tscn`. Instanced `static_tekton_mesh.tscn` as the visual representation.
- [x] **Knock Backfire**: Hitting an empty-handed player consumes a charge and backfires (both players get knocked). - **Face Color Cycling**:
- [x] **Ghost Mechanic**: Starts with 5 charges. Bound to `action_grab_tekton`. - Engineered `set_face_color_rpc(color_index: int)` inside `candy_survival_npc_controller.gd`.
- [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. - 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 ## 4. Gameplay Loop: Blueprints & Stacks
- [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. - **Auto-Pickup Integration**:
- [x] **Ghost AI**: Bots evaluate proximity to sticky walls and actively trigger the native Candy Survival ghost charges to phase through traps. - Hooked into `player_movement_manager.gd` -> `_on_movement_finished()`.
- [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. - 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. ## 5. Gameplay Loop: Delivery & Sugar Rush
- [x] **Wiki**: Fully rewrote the `Game-Modes.-.md` wiki page to document the new rules, RPC lists, Sabotage input mappings, and arena coordinates. - **Proximity Delivery Trigger**:
- [x] **Git Branching**: Deleted `gauntlet`, verified all features on the clean `candy_survival` tracking branch. - 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.