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.projectcis 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(outsidebuild/,.internal/,node_modules/,.defold-types/and the folders.defignorelists) 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, sorunstops here even when a cached stock engine exists. - no engine — the
.projectcis present but no engine is:no engine for <platform>; run "bob run" to download and cache one. A plain project built withbob buildalone lands here, because onlybob runfetches 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 reportFORMAT_ERROR, sorunrefuses instead.bob runre-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=1280Only 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,
runprints 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-driftto 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.