Scalable Project Folder Structures

1. The Core Principle: Function Over Type

When starting a project, many developers fall into the habit of organizing their files by type. This leads to top-level folders like scripts/, scenes/, and textures/. While simple at first, this approach quickly breaks down. If you need to work on the player character, you might have to jump between three or four different folders to find the script, the scene file, the sprites, and the sound effects.

A more robust and scalable approach is to organize by function or feature. In this model, all the files related to a single game entity—like the player, an enemy, or a UI element—are grouped together.

To understand the "why" behind this shift in thinking, let's explore the architectural reasoning.

As the video argues, your project structure should communicate its intent, not what it's made of. A folder structure with directories like player/, enemies/, and ui/ immediately tells you what the game is about. A structure with scripts/ and scenes/ only tells you what technologies you're using.

For a complex project, organizing by function makes your code more modular and easier to manage. If you decide to port your player controller to another project, you can just copy the player/ folder, confident that all its dependencies are contained within it.

2. A Practical Structure for a Metroidvania/RPG

Now that we've established the philosophy, let's look at a practical implementation. How do we apply this "function-over-type" principle to a large Godot project like the one you want to build?

Based on the principles from both videos, here is a recommended folder structure for your project. This is a strong starting point that you can adapt as your game grows.

res://
├── addons/         # For third-party plugins
├── assets/         # For truly global assets (fonts, music)
│   ├── fonts/
│   └── music/
├── entities/       # Things that live in the world
│   ├── player/
│   ├── enemies/
│   └── items/
├── global/         # Game-agnostic, reusable systems
│   └── state_machine/
├── levels/         # The world itself: rooms, maps
│   └── tutorial_area/
├── managers/       # Autoloads/singletons for game state
│   ├── game_manager.gd
│   └── scene_manager.gd
├── ui/             # All user interface scenes and scripts
│   ├── hud/
│   └── menus/
└── main.tscn       # The main entry point scene for your game

Let's break down the key folders:

• entities/: This is where most of your game-specific logic will live. It contains anything that appears in your game world: the player, enemies, NPCs, interactable objects, and items. Each entity gets its own folder containing its scene, script, art, and sounds.
• levels/ (or stages/): This holds your game maps. For a Metroidvania, this folder would contain the scenes for each room or interconnected area, along with their associated TileSet resources.
• ui/: Contains all user interface elements. This includes the main menu, pause menu, inventory screen, dialogue boxes, and the in-game HUD. Keeping UI separate from game logic is a very good practice.
• global/ (or common/): Your CS background will make this folder intuitive. It's for abstract, reusable code that isn't tied to your specific game's logic. A finite state machine implementation, a generic event bus, or a pathfinding algorithm would go here.
• managers/ (or utilities/): This is the place for your autoload singletons. These are scripts that are always active and can be accessed from anywhere. They are perfect for managing global state, like which abilities the player has unlocked, handling scene transitions, or saving/loading the game. We will cover autoloads in detail in a future module.

3. Naming Conventions and Official Best Practices

Finally, to ensure your project is clean and portable, it's important to follow some standard conventions recommended by the Godot documentation.

From the documentation, here are the essential rules:

1. Use snake_case for files and folders: player_character.gd, main_menu/, etc.
   • Why? Windows filesystems are case-insensitive, while Linux and Godot's exported game packages are case-sensitive. Sticking to all lowercase with underscores (snake_case) prevents bugs where Player.gd and player.gd are treated as the same file on your development machine but as different files when you export your game.
2. Use PascalCase for node names: PlayerCharacter, MainMenu, TileMap, etc.
   • Why? This matches the naming convention of Godot's built-in nodes (e.g., CharacterBody2D, AnimationPlayer), creating a consistent style throughout your scene tree.

Conclusion

You now have a complete framework for thinking about and implementing a scalable project structure. This initial investment in organization will pay massive dividends as your Metroidvania grows in scope and complexity.

Key Takeaways:

• Organize your project by function (e.g., player, enemy), not by file type (e.g., scripts, scenes).
• A good starting structure includes top-level folders for entities, levels, ui, global systems, and managers (autoloads).
• Keep all assets for a specific feature (script, scene, art, audio) co-located within that feature's folder.
• Adhere to Godot's naming conventions: snake_case for files and folders, PascalCase for nodes.

This lesson concludes the "Godot Editor & Project Fundamentals" module. You now have a project that is correctly configured for pixel art and organized for future growth.

In our next lesson, we will begin Module 2: GDScript Fundamentals. We'll dive into the heart of Godot development by learning how to declare and use variables with static typing in GDScript, the first step towards programming your character's movement and actions.