Item Stats

Item stats let a blueprint declare a set of named numeric stats with min/max roll ranges. When an item instance is created, each stat is rolled once to a concrete value and persisted on the item — the same "rolled attributes" pattern found in ARPG loot.

Defining stats in a blueprint

Add a top-level stats: block to a blueprint. Each child node is one stat:

stats:
  attack:                         # decorative id — used only in load error messages
    key: "astralstats:attack_damage"
    min: 5
    max: 10
  crit:
    key: "astralstats:critical_damage"
    min: 1
    max: 3
    context: "melee"              # optional

Field	Type	Required	Description
`key`	`Key`	Yes	Adventure key (`namespace:value`). Meant to match an AstralStats `StatType`, but it is not validated against one.
`min`	number	Yes	Lower bound of the roll (inclusive).
`max`	number	Yes	Upper bound of the roll (exclusive). Must be strictly greater than `min`.
`context`	String	No	Free-form string captured once at roll time and stored on the rolled stat. No consumer reads it yet.

The outer map key (attack, crit above) is decorative — it only appears in load error messages. The stat's real identifier is its key: field.

The roll

Stats are rolled once, when the item is created (ItemFactory.makeInstance). Each roll is a uniform double in the half-open range [min, max), then rounded to two decimals (Math.round(v * 100) / 100, half-up). Fractional stat values are therefore normal — 7.34 is a valid roll of a 5–10 stat.

min >= max throws IllegalArgumentException at item creation — ThreadLocalRandom.nextDouble requires a strictly increasing range, so a fixed stat cannot be expressed as min: 5 / max: 5.
Creating a fresh item from a blueprint rolls new values; a version upgrade preserves the existing rolled stats (they are carried over, not re-rolled).

Persistence

Rolled stats are stored in the item's PDC under the sub-key astralitems:stats (a byte array), alongside the other item-data sub-keys — see Developer API › ItemStack PDC layout. The block is only written when the item actually has stats. Legacy items load with an empty stat set.

Stats are not rendered into lore automatically — any display must be authored with the placeholders below.

Placeholders

Placeholder	Resolves to
`%blueprint_stats%`	Iterable of the blueprint's stat templates (`WrappedStatBlueprint`), wrapped in an `ItemProvider` — pass to a menu layout `provider:`.
`%instance_stats%`	Iterable of the item's rolled stats (`WrappedStat`).
`%instance_stat_<key>%`	Direct lookup of one rolled stat's value (`double`). Resolves to nothing when the item carries no stat under that key.

Rolled stat sub-keys

Both stat shapes use the stat namespace; which one you get depends on which iterable you came from.

Iterating %blueprint_stats% yields the templates (WrappedStatBlueprint):

Placeholder	Resolves to
`%stat_key%`	The stat key.
`%stat_min%`	The roll's lower bound, resolved against the current placeholder context.
`%stat_max%`	The roll's upper bound, resolved against the current placeholder context.
`%stat_context%`	The optional context string, resolved against the current placeholder context.
`%stat_hasContext%`	`true` when a context string is set.

Iterating %instance_stats% yields the rolled stats (WrappedStat):

Placeholder	Resolves to
`%stat_key%`	The stat key.
`%stat_value%`	The rolled value (`double`).
`%stat_context%`	The context string captured at roll time, or empty.
`%stat_hasContext%`	`true` when a context string was captured.

layouts:
  stats:
    provider: "%blueprint_stats%"
    taint: "stat-line"
items:
  stat-line:
    taints: ["stat-line"]
    item-stack:
      material: PAPER
      name: "<gray>%stat_key%: <white>%stat_min%–%stat_max%"

Reading one stat directly

%instance_stat_<key>% looks a rolled stat up by its full key and resolves straight to the rolled value — no iteration needed. Everything after stat_ is rejoined with _ to form the key, so an underscored stat name works as written:

name: "<gray>Attack: <red>%instance_stat_astralstats:attack_damage%"

The lookup returns the value only. To read a stat's context — or to render every stat the item happens to carry — iterate %instance_stats% and use the %stat_*% sub-keys above.

AstralStats relationship

AstralItems declares AstralStats as a plugin dependency (added to plugin.yml depend: and as a provided Maven dependency). Stat keys are meant to mirror AstralStats StatTypes — astralstats:attack_damage, astralstats:armor, astralstats:critical_damage, and so on. The layer that actually applies a rolled item stat to the player through AstralStats' modifier system is not implemented in AstralItems yet.

Astral Realms Documentation Help