Developer API

Developer API

Adventure Item Stats exposes a single public entry point so other mods with their own loot systems can roll the same varied stats on their items.

If your custom loot already runs through a vanilla LootTable, you get the variation for free — the bundled mixin already covers that path. You only need this API when you generate item stacks outside vanilla loot tables.

The entry point

package games.brennan.adventureitemstats.api;

public final class StatsModifier {
    public static void applyStats(ItemStack stack, RandomSource rng);
}

Usage

import games.brennan.adventureitemstats.api.StatsModifier;
import net.minecraft.world.item.ItemStack;
import net.minecraft.util.RandomSource;

void onMyCustomLootRoll(ItemStack stack, RandomSource rng) {
    StatsModifier.applyStats(stack, rng);
    // `stack` now carries rolled attribute modifiers if it's a weapon or armor.
}

Contract

• Mutates the stack in place. It writes the rolled values to the stack's ATTRIBUTE_MODIFIERS data component. It does not return a copy.
• No-op for irrelevant items. If the stack has none of the four target attributes (attack damage, attack speed, armor, armor toughness), the call returns without doing anything. It's safe to call on any stack.
• Handles armor's default modifiers. Armor pieces usually expose their stats through Item.getDefaultAttributeModifiers() rather than the ATTRIBUTE_MODIFIERS component. applyStats falls back to those defaults so armor stacks roll correctly even when the component is empty.
• Uses the RandomSource you pass in. Pass a seeded source if you need deterministic, reproducible rolls (e.g. per-position or per-seed loot). The bundled loot mixin passes the loot context's own RNG.
• Preserves tooltip visibility. The rebuilt ATTRIBUTE_MODIFIERS component keeps the original showInTooltip flag.

See How It Works for the distribution model (σ, the ±50% clamp, and the two-axis quality/tradeoff system) that governs the rolled values.

Idempotency

As of v0.2.0 there is no "already rolled" marker, so calling applyStats twice on the same stack rolls it twice (compounding the multipliers, still bounded by the per-call ±50% clamp). Call it once per freshly-generated item. A CustomData marker that makes repeat calls a no-op is planned for v0.3 — see the Roadmap.

Depending on the mod

The public surface is the single games.brennan.adventureitemstats.api package. internal.* and mixin.* are not API and may change without a major version bump.

There is no published Maven artifact yet. Until one exists, the practical options are:

1. Soft, reflective dependency — check whether the mod is loaded and call StatsModifier.applyStats reflectively. Your mod then works with or without Adventure Item Stats installed, with no compile-time coupling.
2. Compile against the released jar — add the loader-matched release jar as a local compileOnly / modCompileOnly dependency and mark Adventure Item Stats as an optional runtime dependency in your mod metadata.

If you'd find a published Maven coordinate useful, open an issue on the repo — it's easy to add to the release pipeline.

Stability

Pre-1.0 (the current 0.x line), the API may still change between minor versions as the datapack/config work lands. The applyStats(ItemStack, RandomSource) signature is the most stable part and is expected to carry forward unchanged.