tekton/_daily_basis/implementation_plan_2025-12-12.md

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

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

# 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

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)

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

• 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

• 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

• 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

• 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

• 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

• 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

Add new input action:

use_powerup={
"deadzone": 0.5,
"events": [Object(InputEventKey,"physical_keycode":70,...)]  # F key
}

---

UI Manager Modifications

[MODIFY] 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

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