Install the SDK

You don't copy the SDK into your repository. Your project commits a small loader, and the loader asks the ase command line to install the SDK when you open the project in the editor. Everyone on the team gets the same SDK, and nobody commits its files.

Before you start

1. Install ase.
2. Sign in with ase login.
3. Have a game on Brain. A game you make with ase new-game comes with the loader and SDK already set up, so you can skip to the loader.

Add the SDK to an existing project

From the root of your engine project:

ase sdk install --game <game-id>

This downloads the SDK, installs it into the engine's SDK folder and wires it into the project. It is safe to run again: a second run changes nothing.

What you commit

Commit the loader and the project config. Keep the SDK itself ignored; ase sdk install writes the ignore rules for you.

ase sync keeps the loader files up to date. Don't edit them: the next sync replaces local changes.

Choose an SDK version

brain/project.toml holds your project's SDK policy. New projects track the newest release:

package_version = "latest"

To pin a release, install it by version. The pin is written to brain/project.toml, so the whole team gets the same one:

ase sdk install --version 1.4.0

To go back to tracking the newest release:

ase sdk update

What happens when you open the project

Each time the editor opens your project, the loader runs ase sdk ensure in the background and shows you its answer:

• No SDK on this machine yet. It installs at once. Restart the editor to load it.
• A newer release is out. A dialog offers it. Restart now and it installs, then reopens the project; choose later and it installs when you close the editor.
• Up to date. Nothing to show.

The loader never replaces an SDK the editor has loaded. Updates always wait for the editor to exit, and if one fails, the loader tells you the next time you open the project.

Offline and signed out

Once the SDK is installed, you can work offline and signed out. ase sdk ensure answers from what this machine already has: the installed SDK and the download cache. The loader logs a warning that it couldn't check for updates, and the SDK keeps working.

When the game can't run

Only two things stop the game from running:

• No SDK is installed on this machine, for example on a fresh clone while you're offline.
• The project pins a version that is neither installed nor in the download cache.

Then the editor shows a dialog and refuses to play the game until you fix it. The message says what to do: run ase login when you're signed out, or try again when ASE Brain can't be reached.

Edited SDK files

The SDK folder belongs to Brain. If you edit a file in it, Brain stops updating the SDK so it never overwrites your change, and the loader names the file. To get back to a clean SDK, delete the SDK folder and reopen the editor.

When the loader stays quiet

The loader skips:

• Headless and batch editors, and CI.
• Editors that ase editor starts, because ase editor prepares the SDK before it opens the project.
• Any editor started with ASE_SDK_LOADER=0 in its environment.

The loader finds ase through the ASE_CLI environment variable, then PATH, then the default install folders. If it can't find ase, it tells you to install it.

Engine notes

The loader is the editor plugin addons/ase_brain_loader. Keep it first in [editor_plugins] enabled in project.godot: on a fresh clone it installs the SDK before Godot loads the Brain plugin.

Keep Brain the first autoload too. Store captures seed your game's random numbers from it, so an autoload listed earlier that draws random numbers makes replays differ.

Scripts checked on their own with --check-only can't see autoloads. Use BrainApi.brain in place of Brain there: it is the same node, typed.

func _ready() -> void:
	BrainApi.brain.screen("title")

ase sdk ensure

Loaders call this command, and you can too, for example to check a project in a script:

ase sdk ensure --project .

It prints one line of JSON:

{"protocol":1,"status":"update_ready","installed":"1.4.0","available":"1.5.0","freshness":"verified","blocking":false,"code":null,"message":"Brain SDK 1.5.0 is ready. Restart the editor to install it.","apply_error":null}

ase sdk apply --wait-pid <pid> installs the waiting SDK once that editor process exits. Loaders start it for you.

Other SDK commands

See the ase sdk reference for every flag.