Building from source

Building from source

You need JDK 25, and Gradle downloads it when it's missing.

1. Clone the repository:

   git clone https://github.com/allay-ai/minecraft
   cd minecraft

2. Build and test:

   ./gradlew build

3. Take the plugin from spigot/build/libs/allay-spigot-dev.jar, the Fabric mod from fabric/build/libs/allay-fabric-dev.jar, and the NeoForge mod from neoforge/build/libs/allay-neoforge-dev.jar. Every dependency is inside each, relocated under chat.allay.libs.

Nothing in the repository holds the version. Local builds are dev, CI builds on master and pull requests are dev-<sha>, and releases pass -PreleaseVersion=X.Y.Z. NeoForge wants a number, so its jar says 0.0.0-dev where the others say dev; Allay itself still calls it dev.

Check it on a real server

The build runs every module's tests, and both mods' game tests on a real server with real players. To see the plugin start on Paper, run the smoke script. It downloads Paper and the Modrinth plugins into ~/.cache/paper-smoke and fails on any error about the plugin:

python3 -I .claude/scripts/paper_smoke.py --game 26.3 --plugin spigot/build/libs/allay-spigot-dev.jar \
  --modrinth placeholderapi --modrinth plan --command "papi list" \
  --expect "registered internal expansion: allay" --expect "Registered extension: Allay" \
  --ignore 'Plan\] Failed to enable geolocation'

The Fabric mod has its own, with the server from meta.fabricmc.net and the mods from Modrinth, cached in ~/.cache/fabric-smoke:

python3 -I .claude/scripts/fabric_smoke.py --game 26.3 --mod fabric/build/libs/allay-fabric-dev.jar \
  --modrinth fabric-api --modrinth placeholder-api --modrinth luckperms \
  --expect "Allay dev is on" --command "allay status"

The NeoForge mod's script installs NeoForge from maven.neoforged.net once into ~/.cache/neoforge-smoke and takes the mods from Modrinth:

python3 -I .claude/scripts/neoforge_smoke.py --game 26.3 --mod neoforge/build/libs/allay-neoforge-dev.jar \
  --modrinth luckperms --modrinth placeholder-api-neoforge \
  --expect "Allay dev is on" --command "allay status"

./gradlew :fabric:runClientGameTest and ./gradlew :neoforge:runClientGameTest open a game window, create a singleplayer world, and check Allay there; ./gradlew :fabric:runClient and ./gradlew :neoforge:runClient open the game to try it by hand.

A real question needs a backend and a player: point server.url at a backend and ask /ask once.

Next: Architecture