Blueprint YAML Reference

A blueprint defines a single collection: its identifier, display item, the items players need to find, and the actions that fire when the collection is completed.

Blueprints live in plugins/AstralCollections/blueprints/ (sub-folders are scanned recursively).

Minimal example

id: "example"

display:
  material: "DIAMOND"
  name: "Example Collection"
  lore:
    - "This is an example collection."
    - "It contains items that are used for demonstration purposes."

completion-actions:
  - "[message] You have completed the Example Collection!"

entries:
  stone: "minecraft:stone"
  diamond: "minecraft:diamond"
  enchanted_book:
    material: "minecraft:enchanted_book"
    enchantments:
      sharpness: 5
      unbreaking: 3

Top-level fields

Field	Type	Required	Description
`id`	String	Yes	Unique blueprint identifier. Duplicates are rejected with a warning.
`display`	ItemStackWrapper	Yes	Item shown in menus and exposed as `%collection_display%`.
`entries`	`Map<String, CollectionEntry>`	Yes	Items to discover. Map key is the entry ID.
`completion-actions`	`List<Action>`	Yes	Actions executed once the player discovers every entry.

`display`

A standard ItemStackWrapper from AstralCore — the same shape used everywhere in menus. Common fields: material, name, lore, enchantments, custom-model-data, attributes, flags. See the Menu Items reference for the full schema.

`entries`

The entries map keys become the entry IDs (stored in the player's progress data). Values can be written in two forms:

Shorthand — a single material or namespaced key:

entries:
  stone: "minecraft:stone"
  obsidian: "minecraft:obsidian"
  custom_sword: "craftengine:legendary_sword"

Expanded — a full ItemStackWrapper for items that require enchantments, NBT, custom-model-data, etc.:

entries:
  enchanted_book:
    material: "minecraft:enchanted_book"
    enchantments:
      sharpness: 5
      unbreaking: 3

  sharp_diamond_sword:
    material: "minecraft:diamond_sword"
    name: "<red>Sharpened Blade"
    enchantments:
      sharpness: 7

`completion-actions`

A PaperActionList executed when the player discovers the last remaining entry. Any registered AstralCore action works here — see Actions for the full catalogue.

completion-actions:
  - "[message] <gold>You completed the <bold>%collection_display_name%</bold> collection!"
  - "[sound] minecraft:ui.toast.challenge_complete"
  - "[console] eco give %player_name% 1000"
  - "[player] particles celebrate"

Actions are scheduled on the main thread immediately after the last entry is recorded. They fire once per player per collection — re-running discovery on an already-completed collection does not re-trigger them.

Validation

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

The entry value cannot be parsed as an ItemStackWrapper.
The blueprint is missing an id field at the top level (entries reference their parent's id).
Two blueprints share the same id — the duplicate is logged as a warning and skipped.

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

Hot reload

/collections reload re-reads every blueprint file from disk and rebuilds the lookup index. Players keep their progress; entries that no longer exist in any blueprint simply stop matching.

When CraftEngine is installed, AstralCollections also reloads automatically after every CraftEngineReloadEvent so custom-item references stay in sync.

Last modified: 25 July 2026