Bob
bob is Defold's own headless build tool — the bob.jar the editor uses under
the hood. This command downloads and caches a sha-keyed bob.jar, resolves
a Java runtime, and invokes java -jar bob.jar <args> for you, so you can build,
bundle, and launch a Defold project entirely from the command line — no editor.
bunx @defold-typescript/cli bob <resolve|build|bundle|status|run> [path]The subcommand is the first positional; the optional project directory [path]
is bob's second positional (after the subcommand), defaulting to the current
directory. This is the transpile-free counterpart to build,
which turns your TypeScript into Lua — you typically build first,
then bob build to compile the Defold project.
Subcommands
resolve— fetch the project's Defold library dependencies (the editor's Fetch Libraries), so a native-extension or library build has its sources. To stop a CI build whose libraries differ from your lockfile, see Dependency safety.build— compile the project. It forces--variant debug, so output lands inbuild/default, matching the debug engine thatrunandbob runlaunch.bundle— produce a platform bundle (an app/executable for a target).status— a read-only pre-flight. It reports the resolved target head (version, channel, sha), the cachedbob.jarpath (and whether it is cached), and the resolved Java. Resolving a channel head may fetch target metadata, but it never downloadsbob.jaror launches Bob. Use it to confirm what a build would do.run— a composite (bob itself has no native run verb): debug-build, ensure a target-matched engine, then launch. See below.
bob run — build then launch
bob run chains a debug build and a launch, all pinned to one resolved SHA so
bob, your typings, and the running engine agree:
- download the target-matched
bob.jar, - debug-build into
build/default, - ensure an engine for the resolved SHA — a native-extension build already
produced
build/<platform>/dmengine, so it launches that; a plain project has no build engine, sobob runfetches the stock engine into the engine cache and records it, so a laterrunreuses it, - launch the game.
A failed build short-circuits with Bob's exit code and never launches. A
project with an ext.manifest outside its ignored folders and no build engine
stops with an error instead of fetching the stock engine, which cannot run the
extension. Once build/default and an engine exist, run
relaunches directly — no rebuild, no Bob, no download.
A successful bob build records the Defold head it compiled with beside the
compiled tree. On the stock-engine lane bob run records the same head beside
the engine it caches, and re-running it rewrites both — which is how a
run refusal over a mismatched pair is cleared. A native-extension
build needs no such record: its engine is co-produced with its data, so it is
exempt from the check rather than refreshed by it. An engine cached before the
toolchain recorded heads keeps working, and the first bob run replaces it with
a recorded one.
The bob.jar cache
The first run downloads a bob.jar into a cache directory and reuses it
afterward (offline after the first fetch). The cache root is
$DEFOLD_TYPESCRIPT_CACHE/bob when set, otherwise
$XDG_CACHE_HOME/defold-typescript/bob, falling back to
~/.cache/defold-typescript/bob.
The jar is keyed by the resolved --defold-target: a pinned version
resolves to that version's artifact SHA, a channel (stable/beta/alpha)
resolves to the channel head. Under --json the result reports the resolved
defoldVersion, defoldChannel (null for a pinned version), and defoldSha,
so you can confirm which engine build bob ran against. status reports the same
head without touching the network's download path.
Java resolution
bob needs a JVM. It resolves one in order:
- the
--java <path>flag, or theDEFOLD_JAVAenvironment variable, javaon yourPATH,- the JDK bundled inside an installed Defold editor — the same locations the
version probe reads, so
DEFOLD_TYPESCRIPT_EDITORpoints this lane at a non-standard install too (seepinning-defold-target).
If none resolve, the command errors and names all three. status resolves Java
the same way — honoring --java / DEFOLD_JAVA before PATH and the bundled
JDK — but reports Java as (not found) rather than failing when nothing
resolves.
Flags
-
--java <path>— the Java override (see above);DEFOLD_JAVAis the environment-variable form. -
--build-server <url>— a native-extension build server, threaded through to bob forresolve/build/bundleand the build phase ofbob run. -
--json— emit one machine-readable object per run, shaped per subcommand:resolve/build/bundle— the resolved head fields plus a top-levelexitCode.status— the head fields plusbobJarandjava, with noexitCode(a pre-flight runs nothing to exit).run— nestedbuildandlaunchobjects, with no top-levelexitCode.
See Agent runbooks.
-
target selection — the resolved Defold version/channel comes from your project's pin (see Pinning the Defold target).
Exit codes
Bob's exit code is the command's exit code: a failed bob build fails the
command, and bob run short-circuits on a failed build with that same code
before it ever launches.
The one exception is --fail-on-drift on bob build/bundle/run, which
fails an otherwise-successful command when the detected editor has drifted from
the pin, or the pin names a version the toolchain cannot provide (see
Pinning the Defold target). It only
ever replaces a success — a non-zero Bob or engine code is still reported as-is.