htdt/godogen / skills/engine-guide
engine-guide
VerifiedBuilding on Godot 4 (C# or GDScript), Bevy, Babylon.js, three.js or HTML: which to choose, installing its toolchain, the project sketch, build commands, headless capture to screenshots and video, and the traps that fail silently. Use when starting or working on a game, a video made in an engine (presentation, explainer, trailer, product showcase), an interactive 3D or 2D page, or anything else built on one of these engines.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.0 KB |
| babylon.md | markdown | 2.8 KB |
| bevy.md | markdown | 4.0 KB |
| godot-gdscript.md | markdown | 6.5 KB |
| godot.md | markdown | 5.7 KB |
| html.md | markdown | 3.0 KB |
| setup.md | markdown | 3.0 KB |
| threejs.md | markdown | 3.7 KB |
godot.md
View on GitHub# Godot engine guide
Stack: **Godot 4 (.NET / Mono build)**, **C#**. All Godot C# classes must be `partial`.
## Project shape
- `project.godot` — config, input actions, display, physics. **Match version-sensitive fields to the installed toolchain** (`config_version`, and in `.csproj` the `Godot.NET.Sdk/...` version + `TargetFramework`) — run `godot --version` / `dotnet --version` and don't hardcode values from memory; on an existing project preserve them. For 3D, set `3d/physics_engine="Jolt Physics"` and a fixed `physics_ticks_per_second`.
- `{ProjectName}.csproj` — name must match `assembly_name`; `<EnableDynamicLoading>true</EnableDynamicLoading>`.
- `scripts/*.cs` runtime behavior · `scenes/*.tscn` scenes · `assets/` **only** files the running game loads (keep generation inputs/refs outside it).
- Build gate: `dotnet build`, then `godot --headless --import` after asset changes, then `godot --headless --quit` (RID-leak warnings on headless exit are benign).
## Scenes are generated at build time, not by hand
Write scenes as **C# `SceneTree` scripts** that run once headless and emit a `.tscn`: `godot --headless --script scenes/BuildX.cs`. A builder builds the node hierarchy, sets properties, attaches scripts, packs, and `Quit()`s — it contains **no** runtime logic (no `_Ready`/`_Process`, signals, or game state). Build **leaf scenes first**, parents after.
The serialization rules below are silent-failure — they pass compilation and drop nodes or bloat files only in the saved `.tscn`:
- **Owner chain:** every node must have `Owner` set to the scene root or it won't serialize. After building, walk the tree and set `child.Owner = root` on all descendants — but **do not recurse into instantiated GLB/`.tscn` nodes** (those have a non-empty `SceneFilePath`). Recursing into a GLB inlines all its meshes as text → 100MB+ `.tscn`.
- **Validate the pack:** count nodes before packing, `Instantiate()` the `PackedScene` after, and compare counts; gate `ResourceSaver.Save()` on the match. A silent drop otherwise looks like success.
- **`SetScript()` disposes the C# wrapper** — set scripts *last*, after the hierarchy is built. For the root, add it under a temp `Node`, set the script, then re-fetch it via `temp.GetChild(0)` before packing.
Sketch of the shared save path:
```csharp
void PackAndSave(Node root, string path) {
SetOwnerRecursive(root, root); // skip nodes with SceneFilePath set
int expected = CountNodes(root);
var packed = new PackedScene();
if (packed.Pack(root) != Error.Ok) { Quit(1); return; }
var test = packed.Instantiate(); int got = CountNodes(test); test.Free();
if (got < expected) { GD.PushError("nodes dropped"); Quit(1); return; } // serialization failed silently
ResourceSaver.Save(packed, path);
Quit(0);
}
```
GLB models: instantiate the `PackedScene`, measure the `MeshInstance3D` AABB to scale, and use a **primitive** collision shape (Box/Sphere/Capsule) from the AABB — never `CreateTrimeshShape()`/`CreateConvexShape()` on imported meshes (drops to <1 FPS).
## Quirks worth knowing (silent-failure)
Most Godot behavior the model already knows; these few fail with no error:
- **On macOS a fatal error hangs instead of exiting.** Godot reports it in an `NSAlert` modal that `--headless` can't dismiss, so the process idles at 0% CPU forever (a missing main scene does it too). Run every `godot` call under `timeout`; exit 124 is the failure. Output ending at `.NET: Initializing module...` means `GodotSharp/` wasn't found — `godot` on `PATH` is a symlink rather than a wrapper script.
- **`ArrayMesh.GenerateNormals()`** is required for a procedural mesh to *receive* shadows. Without it (or with `CullMode.Disabled` as a "safety net"), shadows silently vanish — fix winding instead.
- **MultiMeshInstance3D + GLB** loses the mesh on pack/save; use individual instances. `MaterialOverride` on GLB-internal nodes also won't serialize (owner is skipped) — use a procedural `ArrayMesh` when a custom material is needed.
- **Raycasts don't reliably hit `ConcavePolygonShape3D`** (trimesh) — use a shape query or sample terrain height analytically.
- **`.gdignore`** in a directory makes the importer skip it silently — only `screenshots/` should have one, never `assets/`.
- **C# enum names:** training data is GDScript-biased, so guessed C# enum names are often wrong (`BGMode.Sky`, not `BGModeEnum.Sky`). Verify against the installed Godot — read the C# API in the Godot docs/assemblies rather than guessing.
- Frame-rate-independent damping: `speed *= Mathf.Exp(-rate * delta)`, not `speed *= (1 - drag)` per tick.
## Capture
Video needs hardware **Vulkan** (Metal on macOS); software Vulkan (`llvmpipe`/`lavapipe`) is good for stills only. macOS has no `xvfb`, so capture runs in a real window there — adding `--headless` to `--write-movie` aborts (`Parameter "t" is null`).
Capture deterministically with Godot's movie writer from a dedicated capture `SceneTree` script under `test/`:
```bash
# under xvfb-run -a -s '-screen 0 1920x1080x24' on a headless Linux box; prefer the hardware Vulkan ICD
godot --headless --import
godot --write-movie screenshots/result/frame.png --fixed-fps 30 --quit-after 450 --script test/Presentation.cs
ffmpeg -y -framerate 30 -pattern_type glob -i 'screenshots/result/frame*.png' \
-c:v libx264 -pix_fmt yuv420p -movflags +faststart screenshots/result/video.mp4
```
`--fixed-fps` makes motion deterministic (450 frames @30fps = 15s). **Pre-position the camera** in the builder/`_Initialize` (the first movie frame renders before `_Process`). Drive capture-time input from the script, not live keys. The movie writer also records the scene's audio, in sync, to `frame.wav` beside the frames: add it as a second ffmpeg input when the video needs sound.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |