Blueprint YAML Reference

A blueprint defines a single custom item: its identifier, version, rarity, display appearance, optional metadata, pipelines, and optional default item data.

Blueprints live in plugins/AstralItems/blueprints/ (sub-folders are scanned recursively). The file name is irrelevant; the id field inside combined with the referenced rarity's id forms the item's Key.

Minimal example

id: "hammer"
rarity: abyss
version: "2.0.3"

display:
  copy-from: "%stacksuppliers_ce_items:abyss-hammer%"
  name: "<gradient:#00353D:#11767D><bold>Marteau des Abîmes"
  lore:
    - "%enchantments%"
    - ""
    - "<gray>Breaks blocks in a 3×3 area."
    - ""
    - "%unbreakableStatus%"
    - "%repairableStatus%"

metadata:
  max-stack-size: 1
  repairable: true
  destroyable: false
  available-enchantments:
    efficiency: 7
    fortune: 3
    mending: 1

pipelines:
  mine:
    head:
      type: "block-break"
    links:
      hammer:
        type: hammer
        radius: 3
        depth: 1
      durability:
        type: take-durability
        amount: 1
    tails:
      magnet:
        type: magnet

Top-level fields

Field	Type	Required	Description
`id`	String	Yes	Blueprint identifier. Combined with the rarity id to produce the item's `Key`: `<rarity-id>:<id>`.
`rarity`	String	Yes	Id of an existing rarity in `rarities/`. Loading fails if it does not exist.
`version`	String	No	Semver `major.minor.patch`. Defaults to `1.0.0` when omitted. Stored in the item PDC at creation; bumping it triggers a live re-build the next time the player handles the item (see Item upgrade).
`display`	`ItemStackWrapper`	Yes	Standard AstralCore item template — `material`, `name`, `lore`, `enchantments`, `item-flags`, `durability`, `glow`, … See Menu Items.
`metadata`	`ItemMetadata`	No	Behavioural metadata (see metadata below).
`pipelines`	`Map<String, Pipeline>`	No	Map of pipeline-id → pipeline. Pipeline ids are unique per blueprint, not globally.
`default-data`	`Map<Key, Object>`	No	Default values for the item data registered to the blueprint. Each key resolves through `ItemDataRegistry` to its `ItemDataAdapter`, which deserialises the value.
`stats`	Map	No	Per-item numeric stats rolled once at creation (experimental). See Item Stats.

`metadata`

Field	Type	Default	Description
`max-stack-size`	int	`0`	Override Minecraft's default stack size. `0` keeps the vanilla default; any positive value is applied via `ItemMeta.setMaxStackSize`.
`repairable`	boolean	`false`	If `true`, the `%repairableStatus%` lore placeholder surfaces a message when the item reaches max damage. The custom anvil also uses this to gate enchanted-book combines.
`destroyable`	boolean	`false`	If `true`, the item is consumed when durability hits zero. If `false`, `take-durability` caps damage at `maxDurability - 1` so the item never breaks; the `DurabilityListener` prevents vanilla break attempts.
`tags`	`List<String>`	`[]`	Free-form tags used to filter `drag-and-drop` heads — only cursor items whose blueprint has at least one matching tag are accepted.
`available-enchantments`	`Map<Enchantment, int>`	`{}`	Whitelist + per-enchantment level cap honoured by the custom anvil: books containing other enchantments are rejected, applied levels are clamped to the cap. Also drives the `%enchantments%` lore placeholder rendering.

`default-data`

default-data pre-populates the item data bag every time a new instance is created from the blueprint. Keys must be registered in ItemDataRegistry; values are deserialised by the registered ItemDataAdapter.

default-data:
  "astralitems:stored-material":
    material: AIR
  "astralitems:scalable":
    level: 1
    experience: 0

The first key matches StoredMaterialItemDataAdapter (used by tools like the spade and mallet to remember the block the player loaded onto them). The second matches ScalableItemDataAdapter (used by levelling items).

`stats`

stats declares numeric stats that are rolled once when the item is created and persisted on the instance. Each entry has a key, a min/max roll range, and an optional context:

stats:
  attack:                         # decorative id
    key: "astralstats:attack_damage"
    min: 5
    max: 10

See Item Stats for the roll rules, persistence, placeholders, and the current (experimental) status of the feature.

`version`

The blueprint version is captured by the item at creation and persisted in PDC. When the player handles an item whose stored version is older than the blueprint's current version, the UpgradeListener calls ItemService.upgrade(stack) — it rebuilds the display from the new blueprint while preserving the item's UUID, enchantments, damage, amount, and unbreakable flag. See Developer API.

version: "2.0.3"

Map-form (major: 2, minor: 0, patch: 3) is also accepted by the deserialiser, but the string form is preferred.

`pipelines`

The pipelines block is a map of pipeline id → pipeline definition. Every pipeline has the same three sections:

pipelines:
  <pipeline-id>:
    head:                   # exactly one head — captures a Bukkit event
      type: "<head-type>"
      …head-specific fields
      requirements:         # optional, AstralCore PaperRequirementList
        - …
    links:                  # optional map of <link-id> → chain link
      <link-id>:
        type: "<link-type>"
        …link-specific fields
    tails:                  # optional map of <tail-id> → terminal step
      <tail-id>:
        type: "<tail-type>"
        …tail-specific fields

Inside links and tails the map key is a free-form id used only for ordering and config tooling. Order follows the YAML insertion order — chain links run top-to-bottom, then tails run top-to-bottom.

A blueprint may declare multiple pipelines — for example a spade that has one pipeline for drag-and-drop (to store the seed loaded by the player), one for interact → plant-crops, and a third for interact → spade-grass.

See:

Pipelines Overview — execution model and lifecycle
Pipeline Heads — every available head.type
Pipeline Links — every available link type
Pipeline Tails — every available tail type

Per-component requirements

Every wrapped pipeline component (head, link, or tail) can optionally carry a requirements block evaluated against the player and the current PipelineContext (which exposes item, location, block, entity, drop, and extra-context placeholders):

links:
  durability:
    type: take-durability
    amount: 1
    requirements:
      - "permission:items.use-hammer"
      - "stat:level >= 5"

Requirements use AstralCore's PaperRequirementList. When a head's requirements fail the event is cancelled and the rest of the pipeline is skipped; when a link or tail's requirements fail the component is silently skipped and the next one runs.

Validation

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

Missing or empty id — file is logged and skipped.
Missing or empty rarity, or a rarity that is not registered.
display cannot be parsed as an ItemStackWrapper.
A pipeline references a type that is not registered with PipelineService — see Pipeline Heads / Links / Tails for the registry.
A default-data key is not registered in ItemDataRegistry.
Two blueprints resolve to the same Key (rarity:id) — the duplicate is logged as a warning and skipped.

A bad blueprint does not prevent the rest from loading.

Hot reload

/items reload clears the blueprint registry, re-reads every file from blueprints/, and calls PipelineService.initialize() which:

Unregisters every dummy listener previously registered with Bukkit.
Walks every blueprint's pipelines.
Registers a fresh listener per (EventPriority, Event) pair and inserts the freshly deserialised pipelines into the right EventNode.

CraftEngine triggers the same reload path automatically when it fires CraftEngineReloadEvent (which is also the trigger for the very first blueprint load on server boot).

Item upgrade

When a player handles a stack whose stored blueprint version is older than the current blueprint version, ItemService.upgrade(stack) rebuilds the ItemStack from the new blueprint and transfers:

The ItemInstance UUID.
Enchantments — capped against metadata.available-enchantments.
Damage value.
unbreakable flag.
Stack amount.

Upgrades fire on PlayerDataLoadedEvent (from AstralSync), InventoryOpenEvent, and ChunkLoadEvent (for item frames, containers, and shelves in newly loaded chunks).

Last modified: 25 July 2026