Skip to Content
defold-typescript
Get startedGuidesAPILibraries
CLI

Run

run launches a project you already compiled — the Runnable (an engine executable plus a build/default/game.projectc) left in the tree by a prior build step. A plain project needs bob run, which fetches and records a stock engine for the resolved SHA; a native-extension build already supplies build/<platform>/dmengine, so bob build alone is enough there. run does no transpile, runs no Bob, and downloads nothing: it finds the engine, launches it, and streams the game to your terminal.

bunx @defold-typescript/cli run                  # launch ./build/default
bunx @defold-typescript/cli run path/to/project  # launch a project in another folder
bunx @defold-typescript/cli run -- --verbose     # forward engine args after --

The optional [path] is the project directory; it defaults to the current directory. When the tree is not launchable, run reports one of four distinct resolver errors and exits 1 without launching:

  • no compiled project — build/default/game.projectc is missing: no compiled project at build/default; run "bob build" (or "bob run") first.
  • no build engine for a native extension — the project holds an ext.manifest (outside build/, .internal/, node_modules/, .defold-types/ and the folders .defignore lists) but no build engine: <folder>/ext.manifest declares a native extension, but there is no build engine at build/<platform>/dmengine, and the stock engine cannot run it. The stock engine has no extension code, so run stops here even when a cached stock engine exists.
  • no engine — the .projectc is present but no engine is: no engine for <platform>; run "bob run" to download and cache one. A plain project built with bob build alone lands here, because only bob run fetches and caches the stock engine.
  • version disagreement — both are present, both record the Defold version they were produced at, and the two disagree: build/default was compiled by Defold <build> but the cached engine is <engine>; run "bob run" to refresh the engine for the current target. Bumping your pin and rebuilding leaves the previously cached engine behind; launching that pair makes Defold report FORMAT_ERROR, so run refuses instead. bob run re-fetches the engine for the current head and clears it.

Two lanes pass the version check without being examined. An engine cached before the toolchain recorded versions is a bare path with nothing to compare, so it stays launchable; the first bob run replaces it with an identified marker the check reads from then on. A native-extension build/<platform>/dmengine is produced by the same bob build as the data beside it, so run launches it without consulting either marker.

What it launches

run resolves the engine the same way bob run records it: the native-extension build engine (build/<platform>/dmengine) when a native build produced one, otherwise the stock engine that a prior bob run fetched and cached for the resolved SHA. Either way it points the engine at build/default/game.projectc. On macOS the build folder is bob's <arch>-osx (build/arm64-osx/dmengine), not the <arch>-macos name the stock engine download uses. A project with an ext.manifest and no build engine stops with an error instead of launching the stock engine.

The game streams live to your terminal. The engine's exit code becomes the command's exit code, so a crash or a non-zero quit propagates to whatever ran run. Ctrl-C (SIGINT/SIGTERM) forwards to the engine so it shuts down cleanly rather than being orphaned.

Forwarding engine arguments

Everything after -- passes through to the launched engine untouched:

bunx @defold-typescript/cli run -- --verbose
bunx @defold-typescript/cli run path/to/project -- --config=display.width=1280

Only the tokens before -- are the command's own (the project path); the rest are the engine's.

Stderr notices

Before launching, run writes any advisories to stderr:

  • runnable warnings — surfaced from resolving the engine and project (for example a stale or mismatched build artifact).
  • installed-editor pin-drift notice — when the Defold editor installed on this machine differs from the version your project pins, run prints a one-line heads-up (the same notice the everyday commands share). A pin naming a version the toolchain cannot provide is reported the same way. Both are advisory by default and never change the exit code; pass --fail-on-drift to make either exit non-zero instead. The notice text is identical either way, and the engine's own exit code always wins — escalation turns a clean run into a failure, never a failing run into a different failure.

--json

run accepts --json for agents and scripts. A running game cannot be captured, so the game still streams live to the terminal; a single envelope prints on exit:

{ "command": "run", "ok": true, "enginePath": "build/arm64-osx/dmengine", "projectc": "build/default/game.projectc", "exitCode": 0 }

The envelope carries enginePath, projectc, and exitCode, plus a warnings array and a pinMismatch object when either is present (the drift notice folds into warnings here instead of stderr). See Agent runbooks.

The everyday commands carry no version tag: inside an installed project bunx resolves the @defold-typescript/cli that init pinned, so run uses the version locked alongside your @defold-typescript/types.

On this page