Godot Project Documentation

Project Overview

Core principles and philosophy driving this project

🎯 Project Mission

Building a robust, maintainable 3D action-adventure game in Godot 4.5 following industry best practices. This project emphasizes clean architecture, composition over inheritance, and systems that are easy to understand and extend.

Core Design Principles

1 Composition over Inheritance

Objects reference other objects instead of extending them. Components are attached, not inherited.

2 SOLID Principles

Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.

3 DRY - Don't Repeat Yourself

Code reusability through composition and shared systems. One source of truth for each concern.

4 KISS - Keep It Simple

If it can't be explained easily, it's bad code. Simplicity enables maintenance and collaboration.

Key Architectural Takeaways

Objects bundle data and behavior - CameraController owns its state and methods
Inheritance extends functionality - Build on existing classes when it makes sense
Encapsulation protects state - Private vs public access controls data flow
Methods have single responsibilities - Each method does one thing well
Objects communicate through interfaces - Public methods define contracts
Composition over tight coupling - Objects reference, not own each other
Events enable loose coupling - Signals let objects collaborate without dependencies
Defensive programming prevents crashes - Always validate before using

⚠️ Project Rules

Do not release buggy code
Do not assume something will work - test it
Double-check work against existing scripts
Question potentially bad ideas by analyzing project patterns
Always ask before creating debug scripts

System Architecture

How components compose to create the game

Main Scene Hierarchy

Main

Root Scene

↓

CharacterManager

Manages Characters

CameraController

Camera System

FollowController

AI Followers

↓

BaseCharacter

Character Root

↓

MovementHandler

InputHandler

HealthInterface

Composition in Action

BaseCharacter Composition COMPOSITION

BaseCharacter doesn't do movement itself - it composes MovementHandler, InputHandler, and HealthInterface as child nodes. Each component handles one responsibility.

extends CharacterBody3D
class_name BaseCharacter

# Child node references (Composition)
@onready var movement_handler: MovementHandler = $MovementHandler
@onready var input_handler: InputHandler = $InputHandler
@onready var health_interface: HealthInterface = $HealthInterface

# Connect components together
func setup_child_node_connections():
    input_handler.movement_input_changed.connect(
        movement_handler.set_movement_input)
    input_handler.jump_requested.connect(
        movement_handler.handle_jump)

Why Composition? ▼

Benefits of Composition over Inheritance

Flexibility - Swap components without changing base class
Testability - Test components in isolation
Reusability - Use MovementHandler in different character types
Single Responsibility - Each component has one job
Godot Philosophy - Node composition is the Godot way

Example: Different Character Types

Both Player and Enemy use the same MovementHandler but different InputHandlers:

Player: Uses PlayerInputHandler (reads player controls)
Enemy: Uses AIInputHandler (computes AI decisions)
Same Movement: Both use identical MovementHandler

Core Systems

Detailed breakdown of major game systems

📷

Camera System

Manual camera with autocorrection, first-person mode, and smooth following

🎮

Character System

Modular character architecture with composition-based components

👥

Follower AI

Formation-based following with catch-up mechanics and AI control

💬

Interaction System

Contextual interactions like Zelda - Read, Talk, Pick Up, etc.

⚙️

Manager Systems

CharacterManager, EventBus, ManagerRegistry for coordination

🎯

Targeting System

Z-targeting for lock-on combat mechanics

Signal Flow & Communication

How systems communicate through loose coupling

Character Switch Flow

InputHandler

→

BaseCharacter

→

CharacterManager

CharacterManager
character_switched

⇣

CameraController

FollowController

Other Systems

Key Signal Patterns

EventBus Pattern SOLID ▼

Central event dispatcher for game-wide events. Prevents tight coupling between systems.

# EventBus.gd - Global event dispatcher
extends Node

signal character_switched(new_character)
signal character_damaged(character, damage)
signal item_collected(item_type, amount)

# Any system can emit
EventBus.character_switched.emit(new_char)

# Any system can listen
EventBus.character_switched.connect(_on_character_changed)

Component Signals COMPOSITION ▼

Components communicate through signals to their parent coordinator.

# InputHandler emits signals
signal movement_input_changed(input_vector: Vector3)
signal jump_requested()

# BaseCharacter connects them
input_handler.movement_input_changed.connect(
    movement_handler.set_movement_input)
input_handler.jump_requested.connect(
    movement_handler.handle_jump)

Why this works: InputHandler doesn't need to know MovementHandler exists. BaseCharacter acts as the coordinator.

✅ Signal Best Practices

Name signals clearly - Use past tense (character_died) or request format (jump_requested)
Pass minimal data - Only what listeners need
Document parameters - Type hints help prevent bugs
Use EventBus for global events - Keeps systems decoupled
Connect in _ready() - Ensure connections exist before use

Code Deep Dive

Complete script breakdowns with detailed explanations

📘 How to use: Click on any script card below to see the full code broken down section-by-section with explanations of what each part does and why it matters.

👤

BaseCharacter.gd

Character coordinator using composition pattern

🏃

MovementHandler.gd

Pure movement logic with camera-relative controls

📷

CameraController.gd

Manual camera with subtle autocorrection

⚙️

CharacterManager.gd

Character registration and switching system

Developer Onboarding

Getting up to speed with the project

📚 Essential Concepts

Godot Node System - Everything is a node in a tree structure
Signals for Communication - Loose coupling through event-based architecture
Composition Over Inheritance - Build systems by combining components
CharacterBody3D Physics - How movement and collision work
Autoload Singletons - Global systems like EventBus and ManagerRegistry
GDScript Basics - Static typing, @export, @onready, class_name

🎯 Common Patterns

Pattern: Component Attachment

# Parent gets reference to child component
@onready var movement: MovementHandler = $MovementHandler

# Parent configures child
func _ready():
    movement.set_camera_interface(camera)

Pattern: Defensive Validation

# Always check before using
if not camera or not is_instance_valid(camera):
    push_warning("Invalid camera reference")
    return

if not camera.has_method("get_camera_forward"):
    push_warning("Camera missing required methods")
    return

⚠️ Common Pitfalls

Signal Parameter Mismatch - Ensure signal definitions match connections
Null References - Always validate nodes exist before using them
Missing Methods - Check interfaces have required methods with has_method()
Wrong Node Paths - Use correct absolute paths like /root/Main/CharacterManager
Godot Restart Required - After adding autoloads to project.godot, restart Godot
Collision Layers - Set correct layers for detection (characters=1, interactables=6)

🚀 Getting Started Checklist

Read through this documentation fully
Examine BaseCharacter.gd to understand composition pattern
Look at CharacterManager.gd for manager pattern examples
Study signal connections in BaseCharacter and CameraController
Review MovementHandler for component isolation
Understand camera-relative movement implementation
Test character switching and follower AI
Experiment with the interaction system

💡 Pro Tips

Use print() and push_warning() liberally for debugging
Create get_debug_info() methods in components for inspecting state
Follow the existing naming conventions (snake_case for variables/functions)
Document your signal parameters with type hints
Test in isolation before integrating with other systems
When stuck, check past implementations for patterns