Start Building

Lesson Goal

You have your action-adventure concept from Lesson 1.
Now it is time to build a project structure that prevents chaos once combat, quests, UI, and save systems all start shipping in parallel.

In this lesson you will:

  • Create a folder architecture that scales past prototype stage
  • Define scene ownership rules for gameplay systems
  • Lock naming conventions for files, nodes, scripts, and signals
  • Set up a lightweight architecture guide your team can follow

By the end, your Godot 4 project will be easy to navigate, safer to refactor, and faster to onboard collaborators into.

Step 1 - Create a Production-Friendly res:// Folder Layout

Start by replacing ad hoc folders with intentional structure.

Use this baseline:

  • res://core/ for global systems, autoload scripts, shared helpers
  • res://gameplay/ for player, enemy, combat, quests, items
  • res://world/ for tilemaps, levels, encounters, navigation content
  • res://ui/ for HUD, menus, prompts, settings
  • res://audio/ for buses, music, SFX, ambient collections
  • res://art/ for textures, sprites, VFX sources, imported atlases
  • res://tests/ for test scenes and reproducible debug setups

Keep your file names descriptive and stable. Avoid temporary names like test2_final_really.tscn.

Mini challenge:
Create this folder structure in your project and move at least three existing prototype files into their proper domain.

Step 2 - Define Scene Ownership Before You Add More Features

Most Godot projects become brittle because nobody knows which scene owns what.

Set a simple ownership map:

  1. Main scene owns high-level flow (loading, transitions, persistent managers).
  2. World scene owns level content and mission context.
  3. Player scene owns movement, combat input, and local state.
  4. Feature scenes (inventory, quest tracker, dialogue box) own only their local UI/state.

Keep cross-scene communication explicit with signals rather than direct node path dependencies whenever possible.

Mini challenge:
Write a one-page ownership note listing your top 6 scenes and their ownership boundaries.

Step 3 - Set Naming Rules for Nodes, Scenes, Scripts, and Signals

Use consistency now to avoid migration pain later.

Recommended conventions:

  • Scenes: snake_case.tscn (player_controller.tscn, quest_log_panel.tscn)
  • Scripts: snake_case.gd matching scene/system names
  • Node names: PascalCase for readability in editor hierarchy
  • Signals: snake_case verbs (quest_started, health_changed, checkpoint_reached)
  • Constants: UPPER_SNAKE_CASE

If you use C# in parts of the project, keep class names PascalCase while preserving folder intent.

Common mistake: naming by implementation detail (Node2D3, ManagerNew) instead of gameplay meaning (EncounterSpawner, AbilityCooldownUI).

Step 4 - Add an Architecture Guardrail File in the Repo

Create ARCHITECTURE.md at project root with:

  • folder map and purpose
  • naming rules
  • scene ownership table
  • signal/event naming examples
  • "do not do" anti-patterns (hard-coded deep node paths, global god managers, duplicate singleton logic)

This document keeps future commits aligned and reduces review cycles.

Mini challenge:
Draft your first version of ARCHITECTURE.md in under 30 lines. Keep it short and enforceable.

Step 5 - Build a Fast Validation Routine

Before ending each work session, run a 5-minute architecture check:

  1. Any new files in wrong folder? Move them now.
  2. Any scene with more than one clear owner? Split responsibilities.
  3. Any new signal names inconsistent? Rename while changes are small.
  4. Any hard-coded fragile node paths? Replace with exported references or signal wiring.

Small cleanup daily is cheaper than one giant "refactor month."

Troubleshooting and Common Mistakes

  • Everything in res://scripts/: split by domain first, then by feature complexity.
  • One giant autoload: keep autoloads tiny and service-focused.
  • Copy-paste scene variants: prefer inherited scenes or reusable child scenes.
  • Signal spam with no source of truth: document event producers/consumers in your architecture file.

Pro Tips

  • Keep one "sandbox" scene for rapid mechanics tests so experimental content does not pollute production scenes.
  • Version scene contracts: when changing key scene interfaces, note it in commit message and architecture notes.
  • Use a naming lint checklist during PR reviews for faster consistency.

FAQ

Should I use one folder per feature or one folder per asset type in Godot 4?

Use feature-first at top level (gameplay, world, ui) and type-specific subfolders inside each feature when needed.

When should I introduce autoload singletons?

Only for true app-wide state/services (settings, save gateway, telemetry). Do not autoload gameplay feature logic.

How strict should naming conventions be?

Very strict for scenes/scripts/signals. Consistency improves onboarding speed and reduces wiring bugs.

Quick Recap

In this lesson you:

  • Created a scalable folder structure for your Godot 4 action adventure
  • Defined scene ownership boundaries
  • Standardized naming conventions for code and content
  • Added architecture guardrails and a quick validation routine

Next lesson, you will build scene and node foundations with instancing patterns and signal-first composition so new gameplay modules plug in cleanly.

If this lesson helped, bookmark it for your next project setup and share it with your team before your first big feature sprint.