Turtle Run Main Script

Overview

The Turtle Run main script (Main.gd) manages the core gameplay loop for the endless runner minigame where players control a turtle avoiding obstacles and collecting bonuses. It handles spawning, scrolling, scoring, difficulty progression, and pause/resume functionality. Script Path: minigames/turtle_run/scripts/Main.gd Extends: Node2D

Signals

Emitted when the player wants to return to the main menu.

Exported Variables

scroll_speed

float

default:"200.0"

Base scrolling speed of the parallax background in pixels per second.

floating_text_scene

PackedScene

Scene resource for floating text effects shown when collecting bonuses.

obstacle_scene

PackedScene

Scene resource for obstacles that the player must avoid.

bonus_scene

PackedScene

Scene resource for bonus items that award points.

lanes

Array[float]

default:"[100.0, 160.0, 220.0]"

Y-coordinates for the three vertical lanes where obstacles and bonuses spawn.

Node References

UI Nodes

@onready var parallax := $ParallaxBackground
@onready var spawn_timer := $SpawnTimer
@onready var score_label := $UI/Label
@onready var panel: Control = $UI/GameOverPanel
@onready var backButton: Button = $UI/backButton
@onready var intro_panel := $intro_panel

Container Nodes

@onready var obstacle_container := $ObstacleContainer
@onready var bonus_container := $BonusContainer

Audio Nodes

@onready var sfx_bonus := $AudioBonus
@onready var sfx_hit := $AudioHit

State Variables

score

float

default:"0.0"

Current player score. Increases continuously based on time survived and speed multiplier.

speed_multiplier

float

default:"1.0"

Difficulty multiplier that increases every 6 seconds, affecting scroll speed and score rate.

is_paused

bool

default:"false"

Whether the game is currently paused.

is_intro

bool

default:"true"

Whether the intro panel is currently displayed (game not started).

last_coins_gained

int

default:"0"

Tracks coins earned in the last game session for display on game over screen.

Core Functions

Initialization

_ready

void

Initializes UI, connects signals, sets up intro panel, and configures process modes for pause functionality.Key Actions:

Sets up game over panel and button connections
Adds node to “turtle_game” group
Configures spawn timer (starts stopped until intro completes)
Disables turtle processing until game starts

Game Loop

_process

void

Main game loop that runs every frame.Parameters:

delta (float): Time elapsed since last frame in seconds

Functionality:

Updates parallax scrolling based on speed multiplier
Increases score continuously (delta * 10 * speed_multiplier)
Updates speed multiplier every 6 seconds (multiplies by 1.1)
Updates turtle animation speed to match game speed
Skips processing if paused or in intro state

Spawning System

_on_SpawnTimer_timeout

void

Called when spawn timer expires. Spawns either an obstacle (90% chance) or bonus (10% chance) in a random lane.Logic:

Randomizes next spawn interval between 0.5-1.5 seconds
Avoids spawning in the same lane twice in a row
Uses randf() < 0.9 to determine obstacle vs bonus

spawn_obstacle

void

Instantiates an obstacle at the specified Y position on the right edge of the screen.Parameters:

y_pos (float): Y-coordinate for the obstacle (typically from lanes array)

Position: Vector2(viewport_width + 50, y_pos)

spawn_bonus

void

Instantiates a bonus item at the specified Y position on the right edge of the screen.Parameters:

y_pos (float): Y-coordinate for the bonus (typically from lanes array)

Position: Vector2(viewport_width + 50, y_pos)

Scoring

add_score_bonus

void

Adds bonus points to the current score.Parameters:

amount (int): Points to add

Game Over

game_over

void

Handles game over state when turtle hits an obstacle.Flow:

Stops spawn timer and scrolling
Disables processing for all obstacles, bonuses, and turtle
Plays hit sound effect
Waits 0.8 seconds
Saves high score to ScoreManager (“turtle_runner” key)
Calculates and awards coins (score * 0.1)
Shows game over panel

_show_game_over

void

Displays the game over panel with final score and coins earned.

Pause System

pause_game

void

Pauses the game.Actions:

Sets is_paused = true
Pauses spawn timer
Stores current parallax offset
Disables turtle processing and animation
Pauses all obstacles and bonuses
Pauses audio streams
Shows pause panel

resume_game

void

Resumes the game from paused state.Actions:

Sets is_paused = false
Resumes spawn timer
Re-enables turtle processing and animation
Resumes all obstacles and bonuses
Resumes audio streams
Hides pause panel

pause_all_obstacles

void

Helper function to pause/resume all obstacles.Parameters:

pause (bool): True to pause, false to resume

Effect: Sets process_mode and animation speed_scale for all children in obstacle_container

pause_all_bonus

void

Helper function to pause/resume all bonus items.Parameters:

pause (bool): True to pause, false to resume

Effect: Sets process_mode and animation speed_scale for all children in bonus_container

Audio & Visual Effects

show_floating_text

void

Displays floating text effect at a position.Parameters:

pos (Vector2): World position for the text
text (String): Text to display (default: “+50”)
color (Color): Text color (default: yellow)

play_bonus_sound

void

Plays the bonus collection sound effect.

play_hit_sound

void

Plays the hit/collision sound effect.

_on_back_pressed

void

Handles back button press. Resets screen orientation to portrait and returns to main menu.

_on_retry_pressed

void

Reloads the current scene to restart the game.

_on_backButton_pressed

void

Toggles pause state when the in-game back button is pressed.

ScoreManager Integration

The script integrates with the global ScoreManager singleton:

var score_manager = get_node("/root/ScoreManager")
if score_manager:
    score_manager.save_high_score("turtle_runner", final_score)
    score_manager.add_coins(coins_earned)

Game Key: "turtle_runner" Coin Conversion: Final score × 0.1

Common Patterns

Difficulty Progression

The game increases difficulty by incrementing speed_multiplier by 10% every 6 seconds:

elapsed_time += delta
if elapsed_time >= speed_increase_interval:
    elapsed_time = 0
    speed_multiplier *= 1.1

Process Mode Management

UI elements that need to remain interactive during pause use PROCESS_MODE_ALWAYS:

panel.process_mode = Node.PROCESS_MODE_ALWAYS
back_btn.process_mode = Node.PROCESS_MODE_ALWAYS
backButton.process_mode = Node.PROCESS_MODE_ALWAYS

Usage Example

Typical scene structure:

Main (Node2D) - This script
├── ParallaxBackground
├── Turtle
├── ObstacleContainer (Node2D)
├── BonusContainer (Node2D)
├── SpawnTimer (Timer)
├── UI (CanvasLayer)
│   ├── Label (score display)
│   ├── GameOverPanel
│   └── backButton
└── intro_panel

The script checks is_paused or is_intro at the start of most functions to prevent actions during paused or intro states.

Core Scripts

Minigame Scripts

Turtle Run Main Script

Overview

Signals

Exported Variables

Node References

UI Nodes

Container Nodes

Audio Nodes

State Variables

Core Functions

Initialization

Game Loop

Spawning System

Scoring

Game Over

Pause System

Audio & Visual Effects

Navigation

ScoreManager Integration

Common Patterns

Difficulty Progression

Process Mode Management

Usage Example

Build docs developers (and LLMs) love

Core Scripts

Minigame Scripts

​Overview

​Signals

​Exported Variables

​Node References

​UI Nodes

​Container Nodes

​Audio Nodes

​State Variables

​Core Functions

​Initialization

​Game Loop

​Spawning System

​Scoring

​Game Over

​Pause System

​Audio & Visual Effects

​Navigation

​ScoreManager Integration

​Common Patterns

​Difficulty Progression

​Process Mode Management

​Usage Example

Build docs developers (and LLMs) love

Overview

Signals

Exported Variables

Node References

UI Nodes

Container Nodes

Audio Nodes

State Variables

Core Functions

Initialization

Game Loop

Spawning System

Scoring

Game Over

Pause System

Audio & Visual Effects

Navigation

ScoreManager Integration

Common Patterns

Difficulty Progression

Process Mode Management

Usage Example