How to get ChatGPT, Claude, Gemini, and other AI to generate valid .raku games every time
The Raku engine supports two .raku file formats. Pick the one that matches your needs.
Declarative config — describe what you want, the engine figures out how.
Version key: "schema_version": "1.0"
Top-level: game, ai, entities, scenes, rendering, audio, xr, ai_disclosure
Schema: rakuai.com/schema.json
Examples: All standard samples →
Best for: quick game creation, beginners, most LLM tasks
Explicit API call sequences — every engine function call is specified in order.
Version key: "raku_format": "1.0.0"
Top-level: metadata, assets, initialization, setup, game_loop, ai_pipeline, shutdown
Reference: Runtime format reference card →
Example: void-wyrm.raku (290 lines) →
Best for: complex games, custom behavior trees, granular AI pipeline control
The rest of this page covers the Standard Format. For the runtime format, see the LLM Runtime Reference Card on GitHub.
LLMs will hallucinate a schema if you don't give them the real one. They'll invent fields like
settings, gameplay,
controls, and analytics
that don't exist in the Raku spec. The file will look like valid JSON, but it won't run.
We tested this: we asked ChatGPT to "create a .raku game file for a zombie survival game." It generated
150 lines of valid JSON with a completely made-up structure. The validator caught 2 errors and 2 warnings
including wrong version format ("1.0.0" instead of "1.0"), missing game
object, 6 hallucinated fields, and wrong ai_disclosure format.
Always point the AI at the schema URL: https://rakuai.com/schema.json. When LLMs can read the actual spec, they generate valid files on the first try. Always validate with the validator tool before playing.
Use these tested prompts in any AI assistant. They include the schema URL so the AI reads the real spec.
Copy one of the prompts above into ChatGPT, Claude, Gemini, or any LLM. Fill in your game description. The AI will output JSON.
Save the JSON output as a .raku file. Important: save as UTF-8 without BOM.
If using Windows Notepad, choose "Save As" → Encoding: "UTF-8" (not "UTF-8 with BOM").
If the AI wrapped it in ```json fences, remove those lines first.
Clone raku-public and run the validator:
If the validator reports errors, copy the output back into the AI using the "Iteration Prompt" above.
Or use --fix mode to auto-repair the most common issues.
Once you see PASS - Valid .raku file, double-click the file to play.
Download the runtime →
GPT-4 and GPT-4o read the schema URL reliably. Watch out for: markdown code fences in output (strip ```json lines), and occasionally inventing extra fields. Always include "output only raw JSON" in your prompt.
Claude Opus and Sonnet follow the schema precisely when given the URL. Supports MCP server integration for direct validation. Rarely adds markdown fences when told not to.
Gemini Pro reads schemas well. Best for iterative design across multi-turn conversations. May sometimes use "1.0.0" instead of "1.0" for schema_version.
Works well in VS Code with the schema as a reference file. Open schema.json in an adjacent tab and Copilot will use it for autocomplete in .raku files.
Common validator errors and how to fix them. Most can be auto-fixed with --fix.
The file is empty, has a BOM, or starts with markdown fences (```json).
Fix: Run python tools/validate-raku.py my-game.raku --fix to strip BOM and fences automatically.
LLMs love adding extra digits to version numbers.
Fix: Change "schema_version": "1.0.0" to "schema_version": "1.0". The --fix flag does this automatically.
The AI put title, genre, and template at the top level instead of inside a "game" object.
Fix: Wrap them in "game": { "title": "...", "genre": "...", "template": "..." }. The --fix flag does this automatically.
The AI invented fields like settings, gameplay, controls, ui, analytics, assets, or levels.
Fix: Delete these fields. The only valid top-level fields are: schema_version, game, ai, entities, scenes, rendering, audio, xr, ai_disclosure. The --fix flag removes them automatically.
The AI used fields like compliance, uses_player_data, data_tracked instead of the correct schema.
Fix: Replace the ai_disclosure section with: live_generated (bool), pre_generated (bool), description (string), systems (array). See the schema for valid system names.
Windows Notepad and PowerShell's Set-Content -Encoding UTF8 add invisible BOM bytes.
Fix: Use --fix or in PowerShell: [IO.File]::WriteAllText("$PWD\file.raku", (Get-Content file.raku -Raw), [Text.UTF8Encoding]::new($false))
The complete structure of a valid .raku file. Full schema →