GrimAC Versioning Guide

This document outlines the versioning system used for GrimAC artifacts.

The current public base version in Grim-public/build.gradle.kts is 2.3.74.

Artifact Version Format

Shadow jar names use:

grimac-{platform}-{version}

For non-release builds, {version} is computed as:

{base-version}[-{branch}]-{commit}[+{modifiers}]

Where:

• {platform} - the platform implementation, such as bukkit or fabric
• {base-version} - the semantic base version, such as 2.3.74
• {branch} - the sanitized git branch, omitted for main and the configured main branch
• {commit} - the abbreviated git commit hash
• {modifiers} - optional build settings joined with -, such as lite-no_relocate

The configured main branch defaults to 2.0, unless GRIM_MAIN_BRANCH is set.

Examples

Release Builds

Release mode omits branch, commit, and modifiers:

• grimac-bukkit-2.3.74
• grimac-fabric-2.3.74

Standard Preview Builds

• grimac-bukkit-2.3.74-a4f8b21
• grimac-fabric-2.3.74-a4f8b21

Development Branch Builds

• grimac-bukkit-2.3.74-develop-a4f8b21
• grimac-fabric-2.3.74-feature_xyz-a4f8b21

Builds With Modifiers

• grimac-bukkit-2.3.74-a4f8b21+lite
• grimac-fabric-2.3.74-develop-a4f8b21+lite-no_relocate

Modifier Definitions

The following modifiers indicate non-default build configurations:

• lite - shadePE=false. PacketEvents is not shaded into the jar.
• no_relocate - relocate=false. Shaded packages are not relocated.

These modifiers are only included when the build deviates from current public defaults:

• Default: shadePE=true, relocate=true -> no modifier
• Non-default: shadePE=false -> lite
• Non-default: relocate=false -> no_relocate
• Both non-default -> lite-no_relocate

Build Options Mapping

Modifier	Build option flag	Environment alias	Description
lite	shadePE=false	SHADE_PE=false	Do not shade PacketEvents into the jar
no_relocate	relocate=false	RELOCATE_JAR=false	Disable package relocation
no modifier	shadePE=true, relocate=true	default	Default production-style build settings

Other build flags:

Flag	Environment alias	Default	Version impact
release	RELEASE	false	true returns only the base version
mavenLocalOverride	MAVEN_LOCAL_OVERRIDE	false	no version-string modifier

Flags can be set as JVM system properties, Gradle project properties, or environment variables:

./gradlew build -Prelease=true
./gradlew build -PshadePE=false -Prelocate=false
SHADE_PE=false RELOCATE_JAR=false ./gradlew build
./gradlew build -Drelease=true

User-Facing Versions

For user-facing contexts such as /pl version grim on Bukkit, the grimac-{platform}- prefix is removed and the computed project version is shown.

Workspace IncludeBuilds

The public Grim workspace can include sibling repositories through the root workspace's dynamic includeBuild setup. This is controlled by workspace.defaults.toml and optional local workspace.user.toml overrides.

Important points:

• include = false clones/tracks a repo but skips Gradle includeBuild.
• substitutions = [] keeps a repo in the composite for navigation while suppressing Gradle's automatic dependency substitution.
• Declared substitutions = [...] are version-qualified from consumer libs.versions.toml files so consumers only route to the sibling when they request the matching module version.
• exclude_siblings = [...] opts a consumer out of a sibling's substitutions. This is used for cases like keeping Grim-public off a heavily patched local packetevents sibling while still allowing composite navigation.

These workspace includeBuild controls affect local development resolution and IntelliJ navigation. They do not add a version-string modifier by themselves.

Notes

• The main branch does not include a branch identifier.
• Modifiers are optional and only included for non-default build settings.
• Multiple modifiers are separated by - within the modifier section.
• The + symbol separates core version information from build metadata.
• ./gradlew printVersion prints the computed project version.