Project Scaffold

Project Scaffold

$ARGUMENTS

Generate a new Godot game project with GodotMaker's ECS architecture. Read templates from this skill's templates/ directory, fill {{placeholders}} with values from the game plan or user input, and write results to the target.

Step 1 — Gather Variables

If a confirmed Game Plan exists in the conversation (from game-planner), extract variables from it. Otherwise, ask the user for game name and genre at minimum — use genre defaults for everything else.

Genre defaults:

Step 2 — Create Directory Structure

Create the project root and all subdirectories:

{{game_name}}/
├── project.godot
├── CLAUDE.md
├── .gitignore
├── src/
│   ├── components/          # C_ prefixed component scripts
│   ├── systems/             # NameSystem scripts
│   ├── entities/            # Entity scene definitions
│   └── ui/                  # UI scenes and scripts
├── scenes/
│   ├── main.tscn            # Entry point scene
│   └── game_world.tscn      # Gameplay scene with camera
├── test/
│   └── test_example.gd      # gdUnit4 test template
├── e2e/
│   └── conftest.py           # E2E test config (GODOT_PROJECT = "..")
├── assets/
│   ├── sprites/
│   ├── audio/
│   ├── fonts/
│   └── ui/
├── references/              # Scene reference images (generated by /gm-asset)
└── addons/                  # gecs + gdUnit4 + godot_e2e installed here

.tscn Generation Rules

When writing .tscn files (from templates or manually), follow these rules strictly:

1. No UID references — use res://path/to/script.gd paths, never uid://xxx. UID references fail in headless/CI environments because uid_cache.bin cannot be rebuilt.
2. load_steps formula — load_steps = ext_resource_count + sub_resource_count + 1. Count carefully; mismatch causes parse errors.
3. parent attribute required — only the root [node] omits parent. Every other node MUST have parent="." (direct child of root) or parent="path/to/parent".
4. World node setup — always set system_nodes_root = NodePath(".") and entity_nodes_root = NodePath(".") when using SystemGroups.

Step 3 — Fill Templates

Read each template from templates/, replace all {{placeholders}}, write output. Remove any template comments (lines starting with ; TEMPLATE:) from the output.

gecs World setup

gecs v7.1.0 ships class_name World in addons/gecs/ecs/world.gd. The canonical scene-node pattern:

• Add a Node child to your gameplay scene with script = res://addons/gecs/ecs/world.gd, named World, with system_nodes_root = NodePath("Systems") and entity_nodes_root = NodePath("Entities").
• The main scene script wires it up: @onready var world: World = $World then ECS.world = world in _ready().
• Drive systems via world.process(delta, "gameplay") / world.process(delta, "physics") from _process / _physics_process.

Scaffold leaves the World node out — gameplay scene structure is filled in during /gm-build. See the gecs skill for the full World API.

Game Plan ECS stubs

If the Game Plan includes an ECS Architecture section with components and systems:

• Components: for each planned component (e.g., C_Velocity), create a file in src/components/ based on component.tmpl. Fill the class name and add @export vars from the plan.
• Systems: for each planned system (e.g., MovementSystem), create a file in src/systems/ based on system.tmpl. Fill the class name and query() with the required components.
• World: register systems by adding them as children of the gameplay scene's World node — see "gecs World setup" above for the full pattern.

Step 4 — Genre Adaptations

After writing base template files, apply genre-specific modifications to project.godot:

Platformer / Endless runner (gravity games):

• Add [physics] section: 2d/default_gravity=980.0
• Add [input] section with move + jump actions

Top-down:

• No [physics] section
• Add [input] section with 4-directional movement

For input action serialization format, read references/project_settings.md — it has the exact Object() syntax and key code table.

Step 5 — Post-Scaffold Steps

After all files are written, tell the user what to do next:

1. Deploy GodotMaker skills to the new project:

   bash <godotmaker_repo>/shell/publish.sh {{game_name}}/
   

   This copies skills to .claude/skills/, creates godotmaker.yaml (prompts for Godot executable path on first run), and creates .godotmaker/config.yaml with default project settings.

2. Install addons — pick the row matching your Godot version from the active runtime's config/addon_versions.json (the source of truth for repo, tag, and install path), then install addon-only directories:

   • gecs -> addons/gecs/
   • gdUnit4 -> addons/gdUnit4/
   • godot_e2e -> addons/godot_e2e/

   tools/check_project.py --e2e and the gm-* skills expect those exact paths (note gdUnit4/ is capital U — matches the upstream repo layout). See references/addons.md for the step-by-step installation contract.

3. Register godot-mcp for runtime debugging:

   claude mcp add godot -e GODOT_PATH="<godot_path>" -- npx @coding-solo/godot-mcp
   

4. Verify with headless-build: godot --headless --quit 2>&1

Report

After scaffold completes, output:

• Project path (absolute)
• File tree listing
• Checklist of pending post-scaffold steps

What This Skill Does NOT Do

• Does not implement game logic — only creates the starting structure
• Does not install addons — provides instructions in references/addons.md
• Does not run game-planner — expects a plan or minimal user input already
• Does not deploy skills — that is publish.sh's job