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.

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.

:::caution 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​