Copilot Instructions for Godot 4 Project

Project Context

This is a Godot 4 game development project called "Metropolis". The project follows Godot's standard directory structure and conventions.

Development Approach

IMPORTANT: Always provide options and ask for confirmation before implementing solutions. When the user requests a feature or mentions a problem:

First analyze the situation and understand the requirements
Provide 2-3 different implementation options with pros/cons
Ask the user which approach they prefer
Only implement after getting explicit confirmation
Exception: Only implement directly when the user explicitly asks for a specific option (e.g., "implement option 2")

Node Reference Strategy

PREFERRED: Use

@export

variables for node references instead of complex code to find nodes:

Export all node references as variables at the top of the script
Ask the user to assign these in the Godot editor after writing the script
This approach is cleaner, more maintainable, and easier to debug
Avoid writing complex node-finding code like
```
get_child(0)
```
, recursive searches, etc.

Example:

# ✅ GOOD - Clean and simple
@export var interaction_area: Area3D
@export var mesh_node: Node3D

# ❌ AVOID - Complex node finding
@onready var interaction_area = find_child("InteractionArea") 
@onready var mesh_node = get_child(0).get_child(1)

Code Style and Conventions

GDScript Guidelines

Use snake_case for variables, functions, and file names
Use PascalCase for class names and signals
Use UPPER_CASE for constants and enums
Prefer explicit typing when possible (e.g.,
```
var health: int = 100
```
)
Use
```
@export
```
for properties that should be editable in the editor
Use
```
@onready
```
for node references that are initialized when the node enters the scene tree

File Organization

Scene files (.tscn) should be organized in the
```
scenes/
```
directory by category
Scripts should be co-located with their corresponding scene files
Shared resources should be placed in appropriate subdirectories
Levels should be placed in the
```
levels/
```
directory

Node Structure Conventions

Player-related scripts and scenes in
```
scenes/players/
```
Enemy-related content in
```
scenes/enemies/
```
UI elements in
```
scenes/ui/
```
Environment and level-specific content in
```
scenes/environment/
```

Godot 4 Specific Guidelines

Signal Usage

Use the new signal syntax:
```
signal health_changed(new_health: int)
```

Connect signals using the new callable syntax:

player.health_changed.connect(_on_player_health_changed)

Prefer signal connections in code over the editor when possible for better maintainability

Node References

PREFERRED APPROACH: Use

@export

variables for node references and assign them in the editor

# Export node references - assign these in the Godot editor
@export var build_area: Area3D
@export var interaction_area: Area3D  
@export var chest_mesh: Node3D

This approach is much cleaner than finding nodes programmatically

Always include safety checks when using exported node references:

if build_area:
    build_area.body_entered.connect(_on_build_area_entered)
else:
    print("Warning: build_area not assigned in editor")

Use
```
@onready var
```
only for child nodes that are guaranteed to exist in the scene tree
Avoid complex node finding code like
```
get_child(0)
```
,
```
find_child()
```
, or searching through node hierarchies
When writing a script that needs node references, ask the user to hook up the exported variables in the editor

Physics and Movement

Use CharacterBody3D/CharacterBody2D for player controllers
Implement
```
_physics_process()
```
for movement and physics
Use
```
move_and_slide()
```
for character movement
Set
```
velocity
```
property before calling
```
move_and_slide()
```

Resource Management

Use
```
preload()
```
for resources that are always needed
Use
```
load()
```
for resources that may be loaded conditionally
Consider using ResourcePreloader for multiple resources

Common Patterns

Player Controller Template

extends CharacterBody3D

@export var speed: float = 5.0
@export var jump_velocity: float = 4.5

var gravity = ProjectSettings.get_setting("physics/3d/default_gravity")

func _physics_process(delta):
    if not is_on_floor():
        velocity.y -= gravity * delta
    
    if Input.is_action_just_pressed("ui_accept") and is_on_floor():
        velocity.y = jump_velocity
    
    var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    var direction = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
    if direction:
        velocity.x = direction.x * speed
        velocity.z = direction.z * speed
    else:
        velocity.x = move_toward(velocity.x, 0, speed)
        velocity.z = move_toward(velocity.z, 0, speed)
    
    move_and_slide()

Signal Declaration and Connection

# Signal declaration
signal health_changed(new_health: int)
signal player_died

# Signal connection
func _ready():
    health_changed.connect(_on_health_changed)

func _on_health_changed(new_health: int):
    print("Health is now: ", new_health)

Input Handling

Use Input Map actions defined in Project Settings
Prefer
```
Input.is_action_pressed()
```
for continuous input
Use
```
Input.is_action_just_pressed()
```
for single-frame input
Use
```
Input.get_vector()
```
for 2D directional input

Performance Considerations

Use object pooling for frequently instantiated objects (bullets, particles, etc.)
Prefer
```
_ready()
```
over
```
_enter_tree()
```
unless early initialization is needed
Use
```
_physics_process()
```
for physics-related updates
Use
```
_process()
```
for visual updates and UI
Consider using
```
call_deferred()
```
for operations that should happen after physics

Common Godot 4 Nodes and Their Uses

CharacterBody3D/2D: For player controllers and moving characters
RigidBody3D/2D: For physics-based objects
StaticBody3D/2D: For static collision objects
Area3D/2D: For trigger zones and detection areas
AnimationPlayer: For complex animations and tweening
AudioStreamPlayer: For sound effects and music
Timer: For delayed actions and periodic events

Error Handling and Debugging

Use
```
assert()
```
statements for debugging and validation
Print debug information using
```
print()
```
,
```
print_rich()
```
, or
```
push_warning()
```
Use the debugger and breakpoints for complex issues
Check for null references before accessing node properties

When suggesting code, prioritize Godot 4 best practices and ensure compatibility with the engine's latest features and conventions.

Copilot Instructions for Godot 4 Project

Project Context

This is a Godot 4 game development project called "Metropolis". The project follows Godot's standard directory structure and conventions.

Development Approach

IMPORTANT: Always provide options and ask for confirmation before implementing solutions. When the user requests a feature or mentions a problem:

First analyze the situation and understand the requirements
Provide 2-3 different implementation options with pros/cons
Ask the user which approach they prefer
Only implement after getting explicit confirmation
Exception: Only implement directly when the user explicitly asks for a specific option (e.g., "implement option 2")

Node Reference Strategy

PREFERRED: Use

@export

variables for node references instead of complex code to find nodes:

Export all node references as variables at the top of the script
Ask the user to assign these in the Godot editor after writing the script
This approach is cleaner, more maintainable, and easier to debug
Avoid writing complex node-finding code like
```
get_child(0)
```
, recursive searches, etc.

Example:

# ✅ GOOD - Clean and simple
@export var interaction_area: Area3D
@export var mesh_node: Node3D

# ❌ AVOID - Complex node finding
@onready var interaction_area = find_child("InteractionArea") 
@onready var mesh_node = get_child(0).get_child(1)

Code Style and Conventions

GDScript Guidelines

Use snake_case for variables, functions, and file names
Use PascalCase for class names and signals
Use UPPER_CASE for constants and enums
Prefer explicit typing when possible (e.g.,
```
var health: int = 100
```
)
Use
```
@export
```
for properties that should be editable in the editor
Use
```
@onready
```
for node references that are initialized when the node enters the scene tree

File Organization

Scene files (.tscn) should be organized in the
```
scenes/
```
directory by category
Scripts should be co-located with their corresponding scene files
Shared resources should be placed in appropriate subdirectories
Levels should be placed in the
```
levels/
```
directory

Node Structure Conventions

Player-related scripts and scenes in
```
scenes/players/
```
Enemy-related content in
```
scenes/enemies/
```
UI elements in
```
scenes/ui/
```
Environment and level-specific content in
```
scenes/environment/
```

Godot 4 Specific Guidelines

Signal Usage

Use the new signal syntax:
```
signal health_changed(new_health: int)
```

Connect signals using the new callable syntax:

player.health_changed.connect(_on_player_health_changed)

Prefer signal connections in code over the editor when possible for better maintainability

Node References

PREFERRED APPROACH: Use

@export

variables for node references and assign them in the editor

# Export node references - assign these in the Godot editor
@export var build_area: Area3D
@export var interaction_area: Area3D  
@export var chest_mesh: Node3D

This approach is much cleaner than finding nodes programmatically

Always include safety checks when using exported node references:

if build_area:
    build_area.body_entered.connect(_on_build_area_entered)
else:
    print("Warning: build_area not assigned in editor")

Use
```
@onready var
```
only for child nodes that are guaranteed to exist in the scene tree
Avoid complex node finding code like
```
get_child(0)
```
,
```
find_child()
```
, or searching through node hierarchies
When writing a script that needs node references, ask the user to hook up the exported variables in the editor

Physics and Movement

Use CharacterBody3D/CharacterBody2D for player controllers
Implement
```
_physics_process()
```
for movement and physics
Use
```
move_and_slide()
```
for character movement
Set
```
velocity
```
property before calling
```
move_and_slide()
```

Resource Management

Use
```
preload()
```
for resources that are always needed
Use
```
load()
```
for resources that may be loaded conditionally
Consider using ResourcePreloader for multiple resources

Common Patterns

Player Controller Template

extends CharacterBody3D

@export var speed: float = 5.0
@export var jump_velocity: float = 4.5

var gravity = ProjectSettings.get_setting("physics/3d/default_gravity")

func _physics_process(delta):
    if not is_on_floor():
        velocity.y -= gravity * delta
    
    if Input.is_action_just_pressed("ui_accept") and is_on_floor():
        velocity.y = jump_velocity
    
    var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    var direction = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
    if direction:
        velocity.x = direction.x * speed
        velocity.z = direction.z * speed
    else:
        velocity.x = move_toward(velocity.x, 0, speed)
        velocity.z = move_toward(velocity.z, 0, speed)
    
    move_and_slide()

Signal Declaration and Connection

# Signal declaration
signal health_changed(new_health: int)
signal player_died

# Signal connection
func _ready():
    health_changed.connect(_on_health_changed)

func _on_health_changed(new_health: int):
    print("Health is now: ", new_health)

Input Handling

Use Input Map actions defined in Project Settings
Prefer
```
Input.is_action_pressed()
```
for continuous input
Use
```
Input.is_action_just_pressed()
```
for single-frame input
Use
```
Input.get_vector()
```
for 2D directional input

Performance Considerations

Use object pooling for frequently instantiated objects (bullets, particles, etc.)
Prefer
```
_ready()
```
over
```
_enter_tree()
```
unless early initialization is needed
Use
```
_physics_process()
```
for physics-related updates
Use
```
_process()
```
for visual updates and UI
Consider using
```
call_deferred()
```
for operations that should happen after physics

Common Godot 4 Nodes and Their Uses

CharacterBody3D/2D: For player controllers and moving characters
RigidBody3D/2D: For physics-based objects
StaticBody3D/2D: For static collision objects
Area3D/2D: For trigger zones and detection areas
AnimationPlayer: For complex animations and tweening
AudioStreamPlayer: For sound effects and music
Timer: For delayed actions and periodic events

Error Handling and Debugging

Use
```
assert()
```
statements for debugging and validation
Print debug information using
```
print()
```
,
```
print_rich()
```
, or
```
push_warning()
```
Use the debugger and breakpoints for complex issues
Check for null references before accessing node properties

When suggesting code, prioritize Godot 4 best practices and ensure compatibility with the engine's latest features and conventions.

Copilot Instructions for Godot 4 Project

Related Skills

Markdown Converter

Nano Banana Pro

1password