Rarity YAML Reference

A rarity defines an id and a display item. The id becomes the namespace of every blueprint that references the rarity — Key.key(rarity.id(), blueprint.id) is what ends up in the ItemStack PDC.

Rarities live in plugins/AstralItems/rarities/ (sub-folders are scanned recursively). The file name is irrelevant; the id field inside the file is the identifier.

Minimal example

id: "abyss"

display:
  material: HEART_OF_THE_SEA
  name: "<gradient:#00353D:#11767D><bold>Abîmes"

Top-level fields

Field	Type	Required	Description
`id`	String	Yes	Unique rarity identifier. Becomes the namespace of every blueprint that references it. Duplicates are skipped with a warning.
`display`	`ItemStackWrapper`	Yes	Item shown in UIs that surface the rarity. Standard AstralCore item wrapper — see Menu Items for the full schema.

Referencing a rarity from a blueprint

A blueprint references a rarity by its id:

id: "hammer"
rarity: abyss        # ← matches the `id:` field of rarities/abyss.yml
version: "2.0.3"
display:
  material: DIAMOND_PICKAXE

When the blueprint is deserialised the loader resolves the rarity through RarityService.findByNamespace() (the method name is a hold-over — it actually looks up by id). Blueprint loading fails if the rarity is missing — the file is logged and skipped.

Built-in placeholders

A rarity is itself a placeholder source (ComplexPlaceholder namespace rarity). Access its fields with:

Placeholder	Resolves to
`%rarity_id%`	The rarity id (when invoked from a context where `rarity` is the current scope, e.g. a menu parameter).
`%rarity_display%`	The display `ItemStack` (resolved at render time).
`%rarity_blueprints%`	Iterable of every blueprint registered under this rarity — used by menus to paginate items per rarity.

Validation

The rarity loader rejects entries that fail any of these checks:

The id field is missing or empty.
The display field cannot be parsed as an ItemStackWrapper.
Two rarities share the same id — the duplicate is logged as a warning and skipped.

Errors are logged to the server console. A bad rarity does not prevent the rest from loading.

Hot reload

/items reload re-reads every rarity file from disk and rebuilds the index, then reloads blueprints. Items already in player inventories keep the rarity reference they were created with — only blueprints freshly deserialised pick up new rarity definitions.

Last modified: 25 July 2026