Version: Minecraft 26.2

Poly Mod Loader — Developer & Contributor Guide

Welcome to the Poly Mod Loader contributor documentation. This guide provides all necessary instructions to clone, build, test, debug, and contribute to Poly Mod Loader.

1. Prerequisites & Environment Setup

Required Tools

Java Development Kit (JDK) 25: Poly Mod Loader is built with and targets Java 25. Recommended: Eclipse Temurin 25 or Microsoft Build of OpenJDK 25.
```
java -version   # Must output java version "25" or higher
```
Git 2.40+

2. Getting the Code & Building

# Clone the repository
git clone https://github.com/xyrz47-spec/Poly-Mod-Loader.git
cd Poly-Mod-Loader

# Verify code formatting and run all unit tests
.\gradlew.bat check

# Build the distribution installer (.jar)
.\gradlew.bat :poly-installer:installerDistributions

Note on Minecraft Assets: On the first run, the build automatically downloads the required Minecraft client/server assets from Mojang's official servers and verifies their integrity against SHA-1 checksums. Minecraft files are cached locally in ~/.gradle/caches/poly-minecraft and are never committed to the repository.

3. Key Gradle Tasks

Task	Target / Action	Notes
`.\gradlew check`	Runs Spotless format checks and all unit test suites across all modules.	Mandatory before submitting any PR or commit.
`.\gradlew test`	Runs fast in-memory unit tests across all submodules.	Runs in < 30 seconds.
`.\gradlew :poly-installer:installerDistributions`	Compiles the standalone multiplatform GUI installer.	Produces `.jar` in `poly-installer/build/libs/`.
`.\gradlew serverBootSmokeTest`	Boots a dedicated server with test mods in a headless environment.	Verifies full server lifecycle.
`.\gradlew worldCreateSaveTest`	Creates a new world, ticks game simulation, and saves level data.	Proves zero data corruption during world saves.
`.\gradlew spotCheckPopularMods`	Validates popular real-world Fabric, Forge, and NeoForge mods.	Matrix testing against real jars.

4. Multi-Module Project Architecture

The codebase is strictly modularized into decoupled layers:

Poly-Mod-Loader/
├── poly-bootstrap/             # Early launch agent, CLI arguments, JVM patch shims
├── poly-mod-metadata/          # Parsers for poly.mod.json, fabric.mod.json, mods.toml
├── poly-runtime-api/           # Public lifecycle and runtime contract interfaces
├── poly-runtime-impl/          # Discovery engine, classloader orchestration, pre-flight assessment
├── poly-transform-api/         # Declarative bytecode transform SPI
├── poly-transform-engine/      # ASM 9.11 bytecode transformer and disk cache engine
├── poly-bridge-api/            # Bridge contract for foreign mod loaders
├── poly-bridge-fabric/         # Fabric Loader API & Quilt Loader shims, Mixin bridge
├── poly-bridge-forge/          # MinecraftForge & NeoForge FML layer virtualizer
├── poly-game-api/              # Version-agnostic game abstractions
├── poly-version-adapter-*/     # Minecraft version-specific mapping adapters (26.1, 26.2, 26.3)
├── poly-game-v*/               # In-engine game implementation hooks (26.1, 26.2, 26.3)
└── poly-installer/             # Multiplatform Swing GUI installer & server setup tool

5. Coding Standards & Guidelines

Java 25 Standards: Use modern Java language features (records, pattern matching, sealed classes, virtual threads where appropriate).
Bytecode Safety: Never assume vanilla Minecraft method signatures remain static across minor releases. Always check with javap or automated bytecode tools before authoring ASM transforms.
Fail-Fast Isolation: When encountering an incompatible foreign mod mixin or bytecode instruction, isolate the mod and output a clear POLY-COMPAT-… diagnostic code instead of allowing an unhandled JVM crash.

1. Prerequisites & Environment Setup​

Required Tools​

2. Getting the Code & Building​

3. Key Gradle Tasks​

4. Multi-Module Project Architecture​

5. Coding Standards & Guidelines​