Development Guide¶

This guide covers everything you need to set up a development environment, build the mod, run tests, and work with the multi-version build system.

See also: Contributing for the contribution workflow, Guidelines for code style and conventions.

Prerequisites¶

Note: You do not need to install Gradle — the project includes the Gradle Wrapper (gradlew / gradlew.bat).

Getting Started¶

Clone and Build¶

Windows users: All commands use Unix syntax (./gradlew). On Windows, use WSL 2 (recommended), Git Bash, or replace ./gradlew with gradlew.bat. All scripts in scripts/ require bash — run them via WSL or Git Bash.

# Clone the repository
git clone https://gitlab.com/starshadow/games/minecraft/ansible-crafting.git
cd ansible-crafting

# Build the mod (includes git SHA in version for dev builds)
./gradlew build

Run the Development Client¶

./gradlew runClient

This launches a Minecraft client with the mod loaded. Hot-swap is supported for minor code changes if your IDE is configured for it.

Run the Development Server¶

./gradlew runServer

Build Types¶

flowchart LR
    DEV["./gradlew build"] -->|"includes git SHA"| DEV_JAR["ansiblecrafting-0.1.0+abc1234.jar"]
    REL["./gradlew build -Prelease"] -->|"clean version"| REL_JAR["ansiblecrafting-0.1.0.jar"]

Gradle Task Reference¶

Recommended Pre-Commit Workflow¶

# Format code, then build and test in one command
./gradlew spotlessApply build --no-configuration-cache

The --no-configuration-cache flag is needed because Stonecutter and configuration caching can conflict.

Git Hooks (Optional but Recommended)¶

The project includes git hooks in .githooks/ that automatically enforce formatting and commit message conventions:

To enable the hooks:

# From the ansible-crafting/ directory
git config core.hooksPath .githooks

To disable them later:

git config --unset core.hooksPath

Note: The hooks are opt-in. CI will still catch formatting and commit message issues even without local hooks.

Code Formatting¶

The project uses Spotless with Palantir Java Format for consistent code style.

Key rules: - Tabs for Java indentation, 4 spaces for Gradle - 120-character line length - Import order: java.* → javax.* → net.minecraft.* → net.fabricmc.* → com.ansiblecrafting.* → everything else

# Check formatting (CI will fail if this fails)
./gradlew spotlessCheck

# Auto-fix formatting
./gradlew spotlessApply

Always run spotlessApply before committing. The CI pipeline runs spotlessCheck and will reject improperly formatted code.

Testing¶

The project uses a two-tier testing strategy: fast unit tests for business logic and game tests (Minecraft GameTest Framework) for integration testing inside a headless server.

Test Architecture¶

Unit tests mirror the main source tree structure and mock Minecraft dependencies where needed. On Forge and NeoForge, some tests that require Minecraft bootstrap use assumeTrue guards to skip gracefully when the environment hasn't been initialized (see Bootstrap Guards below). Game tests live under src/main/ because they must be compiled as part of the mod to access the GameTest Framework APIs.

Running Tests¶

Additional useful commands:

# Run a specific test class
./gradlew test --tests "com.ansiblecrafting.config.ModConfigTest"

# Run with verbose output
./gradlew test --info

Test Conventions¶

See Guidelines — Testing for full details. Key rules:

• Naming: methodName_stateUnderTest_expectedBehavior (e.g., scanRange_setToZero_clampsToOne)
• Pattern: AAA (Arrange, Act, Assert) with comments marking each section
• @DisplayName on every test method for human-readable descriptions
• No @Disabled, no @SuppressWarnings — tests must pass or be removed. Exception: assumeTrue is allowed specifically for Minecraft bootstrap guards on Forge/NeoForge (see Bootstrap Guards below).
• Specific assertions (assertEquals, assertNull, assertThrows) over generic assertTrue

Example:

@Test
@DisplayName("scanRange clamps to minimum of 1 when set to 0")
void scanRange_setToZero_clampsToOne() {
    // Arrange
    ModConfig config = new ModConfig();

    // Act
    config.setScanRange(0);

    // Assert
    assertEquals(1, config.getScanRange());
}

Coverage Expectations¶

Adding New Tests¶

Unit test: Create ClassNameTest.java in src/test/java/ mirroring the source structure.

src/main/java/com/ansiblecrafting/crafting/Foo.java
→ src/test/java/com/ansiblecrafting/crafting/FooTest.java

Game test: Add a method to AnsibleCraftingGameTest.java with the @GameTest annotation:

@GameTest(template = EMPTY_STRUCTURE)
@DisplayName("description of what is being tested")
public void featureName_condition_expectedResult(GameTestHelper helper) {
    // Arrange — set up world state using helper

    // Act — trigger the behavior

    // Assert — verify with helper.succeed() or helper.fail()
    helper.succeed();
}

Bootstrap Guards¶

Forge and NeoForge test classpaths include the full Minecraft + loader JARs, which access internal JDK APIs via reflection. The build system configures several accommodations for this:

• forkEvery = 1: Each test class runs in its own JVM process on Forge/NeoForge, preventing a single class-loading failure from killing the entire test executor.
• --add-opens / --add-exports: Extensive module-access flags are passed to the test JVM to prevent InaccessibleObjectException from Forge's class transformers and Mockito/ByteBuddy.
• JAR signature stripping: Forge's universal JAR is cryptographically signed, but NFRT modifies its class files during artifact creation, causing SecurityException on digest mismatches. The build strips META-INF signature files (.SF/.RSA/.DSA) from signed JARs on the test classpath before the test JVM reads them.

Tests that require Minecraft bootstrap (e.g., registry initialization) use assumeTrue to skip gracefully when the environment isn't available:

@BeforeAll
static void checkBootstrap() {
    assumeTrue(
        MinecraftBootstrapReady.check(),
        "Skipping — Minecraft bootstrap not available on this loader"
    );
}

This is the only approved use of assumeTrue — it must not be used for any other purpose.

Known Gaps¶

• Game tests compiled out on NeoForge ≥1.21.10: NeoForge removed @GameTestHolder and changed the GameTest registration API. The entire test body is conditionally compiled out for that target (documented in AnsibleCraftingGameTest.java).
• InventoryStateManagerTest persistence tests compiled out for ≥1.21.10: SavedData.save() and CompoundTag APIs were rewritten in 1.21.10. Persistence tests are conditionally compiled for <1.21.10 only (documented in InventoryStateManagerTest.java).
• Forge game tests excluded in CI: 1.20.1-forge is excluded from the game test matrix due to EMI Forge 1.20.1 SRG mapping incompatibility, which prevents the game test mod from loading. Unit tests still run for this target.

Current Test Inventory¶

Multi-Version Support (Stonecutter)¶

The project uses Stonecutter to support multiple Minecraft versions from a single codebase.

How It Works¶

flowchart TD
    SRC["src/main/java/<br/>Shared source code"] --> SC["Stonecutter<br/>Preprocessor"]
    SC -->|"MC 1.20.1"| V1["versions/1.20.1/<br/>Version-specific overrides"]
    SC -->|"MC 1.20.2+"| V2["versions/1.20.2/<br/>Version-specific overrides"]
    V1 --> JAR1["ansiblecrafting-*-mc1.20.1.jar"]
    V2 --> JAR2["ansiblecrafting-*-mc1.20.2.jar"]

Conditional Compilation¶

Use Stonecutter comment markers for version-specific code:

/*? if >=1.20.2 {*/
// Code for Minecraft 1.20.2 and above
/*?} else {*/
// Code for Minecraft 1.20.1 and below
/*?}*/

Version-Specific Resources¶

Version-specific resource overrides go in versions/<mc-version>/src/main/resources/. These override files in the main src/main/resources/ directory.

Building All Versions¶

./gradlew buildAllVersions

This produces JARs for every configured Minecraft version.

Project Structure¶

ansible-crafting/
├── src/main/java/com/ansiblecrafting/
│   ├── AnsibleCraftingMod.java        # Main mod entry point
│   ├── client/ui/                      # UI components (panels, widgets)
│   ├── config/                         # ModConfig, Cloth Config integration
│   ├── crafting/                       # CraftingSession, CraftingSessionManager
│   ├── integration/                    # Recipe viewer integrations
│   │   ├── emi/                        # EMI plugin
│   │   └── rei/                        # REI plugin
│   ├── inventory/                      # InventoryScanner, AggregatedInventory
│   ├── mixin/                          # Server-side mixins
│   │   └── client/                     # Client-side mixins
│   └── network/                        # Client-server packet definitions
├── src/main/resources/
│   ├── assets/ansiblecrafting/         # Textures, lang files
│   ├── fabric.mod.json                 # Fabric mod metadata
│   └── ansiblecrafting.mixins.json     # Mixin configuration
├── src/test/java/com/ansiblecrafting/  # Unit tests
├── versions/                           # Stonecutter version overrides
├── scripts/                            # Release scripts, splash taglines
├── docs/                               # Technical documentation
├── build.gradle                        # Build configuration
├── gradle.properties                   # Mod metadata and dependency versions
├── stonecutter.gradle                  # Multi-version build config
└── cliff.toml                          # git-cliff changelog config

For a deeper dive into the architecture, see Architecture Overview.

Recipe Viewer Development¶

The mod integrates with both EMI and REI. You can switch which recipe viewer loads in the dev environment by editing gradle.properties:

# Which recipe viewer to load in dev environment (emi, rei, or none)
recipe_viewer = emi

Set to emi, rei, or none and re-run ./gradlew runClient.

Debug Logging¶

For detailed runtime logging during development, see the Debug Logging Guide.

Useful Links¶

• Fabric Wiki
• Fabric API Javadoc (1.20.1)
• Minecraft Wiki
• Stonecutter Documentation
• Spotless Documentation
• JUnit 5 User Guide