saturnclient/VERSION_GUIDE.md

Version guide

How Saturn Client supports several Minecraft versions, and how to change or add one.

Layout

• common/: all version-independent code (mods, UI, cosmetics, the server client). It has no Minecraft dependency and reaches the game only through the interfaces in org.saturnclient.common.
• versions/<mc>/: one module per Minecraft version, implementing those interfaces (providers, refs, mixins). Each is a full copy, and they differ only where Minecraft's API differs.
  • gradle.properties: the Minecraft, Yarn, Fabric Loader and Fabric API versions.
  • src/: the version-specific code and the three mixin configs.

settings.gradle includes every folder under versions/ automatically, as the Gradle project :mc-<mc>.

Porting a change to the other versions

Make the change in one version, usually the newest, then run:

scripts/port.sh                        # port uncommitted changes to every other version
scripts/port.sh --dry-run              # see what would apply cleanly first
scripts/port.sh --to 1.21.9,1.21.10    # only some versions
scripts/port.sh --commit <rev>         # port what a commit changed instead

The script applies the diff under versions/<from>/src to each other version with git apply --3way:

• applied: the files matched, and nothing else is needed.
• CONFLICTS: that version's code really differs. The file gets normal conflict markers, with the version's own code in ours and the ported change in theirs. Adapt the change to that version's API and resolve.
• already has this change: nothing to do, which is safe to see when re-running.

Only src/ is ported. build.gradle and gradle.properties are version-specific on purpose. Then build everything:

./gradlew compileJava

The Check workflow runs the same compile on every pull request, so a version that was missed or mis-ported fails before merging.

Adding a Minecraft version

1. Copy the closest existing version: cp -r versions/1.21.11 versions/<new>. Delete its build/, .gradle/ and run/ folders if present.
2. In versions/<new>/gradle.properties, set minecraft_version, yarn_mappings, loader_version and fabric_api_version. The right values are listed at https://fabricmc.net/develop.
3. Build it with ./gradlew :mc-<new>:compileJava and fix what Minecraft changed. Check the mixin configs in src/main/resources/*.mixins.json as well: a mixin whose target changed fails at startup, not at compile time, so launch it with ./gradlew :mc-<new>:runClient.
4. The release workflow builds every folder under versions/, and "Publish to Modrinth" takes the game version from each jar's name, so neither needs changing.