Skip to main content

Installation

The Traverse web app is a Node service that serves the API, the supporter wizard, and the admin console from a single port, backed by MySQL.

Requirements​

RequirementDetail
Node.js20 or newer
DatabaseMySQL, via Prisma
Native toolchainA C/C++ compiler, Python 3, and node-gyp
Reverse proxyRecommended, terminating TLS

The biome engine is a native Node addon wrapping Cubiomes, which is vendored as a git submodule. That is why a compiler is needed: there is no prebuilt binary.

Toolchain by platform​

  • Windows: Visual Studio Build Tools with the "Desktop development with C++" workload, plus Python 3. MSVC is the supported compiler; Cubiomes' own makefile assumes gcc and is not used.
  • Linux: build-essential (or your distribution's equivalent) and Python 3.

Build and run​

git clone <traverse-repo>
cd ALD-Traverse
git submodule update --init --recursive   # fetches the vendored Cubiomes source
npm install                                # installs the app workspaces
npm run build                              # native addon, then shared, server, and web

npm run build compiles the native addon first (node-gyp rebuild), then the TypeScript packages and the Vite web bundles. The addon's build/ directory is generated output and safe to delete; the command regenerates it.

Then set up the database and start:

npx prisma migrate deploy   # from packages/server
npm run seed                # optional: creates the first admin user
npm start

The server serves the built web bundles from the same port as the API, so no separate static host is needed. Requests under /admin fall through to the admin bundle, /api returns JSON 404s, and everything else falls through to the supporter app.

On first start the server creates the one world this installation serves, disabled, seeding its name, seed, and version from the optional TRAVERSE_WORLD_NAME, TRAVERSE_SEED, and TRAVERSE_MINECRAFT_VERSION variables. Everything else is configured in the admin console. See Configuration and the Admin Guide.

Health check​

GET /api/health is unauthenticated and suited to Coolify or any uptime monitor. It returns 200 while the server and database are reachable, 503 if the database is not, and reports the world state, biome index state, and plugin status in the body. See the Plugin API Reference.

Development​

npm run dev         # server and web together, with hot reload
npm run dev:server
npm run dev:web
npm test            # server test suite
npm run test:e2e    # Playwright end-to-end, builds first

Minecraft version support​

Biome generation comes from the vendored Cubiomes snapshot, so Traverse supports the versions Cubiomes does. As shipped, that is:

MC_1_0 through MC_1_20, plus MC_1_21_1, MC_1_21_3, and MC_26_2_S8.

The default is MC_1_21_3, the newest stable release in the vendored snapshot. MC_26_2_S8 is a snapshot build, cherry-picked from an unmerged upstream commit, and is deliberately not the default.

Match the version to your server, or previews will not match the ground

A world's minecraftVersion controls how biomes are generated for previews. If your live server runs a version Traverse cannot generate, searches for that world return 503 UNSUPPORTED_MINECRAFT_VERSION rather than silently producing wrong terrain. Pick the closest supported version knowingly, and verify a candidate in game before running a campaign.

Next steps​