Commands
bc-bds run --packs <dir> --tag <tag> [options] run a suite
bc-bds optimize --packs <dir> --out <dir> pack built packs into archives
bc-bds fetch download and cache the server
bc-bds where show which build will be used, and from where
bc-bds fetch resolves the build and downloads it into the cache without running anything, so a CI job can warm the cache in a separate step. bc-bds where prints the selected build, the config file it came from, the cache and server tree paths, the schema path, and the current upstream builds; a pin that is not a published build gets a warning.
run options
| Option | Effect |
|---|---|
--packs <dir> | One pack or a directory containing built packs. Repeatable. Required |
--tag <tag> | The gametest tag to run. Required |
--expect-registered <n> | Fail unless the engine announces exactly n tests. Catches a suite that silently failed to register |
--known-failure <id> | A test that is expected to fail. Repeatable. It is reported but does not make the run red |
--allow-script-errors | Report uncaught script errors without failing the run. See Uncaught script errors |
--origin "<x> <y> <z>" | Where test plots are placed. Default 8 -60 8 |
--idle <seconds> | End the run once the server has been quiet this long with every test accounted for. Default 45 |
--timeout <seconds> | Wall-clock limit for the whole run. Default 900 |
--instance <name> | Executable instance name. Uses the configured default, otherwise the selected build version |
--port <n> | Server port. Uses the configured instance's assignment, otherwise 19140 |
--fresh | Recreate the server tree and world from scratch |
--keep-alive | After the results, keep the server running so you can join it. See Looking at the plots |
--offline | Never download. Fail if the server is not already cached |
--quiet | Do not echo server output while the run is in progress |
--json <path> | Also write the result as JSON: tag, server version, duration, per-test verdicts, regressions, uncaught script errors, and any infrastructure error |
Build selection options
Accepted by every command. See Choosing the server build.
| Option | Effect |
|---|---|
--bds-version <v> | An exact build such as 1.26.45.1, or latest |
--bds-channel <c> | stable or preview |
--config <path> | Read this bds-runner.json instead of searching for one |
What --packs accepts
Pass either a pack directory containing manifest.json, or a build directory whose immediate subdirectories are packs. Folder names are arbitrary; manifest module types identify behavior and resource packs.
build/
gameplay/manifest.json
shop/manifest.json
textures/manifest.json
interface/manifest.json
- npm
- yarn
- pnpm
npx bc-bds run --packs ./build --tag example
yarn bc-bds run --packs ./build --tag example
pnpm exec bc-bds run --packs ./build --tag example
One directory can contain several behavior packs and several resource packs. Discovery does not recurse into nested build directories. A directory with its own manifest is treated as one pack.
Repeat --packs to combine outputs from different projects or add an external pack:
- npm
- yarn
- pnpm
npx bc-bds run --packs ./gameplay/build --packs ./shop/build --tag integration
yarn bc-bds run --packs ./gameplay/build --packs ./shop/build --tag integration
pnpm exec bc-bds run --packs ./gameplay/build --packs ./shop/build --tag integration
The selected set must include a behavior pack that registers the GameTests. A resource-only project can be optimized on its own; testing it with GameTests requires a behavior pack test harness. Packs receive distinct deployment directories, and repeated UUIDs are installed once.
optimize options
bc-bds optimize --packs <dir> --out <dir> [--mode <format> | --unpack]
Runs the server's own pack optimizer over built packs. The converter writes the selected format and exits without serving. Preview 26.70.23 introduces brpak, brarchive and unpacked output modes and supports converting already-packed inputs. Earlier builds use the legacy optimizer configuration.
--packs is a directory whose immediate subdirectories are built packs, each with a loose manifest.json or a .brpak archive containing its manifest. Pack folder names are arbitrary, and a collection can contain resource packs, behavior packs or both. Pass the collection directory rather than an individual pack to this command.
| Option | Effect |
|---|---|
--packs <dir> | Directory holding one subfolder per loose or packed pack. Required |
--out <dir> | Where the converted packs are written. Has to sit outside --packs, which is read as a directory of packs. Required |
--mode <format> | brpak, brarchive or unpacked. Omit it to use the selected server's default |
--unpack | Alias for --mode unpacked; selects the legacy unpack option on older builds |
--verbose | Echo the converter's own per-file lines |
--offline | Never download. Fail if the server is not already cached |
The selected build controls available formats and content upgrades. Pin it in bds-runner.json rather than taking latest. With BC_BDS_PATH, supply an exact --bds-version when selecting a mode so the runner can choose the correct configuration. See Choosing the server build.
bc-bds optimize --packs ./build --out ./optimized --mode brpak --bds-version 1.26.70.23 --bds-channel preview
bc-bds optimize --packs ./optimized --out ./loose --unpack --bds-version 1.26.70.23 --bds-channel preview
The runner detects each written pack's format and measures input/output sizes on disk, including BRPAK packs without loose manifests. Per-pack entry details appear when the converter supplies attributable logs. A successful converter exit with missing packs or a different output format is an error.
On BDS Preview 1.26.70.23, direct BRPAK → BRARCHIVE conversion produces loose files instead of archives. The runner rejects this format mismatch. Unpack to a separate directory first, then convert that loose output to BRARCHIVE:
bc-bds optimize --packs ./optimized --out ./loose --unpack --bds-version 1.26.70.23 --bds-channel preview
bc-bds optimize --packs ./loose --out ./archives --mode brarchive --bds-version 1.26.70.23 --bds-channel preview
What converting costs
BRARCHIVE output needs a 1.26.40 or newer client. BRPAK requires a client that supports BRPAK; the older BRARCHIVE minimum does not establish BRPAK compatibility. Unpacked output uses loose files, but JSON may still be upgraded by the selected converter. Optimization does not establish that a pack's declared min_engine_version matches the selected output. Verify the intended client before shipping.
What gets archived
For brpak, the output is a .brpak file inside each pack directory, including its manifest and other pack files. The following layout applies to brarchive:
| Input | Result |
|---|---|
manifest.json | copied out, plus pack_optimization_version in the header |
| anything else at the pack root | copied out — only subdirectories are archived |
**/*.json | archived and minified, // comments stripped |
**/*.png, **/*.js | archived unchanged |
texts/*.lang | listed in the archive, and copied out unchanged |
An entry that carries no bytes is a listing rather than content: the engine learns a directory's contents from one read and still loads that file from disk. Nothing about those files gets smaller, so the summary counts them apart from the archived ones.
The BRARCHIVE content saving comes from JSON minification. Archive indexes and other format overhead also contribute to the measured output size; a small pack can grow.
--unpack is not an inverse
It restores the file tree, not the sources: JSON comes back minified and without the comments it was written with. The build output is the original, not the unpacked copy. Modern builds accept loose or packed inputs for each mode. Legacy builds require converted input for unpacking and refuse to optimize an already-converted pack again.
What a run does
- Resolves the server build and downloads it into the cache if it is not there. See Choosing the server build.
- Reuses the selected named or version-named server instance, copying its build from the cache when needed. Writes
server.propertiesandconfig/default/permissions.json. See Named instances. - On the first run for that tree, boots the server once to generate the world, then turns Beta APIs and the flat generator on in
level.dat. Every later run is a single boot. - Deletes the world's chunks so tests start on unmodified terrain, replaces the isolated server's development packs with the selected packs, and writes the world pack references. World-local pack copies are removed so they cannot shadow this deployment.
- Boots the server, adds a ticking area around the origin so the playerless world simulates, and runs
gametest runset <tag>. - Waits until every announced test has a verdict, the server has been quiet for
--idleseconds, or--timeoutelapses. Then stops the server and prints the verdicts.
The full console transcript of every run is written to .bds/logs/<timestamp>-<tag>.log; named instances include the instance name before the tag. The summary prints the path.
Looking at the plots
A failure message says what the assertion was, not what the world looked like. --keep-alive keeps the server up after the results are printed so you can connect a client and see for yourself:
- npm
- yarn
- pnpm
npx bc-bds run --packs ./build --tag my-suite --keep-alive
yarn bc-bds run --packs ./build --tag my-suite --keep-alive
pnpm exec bc-bds run --packs ./build --tag my-suite --keep-alive
✗ 5 passed, 1 failed (my-suite, BDS 1.26.45.1, 7.1s)
log: .bds/logs/2026-09-07T20-26-53-336Z-core.log
server kept running for inspection: connect to 127.0.0.1:19140
type a server command here; `stop` or Ctrl+C ends the session
The test structures are left exactly as the tests left them. The server is advertised on the local network unless the config explicitly disables LAN visibility. Add a local-only instance as a server at 127.0.0.1 on the run's port. You join in creative mode as an operator.
While it is up, anything typed into the terminal is sent to the server console, so you can teleport, run gametest runset again, or anything else. stop or Ctrl+C shuts the server down cleanly, and the world is wiped once it has exited. The exit code is the one the tests earned, regardless of what happened afterwards.
On Windows, the Minecraft app cannot connect to a server on the same machine until the app is exempted from loopback isolation. This is a one-time step in an elevated prompt:
CheckNetIsolation LoopbackExempt -a -n=Microsoft.MinecraftUWP_8wekyb3d8bbwe
Exit codes
| Code | Meaning |
|---|---|
0 | Every test passed, or the only failures were declared with --known-failure |
1 | Tests failed |
2 | The run could not be trusted: no server, no boot, no tests announced, an unknown tag, an --expect-registered mismatch, or an uncaught script error without --allow-script-errors |
1 and 2 are distinct so that a broken harness can never look like broken code.
Any test the engine announces but never reports a verdict for is counted as a failure. A test the engine counted but never placed a plot for, because its structure is missing or the plot could not be placed, is reported as absent and also fails the run. The run is over when every announced test has a verdict, or when the idle or wall-clock timeout fires.
The verdicts come from the engine's own onTestPassed and onTestFailed console lines and the announced count from its Running N tests with tag line. If a newer engine renames those lines the result is exit code 2, never a pass. Only the most recent runset in the console is read, so running the tag again from a held-open server does not mix results.
Uncaught script errors
An exception thrown outside a test — from an event subscriber or a deferred callback — shares no call stack with any test, so no test can fail on it. The engine catches it, logs it against your pack, and carries on. Left alone that is a green build over broken code.
The runner collects these and fails the run by default:
✓ 11 passed, 0 failed (core, BDS 1.26.43.1, 10.0s)
1 uncaught script error(s), seen by no test:
[my_addon] Error: something broke at <anonymous> (main.js:15976)
infrastructure: 1 uncaught script error(s) were logged.
Errors your own code logs with console.error are left alone; only an exception the engine reports counts, recognized by its error class or its stack frame. Pass --allow-script-errors to report them without failing.