Skip to main content

Configuration

Add a bds-runner.json at or above the directory you run the command from, usually the project root. Every key is optional.

bds-runner.json
{
"$schema": "https://bedrock-core.drav.dev/schemas/bds-runner/beta/config.schema.json",
"version": "1.26.45.1",
"channel": "stable",
"properties": {
"view-distance": 8,
"difficulty": "normal"
}
}
KeyTypeDefaultDescription
versionstring"latest"An exact build, or "latest"
channel'stable' | 'preview'"stable"Which release channel latest resolves in
instancestringSelected versionStable directory name under .bds/server
instancesRecord<string, number>Unrestricted instance selectionNamed instances and their assigned IPv4 UDP ports; IPv6 reserves the following port
propertiesobject{}Overrides written into server.properties before every run. Any key the server documents

Editor schema​

The starter uses the hosted beta schema for runner options and scalar server-property overrides. It works before downloading a server. The installed equivalent is ./node_modules/@bedrock-core/bds-runner/schemas/config.schema.json. Stable versions use separate snapshots; see JSON schemas for URL selection.

For the selected server's own property types and documentation, generate a local schema without starting a test run:

npx bc-bds fetch

Point the configuration at that generated file:

bds-runner.json (fragment)
{
"$schema": "./.bds/schema/bds-runner.json"
}

The path resolves from bds-runner.json. The local schema is generated from the selected server's own server.properties, so every key the build documents is typed and described in the editor, and the five keys the runner owns are marked deprecated. It is rewritten every time a build is resolved (run, fetch, and where once the build is cached), so it always describes the build the next run will use.

Server properties​

server.properties is rewritten before every run. Keys the runner does not list keep the value the build ships with.

KeyValueWhy
server-namebc-bds-runnerIdentifies the server in its own properties file
transportnethernetThe transport every client uses from 1.26.50 on; a server left on raknet refuses players
gamemode, force-gamemodecreative, trueNothing wanders into a plot; a joining player can edit it
difficultypeacefulNo mob AI competes for ticks
default-player-permission-leveloperatorA joining player can run commands
allow-listfalseAnyone on the LAN can join a held-open server
view-distance, tick-distance, max-threads, max-players5, 4, 4, 1The tests run in one plot; the rest is wasted simulation
player-idle-timeout0A kick mid-run would look like a hang
content-log-file-enabled, content-log-file-max-size-bytestrue, 33554432A second copy of the log on disk, next to the server
script-watchdog-hang-threshold60000A long test is not killed by the 10 s default
script-watchdog-enable-shutdownfalseA hung script fails the run instead of taking the server down before it can report
enable-lan-visibilityfalse, true with --keep-aliveAdvertised on the LAN only when someone is meant to join

Anything in properties is applied over those, so "difficulty": "normal" wins. --keep-alive enables LAN visibility unless the config explicitly sets "enable-lan-visibility": false.

Five keys cannot be overridden because the runner depends on them: level-name, server-port and server-portv6 (use --port), allow-cheats, and online-mode. Setting one is an error that names what controls it.

The runner also writes config/default/permissions.json, listing @minecraft/server, @minecraft/server-gametest, @minecraft/server-ui and @minecraft/debug-utilities as modules the world's scripts may import — a fixed list, written explicitly so a run never depends on the build's own default permissions.json.

World​

The world is generated once per server tree, on the first run, and reused after that. level.dat carries the two settings the tests need and that server.properties cannot express: the Beta APIs experiment, without which /gametest does not exist, and a flat generator, which gives every plot a predictable ground plane. Both are written into the generated level.dat and read back to verify they stuck.

Before every run the world's chunks are deleted and level.dat is kept, so each run starts on fresh terrain with the experiments still on. --fresh deletes the whole server tree instead, which forces a new copy of the build and a new world.

Choosing the server build​

By default the runner uses the newest stable build. For one run:

npx bc-bds run --packs ./build --tag my-suite --bds-version 1.26.45.1
npx bc-bds where --bds-channel preview

Precedence, highest first:

  1. --bds-version / --bds-channel
  2. BC_BDS_VERSION / BC_BDS_CHANNEL
  3. The nearest bds-runner.json, or the file named by --config
  4. The build your packs ask for — see below
  5. Newest stable

bc-bds where prints the selected build, the config file it came from, the schema path, and the current upstream builds.

The first run writes the pin for you​

A project with no bds-runner.json does not silently get whatever is newest. Before the first download the runner reads the min_engine_version of every pack manifest in the project, takes the highest, and pins the newest build published in that line — 1.26.40 selects 1.26.40.8. It writes the result and says so:

no bds-runner.json: 2 manifest(s) declare min_engine_version 1.26.40
pinned 1.26.40.8 (stable) in bds-runner.json

min_engine_version is the promise a pack makes to players: this is the oldest client that can load me. Running the tests on that build checks this promise. Pack conversion has a separate format requirement: select an output supported by the intended client and verify it there. The converter can minify or upgrade content without adjusting the declared minimum.

The scan skips node_modules, build, dist, .bds and other generated trees, so a dependency or a stale export cannot decide the project's build. A line that only ever shipped as preview pins the preview build. Nothing is written when no manifest declares a version, when the index is unreachable, or when a config file already exists — the newest stable build is used and the project stays as it was.

This happens once. Edit or delete the file to change the pin; bc-bds where reports what would be detected without writing anything.

Build metadata comes from Bedrock-OSS/BDS-Versions; the download itself comes from minecraft.net and is checked against the published SHA-1. If the index is unreachable the run fails rather than falling back to a build it already has.

Working directory​

Everything the runner keeps lives under one directory, <project>/.bds by default. The project is the directory holding the nearest bds-runner.json, else the nearest package.json or .git, else the working directory.

PathContents
cache/<version>/<platform>/The extracted download, one per build. Never run from
server/<instance-or-version>/The executable instance: a copy of the cache plus the generated server.properties and world. Kept between runs
logs/One console transcript per run, and a .bootstrap log for the world-generating boot
schema/bds-runner.jsonThe JSON Schema for the config file

Symlinks need elevation on Windows, so the server tree is a copy. With BC_BDS_PATH and no instance name, the tree is named after the directory the variable points at. All of .bds is regenerable and may be removed by clean.

Named instances​

Choose a directory name with --instance, or configure a default and fixed port assignments:

bds-runner.json (fragment)
{
"instance": "core",
"instances": {
"core": 19780,
"bench": 19782
}
}

core runs from .bds/server/core on UDP ports 19780 and 19781. --instance bench selects the second instance and its port pair. When instances is present, the selected name must be declared and --port must match its assignment. Names are portable directory names; port pairs cannot overlap.

An instance is locked for the duration of a run. Different instances can run in parallel. A named instance retains its executable path when the build changes; its tree and generated world are refreshed from the selected cache. A source executable checksum also detects changes when BC_BDS_PATH supplies the build.

Environment variables​

VariableEffect
BC_BDS_PATHUse a server you already have. Point it at the directory containing bedrock_server or bedrock_server.exe. Skips download and build selection
BC_BDS_HOMEWhere the cache, server trees and logs are kept. Default <project>/.bds, which belongs in .gitignore
BC_BDS_VERSIONBuild to use. Accepts latest
BC_BDS_CHANNELstable or preview

BC_BDS_PATH is the route for networks that cannot reach minecraft.net.