How htdt/godogen works
1. Repository purpose
- This is not a game project; it is a game-generator source repo.
- The system’s output is a fresh game repo, produced by publishing the appropriate skills and instructions for a target engine and host agent.
2. Top-level architecture
- The repo is organized primarily by engine: godot/, bevy/, babylon/.
- A fourth layer, shared/, holds engine-agnostic generation stages, tooling, and common behavior.
- The root publish.sh renders the right runtime/layout for the selected engine and agent flavor.
3. Generation pipeline
- The core flow is: user describes a game → agent plans it → writes code → generates assets → runs engine → captures screenshots/video → judges visual output → repairs defects.
- The important architectural boundary is between the generator source repo and the generated game repo; the generator publishes instructions, not the final game.
4. Shared subsystem
- shared/skills/godogen/ contains cross-engine stages such as asset planning, asset generation, visual targeting, and tooling wrappers.
- shared/hooks/stop_post_task_gate.py is a common stop-hook layer used to gate or post-process task completion.
- shared/skills/godogen/tools/ includes reusable asset utilities such as background removal, sprite slicing, loop-frame detection, and 3D/asset generation adapters.
5. Godot-specific subsystem
- godot/ contains Godot 4–specific generation instructions and tooling.
- godot/skills/godot-api/ provides language/API guidance for both GDScript and C#, with tooling to generate or normalize API docs.
- godot/hooks/capture_result.sh supports screenshot/video capture and evaluation in the Godot runtime.
- The README emphasizes that Godot output is a real C#/.NET project with scene trees, scene builders, and organized assets.
6. Bevy-specific subsystem
- bevy/ provides Rust/Bevy-specific generation instructions and capture helpers.
- bevy/skills/bevy-help/ includes local docs lookup support, which matters because Bevy generation depends on accessible rustdoc/docs during agent runs.
- The Bevy pipeline is optimized for code-first scenes and deterministic proof/capture bundles.
7. Babylon.js-specific subsystem
- babylon/scaffold/ is a concrete TypeScript/Vite game scaffold used as the generated project baseline.
- It contains the browser app entrypoints, game state/input/scene modules, assets folders, styling, and Vite/TS configuration.
- babylon/hooks/capture_result.sh and babylon/scaffold/scripts/capture.mjs support browser-based WebGL2 capture and screenshot/video proof.
- This branch is explicitly oriented around hot reload and static web builds.
8. Host-agent dimension
- The repo supports two host-agent flavors: Claude Code and Codex.
- That choice is a publish-time rendering concern, not a separate source tree.
- The publishing process emits the right top-level instructions/files for the selected host agent, such as CLAUDE.md or AGENTS.md and corresponding skill layouts.
9. Skill packaging
- The skills/ directories under each engine are the main delivery mechanism: they define how the agent should reason, scaffold, generate, test, and repair within that engine.
- babylon-help, bevy-help, godot-api, and the various godogen folders are not application code; they are agent-facing operational knowledge.
10. Asset generation boundary
- Asset creation is treated as a distinct pipeline from game logic.
- The repo integrates external model/image/video generation services via tools and prompts: Gemini, xAI Grok, and Tripo3D are used for references, textures, simple objects, animations, and 3D conversion.
- This is a key architectural boundary because visual asset production is handled separately from engine-specific game code.
11. Capture and self-repair loop
- The repo is built around frame-grounded evaluation: agents are instructed to judge progress from captured screenshots/video, not from successful compilation alone.
- Capture hooks feed back proof artifacts so visible defects drive the next iteration.
- This loop is central to the architecture because it connects code generation, rendering, and correction.
12. Publishing and transformation scripts
- scripts/publish/ contains the transformation utilities used by publish.sh to render source material into a target game repo.
- Files like generate_codex_metadata.py, render_dir.py, and the frontmatter/hook merge scripts indicate that publishing is a structured doc/render pipeline rather than a simple file copy.
13. Operational and setup layer
- setup.md and setup_bevy_docs.sh define workstation prerequisites and one-time setup for dependencies and docs caches.
- The repo assumes engine toolchains, Python tooling, browser capture capability, and external API keys; these are operational dependencies that materially affect how the architecture runs.
14. What an architecture diagram should show
- Show a central publish/render pipeline feeding three engine-specific branches plus a shared core.
- Show capture/proof hooks looping engine output back into the agent for repair.
- Show asset-generation services as external integrations.
- Show Claude/Codex packaging as a publish-time variant of the same source tree, not a separate product line.
Main entry points: publish.sh publish.sh · visual-target.md visual target · godogen godogen core · godot Godot 4
Components 23
Repo shell
Publish-time packaging, top-level instructions, and setup docs.
- publish.sh · Renders the selected engine and host-agent layout into a target game repo.
publish.sh - CLAUDE.md · Publish-time Claude Code instructions for the generated repo layout.
CLAUDE.md - AGENTS.md · Publish-time Codex instructions for the generated repo layout.
AGENTS.md
Shared core
Engine-agnostic generation stages, asset tooling, and task gates.
- stop gate · Common post-task gate used to control or post-process task completion.
shared/hooks/stop_post_task_gate.py - godogen core · Engine-agnostic planning, asset, and visual-target stages shared across engines.
shared/skills/godogen - asset planner · Plans required visual assets before engine-specific implementation begins.
shared/skills/godogen/asset-planner.md - asset gen · Coordinates external asset generation for textures, objects, and animations.
shared/skills/godogen/asset-gen.md - visual target · Defines frame-grounded visual success criteria for capture-based iteration.
shared/skills/godogen/visual-target.md - asset tools · Reusable helpers for background removal, slicing, loop detection, and 3D adapters.
shared/skills/godogen/tools
Godot branch
Godot 4 generation guidance, hooks, and API knowledge.
- Godot 4 · Godot-specific generation instructions, API guidance, and runtime capture.
godot - godot api · GDScript and C# API guidance plus generated/normalized reference docs.
godot/skills/godot-api - capture hook · Captures screenshots/video from Godot for evaluation and repair loops.
godot/hooks/capture_result.sh
Bevy branch
Rust/Bevy generation guidance and local docs support.
- Bevy · Rust/Bevy generation instructions with deterministic capture-oriented workflows.
bevy - bevy help · Local docs lookup support used during Bevy agent runs.
bevy/skills/bevy-help - capture hook · Captures proof artifacts from the Bevy runtime for the repair loop.
bevy/hooks/capture_result.sh
Babylon branch
TypeScript/Vite scaffold and browser capture flow.
- Babylon.js · Browser/WebGL2 generation branch built around a concrete TypeScript/Vite scaffold.
babylon - scaffold · Generated-project baseline with app entrypoints, game modules, assets, and Vite config.
babylon/scaffold - capture hook · Browser capture path for screenshot/video evaluation in the Babylon branch.
babylon/hooks/capture_result.sh - capture script · Scaffold-side capture script that drives WebGL2 proof generation.
babylon/scaffold/scripts/capture.mjs
Publishing ops
Transformation scripts and setup prerequisites.
- setup.md · Workspace prerequisites and dependency setup for the generator environment.
setup.md - setup_bevy_docs.sh · One-time Bevy docs/cache preparation used by the Bevy help workflow.
setup_bevy_docs.sh - scripts/publish · Transformation utilities that render source materials into the target game repo.
scripts/publish
Other components
- AI services · External model services used for references, textures, simple objects, and animation inputs.
Connections 26
- publish.sh → scripts/publish: renders with · Publish orchestrates the transformation utilities to materialize the target repo.
- publish.sh → CLAUDE.md: packages · Emits Claude Code-facing instructions when selected at publish time.
- publish.sh → AGENTS.md: packages · Emits Codex-facing instructions when selected at publish time.
- publish.sh → Godot 4: targets · Can render the Godot branch layout and instructions.
- publish.sh → Bevy: targets · Can render the Bevy branch layout and instructions.
- publish.sh → Babylon.js: targets · Can render the Babylon branch layout and instructions.
- setup.md → setup_bevy_docs.sh: preps · Captures workstation and docs-cache setup for engine workflows.
- scripts/publish → stop gate: merges · Publishing can inject or merge stop-hook behavior into the rendered output.
- godogen core → asset planner: contains · Shared core begins with asset planning.
- godogen core → asset gen: contains · Shared core includes external asset generation orchestration.
- godogen core → visual target: contains · Shared core defines visual success criteria and iteration targets.
- godogen core → asset tools: uses · Shared pipeline relies on reusable asset-processing utilities.
- asset planner → AI services: requests inputs · Planning stage pulls in model-assisted references and asset specs.
- asset gen → AI services: calls services · Asset generation integrates external image/video/3D generation services.
- visual target → stop gate: gates completion · Frame-grounded evaluation can hold task completion until proof is acceptable.
- Godot 4 → godot api: guides · Godot generation is anchored by GDScript/C# API guidance.
- Godot 4 → capture hook: captures · Godot runtime proof flows through the capture hook.
- Bevy → bevy help: uses · Bevy generation depends on local docs lookup support.
- Bevy → capture hook: captures · Bevy runtime proof feeds the visual repair loop.
- Babylon.js → scaffold: scaffolds · Babylon generation starts from the concrete TypeScript/Vite scaffold.
- Babylon.js → capture hook: captures · Babylon runtime proof is collected through the browser capture hook.
- scaffold → capture script: drives · The scaffold includes the browser capture script used for proof artifacts.
- capture hook → visual target: feeds back · Captured Godot proof is compared against visual targets for repairs.
- capture hook → visual target: feeds back · Captured Bevy proof is compared against visual targets for repairs.
- capture hook → capture script: invokes · Browser capture hook delegates to the scaffold capture script.
- capture hook → visual target: feeds back · Captured Babylon proof is used to judge and repair visible defects.