tekton/docs/gauntlet-technical-implementation.md

Candy Cannon Survival (Gauntlet) — Technical Implementation Plan

1. Feasibility Summary

Verdict: Feasible. The existing codebase provides ~70% of the infrastructure needed. The game mode architecture is modular — each mode has its own manager (StopNGoManager, PortalModeManager) that handles arena setup, HUD, phase logic, and win conditions. A new GauntletManager follows this identical pattern.

Reuse Breakdown

GDD Feature	Existing System	Reuse Level	New Work
Game Mode registration	GameMode.gd enum + LobbyManager	Direct	Add enum entry + strings
20×20 Arena setup	StopNGoManager._setup_arena() pattern	Heavy	Custom layout, same GridMap API
Tile collection / scoring	GoalsCycleManager	Direct	Reuse goal completion + scoring
Mission system (goals)	GoalManager + goals_cycle_manager.gd	Direct	Same 3×3 pattern matching
Timed match (3 min)	GoalsCycleManager.start_match()	Direct	Pass 180s duration
Player movement	PlayerMovementManager	Direct	No changes
Powerup system	SpecialTilesManager	Partial	Cleanser is a new powerup type
Attack/Push mechanic	PlayerMovementManager.try_push()	Adapt	Smack = modified push with new rules
NPC (Candy Cannon)	tekton.gd + TektonController	Pattern	New NPC, reuses projectile/animation patterns
Sticky cells	StopNGoManager safe zone overlay (Layer 2)	Pattern	New tile type, same GridMap layer approach
Telegraph VFX	VFXManager / animation.gd	Pattern	New animations, same system
HUD	StopNGoManager._setup_hud() pattern	Direct	Mode-specific labels
Network sync	RPC patterns throughout codebase	Direct	Same rpc() / sync_* patterns
Lobby settings	LobbyManager signal/sync pattern	Direct	Add gauntlet-specific settings
Bot AI	BotController + BotStrategicPlanner	Adapt	New strategy for cannon avoidance

---

2. Architecture Overview

main.gd
├── _init_managers()          ← Add GauntletManager instantiation (same as StopNGoManager pattern)
├── _setup_host_game()        ← Add gauntlet arena setup branch
├── _start_game()             ← Add gauntlet start_game_mode() call
│
GauntletManager (NEW)
├── _setup_arena()            ← 20×20 grid, center 3×3 NPC zone
├── _setup_hud()              ← Mission label, cleanser indicator
├── start_game_mode()         ← Start cannon timer, spawn tiles
├── _process()                ← Cannon volley timer, phase escalation
├── CandyCannonController     ← Targeting logic, volley fire
├── StickyCell system          ← Layer 2 overlay, trap logic
├── Cleanser system            ← New powerup unlocked via missions
├── Smack system               ← Modified push with charge/cooldown
└── Win condition              ← Highest score at timer end

---

3. File-by-File Implementation

3.1 Game Mode Registration

scripts/game_mode.gd

enum Mode {
    FREEMODE = 0,
    STOP_N_GO = 1,
    TEKTON_DOORS = 2,
    GAUNTLET = 3          # NEW
}

# Add to from_string(), mode_to_string(), get_all_modes(), is_restricted()

scripts/managers/lobby_manager.gd

• Add "Candy Cannon Survival" to available_game_modes
• Add _update_available_areas() entry → "Gauntlet Arena"
• Add gauntlet-specific lobby settings (mirroring Stop N Go pattern):
  • gauntlet_round_duration: int = 180
  • gauntlet_cannon_interval: int = 5
  • gauntlet_volley_size: int = 5
  • Corresponding set_gauntlet_*(), sync_gauntlet_*() RPCs
  • Corresponding signals

---

3.2 Core Manager — gauntlet_manager.gd (NEW)

Location: scripts/managers/gauntlet_manager.gd

Pattern source: StopNGoManager + PortalModeManager

class_name GauntletManager
extends Node

# Signals
signal phase_changed(phase_index: int)
signal cannon_fired(targets: Array)
signal player_trapped(player_id: int)
signal cleanser_granted(player_id: int)

# Constants
const ARENA_SIZE = 20
const NPC_SIZE = 3
const NPC_CENTER = Vector2i(9, 9)  # Center of 20×20
const TILE_STICKY = 17             # New MeshLibrary item ID
const TILE_WALKABLE = 0
const TILE_OBSTACLE = 4

# Phase timing
enum Phase { OPEN_ARENA, ROUTE_PRESSURE, SURVIVAL_ENDGAME }
var current_phase: Phase = Phase.OPEN_ARENA
var elapsed_time: float = 0.0

# Cannon state
var cannon_timer: float = 0.0
var cannon_interval: float = 5.0
var volley_size: int = 5
var sticky_cells: Dictionary = {}  # Vector2i → true
var last_targeted_player_id: int = -1

# Smack state (per-player)
var smack_cooldowns: Dictionary = {}  # player_id → float (time remaining)
var smack_charged: Dictionary = {}    # player_id → float (charge window remaining)

# Cleanser tracking
var player_mission_completions: Dictionary = {}  # player_id → int
var player_cleansers: Dictionary = {}             # player_id → int (0 or 1)

# Trapped players
var trapped_players: Dictionary = {}  # player_id → true

Key methods (mapped to existing patterns):

Method	Pattern Source	Purpose
_setup_arena()	StopNGoManager._setup_arena()	20×20 grid, center 3×3 NPC block, walkable floor
_setup_hud()	StopNGoManager._setup_hud()	Mission label, cleanser indicator
start_game_mode()	StopNGoManager.start_game_mode()	Initialize cannon, spawn tiles, activate HUD
_process(delta)	StopNGoManager._process()	Tick cannon timer, fire volleys, update phase
_fire_volley()	NEW (uses tekton.gd projectile pattern)	Select targets, telegraph, apply sticky
_apply_sticky(pos)	StopNGoManager._spawn_dynamic_safe_zone() (Layer 2 overlay)	Set GridMap Layer 2 to TILE_STICKY
_check_player_trapped(player)	StopNGoManager._is_in_safe_zone() (inverted)	Check if player is on sticky cell
check_win_condition()	StopNGoManager.check_win_condition()	Highest score at match end
sync_phase() RPC	StopNGoManager.sync_phase()	Broadcast phase to clients
sync_sticky_cells() RPC	main.rpc("sync_grid_item")	Sync sticky cell state

---

3.3 Candy Cannon NPC — candy_cannon_controller.gd (NEW)

Location: scripts/controllers/candy_cannon_controller.gd

Pattern source: TektonController + tekton.gd projectile system

class_name CandyCannonController
extends Node

var gauntlet_manager: GauntletManager
var npc_center: Vector2i
var gridmap: Node

# Targeting weights per phase
var phase_weights: Array = [
    # Phase 0 (Open Arena): 1×1=60%, 1×2=40%, 2×2=0%
    {"1x1": 0.6, "1x2": 0.4, "2x2": 0.0},
    # Phase 1 (Route Pressure): 1×1=30%, 1×2=55%, 2×2=15%
    {"1x1": 0.3, "1x2": 0.55, "2x2": 0.15},
    # Phase 2 (Survival): 1×1=15%, 1×2=55%, 2×2=30%
    {"1x1": 0.15, "1x2": 0.55, "2x2": 0.30}
]

Targeting logic reuses the _is_position_valid() and get_neighbors() from EnhancedGridMap, and get_nodes_in_group("Players") for player-proximity targeting.

Projectile visuals reuse tekton.gd's spawn_projectile_rpc() pattern (arc tween from cannon → target cell).

---

3.4 Sticky Cell System

Approach: Use GridMap Layer 2 (same as StopNGoManager safe zone overlay and SpecialTilesManager freeze overlay).

New MeshLibrary item: TILE_STICKY = 17 — Pink/candy-colored semi-transparent panel (same approach as TILE_SAFE = 2).

Feature	Implementation
Visual	Layer 2 overlay with transparent candy-pink mesh
Movement block	PlayerMovementManager.simple_move_to() — add sticky check alongside wall check
Trap on step	GauntletManager._check_player_on_sticky() in _process()
Trap on push	PlayerMovementManager.try_push() — check landing cell for sticky
Cleanser pass-through	Similar to is_invisible wall bypass — temporary flag

Network sync: Use existing main.rpc("sync_grid_item", x, 2, z, TILE_STICKY) — identical to how safe zones and freeze overlays sync.

---

3.5 Telegraph System

Pattern source: StopNGoManager's sync_all_safe_zones_vfx() + _animate_safe_zone_appear()

1. Server selects target cells
2. rpc("sync_telegraph", targets) — all clients show pink glow
3. 1-second delay (Timer)
4. rpc("sync_impact", targets) — apply sticky, VFX, screen shake

Visual approach:

• Reuse Layer 2 overlay with a temporary "warning" tile ID (e.g., TILE_TELEGRAPH = 18)
• Animate alpha 0 → 1 over 0.8s (same _animate_safe_zone_appear() tween pattern)
• On impact: replace with TILE_STICKY, play screen_shake_manager via player.rpc("trigger_screen_shake", "medium")

---

3.6 Smack Mechanic

Pattern source: PowerUpManager.use_special_effect() + PlayerMovementManager.try_push()

The smack mechanic is a reskin of the existing Attack Mode push, with modifications:

Property	Current Attack Mode	Gauntlet Smack
Charge source	PowerUpManager.current_boost >= 100	8s cooldown timer (auto-refill)
Activation	Toggle is_attack_mode	3s charged window (pink model)
Push distance	3 cells backward (X=-1)	3 cells in push direction
Stagger	1.5s apply_stagger()	1.0s stun
Sticky landing	N/A	Trapped on first sticky cell in path
Clash	N/A	Both stunned, no push, bars consumed

Implementation in GauntletManager:

• New per-player smack state (cooldown, charged flag)
• Override or extend PlayerMovementManager.try_push() behavior when in gauntlet mode
• Sticky landing check: iterate push path, stop at first sticky cell → call trap_player()
• Clash detection: if two players activate smack within 0.5s of each other and are in range

---

3.7 Cleanser Power-Up

Pattern source: SpecialTilesManager.inventory system

Property	Implementation
Unlock trigger	GoalsCycleManager.goal_count_updated signal — grant when count % 2 == 0
Storage	GauntletManager.player_cleansers[peer_id] = 1
Activation	New input action or existing powerup key
Effect	For 5 cells of movement, ignore sticky checks + clear sticky overlay on traversed cells
Sync	rpc("sync_cleanser_state", peer_id, count)
Clear sticky	main.rpc("sync_grid_item", x, 2, z, -1) — same as safe zone clear

---

3.8 Candy Cannon NPC Scene — candy_cannon.tscn (NEW)

Pattern source: tekton.tscn + static_tekton_stand.tscn

• 3×3 footprint centered at (9, 9) in 20×20 grid
• Static body (non-movable, non-interactable)
• Animated mesh (cannon rotation, firing animation)
• No grab/throw/knock interactions (like is_static_turret = true)

---

3.9 Arena Scene — gauntlet.tscn (NEW) or gauntlet.scn

Location: scenes/arena/gauntlet.tscn

Pattern source: scenes/arena/freemode.tscn, scenes/arena/stop_n_go.scn

• 3D environment for the gauntlet arena
• Referenced in main.gd._apply_arena_background() under "Gauntlet Arena" match case

---

3.10 Integration Points in main.gd

Following the exact pattern of StopNGoManager / PortalModeManager:

# _init_managers() — Add after portal_mode_manager block:
if LobbyManager.game_mode == "Candy Cannon Survival":
    gauntlet_manager = load("res://scripts/managers/gauntlet_manager.gd").new()
    gauntlet_manager.name = "GauntletManager"
    add_child(gauntlet_manager)
    gauntlet_manager.initialize(self, $EnhancedGridMap)

# _setup_host_game() — Add arena setup branch:
elif LobbyManager.game_mode == "Candy Cannon Survival" and gauntlet_manager:
    gauntlet_manager._setup_arena()

# _start_game() — Add game mode start:
elif LobbyManager.game_mode == "Candy Cannon Survival":
    if gauntlet_manager:
        gauntlet_manager.start_game_mode()
    if goals_cycle_manager:
        var match_duration = LobbyManager.get_match_duration()
        goals_cycle_manager.start_match(float(match_duration))

---

4. New Files Summary

File	Type	Purpose
scripts/managers/gauntlet_manager.gd	Script	Core mode logic, phases, sticky cells, cleanser, smack
scripts/controllers/candy_cannon_controller.gd	Script	Cannon targeting, volley fire, telegraph
scenes/arena/gauntlet.tscn	Scene	3D arena environment
scenes/candy_cannon.tscn	Scene	Candy Cannon NPC (3×3, static)

5. Modified Files Summary

File	Changes
scripts/game_mode.gd	Add GAUNTLET = 3 enum, string mappings
scripts/managers/lobby_manager.gd	Add mode to available list, gauntlet settings, area mapping
scenes/main.gd	Add gauntlet_manager init, arena setup branch, start branch
scripts/managers/player_movement_manager.gd	Add sticky cell check in simple_move_to(), sticky landing in push
scripts/managers/goals_cycle_manager.gd	Cleanser grant on every 2nd goal completion (gauntlet mode only)
scripts/managers/special_tiles_manager.gd	Restrict certain powerups in gauntlet mode (like Stop N Go restrictions)
MeshLibrary .tres	Add TILE_STICKY (17) and TILE_TELEGRAPH (18) mesh items

6. Anti-Unfairness Implementation

# In CandyCannonController._select_targets():
func _select_targets(count: int) -> Array[Vector2i]:
    var targets: Array[Vector2i] = []
    var players = get_tree().get_nodes_in_group("Players")
    
    for i in range(count):
        var roll = randf()
        var target: Vector2i
        
        if roll < 0.60:
            # Near a player (not same as last targeted)
            target = _get_near_player_target(players)
        elif roll < 0.85:
            # Route-blocking (pathfinding bottleneck)
            target = _get_route_blocking_target()
        elif roll < 0.95:
            # Random non-sticky
            target = _get_random_non_sticky_target()
        else:
            # Chaos (anywhere)
            target = _get_random_target()
        
        targets.append(target)
    
    return targets

# Anti-unfairness rules:
# 1. last_targeted_player_id tracking prevents same-player targeting
# 2. 2×2 shots never placed directly ON a player (offset by 1)
# 3. Path validation: ensure at least one path from each active player
#    to a non-sticky region (using EnhancedGridMap.initialize_astar())
# 4. Exception: final 30s allows aggressive blocking

7. Network Considerations

All sync follows existing patterns:

Data	Sync Method	Existing Pattern
Sticky cells	main.rpc("sync_grid_item", x, 2, z, 17)	Safe zone / freeze overlay
Telegraph	rpc("sync_telegraph", targets_array)	StopNGoManager.sync_phase()
Phase changes	rpc("sync_gauntlet_phase", phase_idx, elapsed)	StopNGoManager.sync_phase()
Trap state	player.rpc("sync_trapped", true)	player.rpc("sync_stop_freeze", true)
Cleanser grant	rpc("sync_cleanser", peer_id, count)	goals_cycle_manager.sync_goal_count()
Smack state	player.rpc("sync_smack_state", charged)	player.rpc("sync_modulate", color)
Cannon NPC	Static scene, no movement sync needed	static_tekton_stand.tscn

8. Implementation Priority (Recommended Order)

1. Game Mode Registration — game_mode.gd, lobby_manager.gd, main.gd branches
2. Arena Setup — gauntlet_manager._setup_arena(), 20×20 grid, NPC zone block
3. Tile Spawning — Reuse StopNGoManager._spawn_mission_tiles() pattern
4. Cannon Timer + Volley — Basic 5s interval, 5 shots, 1×1 only (no sizes yet)
5. Sticky Cell System — Layer 2 overlay, movement blocking, trap detection
6. Telegraph VFX — Warning glow → impact
7. Impact Sizes — 1×2 and 2×2 shapes, phase-based weights
8. Smack Mechanic — Modified push with cooldown/charge
9. Cleanser — Unlock tracking, activated movement through sticky
10. Targeting Intelligence — Player proximity, route blocking, anti-unfairness
11. Bot AI — Cannon avoidance, sticky path planning
12. Polish — VFX, SFX, HUD animations, 3D arena scene

9. Risk Assessment

Risk	Mitigation
GridMap Layer 2 conflict with existing freeze/safe overlays	Gauntlet mode is exclusive — no freeze/safe tiles in this mode
20×20 grid performance (400 cells + overlays)	Existing 23×12 (Stop N Go) and 14×14 (Tekton Doors) work fine; 20×20 is comparable
Cannon targeting causing impossible arenas	Anti-unfairness pathfinding check via EnhancedGridMap.initialize_astar()
New MeshLibrary items (17, 18) colliding with existing IDs	Verify current max ID in .tres before adding
Smack clash detection timing	Use server-authoritative timestamp comparison (< 0.5s window)