How It Works

How It Works

This page explains exactly what Adventure Item Stats changes, when it changes it, and the math behind the variation. If you just want to play, the short version is: looted weapons and armor come out with slightly randomized stats, centered on vanilla, clamped to ±50%. The rest of this page is for the curious and for designers tuning a modpack.

What gets varied

Four attributes, on items that already have them:

Stat	On	Vanilla attribute
Attack damage	swords, axes, tridents, maces, any weapon with a base damage modifier	minecraft:generic.attack_damage
Attack speed	the same weapons	minecraft:generic.attack_speed
Armor	helmets, chestplates, leggings, boots, turtle shells	minecraft:generic.armor
Armor toughness	the same armor pieces (mainly diamond/netherite)	minecraft:generic.armor_toughness

An item that has none of these four attributes (a fishing rod, a pickaxe, a stack of arrows) is left completely untouched — the mod is a no-op for it.

When it triggers

The mod injects into vanilla's LootTable.getRandomItems(...) — the single method every loot path funnels through. So an item rolls varied stats when it is generated by any loot table:

• ✅ Chest loot (dungeons, villages, strongholds, bastions, …)
• ✅ Mob equipment drops and entity loot
• ✅ Fishing
• ✅ Archaeology (suspicious sand/gravel)
• ✅ Anything a datapack or another mod rolls through a vanilla loot table

It does not trigger for items obtained any other way:

• ❌ Crafted at a table or anvil
• ❌ Spawned with /give or creative inventory
• ❌ Traded from villagers
• ❌ Items already sitting in a world before the mod was installed

This is deliberate: the "feel" of finding a unique piece of loot comes from finding it. A crafted iron sword is a known quantity; a found one is a small surprise.

The Gaussian model

When a weapon or armor piece rolls, each of its target stats is multiplied by a random factor drawn from a normal (Gaussian) distribution:

• Centered on 1.0 — the average roll is vanilla. Most items you find are close to normal.
• Standard deviation σ = 0.20 — about 68% of rolls land within ±20% of vanilla, about 95% within ±40%.
• Hard-clamped to [0.5, 1.5] — no roll can ever be weaker than 50% or stronger than 150% of the vanilla value, so the long tail of the bell curve can't produce a game-breaking outlier.

It scales the effective value, not the raw modifier

This is the subtle but important part. In Minecraft, the number you see on a weapon is player base + item modifier:

• Attack damage has a player base of 1.0; an Iron Sword adds +5, so the tooltip reads 6.
• Attack speed has a player base of 4.0; an Iron Sword adds −2.4, so the tooltip reads 1.6.

The mod multiplies the effective number (the 6, the 1.6) — the value you actually feel in combat — and then writes back the modifier amount needed to produce it. So σ = 20% means ±20% on what the player experiences, not ±20% on the raw +5/−2.4 modifier. Armor and toughness have a player base of 0, so for those the effective value and the modifier are the same thing.

The two-axis model: quality and tradeoff

A weapon has two stats (damage and speed), and rolling them independently would feel random and noisy. Instead the mod rolls two hidden axes and derives the stats from them, so the variation has character.

For each stat group it draws two standard-normal samples:

• g_q — quality. Lifts both stats together. A high-quality sword hits harder and swings faster. A low-quality one is worse at both.
• g_t — tradeoff. Pushes the two stats in opposite directions. A positive tradeoff means more damage but slower; a negative one means less damage but faster.

The stats are then:

damage    = 1 + (g_q + g_t) · (σ / √2)      // > 1 → hits harder
speed     = 1 + (g_q − g_t) · (σ / √2)      // > 1 → swings faster

Armor works identically — quality lifts both, tradeoff favors one over the other:

armor     = 1 + (g_q + g_t) · (σ / √2)      // > 1 → more armor
toughness = 1 + (g_q − g_t) · (σ / √2)      // > 1 → more toughness

The √2 weighting is chosen so that, after combining the two axes, each individual stat still has a standard deviation of exactly σ (20%). The two-axis trick changes the correlation between a weapon's two stats without changing how spread-out either one is on its own.

Reading the axes

g_q (quality)	g_t (tradeoff)	Resulting weapon
high	~0	Great all-rounder — harder and faster
low	~0	Dull blade — weaker and slower
~0	high	Heavy hitter — more damage, slower swing
~0	low	Quick blade — less damage, faster swing
~0	~0	Vanilla — the average roll

Worked example — Iron Sword (vanilla: 6 damage, 1.6 attacks/sec)

These are illustrative rolls, not fixed values:

Roll	Damage	Attack speed	Feels like
Average (g_q≈0, g_t≈0)	6.0	1.6	a normal Iron Sword
Strong quality (g_q≈+1)	~6.8	~1.8	a noticeably better blade
Heavy tradeoff (g_t≈+1)	~6.8	~1.4	hard-hitting but sluggish
Quick tradeoff (g_t≈−1)	~5.2	~1.8	light and fast
Poor quality (g_q≈−1.5)	~4.7	~1.3	a worn-out, second-rate sword

Determinism and the RNG

The mod uses the loot context's own RandomSource — the same RNG vanilla already seeded for that loot roll. It does not create its own randomness. That means rolls are as deterministic as vanilla loot is: if two loot generations share a seed and position, they roll the same stats.

One efficiency detail: if an item only has armor stats (no weapon stats) or vice versa, the mod only draws the Gaussians for the group it needs, so an armor-only item doesn't consume the same amount of entropy as a weapon — keeping the RNG stream tidy.

Composing with Adventure Item Names

Adventure Item Stats and Adventure Item Names hook the same vanilla LootTable codepath, so they stack cleanly. Install both and a single rolled item can carry both a procedurally-generated name and rolled stats — e.g. a Whispering Diamond Blade of Iron that happens to swing 18% faster than a normal Diamond Sword. Neither mod interferes with the other; order doesn't matter.

Current limitation: no idempotency marker yet

As of v0.2.0, a rolled item is not tagged as "already rolled." In normal play this is harmless — the loot hook fires exactly once per generated item. The only way to double-roll is if another mod deliberately feeds an already-generated stack back through LootTable.getRandomItems. Even then, the ±50% clamp bounds how far things can drift. A CustomData "already rolled" marker is planned for v0.3 (see the Roadmap) to make double-rolling impossible.

---

Next: FAQ · Developer API · Installation