# Game Mechanics Refactor Implementation Plan

This plan transforms the game from a lap-based racing system to a cycle-based goals system with power-ups, scoring, and a live leaderboard.

## User Review Required

> [!IMPORTANT]
> **Major Breaking Change**: This removes the entire lap/finish line mechanic. Players will no longer race to a finish line. The game becomes purely score-based with timed goal cycles.

> [!WARNING]
> **UI Changes**: The AllPlayerGoals panels will be modified to add timers. A new leaderboard panel will be added to the right side of main.tscn.

---

## Proposed Changes

### GoalsCycleManager (New Manager)

#### [NEW] [goals_cycle_manager.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scripts/managers/goals_cycle_manager.gd)

New autoload manager handling:
- 60-second countdown timer for goal cycles
- Broadcasting timer sync across multiplayer
- Goal regeneration on cycle end
- Score calculation (early completion = bonus points)
- Playerboard clear on timer end with match-to-score conversion

```gdscript
# Key properties:
var cycle_duration: float = 60.0
var current_cycle_timer: float = 0.0
var player_scores: Dictionary = {}  # peer_id -> score

# Key methods:
func start_cycle()
func _process_timer(delta)
func on_goal_completed(player, time_remaining: float)  # More time = more score
func on_cycle_end()  # Clear playerboards, convert matches to score
func regenerate_goals_for_player(player)
```

---

### PowerUpManager (New Manager)

#### [NEW] [powerup_manager.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scripts/managers/powerup_manager.gd)

New manager (attached to player) handling:
- Power-up points tracking (max 12 points = 4 bars)
- Holo tile pickup tracking (4 pickups = 1 bar = 4 points)
- Goal completion awards 1 bar (4 points)
- Using special effect consumes 1 bar (4 points)

```gdscript
const MAX_POINTS: int = 12
const POINTS_PER_BAR: int = 4
const MAX_BARS: int = 4

var current_points: int = 0
var holo_pickup_count: int = 0

func add_holo_pickup()            # Called when picking holo tile
func add_goal_completion_reward() # Called when goal completed
func can_use_special() -> bool    # True if >= 4 points
func use_special_effect()         # Consume 4 points, trigger random effect
```

---

### Player Modifications

#### [MODIFY] [player.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scenes/player.gd)

- Add `score: int` property
- Add `powerup_manager` reference
- Remove/deprecate references to `can_finish`, `finish_race`, lap tracking
- Add input handling for `use_powerup` action
- Add `on_goal_completed()` method that triggers tile randomization

---

### Special Tiles Manager Modifications

#### [MODIFY] [special_tiles_manager.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scripts/managers/special_tiles_manager.gd)

- Remove auto `trigger_random_effect()` call on holo tile pickup
- Instead, call `player.powerup_manager.add_holo_pickup()`
- Move `trigger_random_effect()` to be called by PowerUpManager

---

### Playerboard Manager Modifications

#### [MODIFY] [playerboard_manager.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scripts/managers/playerboard_manager.gd)

- In `grab_item()`: Change holo tile handling to add power-up points instead of triggering effect
- Add `check_goal_completion()` method that detects if current playerboard matches goals
- Add `clear_and_convert_to_score()` method for cycle end

---

### Race Manager Modifications (Heavy Refactor)

#### [MODIFY] [player_race_manager.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scripts/managers/player_race_manager.gd)

- Remove: `current_lap`, `lap1_finishers`, `lap2_finishers`, `finish_locations`, `spawn_locations`
- Remove: `finish_race()`, `start_new_lap()`, `get_current_finish_locations()`
- Keep: `goals`, `playerboard`, `check_pattern_match()` (renamed to `check_goal_completion()`)
- Add: `on_goal_completed()` → triggers 9-tile randomization around player

---

### Main Scene Modifications

#### [MODIFY] [main.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scenes/main.gd)

- Initialize `GoalsCycleManager` (as autoload or child)
- Add leaderboard UI update logic in `_process()`
- Add timer sync RPCs
- Remove lap/finish related code paths

#### [MODIFY] [main.tscn](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scenes/main.tscn)

- Add `TimerLabel` to each panel in `AllPlayerGoals` (shows countdown)
- Add `LeaderboardPanel` (VBoxContainer on right side with 4 player entries)
- Add `PowerUpBar` UI (battery-style visualization)

---

### Project Settings

#### [MODIFY] [project.godot](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/project.godot)

Add new input action:
```ini
use_powerup={
"deadzone": 0.5,
"events": [Object(InputEventKey,"physical_keycode":70,...)]  # F key
}
```

---

### UI Manager Modifications

#### [MODIFY] [ui_manager.gd](file:///c:/Users/ADT/Documents/GodotProjects/tekton-enet/scripts/managers/ui_manager.gd)

- Add `update_timer_display(player_idx, time_remaining)` method
- Add `update_leaderboard(scores_dict)` method
- Add `update_powerup_bar(current_points, max_points)` method

---

## Diagram: New Game Flow

```mermaid
flowchart TD
    A[Game Start] --> B[Cycle Begins - 60s Timer]
    B --> C{Player Actions}
    C --> D[Grab Tile]
    D --> E{Holo Tile?}
    E -->|Yes| F[Add to Holo Counter]
    F --> G{4 Holo Pickups?}
    G -->|Yes| H[+1 Bar Power-up]
    G -->|No| C
    H --> C
    E -->|No| I[Place in Playerboard]
    I --> J{Goal Complete?}
    J -->|Yes| K[+Score based on time left]
    K --> L[+1 Bar Power-up]
    L --> M[Randomize 9 tiles around player]
    M --> N[Regenerate Goals]
    N --> C
    J -->|No| C
    
    C --> O[Use Power-up Hotkey]
    O --> P{Has 1 Bar?}
    P -->|Yes| Q[Trigger Random Special Effect]
    P -->|No| C
    Q --> C
    
    B --> R{Timer = 0?}
    R -->|Yes| S[Clear Playerboard]
    S --> T[Convert Matching Tiles to Score]
    T --> U[New Cycle Begins]
    U --> B
```

---

## Verification Plan

### Manual Testing (User Required)

Since this is a Godot game with multiplayer networking, automated testing is limited. The following manual tests are required:

#### Test 1: Goal Cycle Timer
1. Launch the game from `res://scenes/lobby.tscn`
2. Create a lobby and start the game
3. **Verify**: A 60-second timer appears next to each player's goals panel
4. **Verify**: Timer counts down in real-time
5. **Verify**: When timer reaches 0, playerboard is cleared and new goals appear

#### Test 2: Goal Completion & Scoring
1. Play until you complete a goal pattern (match 3x3 in playerboard to goals)
2. **Verify**: Score increases (formula: base + time_remaining_bonus)
3. **Verify**: 1 bar of power-up is added
4. **Verify**: 9 tiles around your player position are randomized
5. **Verify**: New goals are generated immediately

#### Test 3: Power-up Points (Holo Tiles)
1. Pick up 4 holo tiles (indices 11-14)
2. **Verify**: No automatic special effect triggers
3. **Verify**: Power-up bar shows +1 bar (4 points accumulated)
4. **Verify**: Power-up bar UI shows battery-style visualization

#### Test 4: Using Special Effects
1. Accumulate at least 1 bar of power-up (4 points)
2. Press the `F` key (use_powerup action)
3. **Verify**: A random special effect triggers
4. **Verify**: Power-up bar decreases by 1 bar

#### Test 5: Live Leaderboard
1. Play with multiple players or bots
2. **Verify**: Leaderboard appears on right side of screen
3. Complete goals to gain score
4. **Verify**: Leaderboard reorders dynamically based on score
5. **Verify**: Position shows 1st, 2nd, 3rd, 4th correctly

#### Test 6: Multiplayer Sync
1. Host a game with 2+ players
2. **Verify**: Timer is synchronized across all clients
3. **Verify**: Score updates appear for all players on all clients
4. **Verify**: Leaderboard shows same order for all clients
5. **Verify**: Power-up usage effects are visible to all players