Developers Getting Started

Developers — Getting Started

This page is about Advanced Loot Info. For Advanced Worldgen Info, start at Worldgen Info → Overview; the two pages below — Plugin Lifecycle and Tooltips — apply to both mods.

If your mod adds loot entry types, loot conditions, loot functions, custom ingredients, number providers, villager trades or loot modifiers, ALI cannot know how to describe them. Without a plugin it falls back to dumping their JSON under an Auto-detected heading; with a plugin they render like vanilla ones.

ALI itself ships no compatibility shims for individual mods; the separate, optional ALI Compat add-on covers a fixed list of mods that ship none of their own. The supported way to get your content displayed properly is to ship a plugin with your mod.

Depending on ALI

ALI is published on Modrinth and CurseForge. There is no dedicated Maven repository for it, so use one of the usual mirrors (CurseMaven or the Modrinth Maven) and depend on the jar built for your Minecraft version and loader. Keep the dependency optional at runtime — your mod must still load when ALI is absent, which means the plugin class is the only place allowed to touch ALI's API.

The API you compile against spans two jars:

• com.yanny.ali.api — the loot-specific part, from the ALI jar.
• com.yanny.aci.api, com.yanny.aci.tooltip and com.yanny.aci.language (translation keys) — the shared part, from Advanced Core Info (ACI), a separate library mod that ALI requires, published on Modrinth and CurseForge. Add it as a second compile-time dependency, from the same mirrors.

At runtime you do not need to handle ACI separately: ACI is mandatory for ALI, so whenever ALI is present ACI is too, and when ALI is absent your plugin class is never touched.

1.20.1–1.21.1: Mojang's Identifier is called ResourceLocation. API signatures on this wiki use Identifier; substitute ResourceLocation there.

Writing the plugin class

A plugin implements com.yanny.ali.api.IPlugin:

package com.example.mymod.ali;

import com.yanny.ali.api.AliEntrypoint;
import com.yanny.ali.api.IClientRegistry;
import com.yanny.ali.api.ICommonRegistry;
import com.yanny.ali.api.IPlugin;
import com.yanny.ali.api.IServerRegistry;

@AliEntrypoint
public class MyModAliPlugin implements IPlugin {
    @Override
    public String getModId() {
        return "mymod";
    }

    @Override
    public void registerCommon(ICommonRegistry registry) {
    }

    @Override
    public void registerClient(IClientRegistry registry) {
    }

    @Override
    public void registerServer(IServerRegistry registry) {
        // the interesting part, see the Registration Reference
    }
}

getModId() is the mod ID that owns the plugin — ALI uses it to skip plugins whose mod is not loaded.

What each of the three methods is for, and when it runs, is described in Plugin Lifecycle.

Making ALI find the plugin

Discovery differs per loader:

Fabric — entrypoint in fabric.mod.json

{
  "entrypoints": {
    "ali": [
      "com.example.mymod.ali.MyModAliPlugin"
    ]
  }
}

Forge / NeoForge — the @AliEntrypoint annotation

Annotate the class with @AliEntrypoint (as in the example above). ALI scans the mod list for it; nothing else is needed.

Annotating the class on Fabric too is harmless, so a multi-loader plugin can carry both.

Plugins are discovered in unspecified order. Never rely on running before or after another plugin — in particular, do not re-register a type that ALI itself registers and expect your registration to win.

Configuration file format

Worth knowing if you ship a config file with your pack or mod, or generate one: the file is parsed differently depending on the Minecraft version. On 1.20.1 it is read with Gson through a hand-written adapter, and the category's type field is what selects the category class — it is mandatory there. From 1.21.1 on the config is read through codecs, the category kind follows from the list it sits in, and type is neither written nor read (unknown fields are ignored). The user-facing description of the format is in Configuration and Loot Categories.

Getting help

Questions about the API, or a type you cannot get to render: Discord, or an issue if it looks like a bug on ALI's side.

Where to go next

• Plugin Lifecycle — the three registration phases and which side they run on.
• Tooltips — how to build the tooltip content itself (TooltipBuilder), and how lookup/dispatch works.
• Registration Reference — every ALI-specific registration method with an example.
• Nodes and Widgets — when your content needs a custom node in the tree.
• Global Loot Modifiers — Forge/NeoForge GLM support.
• Example: loot conditions and functions — a complete minimal plugin for your own predicates and item modifiers, step by step.
• Example: a custom node — a composite loot entry with its own node and widget.
• Example: a Global Loot Modifier — a complete minimal plugin, step by step.
• Worldgen Info — the same, for Advanced Worldgen Info.