setup-engine

name	setup-engine
description	Configure the project's game engine and version. Pins the engine in CLAUDE.md, detects knowledge gaps, and populates engine reference docs via WebSearch when the version is beyond the LLM's training data.

Setup Engine

This is the Codex-adapted version of the original workflow. Use only .codex/ runtime assets when following it.

Arguments: [engine version] or no args for guided selection

When this skill is invoked:

1. Parse Arguments

Three modes:

• Full spec: ``setup-engine godot 4.6 — engine and version provided
• Engine only: ``setup-engine unity — engine provided, version will be looked up
• No args: setup-engine — fully guided mode (engine recommendation + version)

---

2. Guided Mode (No Arguments)

If no engine is specified, run an interactive engine selection process:

Check for existing game concept

• Read design/gdd/game-concept.md if it exists — extract genre, scope, platform targets, art style, team size, and any engine recommendation from brainstorm
• If no concept exists, inform the user:

  "No game concept found. Consider running brainstorm first to discover what you want to build — it will also recommend an engine. Or tell me about your game and I can help you pick."

If the user wants to pick without a concept, ask:

1. What kind of game? (2D, 3D, or both?)
2. What platforms? (PC, mobile, console, web?)
3. Team size and experience? (solo beginner, solo experienced, small team?)
4. Any strong language preferences? (GDScript, C#, C++, visual scripting?)
5. Budget for engine licensing? (free only, or commercial licenses OK?)

Produce a recommendation

Use this decision matrix:

Factor	Godot 4	Unity	Unreal Engine 5
Best for	2D games, small 3D, solo/small teams	Mobile, mid-scope 3D, cross-platform	AAA 3D, photorealism, large teams
Language	GDScript (+ C#, C++ via extensions)	C#	C++ / Blueprint
Cost	Free, MIT license	Free under revenue threshold	Free under revenue threshold, 5% royalty
Learning curve	Gentle	Moderate	Steep
2D support	Excellent (native)	Good (but 3D-first engine)	Possible but not ideal
3D quality ceiling	Good (improving rapidly)	Very good	Best-in-class
Web export	Yes (native)	Yes (limited)	No
Console export	Via third-party	Yes (with license)	Yes
Open source	Yes	No	Source available

Present the top 1-2 recommendations with reasoning tied to the user's answers. Let the user choose — never force a recommendation.

---

3. Look Up Current Version

Once the engine is chosen:

• If version was provided, use it
• If no version provided, use WebSearch to find the latest stable release:
  • Search: "[engine] latest stable version [current year]"
  • Confirm with the user: "The latest stable [engine] is [version]. Use this?"

---

4. Update .codex/docs/project-instructions.md Technology Stack

Read .codex/docs/project-instructions.md and update the Technology Stack section. Replace the [CHOOSE] placeholders with the actual values:

For Godot:

- **Engine**: Godot [version]
- **Language**: GDScript (primary), C++ via GDExtension (performance-critical)
- **Build System**: SCons (engine), Godot Export Templates
- **Asset Pipeline**: Godot Import System + custom resource pipeline

For Unity:

- **Engine**: Unity [version]
- **Language**: C#
- **Build System**: Unity Build Pipeline
- **Asset Pipeline**: Unity Asset Import Pipeline + Addressables

For Unreal:

- **Engine**: Unreal Engine [version]
- **Language**: C++ (primary), Blueprint (gameplay prototyping)
- **Build System**: Unreal Build Tool (UBT)
- **Asset Pipeline**: Unreal Content Pipeline

---

5. Populate Technical Preferences

After updating .codex/docs/project-instructions.md, create or update .codex/docs/reference/technical-preferences.md with engine-appropriate defaults. Read the existing template first, then fill in:

Engine & Language Section

• Fill from the engine choice made in step 4

Naming Conventions (engine defaults)

For Godot (GDScript):

• Classes: PascalCase (e.g., PlayerController)
• Variables/functions: snake_case (e.g., move_speed)
• Signals: snake_case past tense (e.g., health_changed)
• Files: snake_case matching class (e.g., player_controller.gd)
• Scenes: PascalCase matching root node (e.g., PlayerController.tscn)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_HEALTH)

For Unity (C#):

• Classes: PascalCase (e.g., PlayerController)
• Public fields/properties: PascalCase (e.g., MoveSpeed)
• Private fields: _camelCase (e.g., _moveSpeed)
• Methods: PascalCase (e.g., TakeDamage())
• Files: PascalCase matching class (e.g., PlayerController.cs)
• Constants: PascalCase or UPPER_SNAKE_CASE

For Unreal (C++):

• Classes: Prefixed PascalCase (A for Actor, U for UObject, F for struct)
• Variables: PascalCase (e.g., MoveSpeed)
• Functions: PascalCase (e.g., TakeDamage())
• Booleans: b prefix (e.g., bIsAlive)
• Files: Match class without prefix (e.g., PlayerController.h)

Remaining Sections

• Performance Budgets: Leave as [TO BE CONFIGURED] with a suggestion:

  "Typical targets: 60fps / 16.6ms frame budget. Want to set these now?"

• Testing: Suggest engine-appropriate framework (GUT for Godot, NUnit for Unity, etc.)
• Forbidden Patterns / Allowed Libraries: Leave as placeholder

Collaborative Step

Present the filled-in preferences to the user:

"Here are the default technical preferences for [engine]. Want to customize any of these, or shall I save the defaults?"

Wait for approval before writing the file.

---

6. Determine Knowledge Gap

Check whether the engine version is likely beyond the LLM's training data.

Known approximate coverage (update this as models change):

• LLM knowledge cutoff: May 2025
• Godot: training data likely covers up to ~4.3
• Unity: training data likely covers up to ~2023.x / early 6000.x
• Unreal: training data likely covers up to ~5.3 / early 5.4

Compare the user's chosen version against these baselines:

• Within training data → LOW RISK — reference docs optional but recommended
• Near the edge → MEDIUM RISK — reference docs recommended
• Beyond training data → HIGH RISK — reference docs required

Inform the user which category they're in and why.

---

7. Populate Engine Reference Docs

If WITHIN training data (LOW RISK):

Create a minimal .codex/knowledge/engine-reference/<engine>/VERSION.md:

# [Engine] — Version Reference

| Field | Value |
|-------|-------|
| **Engine Version** | [version] |
| **Project Pinned** | [today's date] |
| **LLM Knowledge Cutoff** | May 2025 |
| **Risk Level** | LOW — version is within LLM training data |

## Note

This engine version is within the LLM's training data. Engine reference
docs are optional but can be added later if agents suggest incorrect APIs.

Run ``setup-engine` refresh` to populate full reference docs at any time.

Do NOT create breaking-changes.md, deprecated-apis.md, etc. — they would add context cost with minimal value.

If BEYOND training data (MEDIUM or HIGH RISK):

Create the full reference doc set by searching the web:

1. Search for the official migration/upgrade guide:

   • "[engine] [old version] to [new version] migration guide"
   • "[engine] [version] breaking changes"
   • "[engine] [version] changelog"
   • "[engine] [version] deprecated API"

2. Fetch and extract from official documentation:

   • Breaking changes between each version from the training cutoff to current
   • Deprecated APIs with replacements
   • New features and best practices

3. Create the full reference directory:

   .codex/knowledge/engine-reference/<engine>/
   ├── VERSION.md              # Version pin + knowledge gap analysis
   ├── breaking-changes.md     # Version-by-version breaking changes
   ├── deprecated-apis.md      # "Don't use X → Use Y" tables
   ├── current-best-practices.md  # New practices since training cutoff
   └── modules/                # Per-subsystem references (create as needed)
   

4. Populate each file using real data from the web searches, following the format established in existing reference docs. Every file must have a "Last verified: [date]" header.

5. For module files: Only create modules for subsystems where significant changes occurred. Don't create empty or minimal module files.

---

8. Update .codex/docs/project-instructions.md Import

Update the @ import under "Engine Version Reference" to point to the correct engine:

## Engine Version Reference

@.codex/knowledge/engine-reference/<engine>/VERSION.md

If the previous import pointed to a different engine (e.g., switching from Godot to Unity), update it.

---

9. Update Agent Instructions

For the chosen engine's specialist agents, verify they have a "Version Awareness" section. If not, add one following the pattern in the existing Godot specialist agents.

The section should instruct the agent to:

1. Read .codex/knowledge/engine-reference/<engine>/VERSION.md
2. Check deprecated APIs before suggesting code
3. Check breaking changes for relevant version transitions
4. Use WebSearch to verify uncertain APIs

---

10. Refresh Subcommand

If invoked as ``setup-engine refresh:

1. Read the existing .codex/knowledge/engine-reference/<engine>/VERSION.md to get the current engine and version
2. Use WebSearch to check for:
   • New engine releases since last verification
   • Updated migration guides
   • Newly deprecated APIs
3. Update all reference docs with new findings
4. Update "Last verified" dates on all modified files
5. Report what changed

---

11. Output Summary

After setup is complete, output:

Engine Setup Complete
=====================
Engine:          [name] [version]
Knowledge Risk:  [LOW/MEDIUM/HIGH]
Reference Docs:  [created/skipped]
.codex/docs/project-instructions.md:       [updated]
Tech Prefs:      [created/updated]
Agent Config:    [verified]

Next Steps:
1. Review .codex/knowledge/engine-reference/<engine>/VERSION.md
2. [If from `brainstorm`] Run `map-systems` to decompose your concept into individual systems
3. [If from `brainstorm`] Run `design-system` to author per-system GDDs (guided, section-by-section)
4. [If from `brainstorm`] Run `prototype` [core-mechanic] to test the core loop
5. [If fresh start] Run `brainstorm` to discover your game concept
6. Create your first milestone: `sprint-plan` new

---

Guardrails

• NEVER guess an engine version — always verify via WebSearch or user confirmation
• NEVER overwrite existing reference docs without asking — append or update
• If reference docs already exist for a different engine, ask before replacing
• Always show the user what you're about to change before making .codex/docs/project-instructions.md edits
• If WebSearch returns ambiguous results, show the user and let them decide