Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Godot Project Structure: res://, user:// and Files

Understand how a Godot project is laid out on disk: project.godot, res:// and user:// paths, .tscn and .tres text files, the .godot cache, imports and a clean folder structure.

A Godot project is just a folder. There is no hidden database: scenes, scripts, settings and assets are ordinary files, and most of them are readable text. This makes Godot friendly to version control, code review and troubleshooting. In this lesson you will learn what each file is, how paths with res:// and user:// work, and how to organize a project so it stays tidy as it grows.

Godot is not available on this site, so file examples are shown read-only. A Python stand-in at the end models how res:// and user:// map to real folders.

The root folder

A fresh project looks like this:

TEXT
my-game/
  .godot/           cache (generated, do not commit)
  .gitignore
  icon.svg
  project.godot     project settings
  main.tscn         a scene
  main.gd           a script

The folder containing project.godot is the project root. Godot treats everything under it as part of the project.

project.godot

This is an INI-style text file. Open it in any editor and you will see sections like this:

INI
config_version=5

[application]
config/name="My Game"
run/main_scene="res://main.tscn"
config/features=PackedStringArray("4.4", "Forward Plus")

[display]
window/size/viewport_width=1280
window/size/viewport_height=720

You rarely edit it by hand. Project > Project Settings writes it for you, and only settings that differ from the default are saved, which keeps the file short and the version control diffs readable.

Paths: res:// and user://

Godot does not use operating-system paths such as C:\Users\you\my-game\main.gd in your code. It uses two virtual prefixes.

Prefix Meaning Writable?
res:// The project root (the "resources" of the game). res://main.tscn is main.tscn in the project root. Read-only in an exported game
user:// A per-user, per-project folder chosen by the operating system, for saves and settings. Yes

Why two? After you export, your game's files are packed into a single archive (a .pck or inside the executable) that you cannot write into. Save games, logs and configuration therefore go to user://. You can open this folder from the editor with Project > Open User Data Folder.

GDSCRIPT
# Reading a file shipped with the game
var text := FileAccess.get_file_as_string("res://data/levels.json")

# Writing a save file (works in the editor and in exports)
var file := FileAccess.open("user://save.json", FileAccess.WRITE)
file.store_string('{"score": 120}')

Paths use forward slashes on every platform, and are case-sensitive in exports even on Windows. Name files in lowercase to avoid "works on my machine" bugs. We use snake_case for files (player_ship.tscn), which matches Godot's own style guide.

Scenes and resources as text

Saved scenes use the .tscn extension (text scene). Everything else that is a saved object (materials, themes, animations, tile sets) is a resource saved as .tres (text) or .res (binary). Here is a tiny scene file:

INI
[gd_scene load_steps=2 format=3 uid="uid://c4x9k2vqj8d1m"]

[ext_resource type="Script" path="res://main.gd" id="1_abcde"]

[node name="Main" type="Control"]
layout_mode = 3
script = ExtResource("1_abcde")

[node name="Label" type="Label" parent="."]
layout_mode = 0
text = "Hello, Godot!"

You can read it: one root node Main, one child Label whose parent is "." (the root), and an external resource (the script) referenced by an id. Because it is text, two people editing different parts of a project usually merge cleanly in Git.

The uid://... is a unique ID. Since Godot 4.4, files also get stable IDs so that renaming or moving a file in the editor does not break references to it. Always move and rename files inside Godot's FileSystem dock, not in your file explorer, so references update.

Imported assets and the .godot folder

Images, audio and 3D models are not used as they are. When you drop player.png into the project, Godot imports it: it creates a player.png.import text file next to it (import settings, which you do commit) and a processed copy in .godot/imported/ (the cache, which you do not). To change import options (for example pixel-art filtering), select the file, open the Import dock, change settings and press Reimport.

If .godot/ is deleted or corrupted, nothing is lost: reopening the project rebuilds it, which may take a moment.

A folder structure that scales

Godot is flexible. There are two common styles:

  • By type: scenes/, scripts/, art/, audio/. Easy to start with.
  • By feature (recommended for bigger games): everything about the player lives together.
TEXT
player/
  player.tscn
  player.gd
  player_sprites.png
enemies/
  slime/
    slime.tscn
    slime.gd
ui/
  main_menu.tscn
audio/
  sfx/
  music/
autoload/
  game_state.gd

Keep a scene and its script in the same folder with the same base name (player.tscn, player.gd). When you search a project for "player", you find them together, and moving the folder moves both.

What to commit to Git

  • Commit: project.godot, all .tscn, .tres, .gd, assets, and their .import files.
  • Do not commit: .godot/, exports, and *.translation generated files.

The .gitignore made by Godot already contains .godot/. Check it exists.

Stand-in: mapping res:// and user:// to folders

This is not Godot: a Python model showing how virtual paths become real ones, and why res:// cannot be written to in an export.

Python Stand-in (Python): resolving virtual paths

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should a game write save files so they work in an exported build?

    res:// is read-only in an export. user:// is a writable per-user folder.
  2. 2. Which file stores the project's settings as text?

    project.godot is an INI-style text file that stores only the settings that differ from defaults.
  3. 3. What should you do when you want to rename or move a scene file?

    The FileSystem dock updates references to the moved file. Moving files outside the editor can break them.
  4. 4. Which of these should you NOT commit to Git?

    The .godot cache is regenerated on open. Import settings files (.import) should be committed.

Summary

  • A project is a folder with project.godot; everything is files, mostly text.
  • res:// is the read-only project root; user:// is the writable per-user folder for saves.
  • .tscn and .tres files are text, so Git works well; the .godot/ cache is generated.
  • Imported assets get .import files you commit.
  • Organize by feature, use snake_case names, and move files inside the editor.

Next: A Tour of the Godot Editor