Crate Files

id

The crate's unique identifier, matched case-insensitively (CrateService#findById). It drives three things:

• The item-supplier key. The plugin registers itself under the crates namespace (AstralPaperAPI.registerItemStackSupplier("crates", ...)), so any AstralCore item reference of the form crates:<id> resolves through CrateItemSupplier to CrateConfiguration#createItemStack(amount).

• The value stored in the key's PDC. createItemStack renders the key item, then tags it with id under the astralcrates:crate PersistentDataContainer key (CrateService.CRATE_KEY). That tag — not the item's material, name, or lore — is what isKeyFor/getCrateKey check to decide which crate a held item opens.

• Hologram entity IDs. Each rendered hologram is registered as <id>_hologram_<index> (one per entry in locations).

key

An ItemStackWrapper — the same schema used by Menu Items → item-stack (material, copy-from, name, lore, append-lore, amount, enchantments, item-flags, plus any item component key such as glow, used above to force an enchant glint without an actual enchantment). createItemStack(amount) resolves this template, applies the PDC tag and amount, and clones the result — that resolved ItemStack is what backs the crates:<id> item-supplier reference and the key-needed message's %item_name% placeholder.

Any copy of a tagged ItemStack opens the crate — key identity is the PDC tag, not object identity, appearance, or amount.

locations

A map of named entries → Location (world, x, y, z, optional yaw/pitch, defaulting to 0). The map key (1 above) is a free-form label used only for YAML organization — it is never read back. Only the block coordinates matter: CrateListener and CrateService#findByLocation compare a clicked block's (rounded) coordinates against every location across every loaded crate.

Vault blocks are recommended — placing the crate on a vanilla Vault block lets AstralCrates fill its built-in item-preview slot (VaultDisplayItemEvent) and cancel its EJECTING state (VaultChangeStateEvent) so the block never dispenses vanilla loot on its own. The click-to-open logic itself does not check block type — it matches purely on coordinates — but the Vault-specific display/eject overrides only apply to actual Vault blocks.

menu

A nested record: id (String), title (ComponentWrapper), size (int). Left-clicking (or any non-right-click interaction) opens this preview via CrateService#openCratePreview, which calls plugin.menus().computeAndOpen(player, menu.id(), Map.of("crate", configuration)) — menu.id must match the id of an actual menu blueprint registered separately, under the plugin's own menus/ folder (the standard AstralCore menu system; see Menu Items). title and size here are metadata only — they are exposed as %crate_menu_title%/%crate_menu_size% (see Placeholders) but do not define the opened menu's real title or size; that is entirely up to the blueprint registered under menu.id. openCratePreview defensively no-ops (opens nothing) if menu is null.

open-menu-title

Not present in the shipped crates/example.yml (shown above for reference only) — this key is not truly optional in practice even though nothing enforces it at the type level beyond the record component not being @Nullable: ComponentWrapperTypeSerializer reads it with a plain node.getString() and passes the result straight to Adventure's MiniMessage#deserialize, which does not tolerate a null input, so omitting the key entirely is expected to fail the whole file's load rather than fall back to an empty title.

A ComponentWrapper — the MiniMessage title of the 27-slot spin-animation GUI opened by CrateOpenMenu when a key is consumed right-click-not-sneaking (Bukkit.createInventory(this, 27, configuration.openMenuTitle().get(...))). This is a different menu from the menu preview block above: this one is the actual reward-spin animation, always exactly 27 slots, built entirely in code (there is no separate blueprint to register). See Opening & Rewards for the spin/shuffle mechanics.

hologram

A ComponentWrapperList — one MiniMessage line per entry. On load, CrateService#createHolograms renders it once per locations entry via AstralHologramAPI.registerTextHologram, positioned 0.5, 1.2, 0.5 blocks above the location's block corner (i.e. roughly 1.2 blocks above the block, centered on it), center-aligned (TextAlignment.CENTER), and BillboardType.FIXED (does not rotate to face viewers). Holograms are only created/cleared when crates-enabled: true in config.yml — see Configuration.

open-actions and win-actions

Both are @Nullable PaperActionList — omit either key entirely for no extra behavior. Neither appears in crates/example.yml.

• open-actions run whenever a key is actually consumed to open the crate:

  • Right-click, not sneaking: once, immediately after removing the key, before the spin menu opens.

  • Right-click, sneaking (bulk-open): once per key held, run immediately after that key's picked reward's own actions — so with 3 keys, open-actions runs 3 times, interleaved with 3 reward payouts.

• win-actions run only on the non-sneaking path, and only once the spin animation lands on a winner (never for the bulk/sneak path, and never if there were no eligible rewards to win). They run with the winning CrateReward registered as a placeholder on the action context, so %reward_item% and %reward_chance% resolve inside win-actions strings (see rewards below for that namespace).

See Opening & Rewards for the full open/win/no-rewards flow and message keys.

rewards

A map of <free-form-id> → reward entry, deserialized by CrateRewardTypeSerializer. Unlike a menu item, a reward's item fields sit directly on the reward node — material, name, lore, etc. are siblings of chance/actions/requirements, not nested under an item-stack key — because the serializer parses the whole reward node as an ItemStackWrapper (node.get(ItemStackWrapper.class)) alongside three other fields read from the same node:

Because the ItemStackWrapper deserializer only reads the keys it recognizes, any other key placed at the reward's top level (like slot above) is silently ignored — see the walkthrough below; the shipped example ships a slot on every reward that has no effect on anything. The map key itself (1, 2, 3) is likewise free-form and never read back.

CrateReward is a ComplexPlaceholder under the reward namespace: %reward_item% and %reward_chance% resolve to the reward's item and its chance weight respectively — usable from win-actions (see above) and from the crate opening menu/placeholders.