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 (inclusive).
`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 integer in the inclusive range [min, max] (both bounds are truncated to int). The stored value is a double, but the rolled result is always a whole number.

min == max always yields that value.
min > max throws at item creation — keep min <= max.
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>%`	The rolled stat for `<key>` (e.g. `%instance_stat_astralstats:attack_damage%`), or empty if the item has no such stat.

When you iterate %blueprint_stats%, each element uses the stat namespace and exposes:

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

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%"

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