Gododin examples

Choose an example for the task you want to learn. Start with Ripple Pond for a small native component and the usage guide. Then try Cavern Lab for generation, background work and asset baking, or choose a more specialized example below.

In each project, Godot owns the scene, UI and presentation. A native Odin class connects it to ordinary Odin code that owns the computation and data. That subsystem has no Godot, Gododin or Raylib imports.

Prerequisites

The examples are installed-authority projects: they run through an extracted immutable Gododin SDK, not through this checkout's tree. Running one needs three machine-local inputs:

• an extracted immutable Gododin SDK — the <release>-macos-arm64-sdk directory from a release archive; releasing owns packing one from a fresh source checkout;
• the exact Odin compiler executable named by the SDK lock; and
• the exact active Godot executable named by the matching lock, whose identity each example's runner verifies. See the active-target record.

The shared setup script below documents the macOS SDK path. Individual examples also retain Windows development-host journeys; their READMEs name the actual executed scope. The platform record tracks the owner's Windows/Linux verification and its precise scope; general platform verification does not silently rerun these example workloads.

One-time setup

setup.sh wires every example in one step: it writes each example's ignored .gododin/local.toml from your three paths, authenticates the SDK against the example's committed lock (attach), and verifies the whole configuration with doctor:

examples/setup.sh \
  --sdk /absolute/extracted/<release>-macos-arm64-sdk \
  --odin /absolute/locked/Odin/odin \
  --godot /absolute/Godot.app/Contents/MacOS/Godot

# or wire a single example:
examples/setup.sh --sdk ... --odin ... --godot ... voxel_stream

Machine-local state lives only in each example's git-ignored .gododin/ directory. The three input paths may be relative to your working directory; setup.sh canonicalizes them before writing, because the CLI requires exact absolute paths in the stored configuration. If attach reports AUTHORITY_SDK_LOCK_MISMATCH, use a matching SDK or deliberately follow SDK upgrade/adoption; do not copy an arbitrary lock over the example's committed evidence identity. The setup guide's local configuration and attachment flow are the manual equivalents. setup.sh defaults to the seven names in its own source; select logistics_post explicitly for that eighth project. Its committed lock must match the SDK you choose.

Run

cd examples/bunny_mark
./test.sh          # subsystem tests, doctor, generate/check, accepted debug build
./test.sh play     # interactive run of that accepted build

Debug is the default profile. Most shared runners use the selected profile for both build and launch; Ripple Pond's runner limitation is explicit. For optimized native code in the shared runners, set GODODIN_PROFILE=release for the build and for every later launch; profiles keep separate acceptance caches, and the runner checks the publication's profile before launching:

GODODIN_PROFILE=release ./test.sh       # tests plus the accepted release build
GODODIN_PROFILE=release ./test.sh play  # interactive release run

The runner binds an accepted build to the current source and configured tools, so a configuration change (setup.sh, an SDK reseat, editing local.toml) intentionally invalidates acceptance: run ./test.sh once to re-establish it before play. Windowed launches also refuse while another Godot process is running.

./test.sh takes a mode argument, and the exact names differ per example (eval for offline measurement, run for the scripted windowed campaign, shot, probe, and so on). Each example's README is the authority for its modes, controls, and what its measurements do and do not establish. Cavern Lab predates the shared runner shape and is qualified through its own harnesses; see its build and run section.

Windowed runs pin the GL compatibility renderer because of the dev5 windowed Metal texture-free defect (GH-123394); upstream fixed that defect during dev6 and the dev6 compositor evidence passes windowed Forward+/Metal, but the example runners keep the pin until the example requalification batch reruns their windowed campaigns on the current target — do not override the flag, and run one Godot process at a time.

Development and evidence

Each README keeps its controls, source map and runnable commands separate from its recorded measurements. A timing or capture applies only to the workload, tools and host named by that record.

The integration plan records remaining showcase and gameplay work; Rewind is implemented through RL-3. The DevX completion plan orders the remaining packages and new examples.