Installation and project setup

Use this guide to connect an SDK to a new or existing Godot project. Follow the artifact and tool prerequisites for your SDK release, then return to the usage guide for authoring, iteration and shipping.

Choose matching artifacts

For the Godot-first implementation:

1. Install the matching immutable SDK and editor add-on. Enable Gododin in Project Settings > Plugins in your existing game.
2. In the Gododin dock, select the SDK's bin/gododin and choose Connect this project to the selected SDK. The dock initializes/attaches the project, configures the current exact Godot executable and validates this machine. SDKs needing an external Odin compiler expose that selection in the dock.
3. Wait for the initial build to activate. Continue authoring in the same editor; subsequent normal openings reconnect automatically. Use Connection settings for relocation, or Use selected SDK release for deliberate same-engine lock adoption. No terminal command or hand-written local configuration is required for this path.
4. Install matching export templates through Godot's normal template manager and create a preset in Project > Export. Choose an architecture for which the project has native artifacts; a missing native toolchain is an export error.

The connection and tool paths are ignored per-machine state. Commit the project configuration and lock. SDK releases predating ADR 0070 retain their earlier launcher workflow; use a matching SDK/add-on publication for the new entry.

The remaining commands document advanced/manual setup and CI.

Obtain an immutable SDK archive, matching editor add-on and the Ripple Pond sources from the same source snapshot. The companion sealed first-CLI archive is needed for the advanced bootstrap example below. The SDK includes the managed Odin compiler; this path needs no separately installed Odin. Use the exact engine and native build tools named by its gododin.lock, with matching export templates when shipping. SDK packing and distribution belong to release tooling. A store add-on connects to an SDK you already have; it does not download one.

Use the active-target record and your SDK lock to select the exact Godot identity. The support policy and platform reconciliation own release availability and executed platform scope. The compiler and code-generation tools have their own minimum OS requirements; the game's deployment floor alone is insufficient for a development machine.

The manual configuration below uses the macOS arm64 layout. Fresh init emits the host platform's library suffix and target row. Windows/Linux setup requires that platform's matching SDK/toolchain records. Platform-specific procedures and retained execution records stay in the platform workstream.

Extract the SDK into a private, user-owned directory, preserving its read-only payload. Set these paths to your own locations:

sdk="/absolute/path/to/gododin-sdk"
project="/absolute/projects/ripple_pond"
pond_sources="/absolute/gododin-sources/examples/ripple_pond"
cli_archive="/absolute/downloads/<locked-first-cli-archive>.tar"

"$sdk/bin/gododin" sdk validate \
  --project-lock "$sdk/gododin.lock" --sdk-root "$sdk"

GODODIN_SDK_AUTHORITY_PASS confirms the lock, manifest, complete inventory, modes and CLI agree. Paths must be canonical absolute paths, without symlink components. The guide uses the same sdk and project variables.

Initialize a project

Choose one entry, then converge on the same local configuration.

New project: create an empty directory and initialize the scaffold:

mkdir -p "$project"
"$sdk/bin/gododin" init --project-root "$project" --project-key ripple_pond
game_dir="$project/live/project"

The root project.godot is a recovery shell. Your editable game is live/project/, the configured godot_project_root.

Existing game: point init at the directory containing its project.godot. To prepare the tutorial, first copy Ripple Pond's working GDScript before-state into a new directory:

mkdir -p "$project"
cp -R "$pond_sources/game/." "$project/"
"$sdk/bin/gododin" init --project-root "$project" --project-key ripple_pond
game_dir="$project"

For your own game, omit the copy and choose its existing root. Adoption adds Gododin-owned files, refuses collisions before writing, and preserves the game's scenes, scripts, assets, UIDs and settings. If you already have a .gitignore, add .gododin/ and .godot/ yourself, plus ols.json when it is generated by Gododin. Keep an intentionally user-owned OLS configuration under your own version-control policy. The project key is a stable lowercase name; do not change it casually after saving native classes.

If a matching store-shaped add-on is already installed, enable it in Project Settings → Plugins, select the SDK's bin/gododin in the Gododin dock, and choose Connect this project to the selected SDK. Connect invokes the same initializer using a key derived from the project directory. For this tutorial, name that directory ripple_pond. Connect also prepares this machine and enters the live editor workflow. Check connection revalidates the selected SDK. The manual configuration below is an alternative for automation.

Configure this machine once

Verify the companion CLI archive's checksum against the SDK lock's first_cli.prebuilt_gododin.distribution record before extraction. It supplies the authenticated cache entry used by first; the SDK's bin/gododin alone does not populate that cache.

mkdir -p -m 700 "$project/.gododin/first-cache" \
  "$project/.gododin/first-home" "$project/.gododin/first-tmp" \
  "$project/.gododin/godot-home"
tar -xf "$cli_archive" -C "$project/.gododin/first-cache"

Write ignored .gododin/local.toml, substituting your project's real paths and exact engine executable:

format = 1

[first_cli]
mode = "prebuilt_gododin"

[first_cli.prebuilt_gododin]
cache_root = "/absolute/projects/ripple_pond/.gododin/first-cache"
home_directory = "/absolute/projects/ripple_pond/.gododin/first-home"
temporary_directory = "/absolute/projects/ripple_pond/.gododin/first-tmp"

[godot]
home_directory = "/absolute/projects/ripple_pond/.gododin/godot-home"

[godot.executables]
godot_4_8_0_executable = "/absolute/Godot.app/Contents/MacOS/Godot"

All named directories must exist. Commit gododin.toml and gododin.lock; keep .gododin/ private. init already linked the SDK in ignored .gododin/authority.toml, so a newly initialized project needs no attach. Enter and diagnose the connection:

"$sdk/bin/gododin" first --project-root "$project"
"$sdk/bin/gododin" doctor --project-root "$project"

Expect one authenticated toolchain handoff and GODODIN_DOCTOR_PASS with matching engine/compiler/SDK identities. Tool resolution never searches PATH. If either refuses an artifact, correct the named input before building.

Prepare the Ripple Pond tutorial

For this new tutorial directory, replace the initializer's sample with the runnable native component and pure kernel. Remove only the two newly emitted subsystem samples so their package names do not conflict:

cp "$pond_sources/declarations/ripple_pond.odin" "$project/declarations/ripple_pond.odin"
rm "$project/subsystem/ripple_pond.odin" "$project/subsystem/ripple_pond_test.odin"
cp "$pond_sources/subsystem/"*.odin "$project/subsystem/"
cp "$pond_sources/main.gd" "$pond_sources/main.tscn" \
  "$pond_sources/gd_ripples.gd" "$game_dir/"
mkdir -p "$game_dir/tests"
cp "$pond_sources/tests/oracle.gd" "$game_dir/tests/"

For the fresh scaffold, also copy pond_sources/project.godot to game_dir/project.godot: it supplies this demonstration's window and Compatibility renderer settings. The existing before-state already has that same settings file. These replacement steps are for the tutorial copy; in your own game, wire a native node into your scene without replacing your game files.

Return to Getting started to open the game and observe the native result. Checkout compiler/authority setup and repository validation belong in the contributor/testing guide.

Configure editing and debugging

Your external editor supplies OLS and native debugger integration. Enable the existing [language_tools] section's enabled = true in gododin.toml, then run doctor. It derives ols.json with the authenticated Gododin collection and staged compiler paths. A user-owned ols.json is reported and preserved. Re-run doctor after SDK relocation to refresh derived paths. These optional tools do not enter the game's runtime/export dependencies.

Use a debug publication's native library and its matching symbols. Configure your debugger to map captured source paths back to your authored tree. The engine executable must also permit native debugger attachment. On macOS, hardened runtime and entitlements can prevent this: the debugger setup record records the engine preparation used in the exercised workflow. Re-signing an engine changes its identity; it must be admitted by the matching toolchain, not substituted silently for the locked executable.

Continue with Navigate and debug once your tools are configured.

Prepare export tools

Install the exact export templates selected by the SDK release in the configured Godot home. On macOS, the admitted template is the authenticated arm64-thinned macos.zip; the SDK lock must include its godot.runtime.macos_arm64_template_sha256. The upstream template archive's hash is a different identity and cannot substitute for it. Native linker/SDK identities must also match the lock.

The release's acquisition instructions own template preparation and platform-specific locations. Export reports a missing template or authority as a setup error; use a complete matching release rather than editing an immutable SDK. The documentation work's actual artifact checks and unexecuted steps are retained in the verification record.

Once the tools are configured, follow Shipping and updating.

Upgrade prerequisites

Select a new SDK for the same exact Godot target as your project before adopting its lock. If the release changes the companion CLI identity, populate the configured first-CLI cache with its matching sealed archive using the local configuration step.

The adoption check compares selected_target, a version triple; successive dev snapshots can share that triple. Check the tag, commit and reported runtime identity in the release locks before using this flow. A Godot/Odin target advance follows the version-policy transaction, including regeneration and affected verification. update --check belongs to the authority checkout, rather than installed-consumer SDK upgrades.