hermeticormus/claude-code-game-development/godot-development

# Pattern A: Always duplicate
@onready var my_config: ConfigResource = config.duplicate()
 
# Pattern B: Make Unique in Inspector
# Right-click resource → Make Unique. Per-scene instance.
 
# Pattern C: Treat as immutable
# Document + discipline. Never write to config from runtime code.

emit_signal("event")
await get_tree().process_frame
# Now all listeners have processed

res://
├── scenes/        # PackedScene files (.tscn)
├── scripts/       # GDScript and C# files
├── resources/     # Custom Resources (configs, themes)
├── assets/        # Art, audio, fonts
│   ├── sprites/
│   ├── audio/
│   ├── fonts/
│   └── shaders/
├── autoloads/     # Singleton scripts (Project Settings → Autoload)
└── addons/        # Editor plugins

class_name PlayerCharacter extends CharacterBody3D
## Player character controller with movement and combat.
## Requires: CollisionShape3D child, AnimationTree child
 
signal died
signal health_changed(old_health: float, new_health: float)
 
const SPEED: float = 6.0
const JUMP_VELOCITY: float = 5.5
const GRAVITY: float = 9.8
 
@export var max_health: float = 100.0
@export var weapon_data: WeaponData  # Resource reference
 
@onready var animation_tree: AnimationTree = $AnimationTree
@onready var weapon_pivot: Node3D = $WeaponPivot
@onready var health_bar: ProgressBar = %HealthBar  # % = unique name shortcut
 
var _current_health: float
var _is_dead: bool = false
 
func _ready() -> void:
    _current_health = max_health
    animation_tree.active = true
 
func _physics_process(delta: float) -> void:
    if _is_dead:
        return
    _handle_gravity(delta)
    _handle_movement()
    move_and_slide()
 
func take_damage(amount: float) -> void:
    if _is_dead:
        return
    var old_health := _current_health
    _current_health = maxf(0.0, _current_health - amount)
    health_changed.emit(old_health, _current_health)
    if _current_health <= 0.0:
        _die()
 
func _die() -> void:
    _is_dead = true
    set_physics_process(false)  # Stop physics checks, cheaper than bool guard
    died.emit()
 
func _handle_gravity(delta: float) -> void:
    if not is_on_floor():
        velocity.y -= GRAVITY * delta
 
func _handle_movement() -> void:
    var input_dir := Input.get_vector(
        &"move_left", &"move_right", &"move_forward", &"move_back"
    )
    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)

# Base scene: Enemy.tscn with Enemy.gd
class_name Enemy extends CharacterBody3D
@export var move_speed: float = 3.0
@export var health: float = 50.0
 
func _ready() -> void:
    _setup()
 
func _setup() -> void:
    pass  # Override in subclasses
 
func attack(target: Node3D) -> void:
    pass  # Override in subclasses
 
# Inherited scene: GoblinEnemy.tscn extends Enemy.tscn
class_name GoblinEnemy extends Enemy
 
func _setup() -> void:
    move_speed = 4.0  # Goblins are faster
    health = 30.0
 
func attack(target: Node3D) -> void:
    # Goblin-specific attack logic
    pass

# res://autoloads/GameManager.gd
# Added in Project Settings > Autoloads as "GameManager"
class_name GameManager extends Node
# Correct uses for Autoloads:
# - Global event bus
# - Save system
# - Audio manager
# - Input rebinding
# WRONG uses: player state, enemy state, level data (use scene nodes instead)
 
signal scene_changed(scene_name: StringName)
 
var current_scene: StringName = &""
var _score: int = 0
 
func change_scene(scene_path: String) -> void:
    current_scene = scene_path.get_file().get_basename() as StringName
    get_tree().change_scene_to_file(scene_path)
    scene_changed.emit(current_scene)
 
func add_score(points: int) -> void:
    _score += points

# Object pool for frequently spawned scenes (bullets, particles, enemies)
class_name ScenePool extends Node
@export var scene: PackedScene
@export var initial_size: int = 20
 
var _pool: Array[Node] = []
 
func _ready() -> void:
    for i in initial_size:
        _create_instance()
 
func _create_instance() -> Node:
    var instance := scene.instantiate()
    add_child(instance)
    instance.hide()
    _pool.append(instance)
    return instance
 
func acquire() -> Node:
    for instance in _pool:
        if not instance.visible:
            instance.show()
            return instance
    # Pool exhausted: grow it
    var new_instance := _create_instance()
    new_instance.show()
    return new_instance
 
func release(instance: Node) -> void:
    instance.hide()
    # Reset state - position, velocity, etc.
    if instance.has_method(&"reset"):
        instance.reset()

# Loose coupling: HealthComponent emits, HUDComponent receives
# No direct reference between gameplay and UI
 
# In HealthComponent:
class_name HealthComponent extends Node
signal health_changed(ratio: float)  # 0.0 to 1.0
signal died
 
@export var max_health: float = 100.0
var _hp: float
 
func _ready() -> void:
    _hp = max_health
 
func damage(amount: float) -> void:
    _hp = maxf(0.0, _hp - amount)
    health_changed.emit(_hp / max_health)
    if _hp <= 0.0:
        died.emit()
 
# In scene setup (via editor or code):
# $HealthComponent.health_changed.connect($HUD/HealthBar.set_value)
# $HealthComponent.died.connect(_on_player_died)

# test/test_health_component.gd
extends GutTest
 
var _health: HealthComponent
var _signals_watched: bool = false
 
func before_each() -> void:
    _health = HealthComponent.new()
    _health.max_health = 100.0
    add_child_autofree(_health)
    watch_signals(_health)
 
func test_starts_at_full_health() -> void:
    assert_eq(_health._hp, 100.0, "Health should start at max")
 
func test_damage_reduces_health() -> void:
    _health.damage(30.0)
    assert_eq(_health._hp, 70.0, "Health should be 70 after 30 damage")
 
func test_damage_emits_health_changed() -> void:
    _health.damage(50.0)
    assert_signal_emitted(_health, "health_changed")
 
func test_lethal_damage_emits_died() -> void:
    _health.damage(200.0)
    assert_signal_emitted(_health, "died")
    assert_eq(_health._hp, 0.0, "Health should not go below 0")
 
func test_overkill_does_not_underflow() -> void:
    _health.damage(999.0)
    assert_gte(_health._hp, 0.0, "Health should never be negative")