Skip to main content

Developer Guide

Zero to running mod.
Five steps.

This guide assumes basic familiarity with Java. If you can write a class and run a Gradle task, you're ready.

01

Install Prerequisites

You'll need JDK 21+ and an IDE with Gradle support. We recommend IntelliJ IDEA, but any Java IDE works.

terminal
# Verify your Java version
java -version
# Should output: openjdk 21.x.x or higher
02

Scaffold Your Mod

Use the Alloy CLI to bootstrap a new mod project. It pulls the latest template, resolves dependencies, and generates mappings automatically.

terminal
$ alloy init my-first-mod
✓ Scaffolded project from template
✓ Resolved Alloy API 1.0.0
✓ Generated mappings for 1.21.4

$ cd my-first-mod
03

Configure Your Mod

Edit alloy.mod.json in your project root to set your mod's ID, name, version, and description.

alloy.mod.json
{
  "id": "my-first-mod",
  "name": "My First Mod",
  "version": "1.0.0",
  "description": "A mod built with Alloy",
  "entrypoint": "com.example.MyMod",
  "minecraft": "1.21.x",
  "alloy": "1.0.x"
}
04

Write Your Mod

Implement your mod's entry point. The Alloy API provides clean, well-documented hooks into the game.

src/main/java/com/example/MyMod.java
package com.example;

import net.alloymc.api.mod.AlloyMod;
import net.alloymc.api.mod.Mod;
import net.alloymc.api.event.lifecycle.InitEvent;

@Mod("my-first-mod")
public class MyMod implements AlloyMod {

    @Override
    public void onInit(InitEvent event) {
        event.logger().info("Hello from Alloy!");
    }
}
05

Build & Run

One command. Alloy compiles your mod, launches Minecraft, and enables hot-reload so changes appear instantly.

terminal
$ alloy dev
✓ Compiled in 340ms
✓ Hot-reload enabled
⚡ Minecraft 1.21.4 running with my-first-mod@1.0.0

# Make changes to your mod — they reload automatically.
# When you're ready to ship:

$ alloy publish
✓ Built release artifact
✓ Published my-first-mod@1.0.0

You're in.

Explore the API docs, dig through example mods, or jump into Discord where the rest of the community builds in the open.

Read the DocsJoin Discord