Astral Realms Documentation Help

Overview

AstralCrates turns vanilla Vault blocks into loot crates. Server operators place a Vault at a location, register it in a crate YAML file, and give out matching keys; players right-click the block with a valid key to spin a reward-picker menu and win one of the crate's weighted-random rewards.

What it does

  • Crates are physical blocks. A crate definition lists one or more world coordinates, and the plugin matches player interaction to a crate by comparing the clicked block's location against those coordinates — there is no separate "crate entity", the Vault block itself is the crate.

  • Keys are tagged ItemStacks, not a permission or an inventory count. A key carries the crate's id in its PersistentDataContainer under astralcrates:crate, so any copy of the item — however it was obtained — opens that crate.

  • Rewards are weighted-random. Each reward declares a chance (a relative weight, not a percentage) and optional requirements; CrateService picks a winner with a cumulative-weight RandomCollection.

  • Opening plays a spin animation. CrateOpenMenu shuffles the crate's eligible rewards into a 9-slot strip, predetermines the winner, then animates the strip shifting (fast, then decelerating) until the winner lands in the center slot before running its actions.

  • Holograms mark each location. On load, the plugin renders a text hologram (via AstralHologram) 1.2 blocks above every crate location, using the crate's configured hologram lines.

  • Vanilla Vault behavior is overridden. The plugin fills the Vault's built-in item-preview slot (VaultDisplayItemEvent) with a random reward from the crate, and cancels the Vault's own EJECTING state so the block never dispenses vanilla loot on its own — the plugin's key/menu flow is the only way to receive a reward.

  • Keys can't be placed as blocks. KeyListener cancels BlockPlaceEvent for any ItemStack tagged as a crate key.

Requirements

Dependency

Required

Notes

Paper 1.21+

Yes

api-version: '1.21'; crates are the vanilla Vault block type added in 1.21.

AstralCore

Yes

Declared in plugin.yml. Configuration/menu framework, action & requirement lists, placeholders, item-supplier registry, ACF command registration.

AstralHologram

Yes

Declared in plugin.yml. AstralHologramAPI renders/unregisters the text hologram above each crate location.

How a crate opens

CrateListener matches every block interaction against the crate locations map and always cancels the event for a match, then branches on how the player clicked:

Interaction

Behavior

Left-click (or any non-right-click action) on the block

Opens the crate's preview menu (CrateService#openCratePreview) — no key required, nothing is consumed.

Right-click holding an item that is not a valid key for this crate

Sends the key-needed message; nothing happens.

Right-click holding a valid key, not sneaking

Runs the crate's open-actions, removes one key, then opens CrateOpenMenu — the spin animation — which runs the winning reward's actions and, once it lands, win-actions.

Right-click holding a valid key, sneaking

Removes the entire held stack at once and picks one reward per key (CrateService#pickMultipleRewards) — no spin animation, all rewards and open-actions fire immediately per key.

Only main-hand interactions are evaluated (off-hand clicks are cancelled but otherwise ignored). If a crate has no eligible rewards (all filtered out by requirements), the menu path sends the no-rewards message and hands the key back to the player instead of consuming it.

See Opening & Rewards for the full reward/action pipeline and message details.

Configuration & commands

A single global switch in config.yml, crates-enabled, gates the crate system: when false, the plugin skips registering CrateListener entirely (so Vault interactions are no longer intercepted) and skips creating/clearing crate holograms. KeyListener (which blocks placing keys as blocks) is unaffected by the toggle and always registers. See Configuration.

Crate definitions live one-per-file under crates/ (the plugin ships example.yml) and are loaded on enable via configurationManager().loadFolder("crates", CrateConfiguration.class). See Crate Files.

The only command is /crate (alias /crates) with a single subcommand, /crate reload, which reloads the main config, crate definitions, menus, and messages. There is no built-in command to give a key — keys are dispensed through AstralCore's item-supplier system: the plugin registers itself under the crates namespace, so any AstralCore item reference of the form crates:<crate-id> resolves to that crate's key ItemStack (tagged with its astralcrates:crate id). See Commands.

See also

  • Crate Files — the full YAML shape of a crate definition.

  • Opening & Rewards — the reward pool, actions, and message flow in detail.

  • Placeholders — the %crate_*% and %reward_*% placeholder namespaces.

  • Developer API — CrateService, the astralcrates:crate PDC key, and the crates:<id> item-supplier namespace.

Last modified: 25 July 2026
Developer APIConfiguration