Building

Building

Maven

The repository is a Maven multi-module project. Java 21 is required.

mvn package

Module	Output
vistructum-api	public API, bundled into the core jar
vistructum-inference	model inference shared by core and sidecar
vistructum-core	vistructum-core/target/vistructum-<version>.jar
vistructum-ui	vistructum-ui/target/vistructum-ui-<version>.jar
vistructum-sidecar	vistructum-sidecar/target/vistructum-sidecar.jar

Copy the core jar and the UI jar into plugins/. Paper downloads SQLite JDBC and ONNX Runtime on first start through the libraries entry in plugin.yml.

Docker

docker compose build
docker compose up -d server

docker-compose.yml defines two services:

• server: Paper 1.21.4 (itzg/minecraft-server) with both plugins, ViaVersion, and ViaBackwards. Port 25565 for players, 8765 for the resource pack.
• sidecar: the optional inference server on port 8000. Start it only when you use inference.mode: remote.

Volumes:

Volume	Mount	Content
vistructum-state	/data/plugins/vistructum	SQLite database, downloaded models
vistructum-ui-config	/data/plugins/vistructum-ui	config.yml, messages.yml
sidecar-models	/models	models the sidecar downloaded

Images contain no secrets. Configure them with environment variables and mounted volumes.

Releasing

Pushing a version tag publishes a release. The release workflow sets the Maven version from the tag, runs mvn verify, and attaches the core, UI, and sidecar jars, the resource pack, and SHA256SUMS to a GitHub release.

git tag -a v1.1.0 -m "Release notes in Markdown"
git push origin v1.1.0

• The tag annotation becomes the release notes. A lightweight tag gets notes generated from the merged pull requests.
• A tag with a suffix, such as v1.1.0-beta.1, becomes a prerelease. Every other version tag becomes the latest release.
• main stays on a -SNAPSHOT version. The release build doesn't commit the tag version.
• To rebuild an existing tag, run the workflow manually: gh workflow run release.yml -f tag=v1.1.0. It replaces the assets of an existing release or draft and publishes it.
• Model releases use models-* tags and don't trigger this workflow.

Python (ml/)

ml/ holds model training and the Python reference implementation. The plugins do not need Python at runtime.

cd ml
pip install -r requirements-dev.txt
pip install --extra-index-url https://download.pytorch.org/whl/cpu -r train/requirements.txt
pip install --no-deps -e .
PYTHONPATH=$PWD:$PWD/train python -m pytest -q tests train/tests