CLI

Build and run

Compile, run, watch, and check a BornEngine game for your computer or for another target.

Four commands take your game’s entry file, usually main.ts. build compiles an optimized executable. run compiles a fast development build and starts it. dev does the same as run, and with --watch it restarts the game when your files change. check asks Perry whether your code can be compiled, without producing a binary. All four call Perry and work inside a BornEngine project.

shell
bornengine build main.ts --name my-game --os linux
bornengine run main.ts
bornengine dev main.ts --watch
bornengine run main.ts --release --jobs 4
bornengine check main.ts --target web

--name, or -n, sets the output name. --os, or -o, selects a friendly target name. --target selects an exact Perry target. --jobs limits parallel Cargo jobs. The command reference at the end of this page lists every option.

What happens during a build

  1. The CLI finds the project root and reads package.json. The file must declare the BornEngine engine package.
  2. It runs perry compile --help to learn which targets your Perry supports, then resolves --os or --target against that list.
  3. It validates your assets (see Asset audit). An error stops the build. Warnings are not printed here. Run bornengine assets validate to see them.
  4. It creates a new output folder under .bornengine/builds/.
  5. It runs perry compile with the entry file and the output path. Compiler output streams to your terminal. The CLI also prints Compiling... and the time it took.
  6. It copies your project assets next to the executable.
  7. It records every file it wrote, so that bornengine clean can remove them. Files from a failed build are recorded too.

While Perry runs, the CLI puts a small cargo wrapper first on PATH. The wrapper calls your real Cargo. When Perry builds the engine’s native library, the wrapper adds the features chosen by the native profile. The wrapper lives in .bornengine/tmp/ and is removed afterwards. If Cargo is not on your PATH, a native build stops with Cargo was not found in PATH.

Build for a target

build always produces an optimized executable and never starts it:

shell
bornengine build main.ts --name my-game --os linux

When it finishes, it prints the target, the entry file, and the path of the output. The output name is --name if you pass it. Otherwise it comes from the name in package.json, lowercased, with other characters replaced by hyphens, and from the entry file name if package.json has no name. A name may contain only letters, digits, -, _, and .. The CLI adds .exe for Windows targets and .html for Web targets.

Web and mobile outputs are build-only. Follow the platform guide to package or serve them: Web and WASM, Mobile, or Apple platforms.

Run on this computer

shell
bornengine run main.ts
bornengine run main.ts -- --level tutorial

run builds a development executable, prints Launching game..., and starts it. The game process starts with the project root as its working directory, so a relative path such as assets/player.png resolves from the project folder. Everything after -- goes to the game unchanged. run exits with the game’s exit status.

run accepts only a target that can run on your computer: Linux on Linux, Windows on Windows, and macOS on macOS. A phone, a simulator, or a browser needs build and the steps in its platform guide.

Develop with dev

dev main.ts is the same as run main.ts without program arguments. It builds, starts the game once, and exits when the game exits.

shell
bornengine dev main.ts --watch

With --watch, dev hands the work to Perry’s own watch mode. Perry rebuilds and restarts the game when a source file changes. The CLI also passes every folder that contains project assets, so a changed image or data file restarts the game too. Watch output goes to .perry-dev/<name>/<timestamp>-<process id>-<n>/, and Perry does not watch that folder. After a watch session, the CLI moves any new Perry object files (names ending in _ts.o, _tsx.o, _mts.o, or _cts.o) from the project root into that folder.

Development builds also turn on the engine’s hot-reload feature. A running native game then reloads file-backed textures, sounds, music, and material shader files when they change on disk. Set the environment variable BLOOM_NO_HOT_RELOAD=1 when you start the game to turn the watchers off. Optimized builds leave the feature out by default, and Web builds never watch files. See Assets.

Choose a target

Without --os or --target, the CLI passes no target to Perry, and Perry builds for your computer. With --os, the CLI passes the matching Perry target after it checks that your Perry lists it:

--os valuePassed to PerryNotes
linux--target linux
windows--target windows
macos or darwinno targetPerry’s native macOS build. Only on a macOS host.
android--target androidBuild only.
ios--target iosBuild only.
tvos--target tvosBuild only.
watchos--target watchosBuild only.
visionos--target visionosBuild only.
web--target webBuild only. The output is an HTML file.

--target passes an exact name to Perry. The CLI recognizes linux, windows, macos, android and android-* names, ios, ios-simulator, tvos, tvos-simulator, watchos, watchos-simulator, visionos, visionos-simulator, wearos, web, and wasm. It also accepts any other name your Perry lists, and treats it as a build-only target. Use --target for names that have no --os value, such as simulators.

--os and --target conflict, and the command stops if you pass both. If your Perry does not list the target, the error names the targets it does list. The CLI never builds for a different platform instead. Cross builds depend on Perry and on the SDKs and linkers on your machine. The CLI only checks the target name.

Development and optimized builds

The first native build of an engine version, target, and feature set compiles the engine’s Rust code. That takes a while, and the result is kept in a shared cache. See Native build cache.

CommandRust optimizationExtra engine features
buildOptimizedNone
run and devLevel 1, with incremental compilationhot-reload and dev
run --release and dev --releaseOptimizedNone

These settings apply to Cargo’s build of the engine’s native library. build has no --release option because it is always optimized.

--jobs N sets the maximum number of parallel Cargo jobs for build, run, dev, and cache warm. N must be a positive integer. Without --jobs, the CLI keeps a CARGO_BUILD_JOBS value from your environment, and Cargo chooses its own concurrency otherwise.

Output folders

Every build, run, and dev (without --watch) creates a new folder. Old folders stay until you run bornengine clean:

plaintext
.bornengine/
  builds/
    manifest.json
    linux/
      my-game/
        <timestamp>-<process id>-<n>/
          my-game
          assets.manifest.json
          assets/
            player.png

The folder under builds/ is the target: linux, windows, macos, or the exact Perry target such as web. The executable sits next to a copy of your assets and their manifest, the same files that assets pack writes. manifest.json lists every file the CLI created, and clean uses it. Both .bornengine/ and .perry-dev/ are in the .gitignore that create, new, and init write.

Check a game with Perry

shell
bornengine check main.ts
bornengine check main.ts --check-deps
bornengine check main.ts --check-deps --deep-deps --all
bornengine check main.ts --check-deps --strict

check runs Perry’s compatibility check on the entry file for the selected target and shows Perry’s output. On success it prints Perry check completed successfully., and it exits with Perry’s exit status. It does not validate assets or build native code.

  • --check-deps asks Perry to scan the installed packages that your entry file imports.
  • --deep-deps scans the whole installed dependency tree. It requires --check-deps.
  • --all includes every Perry finding, including hints.
  • --strict makes Perry treat warnings as errors.

Perry reports what it can see in your code and in package declarations. A clean result does not prove that every code path works on every platform. A warning is a finding to review, not proof that a package cannot run.

Windows linkers

On 64-bit Windows, the CLI sets PERRY_LLD_LINK and CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER for the programs it starts. Each variable keeps the value you set. If only one is set, the other copies it. If neither is set and lld-link.exe is on your PATH, both use lld-link.exe.

Common errors

MessageCause and fix
could not find a BornEngine project; run this command inside a projectNo parent folder of the entry file or the current folder has a package.json that declares the engine. Run the command inside the project.
does not declare a BornEngine dependencyThe package.json has no engine dependency. Run bornengine engine install.
entry file does not existThe path is wrong. It is relative to your current folder.
could not start `perry`; make sure it is installed and on PATHPerry is missing. Run bornengine perry install.
installed Perry does not advertise targetYour Perry does not support the target. The message lists the targets it does support.
cannot be run on the currentYou used run or dev with a target for another system. Use build.
macOS builds require a macOS host--os macos works only on a Mac.
Cargo was not found in PATHInstall Rust. See Installation.
asset validation failedThe asset audit found an error. See Asset audit.
output name must be a simple file name--name contains characters other than letters, digits, -, _, and ..

Next steps

  • Native build cache explains why the first native build is slow and how to prepare it ahead of time.
  • Asset audit explains the checks that run before every build.
  • Diagnostics checks your setup when a build fails for an unclear reason.
  • Platforms lists what each target needs and what it cannot do.

Command reference

Build a game

Compile a TypeScript entry file for a target platform.

bornengine build <entry-file> [--name <output>] [--os <friendly-os> | --target <exact-target>] [--jobs <n>]

Options

  • --name <output>, -n <output>
  • --os <friendly-os>, -o <friendly-os>
  • --target <exact-target> (conflicts with --os)
  • --jobs <n> (positive Cargo job limit)
  • -v, --verbose (repeatable)

Behavior

Writes build artifacts under .bornengine/builds/. Web and mobile targets are build-only; they do not run through the native run command.

Examples

bornengine build main.ts --name my-game --os linux
bornengine build src/main.ts --target web

Build and run locally

Build a native executable and launch it on the current host.

bornengine run <entry-file> [--name <output>] [--os <friendly-os> | --target <exact-target>] [--release] [--jobs <n>] [-- <program-args>]

Options

  • --name <output>, -n <output>
  • --os <friendly-os>, -o <friendly-os>
  • --target <exact-target> (conflicts with --os)
  • --release selects optimized native output (default is fast/incremental)
  • --jobs <n> sets a positive Cargo job limit
  • Arguments after -- are passed to the game
  • -v, --verbose (repeatable)

Behavior

Runs a native executable for the current host. Web and mobile outputs are build-only and require their platform workflow.

Examples

bornengine run main.ts
bornengine run main.ts -- --level tutorial

Develop with a watch loop

Build during development and optionally rebuild when files change.

bornengine dev <entry-file> [--name <output>] [--os <friendly-os> | --target <exact-target>] [--watch] [--release] [--jobs <n>]

Options

  • --name <output>, -n <output>
  • --os <friendly-os>, -o <friendly-os>
  • --target <exact-target> (conflicts with --os)
  • --watch
  • --release selects optimized native output (default is fast/incremental)
  • --jobs <n> sets a positive Cargo job limit
  • -v, --verbose (repeatable)

Behavior

Without --watch, dev behaves like run. Watch mode uses .perry-dev/ for its development artifacts. Use a native target for a local executable.

Examples

bornengine dev main.ts --watch
bornengine dev main.ts --os macos

Check a project

Run Perry compatibility checks on an entry file and optionally scan installed dependencies.

bornengine check <entry-file> [--os <friendly-os> | --target <exact-target>] [--check-deps [--deep-deps]] [--all] [--strict]

Options

  • --os <friendly-os>, -o <friendly-os>
  • --target <exact-target> (conflicts with --os)
  • --check-deps asks Perry to scan installed dependencies used by the entry file
  • --deep-deps scans the full installed dependency tree; requires --check-deps
  • --all includes all Perry findings, including hints
  • --strict treats Perry warnings as errors
  • -v, --verbose (repeatable)

Behavior

Runs Perry's compatibility check for the selected target, streams its diagnostics, and preserves its exit status. Dependency scanning is opt-in.

Examples

bornengine check main.ts
bornengine check main.ts --target web
bornengine check main.ts --check-deps --deep-deps --all
bornengine check main.ts --check-deps --strict