CLI

Engine versions

Inspect, install, select, update, and remove the engine dependency of a project.

Each project pins the exact engine version it uses in package.json, and your package manager records the resolved packages in a lockfile. The CLI does not install an engine for the whole computer. The engine commands and upgrade edit the dependency of the project you are in and then run your package manager’s install command, which updates node_modules/ and the lockfile. The CLI and the engine have separate version numbers.

shell
bornengine engine current
bornengine engine list
bornengine engine install 0.18.2
bornengine engine update
bornengine engine use ../BornEngine
bornengine engine remove

Run these commands inside the project, or in any folder below its root.

See what a project uses

engine current prints the package name and version from package.json, and where the dependency comes from:

plaintext
@bornengine/engine 0.18.2
Source: npm registry

The source is npm registry for a version number, local path for a link: or file: dependency, and GitHub/Git for a github: or git+ dependency.

engine list asks the npm registry for the published releases and prints each stable version with its package name, newest first. Prereleases are not listed. Both commands change nothing.

Change the version

Four commands select a release from the registry:

CommandResult
engine install <version>Selects that version.
engine installSelects the latest stable version. It ignores the engine-version setting in your configuration.
engine updateSelects the latest stable version.
upgrade [version]The same as engine install. upgrade --latest selects the latest version, and you cannot combine --latest with a version.

A version must be an exact stable release, such as 0.18.2, or the word latest. Version ranges such as ^0.18.0 and prereleases are rejected. The CLI writes the exact version to package.json, without a range prefix.

If the project already uses the selected version, the CLI prints BornEngine dependency is already <package> <version> and does nothing else. Otherwise it removes any engine entry from dependencies, devDependencies, and optionalDependencies, adds the new one to dependencies, and prints Updated BornEngine: <old> -> <new>, or Added BornEngine: when there was none. Then it runs the package manager’s install command. The command exits with the package manager’s status.

The CLI takes the package manager from the packageManager field of package.json, then from a lockfile, then from your configuration. The manager must be on your PATH.

Registry and older package

The CLI looks for versions of @bornengine/engine first. If the version you ask for is not published under that name, it falls back to @bloomengine/engine, the older package name, so projects made for that package keep working. engine list uses the older package only if the new one has no versions. Both package names count as an engine dependency. Native profile settings in perry.toml apply only to @bornengine/engine.

Use a local checkout

While you work on the engine itself, point a project at your clone:

shell
bornengine engine use ../BornEngine
bornengine engine use 0.18.2

engine use treats its argument as a folder when a folder with that name exists. Otherwise it treats the argument as a version. The folder must contain a package.json named @bornengine/engine or @bloomengine/engine. The CLI writes a link: dependency for pnpm, and a file: dependency for npm and yarn, with a path relative to the project root. Pass a version number to switch back to a published release. new and init take a checkout through --engine-path. See Project commands.

Remove the engine

shell
bornengine engine remove
bornengine engine remove 0.18.2

remove deletes the engine entry from package.json and runs the package manager’s install command. If you pass a version, it must equal the version now in package.json, or the command refuses. A project without an engine dependency prints This project has no BornEngine dependency. and exits with 0. After removal, build and run stop with an error such as does not declare a BornEngine dependency until you run engine install again.

After you change the version

  • The first native build compiles the engine again, because the cache is keyed by engine version. See Native build cache, or run bornengine cache warm.
  • Read the migration notes for changes that can break your code.
  • Run bornengine doctor to confirm that the new package is installed.
  • Commit package.json and the lockfile together.

upgrade and engine update change the engine of one project. To check whether a newer CLI exists, use bornengine update, described in Configuration.

Next steps

Command reference

Show the selected engine

Print the engine version or path currently selected by the project.

bornengine engine current

Options

  • -v, --verbose (repeatable)

Behavior

Reads the active engine selection without changing it.

Examples

bornengine engine current

Select an engine release

Set this project's BornEngine dependency to a stable release.

bornengine engine install [version]

Options

  • [version] selects an exact stable release; omit it to select the latest stable release
  • -v, --verbose (repeatable)

Behavior

Updates the project's BornEngine dependency and package-manager lockfile to the selected stable release.

Examples

bornengine engine install 0.15.0
bornengine engine install

List stable engine releases

Show stable BornEngine versions available from the registry.

bornengine engine list

Options

  • -v, --verbose (repeatable)

Behavior

Lists stable releases available for project dependencies.

Examples

bornengine engine list

Update the project's engine dependency

Select the latest stable engine release for the current project.

bornengine engine update

Options

  • -v, --verbose (repeatable)

Behavior

Changes the project's BornEngine dependency and lockfile to the latest stable release.

Examples

bornengine engine update

Remove the project engine dependency

Remove BornEngine from this project's package manifest.

bornengine engine remove [version]

Options

  • [version], if given, must equal the version now in package.json; otherwise the command refuses
  • -v, --verbose (repeatable)

Behavior

Removes the project's BornEngine dependency and updates the package manifest and lockfile.

Examples

bornengine engine remove
bornengine engine remove 0.18.2

Select an engine source

Choose a published stable version or a local engine checkout for the project.

bornengine engine use <version-or-path>

Options

  • <version-or-path> is an exact stable version, or the path of a local engine checkout
  • -v, --verbose (repeatable)

Behavior

Changes the project's BornEngine dependency to the selected release or local checkout and updates its lockfile.

Examples

bornengine engine use 0.15.0
bornengine engine use ../BornEngine

Upgrade the project engine dependency

Select a specific or latest BornEngine release for this game project.

bornengine upgrade [version] [--latest]

Options

  • [version] selects a release
  • --latest selects the latest release
  • -v, --verbose (repeatable)

Behavior

Changes the current project's BornEngine dependency and lockfile. Use bornengine update to check for a newer CLI release.

Examples

bornengine upgrade
bornengine upgrade 0.15.0
bornengine upgrade --latest