---
name: godot-project-setup
description: Use when creating a new Godot 4.x project — scaffolds recommended directory structure, project settings, autoloads, and .gitignore
title: godot-project-setup
canonical_url: https://skilld.dev/gh/jame581/godotprompter/godot-project-setup
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/godot-project-setup`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/godot-project-setup`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/godot-project-setup) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/godot-project-setup`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/godot-project-setup --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/godot-project-setup --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Godot Project Setup

This skill scaffolds a new Godot 4.3+ project with recommended directory structure, project settings, autoloads, and version control configuration.

> **Related skills:** **scene-organization** for structuring scene trees, **event-bus** for the EventBus autoload pattern, **save-load** for the SaveManager autoload pattern.

## Recommended Directory Structure (Split Layout)

The split layout separates assets, scenes, and scripts into distinct top-level directories. This scales well for medium-to-large projects and makes it easy to find resources by type.

```
res://
├── assets/
│   ├── audio/
│   │   ├── music/
│   │   └── sfx/
│   ├── fonts/
│   ├── shaders/
│   ├── sprites/
│   │   ├── characters/
│   │   ├── environment/
│   │   └── ui/
│   └── textures/
├── scenes/
│   ├── autoloads/
│   ├── characters/
│   ├── environment/
│   ├── levels/
│   ├── screens/
│   └── ui/
├── scripts/
│   ├── autoloads/
│   ├── characters/
│   ├── components/
│   ├── resources/
│   └── ui/
├── resources/
│   ├── items/
│   ├── levels/
│   └── themes/
└── addons/
```

**Why split layout?**
- Assets managed by artists can be updated without touching script directories.
- Glob patterns in export presets are simpler (`assets/**` stays separate from `scripts/**`).
- Easier to configure `.gitattributes` binary rules per directory.
- Scales to teams where artists and programmers work in different areas.

## Alternative: Co-Located Structure

For solo projects or small teams, keep scenes and scripts together by feature. Easier to move a feature wholesale; harder to apply binary `gitattributes` rules.

```
res://
├── assets/
│   ├── audio/
│   ├── fonts/
│   └── textures/
├── entities/
│   ├── player/
│   │   ├── player.tscn
│   │   ├── player.gd          # or Player.cs
│   │   └── player_state.gd
│   └── enemy/
│       ├── enemy.tscn
│       └── enemy.gd
├── levels/
│   ├── level_01/
│   │   ├── level_01.tscn
│   │   └── level_01.gd
│   └── main_menu/
│       ├── main_menu.tscn
│       └── main_menu.gd
├── systems/
│   ├── inventory/
│   └── dialogue/
├── autoloads/
├── resources/
└── addons/
```

## .gitignore

```gitignore
# Godot editor data — never commit
.godot/

# Export artifacts
*.apk
*.aab
*.ipa
*.exe
*.x86_64
*.x86_32
*.arm32
*.arm64
*.pck
*.zip
export/

# C# / Mono build output
.mono/
.import/
bin/
obj/
*.csproj.user
*.sln.user
*.user

# IDE and OS files
.vs/
.vscode/settings.json
.idea/
*.swp
.DS_Store
Thumbs.db

# GodotPrompter (if used in-project)
.godot-prompter-cache/
```

## .gitattributes

Normalize line endings for text files and mark binary assets so Git does not attempt text diffs on them.

```gitattributes
# Default: normalize line endings to LF on commit
* text=auto eol=lf

# Godot-specific text files
*.gd text eol=lf
*.gdshader text eol=lf
*.gdshaderinc text eol=lf
*.tscn text eol=lf
*.tres text eol=lf
*.godot text eol=lf
*.cfg text eol=lf
*.import text eol=lf

# C# source
*.cs text eol=lf
*.csproj text eol=lf
*.sln text eol=lf

# Binary assets — no diff, no merge, no EOL conversion
*.png binary
*.jpg binary
*.jpeg binary
*.webp binary
*.svg binary
*.psd binary
*.aseprite binary
*.wav binary
*.ogg binary
*.mp3 binary
*.ttf binary
*.otf binary
*.woff binary
*.woff2 binary
*.glb binary
*.gltf binary
*.blend binary
*.fbx binary
*.mp4 binary
*.ogv binary
```

## Project Settings

Configure these in `Project > Project Settings` or directly in `project.godot`.

### Display

| Setting | Recommended value | Notes |
|---|---|---|
| `display/window/size/viewport_width` | 1920 | Base resolution — art reference size |
| `display/window/size/viewport_height` | 1080 | |
| `display/window/stretch/mode` | `canvas_items` | Scales 2D content; use `viewport` for pixel-perfect |
| `display/window/stretch/aspect` | `keep` | Adds letterbox/pillarbox; `expand` fills screen |
| `display/window/size/resizable` | `true` | Allow window resize on desktop |

For pixel-art projects use `stretch/mode = viewport` and `texture_filter = nearest` on the root CanvasItem or globally via `rendering/textures/canvas_textures/default_texture_filter`.

> **Godot 4.7+:** Projects **newly created** in Godot 4.7 already default `display/window/stretch/mode` to `canvas_items` and `display/window/stretch/aspect` to `expand` (previously `disabled` / `keep`), so only `aspect` needs changing if you want `keep`'s letterboxing. Projects created on older versions keep their existing values — set both explicitly when upgrading.

> **Changed in Godot 4.8:** Projects **newly created** in Godot 4.8 keep those two entries and add three more defaults: `gui/common/auto_focus_strategy = Balloon` (class default `Legacy`), `input_devices/joypads/ignore_joypad_on_unfocused_application = true` (class default `false`), and `rendering/lights_and_shadows/multi_bounce_occlusion/enabled = true`. Upgraded projects keep their existing behavior, so set them explicitly if you want the new-project values.

### Input Map

Define actions in `Project > Project Settings > Input Map` rather than hard-coding key constants. This lets players rebind controls at runtime.

**GDScript — reading input actions:**

```gdscript
# Good: action-based (rebindable)
func _process(delta: float) -> void:
    var direction := Input.get_axis("move_left", "move_right")
    if Input.is_action_just_pressed("jump"):
        _jump()

# Avoid: hard-coded key checks
func _input(event: InputEvent) -> void:
    if event is InputEventKey and event.keycode == KEY_SPACE:
        _jump()
```

**C# — reading input actions:**

```csharp
// Good: action-based (rebindable)
public override void _Process(double delta)
{
    float direction = Input.GetAxis("move_left", "move_right");
    if (Input.IsActionJustPressed("jump"))
        Jump();
}

// Avoid: hard-coded key checks
public override void _Input(InputEvent @event)
{
    if (@event is InputEventKey key && key.Keycode == Key.Space)
        Jump();
}
```

**Saving and restoring custom bindings at runtime (GDScript):**

```gdscript
func save_bindings() -> void:
    var config := ConfigFile.new()
    for action in InputMap.get_actions():
        if action.begins_with("ui_"):
            continue  # skip built-in UI actions
        var events := InputMap.action_get_events(action)
        config.set_value("bindings", action, events)
    config.save("user://bindings.cfg")

func load_bindings() -> void:
    var config := ConfigFile.new()
    if config.load("user://bindings.cfg") != OK:
        return
    for action in config.get_section_keys("bindings"):
        InputMap.action_erase_events(action)
        for event in config.get_value("bindings", action):
            InputMap.action_add_event(action, event)
```

**Saving and restoring custom bindings at runtime (C#):**

```csharp
public void SaveBindings()
{
    var config = new ConfigFile();
    foreach (StringName action in InputMap.GetActions())
    {
        if (((string)action).StartsWith("ui_"))
            continue; // skip built-in UI actions
        var events = InputMap.ActionGetEvents(action);
        config.SetValue("bindings", action, events);
    }
    config.Save("user://bindings.cfg");
}

public void LoadBindings()
{
    var config = new ConfigFile();
    if (config.Load("user://bindings.cfg") != Error.Ok)
        return;
    foreach (string action in config.GetSectionKeys("bindings"))
    {
        InputMap.ActionEraseEvents(action);
        var events = (Godot.Collections.Array)config.GetValue("bindings", action);
        foreach (InputEvent @event in events)
            InputMap.ActionAddEvent(action, @event);
    }
}
```

## Autoloads

Register autoloads in `Project > Project Settings > Globals > Autoload`. Autoloads are singleton nodes available globally via their registered name.

### Common Autoloads

| Name | Path | Purpose |
|---|---|---|
| `GameManager` | `autoloads/game_manager.gd` | Game state, scene transitions, pause |
| `EventBus` | `autoloads/event_bus.gd` | Decoupled signal relay |
| `AudioManager` | `autoloads/audio_manager.gd` | Music, SFX, volume control |
| `SaveManager` | `autoloads/save_manager.gd` | Save/load game data |

Keep autoloads small. Move logic into standalone classes and call them from the autoload.

### Minimal GameManager — GDScript

```gdscript
# autoloads/game_manager.gd
extends Node

signal scene_changed(scene_path: String)
signal game_paused(is_paused: bool)

var current_level: String = ""
var is_paused: bool = false


func change_scene(path: String) -> void:
    current_level = path
    scene_changed.emit(path)
    get_tree().change_scene_to_file(path)


func set_paused(paused: bool) -> void:
    is_paused = paused
    get_tree().paused = paused
    game_paused.emit(paused)


func quit_game() -> void:
    get_tree().quit()
```

### Minimal GameManager — C#

```csharp
// autoloads/GameManager.cs
using Godot;

public partial class GameManager : Node
{
    [Signal]
    public delegate void SceneChangedEventHandler(string scenePath);

    [Signal]
    public delegate void GamePausedEventHandler(bool isPaused);

    public string CurrentLevel { get; private set; } = "";
    public bool IsPaused { get; private set; }

    public void ChangeScene(string path)
    {
        CurrentLevel = path;
        EmitSignal(SignalName.SceneChanged, path);
        GetTree().ChangeSceneToFile(path);
    }

    public void SetPaused(bool paused)
    {
        IsPaused = paused;
        GetTree().Paused = paused;
        EmitSignal(SignalName.GamePaused, paused);
    }

    public void QuitGame() => GetTree().Quit();
}
```

### Minimal EventBus — GDScript

```gdscript
# autoloads/event_bus.gd
extends Node

# Declare all cross-system signals here.
# Systems emit to EventBus; listeners connect to EventBus.

signal player_died
signal item_collected(item_id: String, quantity: int)
signal score_changed(new_score: int)
signal level_completed(level_id: String)
```

Nodes connect with:

```gdscript
EventBus.player_died.connect(_on_player_died)
EventBus.player_died.emit()
```

## C# Project Setup

### .csproj

When you enable C# support Godot generates a `.csproj`. Keep it minimal and set the target framework as below (Godot 4.5 to 4.7: `net8.0`, `net9.0` for Android; 4.4 has no Android override; 4.3 generated `net6.0`, `net7.0` for Android and `net8.0` for iOS). Godot 4.8 needs `net10.0` everywhere, see the callout below:

```xml
<Project Sdk="Godot.NET.Sdk/4.3.0">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <RootNamespace>MyGame</RootNamespace>
  </PropertyGroup>
</Project>
```

Replace `MyGame` with your project name. Namespaces are free-form; what Godot needs is a class whose name matches its file name (`Player.cs` → `class Player`).

> **Changed in Godot 4.8:** The minimum target framework is **.NET 10**. A new 4.8 C# project gets `net10.0` for every platform, Android included (4.5 to 4.7 wrote `net9.0` for Android). On 4.8 replace each `net8.0` above with `net10.0`; the 4.8 editor also raises an older `TargetFramework` when it opens the project.

### partial class Requirement

Every C# class that extends a Godot type **must** be declared `partial`. Godot's source generator adds the registration code in a companion partial file.

```csharp
// Correct
public partial class Player : CharacterBody2D { }

// Wrong — build error GD0001: missing partial modifier
public class Player : CharacterBody2D { }
```

### Namespace Convention

Use a single root namespace for the project. Sub-namespaces are optional but keep them shallow:

```csharp
namespace MyGame.Characters;   // OK
namespace MyGame.UI;           // OK
namespace MyGame.Systems.Inventory.Data.Containers;  // Too deep — flatten
```

### Signal Declaration in C#

Signals must use the `[Signal]` attribute with a delegate ending in `EventHandler`:

```csharp
[Signal]
public delegate void HealthChangedEventHandler(int newHealth, int maxHealth);

// Emit
EmitSignal(SignalName.HealthChanged, health, maxHealth);

// Connect
someNode.HealthChanged += OnHealthChanged;

// Disconnect
someNode.HealthChanged -= OnHealthChanged;
```

## Project Setup Checklist

Use this checklist after scaffolding a new project to verify everything is in place.

- [ ] Directory structure created (`assets/`, `scenes/`, `scripts/` or co-located layout)
- [ ] `.gitignore` created and includes `.godot/`, `.mono/`, `bin/`, `obj/`
- [ ] `.gitattributes` created with LF normalization and binary asset rules
- [ ] `project.godot` — viewport resolution set (1920x1080 or project target)
- [ ] `project.godot` — stretch mode configured (`canvas_items` or `viewport`)
- [ ] Input Map actions defined for all player inputs (no hard-coded key constants)
- [ ] Autoloads registered: `GameManager`, `EventBus`, `AudioManager`, `SaveManager`
- [ ] Autoload scripts created under `autoloads/` (or `scripts/autoloads/`)
- [ ] Autoloads are process mode `Always` if they must run while paused
- [ ] For C# projects: `.csproj` targets `net8.0` (Godot 4.4 to 4.7; Android `net9.0` from 4.5) or `net10.0` (Godot 4.8), `RootNamespace` set, `Nullable` enabled
- [ ] For C# projects: all node scripts use `partial class`
- [ ] Initial commit on `main` branch before adding game content
- [ ] The project's agent instructions file (`CLAUDE.md`, or `AGENTS.md` / `GEMINI.md` if that is what the repo maintains) contains a `## GodotPrompter` section with the skill invocation rule — a skill for a new system, the project's code for an existing one (see `godot-prompter:godot-brainstorming` for content)
- [ ] CI pipeline (optional but recommended): runs `godot --headless --check-only` on GDScript files
