# htdt/godogen architecture

> Architecture diagram of the GitHub repository htdt/godogen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/htdt/godogen
- Repository: https://github.com/htdt/godogen

## Overview

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`](https://github.com/htdt/godogen/blob/master/publish.sh) (publish.sh), [`shared/skills/godogen/visual-target.md`](https://github.com/htdt/godogen/blob/master/shared/skills/godogen/visual-target.md) (visual target), [`shared/skills/godogen`](https://github.com/htdt/godogen/tree/master/shared/skills/godogen) (godogen core), [`godot`](https://github.com/htdt/godogen/tree/master/godot) (Godot 4)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo shell"]
  node_publish_sh["publish.sh<br/>publish entrypoint<br/>[publish.sh]"]
  node_claude_md["CLAUDE.md<br/>agent packaging<br/>[CLAUDE.md]"]
  node_agents_md["AGENTS.md<br/>agent packaging<br/>[AGENTS.md]"]
end

subgraph group_shared["Shared core"]
  node_stop_gate["stop gate<br/>hook layer"]
  node_shared_godogen["godogen core<br/>shared pipeline"]
  node_asset_planner["asset planner<br/>stage<br/>[asset-planner.md]"]
  node_asset_gen["asset gen<br/>stage<br/>[asset-gen.md]"]
  node_visual_target["visual target<br/>stage<br/>[visual-target.md]"]
  node_rembg_tools["asset tools<br/>utility tools"]
end

subgraph group_godot["Godot branch"]
  node_godot_branch["Godot 4<br/>engine branch"]
  node_godot_api["godot api<br/>language guidance"]
  node_godot_capture["capture hook<br/>runtime proof<br/>[capture_result.sh]"]
end

subgraph group_bevy["Bevy branch"]
  node_bevy_branch["Bevy<br/>engine branch"]
  node_bevy_help["bevy help<br/>docs lookup"]
  node_bevy_capture["capture hook<br/>runtime proof<br/>[capture_result.sh]"]
end

subgraph group_babylon["Babylon branch"]
  node_babylon_branch["Babylon.js<br/>engine branch"]
  node_babylon_scaffold["scaffold"]
  node_babylon_capture["capture hook<br/>runtime proof<br/>[capture_result.sh]"]
  node_babylon_capture_script["capture script<br/>browser capture<br/>[capture.mjs]"]
end

subgraph group_ops["Publishing ops"]
  node_setup_md["setup.md<br/>ops guide<br/>[setup.md]"]
  node_setup_bevy_docs["setup_bevy_docs.sh<br/>docs setup<br/>[setup_bevy_docs.sh]"]
  node_scripts_publish["scripts/publish<br/>render tools"]
end

node_external_ai(("AI services<br/>external generation"))

node_publish_sh -->|"renders with"| node_scripts_publish
node_publish_sh -->|"packages"| node_claude_md
node_publish_sh -->|"packages"| node_agents_md
node_publish_sh -->|"targets"| node_godot_branch
node_publish_sh -->|"targets"| node_bevy_branch
node_publish_sh -->|"targets"| node_babylon_branch
node_setup_md -.->|"preps"| node_setup_bevy_docs
node_scripts_publish -.->|"merges"| node_stop_gate
node_shared_godogen -->|"contains"| node_asset_planner
node_shared_godogen -->|"contains"| node_asset_gen
node_shared_godogen -->|"contains"| node_visual_target
node_shared_godogen -->|"uses"| node_rembg_tools
node_asset_planner -.->|"requests inputs"| node_external_ai
node_asset_gen -.->|"calls services"| node_external_ai
node_visual_target -.->|"gates completion"| node_stop_gate
node_godot_branch -->|"guides"| node_godot_api
node_godot_branch -->|"captures"| node_godot_capture
node_bevy_branch -->|"uses"| node_bevy_help
node_bevy_branch -->|"captures"| node_bevy_capture
node_babylon_branch -->|"scaffolds"| node_babylon_scaffold
node_babylon_branch -->|"captures"| node_babylon_capture
node_babylon_scaffold -->|"drives"| node_babylon_capture_script
node_godot_capture -.->|"feeds back"| node_visual_target
node_bevy_capture -.->|"feeds back"| node_visual_target
node_babylon_capture -->|"invokes"| node_babylon_capture_script
node_babylon_capture -.->|"feeds back"| node_visual_target

click node_publish_sh "https://github.com/htdt/godogen/blob/master/publish.sh"
click node_claude_md "https://github.com/htdt/godogen/blob/master/CLAUDE.md"
click node_agents_md "https://github.com/htdt/godogen/blob/master/AGENTS.md"
click node_setup_md "https://github.com/htdt/godogen/blob/master/setup.md"
click node_setup_bevy_docs "https://github.com/htdt/godogen/blob/master/setup_bevy_docs.sh"
click node_scripts_publish "https://github.com/htdt/godogen/tree/master/scripts/publish"
click node_stop_gate "https://github.com/htdt/godogen/blob/master/shared/hooks/stop_post_task_gate.py"
click node_shared_godogen "https://github.com/htdt/godogen/tree/master/shared/skills/godogen"
click node_asset_planner "https://github.com/htdt/godogen/blob/master/shared/skills/godogen/asset-planner.md"
click node_asset_gen "https://github.com/htdt/godogen/blob/master/shared/skills/godogen/asset-gen.md"
click node_visual_target "https://github.com/htdt/godogen/blob/master/shared/skills/godogen/visual-target.md"
click node_rembg_tools "https://github.com/htdt/godogen/tree/master/shared/skills/godogen/tools"
click node_godot_branch "https://github.com/htdt/godogen/tree/master/godot"
click node_godot_api "https://github.com/htdt/godogen/tree/master/godot/skills/godot-api"
click node_godot_capture "https://github.com/htdt/godogen/blob/master/godot/hooks/capture_result.sh"
click node_bevy_branch "https://github.com/htdt/godogen/tree/master/bevy"
click node_bevy_help "https://github.com/htdt/godogen/tree/master/bevy/skills/bevy-help"
click node_bevy_capture "https://github.com/htdt/godogen/blob/master/bevy/hooks/capture_result.sh"
click node_babylon_branch "https://github.com/htdt/godogen/tree/master/babylon"
click node_babylon_scaffold "https://github.com/htdt/godogen/tree/master/babylon/scaffold"
click node_babylon_capture "https://github.com/htdt/godogen/blob/master/babylon/hooks/capture_result.sh"
click node_babylon_capture_script "https://github.com/htdt/godogen/blob/master/babylon/scaffold/scripts/capture.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_publish_sh,node_claude_md,node_agents_md toneBlue
class node_stop_gate,node_shared_godogen,node_asset_planner,node_asset_gen,node_visual_target,node_rembg_tools toneAmber
class node_godot_branch,node_godot_api,node_godot_capture toneMint
class node_bevy_branch,node_bevy_help,node_bevy_capture toneRose
class node_babylon_branch,node_babylon_scaffold,node_babylon_capture,node_babylon_capture_script toneIndigo
class node_setup_md,node_setup_bevy_docs,node_scripts_publish toneTeal
class node_external_ai toneNeutral
```

## Components

### Repo shell

Publish-time packaging, top-level instructions, and setup docs.

- [publish.sh](https://github.com/htdt/godogen/blob/master/publish.sh): publish entrypoint · Renders the selected engine and host-agent layout into a target game repo. · `publish.sh`
- [CLAUDE.md](https://github.com/htdt/godogen/blob/master/CLAUDE.md): agent packaging · Publish-time Claude Code instructions for the generated repo layout. · `CLAUDE.md`
- [AGENTS.md](https://github.com/htdt/godogen/blob/master/AGENTS.md): agent packaging · Publish-time Codex instructions for the generated repo layout. · `AGENTS.md`

### Shared core

Engine-agnostic generation stages, asset tooling, and task gates.

- [stop gate](https://github.com/htdt/godogen/blob/master/shared/hooks/stop_post_task_gate.py): hook layer · Common post-task gate used to control or post-process task completion. · `shared/hooks/stop_post_task_gate.py`
- [godogen core](https://github.com/htdt/godogen/tree/master/shared/skills/godogen): shared pipeline · Engine-agnostic planning, asset, and visual-target stages shared across engines. · `shared/skills/godogen`
- [asset planner](https://github.com/htdt/godogen/blob/master/shared/skills/godogen/asset-planner.md): stage · Plans required visual assets before engine-specific implementation begins. · `shared/skills/godogen/asset-planner.md`
- [asset gen](https://github.com/htdt/godogen/blob/master/shared/skills/godogen/asset-gen.md): stage · Coordinates external asset generation for textures, objects, and animations. · `shared/skills/godogen/asset-gen.md`
- [visual target](https://github.com/htdt/godogen/blob/master/shared/skills/godogen/visual-target.md): stage · Defines frame-grounded visual success criteria for capture-based iteration. · `shared/skills/godogen/visual-target.md`
- [asset tools](https://github.com/htdt/godogen/tree/master/shared/skills/godogen/tools): utility 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](https://github.com/htdt/godogen/tree/master/godot): engine branch · Godot-specific generation instructions, API guidance, and runtime capture. · `godot`
- [godot api](https://github.com/htdt/godogen/tree/master/godot/skills/godot-api): language guidance · GDScript and C# API guidance plus generated/normalized reference docs. · `godot/skills/godot-api`
- [capture hook](https://github.com/htdt/godogen/blob/master/godot/hooks/capture_result.sh): runtime proof · 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](https://github.com/htdt/godogen/tree/master/bevy): engine branch · Rust/Bevy generation instructions with deterministic capture-oriented workflows. · `bevy`
- [bevy help](https://github.com/htdt/godogen/tree/master/bevy/skills/bevy-help): docs lookup · Local docs lookup support used during Bevy agent runs. · `bevy/skills/bevy-help`
- [capture hook](https://github.com/htdt/godogen/blob/master/bevy/hooks/capture_result.sh): runtime proof · 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](https://github.com/htdt/godogen/tree/master/babylon): engine branch · Browser/WebGL2 generation branch built around a concrete TypeScript/Vite scaffold. · `babylon`
- [scaffold](https://github.com/htdt/godogen/tree/master/babylon/scaffold): game scaffold · Generated-project baseline with app entrypoints, game modules, assets, and Vite config. · `babylon/scaffold`
- [capture hook](https://github.com/htdt/godogen/blob/master/babylon/hooks/capture_result.sh): runtime proof · Browser capture path for screenshot/video evaluation in the Babylon branch. · `babylon/hooks/capture_result.sh`
- [capture script](https://github.com/htdt/godogen/blob/master/babylon/scaffold/scripts/capture.mjs): browser capture · Scaffold-side capture script that drives WebGL2 proof generation. · `babylon/scaffold/scripts/capture.mjs`

### Publishing ops

Transformation scripts and setup prerequisites.

- [setup.md](https://github.com/htdt/godogen/blob/master/setup.md): ops guide · Workspace prerequisites and dependency setup for the generator environment. · `setup.md`
- [setup_bevy_docs.sh](https://github.com/htdt/godogen/blob/master/setup_bevy_docs.sh): docs setup · One-time Bevy docs/cache preparation used by the Bevy help workflow. · `setup_bevy_docs.sh`
- [scripts/publish](https://github.com/htdt/godogen/tree/master/scripts/publish): render tools · Transformation utilities that render source materials into the target game repo. · `scripts/publish`

### Other components

- **AI services**: external generation · External model services used for references, textures, simple objects, and animation inputs.

## Connections

- 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.