Create your first Poly Mod

A Poly Mod is a mod built with Poly Mod Loader's Native API that runs on Poly Mod Loader. It is the same kind of name as Fabric mod or Forge mod.

In this tutorial, you build a Poly Mod called Crystal Garden from scratch. You plant a crystal sprout, it grows over time, and using a fully grown sprout gives you a crystal. It takes about 30 minutes.

PREVIEW API (1.0.0)

You start from the mod template on the Poly Mod Loader website, and Gradle downloads Poly Mod Loader from the website's Maven repository. Every API is at the PREVIEW level and can change.

What you build

Feature	Native API	Page
A crystal item and a crystal block	Content declaration, automatic resource generation with polyResources	First block
A crystal sprout that grows in 4 stages	Block state properties, a block entity that ticks every tick, block behavior	Growing block
Per-player and per-world harvest records	Entity data, world storage (synced to the client)	Stored data and commands
/garden stats, /garden grow	Commands, permission nodes	Stored data and commands
Clients without the mod get a notice before joining	Join preparation phase exchange	Join check
Growth display above the sprout, harvest count HUD, hotkey	Block entity rendering, HUD layer, key binding	Client code
Automatic checks of the features	In-game tests (run without a window)	Game tests

All the code uses only the public API (dev.polymodloader.api.*). You need no Minecraft class names, no Mixin, and no separate API mod. So if you write "minecraft": ["26.*"] in poly.mod.json, the mod works on the 26-series versions Poly Mod Loader supports without rebuilding.

Steps

1. Check the requirements — JDK 25
2. Get the mod template — download and unzip one zip
3. Create the project — one initPolyMod line
4. poly.mod.json — mod metadata
5. Entrypoint — CommonModInitializer and ModContext
6. First block — a crystal and a crystal block, automatic resource generation
7. Growing block — block state and block entity
8. Stored data and commands — harvest records, commands, permissions
9. Join check — make the server and client agree on the mod
10. Client code — rendering, HUD, key binding
11. Game tests — check the features without a window
12. Build, run, and distribute — run in game and distribute the jar

If you use IntelliJ IDEA, see IntelliJ IDEA. If you get stuck, see Troubleshooting.

What the finished mod looks like

crystal-garden/
├─ settings.gradle.kts              project name, where Gradle finds Poly Mod Loader
├─ build.gradle.kts                 mod plugin dev.polymodloader.mod, polyResources
├─ src/main/java/com/example/crystalgarden/
│  ├─ CrystalGardenMod.java         common entrypoint: collects the declarations
│  ├─ CrystalSprout.java            the growing sprout block
│  ├─ GardenCommands.java           /garden commands
│  ├─ GardenTests.java              in-game tests
│  └─ CrystalGardenClient.java      client entrypoint
└─ src/main/resources/
   ├─ poly.mod.json                 mod metadata
   └─ assets/crystal_garden/        sprout block state, translations

The finished project is examples/crystal-garden in the Poly Mod Loader source. The source is private for now, so these pages show the code of every file you write.