godot-project-setup

Godot プロジェクトのセットアップ

このスキルは、推奨ディレクトリ構成、プロジェクト設定、オートロード、バージョン管理設定を備えた Godot 4.3 以降の新規プロジェクトを作成します。

関連スキル： シーンツリーの構成には scene-organization、EventBus オートロードパターンには event-bus、SaveManager オートロードパターンには save-load を参照してください。

推奨ディレクトリ構成（分割レイアウト）

分割レイアウトでは、アセット、シーン、スクリプトをそれぞれ別の最上位ディレクトリに分けます。中規模から大規模のプロジェクトでも拡張しやすく、種類ごとにリソースを見つけやすくなります。

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/

分割レイアウトを選ぶ理由

• アーティストが管理するアセットを、スクリプトのディレクトリに触れることなく更新できます。
• エクスポートプリセットの glob パターンがシンプルになります（assets/** と scripts/** を分けて管理できます）。
• ディレクトリごとに .gitattributes のバイナリルールを設定しやすくなります。
• アーティストとプログラマーが別々の領域で作業するチームにも適しています。

代替案：同一配置の構成

個人プロジェクトや小規模チームでは、機能ごとにシーンとスクリプトをまとめて配置します。機能一式を移動しやすくなりますが、バイナリ用の gitattributes ルールを適用しにくくなります。

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

# 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

テキストファイルの改行コードを統一し、バイナリアセットにマークを付けて、Git がそれらにテキスト差分を適用しないようにします。

# 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 > Project Settings または project.godot で設定します。

表示

設定	推奨値	備考
display/window/size/viewport_width	1920	基準解像度 — アートの参照サイズ
display/window/size/viewport_height	1080
display/window/stretch/mode	canvas_items	2D コンテンツを拡大縮小します。ピクセルパーフェクトにするには viewport を使用します
display/window/stretch/aspect	keep	レターボックス／ピラーボックスを追加します。expand は画面全体に表示します
display/window/size/resizable	true	デスクトップでウィンドウのサイズ変更を許可します

ピクセルアートのプロジェクトでは、stretch/mode = viewport を使用し、ルート CanvasItem で texture_filter = nearest を設定するか、rendering/textures/canvas_textures/default_texture_filter を使ってグローバルに設定してください。

Godot 4.7 以降： Godot 4.7 で新規作成されたプロジェクトでは、display/window/stretch/mode の既定値は canvas_items、display/window/stretch/aspect の既定値は expand になっています（以前は disabled／keep でした）。そのため、keep のレターボックスを使いたい場合は aspect のみ変更してください。旧バージョンで作成されたプロジェクトでは既存の値が維持されるため、アップグレード時には両方を明示的に設定してください。

入力マップ

キー定数をハードコードするのではなく、Project > Project Settings > Input Map でアクションを定義してください。これにより、プレイヤーが実行中に操作を割り当て直せるようになります。

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# — 入力アクションの読み取り：

// 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();
}

実行中のカスタム割り当ての保存と復元（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)

実行中のカスタム割り当ての保存と復元（C#）：

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);
    }
}

オートロード

Project > Project Settings > Globals > Autoload でオートロードを登録します。オートロードは、登録名を使ってグローバルに利用できるシングルトンノードです。

一般的なオートロード

名前	パス	目的
GameManager	autoloads/game_manager.gd	ゲームの状態、シーン遷移、一時停止
EventBus	autoloads/event_bus.gd	疎結合なシグナルの中継
AudioManager	autoloads/audio_manager.gd	音楽、効果音、音量制御
SaveManager	autoloads/save_manager.gd	ゲームデータの保存／読み込み

オートロードは小さく保ってください。ロジックは独立したクラスに移し、オートロードから呼び出します。

最小限の GameManager — 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()

最小限の GameManager — C#

// 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();
}

最小限の EventBus — 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)

ノードは次のように接続します。

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

C# プロジェクトのセットアップ

.csproj

C# サポートを有効にすると、Godot は .csproj を生成します。内容を最小限に保ち、ターゲットフレームワークを net8.0 に設定してください。

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

MyGame をプロジェクト名に置き換えてください。名前空間は自由に指定できます。Godot が必要とするのは、ファイル名と一致するクラス名です（Player.cs → class Player）。

partial クラスの要件

Godot の型を継承するすべての C# クラスは、partial として宣言する必要があります。Godot のソースジェネレーターは、コンパニオンとなる partial ファイルに登録コードを追加します。

// Correct
public partial class Player : CharacterBody2D { }

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

名前空間の規約

プロジェクトでは単一のルート名前空間を使用します。サブ名前空間は任意ですが、階層を浅く保ってください。

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

C# でのシグナル宣言

シグナルには [Signal] 属性を使用し、デリゲート名の末尾は EventHandler にしてください。

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

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

// Connect
someNode.HealthChanged += OnHealthChanged;

// Disconnect
someNode.HealthChanged -= OnHealthChanged;

プロジェクトセットアップのチェックリスト

新しいプロジェクトのひな型を作成した後、このチェックリストを使ってすべてが整っていることを確認します。

• ディレクトリー構造を作成した（assets/、scenes/、scripts/、または同じ場所に配置する構成）
• .gitignore を作成し、.godot/、.mono/、bin/、obj/ を含めた
• LF の正規化ルールとバイナリーアセットのルールを含む .gitattributes を作成した
• project.godot — ビューポートの解像度を設定した（1920x1080、またはプロジェクトの目標値）
• project.godot — ストレッチモードを設定した（canvas_items または viewport）
• すべてのプレイヤー入力に対応する Input Map アクションを定義した（キー定数をハードコードしていない）
• オートロードを登録した：GameManager、EventBus、AudioManager、SaveManager
• オートロードスクリプトを autoloads/（または scripts/autoloads/）の下に作成した
• 一時停止中も実行する必要があるオートロードの処理モードを Always に設定した
• C# プロジェクトの場合：.csproj で net8.0 をターゲットにし、RootNamespace を設定し、Nullable を有効にした
• C# プロジェクトの場合：すべてのノードスクリプトで partial class を使用した
• ゲームコンテンツを追加する前に、main ブランチで最初のコミットを作成した
• プロジェクトのエージェント指示ファイル（CLAUDE.md、またはリポジトリーで管理している場合は AGENTS.md / GEMINI.md）に、スキルの呼び出しルールを含む ## GodotPrompter セクションがある（内容については godot-prompter:godot-brainstorming を参照）
• CI パイプライン（任意ですが推奨）：GDScript ファイルに対して godot --headless --check-only を実行する