Skip to content

M1.2 — Folder Layout & res:// Paths

What you'll learn

  • Address project files by res:// path, and move or rename them safely inside the FileSystem dock.
  • Organize a project by architectural role (scenes/{actor,component,ui,world}, resources) rather than by scene hierarchy.
  • Explain what a .uid file does and why it makes moves safer in Godot 4.6.

How it applies

  • The layout you start with is the layout you keep. A flat project (everything in the root) is not wrong at four files; it is unworkable at forty, and there is no painless moment to retrofit it — by the time it hurts, dozens of paths reference the mess. Choosing a role-based layout on day one costs nothing and saves a future reorganization.
  • Find-the-file is a real cost in an ARPG. This genre accumulates many small scenes — every enemy, every item, every UI panel, every reusable component. A layout where you can predict which folder a thing lives in turns "where is the skeleton's hurtbox scene?" from a search into a guess that is always right.
  • Source-control diffs stay legible. Role-based folders mean a combat change touches scenes/component/, a loot change touches resources/items/, and a reviewer can tell at a glance what a commit is about from the paths alone.
  • Test isolation. Organizing by role keeps reusable, dependency-free components (scenes/component/) physically separate from the scenes that wire them together. That boundary is the same one a tester wants: the components are the units; the assemblies are the integrations.

Concepts

res:// paths name files

Every file in the project is addressed by a path beginning with res:// — the root of the project's resource filesystem. res://scenes/actor/player.tscn is the player scene; res://scripts/health.gd is a script. Code and scenes refer to each other by these paths: preload("res://scenes/actor/enemy.tscn") loads a scene; a scene file records the res:// path of each script and sub-scene it uses.

The consequence: a path is a contract. If you move health.gd to a new folder, every file that referenced the old path must update. The editor does this for you when you move files inside Godot's FileSystem dock — it rewrites the references. Move the same file in Windows Explorer and the editor cannot follow; the references break. Rule: rename and move inside the FileSystem dock, never in the OS file manager.

.uid files — a safety net, not a license to be sloppy

Godot 4.4+ writes a .uid sidecar file next to scripts and resources (e.g., health.gd.uid) containing a stable identifier like uid://b8x.... References can point at the UID instead of the path, so a file found by UID survives a move even if a path somewhere was missed. This makes moves safer than in Godot 3, but it is a net, not a plan: a predictable layout you rarely have to reorganize beats relying on the net. Commit .uid files to source control alongside their owners.

Layout by role, not by hierarchy

The instinct is to mirror the scene tree on disk — a folder per level, sub-folders for what's in each level. That couples your file layout to your current game structure, which changes constantly. The durable alternative organizes by what kind of work a file does, which changes rarely.

This book uses:

res://
  scenes/
    actor/       # things that act: player.tscn, enemy_skeleton.tscn, enemy_bat.tscn
    component/   # reusable, dependency-free parts: hurtbox.tscn, hitbox.tscn, health.tscn, state_machine.tscn
    ui/          # HUD and screens: hud.tscn, inventory_screen.tscn, tooltip.tscn
    world/       # maps and arenas: arena_01.tscn, level_transition.tscn
    fx/          # effects: damage_number.tscn, hit_spark.tscn, loot_beam.tscn
  scripts/       # scripts not owned by one scene (autoloads, base classes, pure helpers)
  resources/
    items/       # ItemData .tres files
    stats/       # StatBlock .tres files
    affixes/     # affix-pool .tres files
  assets/
    sprites/
    audio/
    fonts/
  addons/        # third-party plugins (if any)

The load-bearing folder is scenes/component/. A component is a small scene with no dependencies on the actor that hosts it — a Hurtbox does not know whether it is on the player or a skeleton. That independence is what lets the player and every enemy reuse the same component, and it is the genre's loose-coupling answer (the Godot docs' "design scenes to have no dependencies" rule, made concrete).

Example

Two layouts, same four-enemy game. By hierarchy: levels/cave/enemies/skeleton/skeleton.tscn, levels/cave/enemies/skeleton/hurtbox.tscn, levels/crypt/enemies/skeleton/skeleton.tscn — the skeleton (and its hurtbox) is duplicated per level, and a fix to the skeleton must be applied in several places. By role: one scenes/actor/enemy_skeleton.tscn and one scenes/component/hurtbox.tscn, reused by every level and every enemy. The role layout has one skeleton; the hierarchy layout has as many as you have levels.

Example

A naming convention pays for itself: files are snake_case and a scene's root node matches its purpose. enemy_skeleton.tscn has a root named EnemySkeleton; hurtbox.tscn has a root Hurtbox. When you instance a component, the node name in the tree already tells you what it is. The Godot editor follows this convention; matching it keeps your project legible to anyone who has read any other Godot project.

Folder color and the FileSystem dock

The FileSystem dock (lower-left) is your map of res://. Right-click a folder → Set Folder Color to tint the ones you open most (scenes/component/ is a good candidate). It is cosmetic, but in a project with many folders the color cuts the time to find the busy ones. Double-click a scene to open it; drag a scene from the dock into the editor viewport to instance it.

Walkthrough

Perform these in your project's FileSystem dock (not in Windows Explorer).

  1. In the FileSystem dock, right-click the res:// root → New Folder → name it scenes. Repeat to create scripts, resources, assets, and (optionally) addons.
  2. Inside scenes, create actor, component, ui, world, fx.
  3. Inside resources, create items, stats, affixes.
  4. Inside assets, create sprites, audio, fonts.
  5. Optionally set a folder color on scenes/component so it is easy to spot — you will open it constantly from M3 on.
  6. Leave the folders empty for now. M1.3 adds input actions (no files); M1.4 creates the first scenes and scripts and places them in scenes/world, scenes/ui, and scripts.

Optional sanity check

Create a throwaway script anywhere, then drag it in the FileSystem dock from one folder to another. Watch the editor report that it updated references (there are none yet, but you will see the move is tracked). Then delete it. This confirms you are moving files inside Godot, where references are maintained.

Self-check quiz

Q1 — You move health.gd from scripts/ to scenes/component/ using Windows Explorer while Godot is closed. What is the most likely result on next open?

A. Nothing — Godot scans paths fresh each launch and re-links automatically. B. Scenes that referenced res://scripts/health.gd may fail to load or show a broken script, because the editor wasn't there to rewrite the references. C. The .uid file guarantees zero breakage in all cases. D. The project refuses to open until you rename the file back.

Reveal answer

B. Moving inside the FileSystem dock lets the editor rewrite every res:// reference; moving in the OS bypasses that. The .uid sidecar (C) helps when references use the UID and the sidecar moved with the file, but it is not a guarantee for every reference, especially if the .uid was left behind or a reference used the raw path. A overstates the engine's link-healing. D is not how Godot fails here — it loads with broken references rather than refusing.

Q2 — Why does a Hurtbox scene belong in scenes/component/ rather than scenes/actor/?

A. Components render faster than actors. B. A component is a reusable, dependency-free part shared by many actors; the folder marks that contract and keeps the reusable units separate from the assemblies that wire them. C. Godot requires Area2D nodes to live in a folder named component. D. It is purely alphabetical convenience.

Reveal answer

B. The component folder encodes an architectural promise: a Hurtbox knows nothing about whether it sits on the player or an enemy, so it can be reused by both. Keeping components apart from actors mirrors the unit-vs-integration boundary a tester also cares about. A and C are fabricated (the folder has no rendering or engine meaning). D undersells the reason — the layout carries information, not just order.

Q3 — A role-based layout is described as scaling where a flat layout does not. What is the precise failure of the flat layout?

A. Flat layouts exceed a file-count limit Godot enforces. B. Flat layouts are fine until the project grows, at which point dozens of references point into an unstructured root and there is no painless moment to reorganize. C. Flat layouts cannot use preload. D. Flat layouts break user:// saves.

Reveal answer

B. There is no engine limit (A) and no effect on preload (C) or saves (D). The cost is organizational and back-loaded: the flat root works at small scale, and by the time it hurts, too many paths reference it to reorganize cheaply. The fix is to choose structure before the cost lands.

Integration question

Q4 — open

M1.1 fixed the coordinate system for space (base resolution and stretch). This chapter fixed a different coordinate system. What is it, and how does the scenes/component/ folder specifically set up the architecture you will build in M3 (combat) and reuse in M4 (enemies)?

Reveal expected answer

This chapter fixes the coordinate system for file references: every res:// path you type from M2 onward is reasoned against this layout, so locking it now means later chapters never rewrite paths. scenes/component/ specifically pre-commits to the component architecture that M3 builds — Hurtbox, Hitbox, and Health are authored once as dependency-free scenes in that folder, and M4 reuses the same scenes on enemies. The folder is not just storage; it is a declaration that combat will be built from shared, loosely-coupled parts rather than copied per actor.