Skip to main content

Make mods with the Native API

Make Minecraft 26.2 mods with Poly Mod Loader's Native API instead of the game's internal classes.Declare blocks, mobs, world generation, screens and networking in code, and check them with game tests inside the real game.The API is in preview and can still change.

Make your first modNative API guide
Minecraft
26.2
Java
25
Poly Mod Loader
1.0.0
Stage
stable
RubyMod.java
public final class RubyMod implements CommonModInitializer {
    @Override
    public void onInitializeCommon(ModContext mod) {
        ResourceId ruby = ResourceId.of("ruby_mod", "ruby");
        mod.content().item("ruby", ItemDefinition.builder()
                .creativeTab(CreativeTab.INGREDIENTS)
                .build());

        mod.commands().register(CommandNode.literal("ruby")
                .executes(context -> {
                    context.source().sendMessage("Ruby!");
                    return 1;
                }));

        mod.gameTests().register("ruby_can_be_given", test -> {
            PlayerView player = test.createMockPlayer();
            player.give(ruby, 2);
            test.assertTrue(player.countItem(ruby) == 2, "2 rubies");
            test.succeed();
        });
    }
}

An item, a command and a game test in one entrypoint. No Minecraft types.

Three steps to your first mod

  1. Get the template

    Download the mod template from this site, unzip it, and run initPolyMod with your mod ID. Gradle fetches Poly Mod Loader itself.

    initPolyMod -PmodId=ruby_mod

  2. Declare your mod

    Fill in poly.mod.json and the entrypoint, then declare blocks and items in code.

    build

  3. Check it in the game

    Play it in the client, or run your game tests on a test server without a window.

    gameTests "-PpolyTests=ruby_mod:*"

What you can make with the Native API

Full API reference

Design principles

No game types in the API

Mods see only poly-game-api. Poly Mod Loader's game layer implements it for each Minecraft version.

Failures come with error codes

A wrong declaration fails in its entrypoint, with a POLY-… code that says what to fix.

Checked game patches

Poly Mod Loader changes game code only through declared rules, and refuses rules that conflict.

Buy me a coffee