Debugging Guide
During local development, you can iterate on the web frontend independently or launch a Minecraft development server for any supported version and loader via Gradle.
Prerequisites
- Node.js: Required to run the Vite dev server and build the
web/frontend. - JDK: Install the JDK version required by your target Minecraft version in
versions.json, such as JDK 8 for1.7.10and1.12.2, JDK 21 for1.21.1, and JDK 25 for26.3.
Frontend Development & Build
Install dependencies inside web/ and start the Vite dev server:
cd web
npm install
npm run devTo bundle the latest frontend assets into the mod .jar for full integration testing, run:
cd web
npm run buildThen build or run the target platform module with Gradle to load the updated frontend.
Running a Development Server
Loader projects under platforms/ and legacy/ accept -Ptarget_mc to select the target Minecraft version, sharing the root run/ directory.
Run NeoForge 1.21.1 server:
cd platforms/neoforge
../../gradlew runServer -Ptarget_mc=1.21.1Run Fabric 1.21.1 server:
cd platforms/fabric
../../gradlew runServer -Ptarget_mc=1.21.1Run Forge 1.21.1 or 1.16.5 server:
cd platforms/forge
../../gradlew runServer -Ptarget_mc=1.21.1Run Forge 1.12.2 or 1.7.10 server:
cd legacy/forge-1.12.2
../../gradlew runServerOnce started, check the console log for the web port, defaulting to 55533, and setupToken in config/utopia_server_panel.toml, then open http://127.0.0.1:55533 in your browser.
Running Core Unit Tests
The core/ module includes unit tests covering authentication, services, and player profiles. Run them from the repository root:
./gradlew :core:test