Rivencraft Build Instructions
============================

These instructions apply when source code, models, textures, data, or other
resources have been changed.

Requirements
------------

- Java 21 JDK
- A working Gradle wrapper
- The project dependencies available in the Gradle cache, or network access
  for Gradle to download them

The project targets Minecraft 1.21.1 and NeoForge 21.1.251.

1. Open the project directory
--------------------------------

    cd /path/to/rivencraft

2. Check the changed files
--------------------------

Confirm that model, texture, and other resource files are inside
`src/main/resources`. Java source files belong under `src/main/java`.

For example, block models are normally stored under:

    src/main/resources/assets/rivencraft/models/block/

Resource files placed under `src/main/resources` are automatically included in
the finished mod JAR by Gradle.

3. Update the version when appropriate
---------------------------------------

Rivencraft uses the version format `x.y.z.b`:

- `x`: major release
- `y`: milestone completion
- `z`: release slice
- `b`: bug fixes and additional work within that slice

Edit `mod_version` in `gradle.properties` before creating a new release. Do
not reuse a version that has already been published.

4. Build the mod
----------------

From the project directory, run:

    ./gradlew build --offline

If the required dependencies are not cached locally, remove `--offline`:

    ./gradlew build

On systems using mise-managed Java and Gradle, use:

    mise exec -- ./gradlew build --offline

5. Run the automated tests
--------------------------

To build and run the GameTest suite:

    ./gradlew build runGameTestServer --offline

Or, with mise:

    mise exec -- ./gradlew build runGameTestServer --offline

All required GameTests should pass before distributing a build.

GameTests use `build/gametest-run/world`, separate from the normal development
world. Gradle starts each default run with a fresh world and removes it after
every run, whether tests pass or fail. The GameTest server always uses seed `0`,
so retries regenerate a clean world with that seed. Logs and configuration are kept.
A caller-supplied `-PgameTestRunDir`
is never removed automatically.

To run the suite in a fresh temporary directory instead, use:

    test_dir=$(mktemp -d /tmp/rivencraft-gametest.XXXXXX)
    ./gradlew runGameTestServer --offline -PgameTestRunDir="$test_dir"

With mise, prefix the second command with `mise exec --`.

6. Locate and inspect the JAR
-----------------------------

Build outputs are written to:

    build/libs/

The filename uses the configured version, for example:

    build/libs/rivencraft-0.3.6.9.jar

To verify that changed resource files are packaged:

    unzip -l build/libs/rivencraft-VERSION.jar | rg 'models|textures|data'

Replace `VERSION` with the actual version number.

To create a checksum for distribution:

    sha256sum build/libs/rivencraft-VERSION.jar

7. Stop the Gradle daemon when finished
----------------------------------------

This is optional, but useful after a long test run:

    ./gradlew --stop

Release checklist
-----------------

- Confirm the version was incremented when required.
- Confirm the build completed successfully.
- Confirm all required GameTests passed.
- Confirm changed resources are present in the JAR.
- Generate and record the SHA-256 checksum.
- Test the JAR in the target Minecraft 1.21.1 NeoForge instance.
- Publish the JAR only after client-side testing is complete.