Developer API

AstralItems exposes its services through AstralItems.get() and persists item identity directly on the ItemStack via PDC. Other plugins can build items, resolve items back to their blueprint, register custom item data, listen to HandEquipEvent/AnvilResultEvent, or open the custom anvil for a player.

Maven coordinates

<dependency>
    <groupId>com.astralrealms</groupId>
    <artifactId>items</artifactId>
    <version>2.0-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

Repository: https://maven.astralrealms.fr/repository/maven-public/.

Accessing services

import com.astralrealms.items.AstralItems;

AstralItems plugin = AstralItems.get();

RarityService rarities       = plugin.rarities();
BlueprintService blueprints  = plugin.blueprints();
PipelineService pipelines    = plugin.pipelines();
EventService events          = plugin.events();
AnvilService anvil           = plugin.anvil();
ItemService items            = plugin.items();
SkinService skins            = plugin.skins();
MenuContainer menus          = plugin.menus();

Getter	Type	Use
`plugin.rarities()`	`RarityService`	Look up rarities, list all loaded rarities.
`plugin.blueprints()`	`BlueprintService`	Look up blueprints by `Key`, list by rarity, list every loaded blueprint.
`plugin.pipelines()`	`PipelineService`	Look up the class behind a `type:` string.
`plugin.events()`	`EventService`	Fire a virtual event through the dispatcher (advanced).
`plugin.anvil()`	`AnvilService`	Open the custom anvil for a player.
`plugin.items()`	`ItemService`	Read / write item PDC, test for custom items, upgrade outdated stacks.
`plugin.skins()`	`SkinService`	Look up skins, build skin items, apply / remove a skin on a custom item.
`plugin.menus()`	`MenuContainer`	AstralCore menu container — opens the plugin's `menus/*.yml`.

`RarityService`

Method	Returns	Use
`findByNamespace(String id)`	`Optional<ItemRarity>`	Resolve a rarity by id. (Method name is a hold-over — `id` is the actual lookup key.)
`all()`	`Collection<ItemRarity>`	Iterate every loaded rarity (read-only).
`load()`	`void`	Re-scan `rarities/` from disk.

`BlueprintService`

Method	Returns	Use
`findByKey(Key key)`	`Optional<ItemBlueprint>`	Resolve a blueprint by its composite `Key` (`<rarity-id>:<id>`).
`findByRarity(String id)`	`List<ItemBlueprint>`	Every blueprint registered under a given rarity id.
`keys()`	`Collection<Key>`	Every blueprint key currently registered.
`all()`	`Set<ItemBlueprint>`	Every loaded blueprint (read-only).
`load()`	`void`	Re-scan `blueprints/` from disk and call `PipelineService.initialize()`.

import net.kyori.adventure.key.Key;

plugin.blueprints().findByKey(Key.key("abyss", "hammer"))
    .ifPresent(bp -> getLogger().info("Found " + bp.id()));

`PipelineService`

Method	Returns	Use
`findComponentTypeById(String id)`	`Optional<Class<? extends PipelineComponent>>`	Resolve a pipeline `type:` string to the implementing class.
`initialize()`	`void`	Unregister every dummy listener and rewire all pipelines. Called automatically by `BlueprintService.load`.

`ItemService`

Method	Returns	Use
`fromItemStack(ItemStack stack)`	`Optional<ItemInstance>`	Read the `astralrealms:item` PDC value off any item.
`updateItemStack(ItemStack stack, ItemInstance instance)`	`boolean`	Re-write the PDC with a new instance and refresh the lore. Returns `false` if the stack is air or has no meta.
`updateLore(ItemStack stack, ItemInstance instance)`	`boolean`	Re-render the lore using the blueprint's lore template + current instance state (enchantments, unbreakable, repairable status).
`isCustomItem(ItemStack stack)`	`boolean`	Cheap PDC presence check.
`cannotBeUsed(ItemStack stack)`	`boolean`	`true` when a non-`destroyable` custom item is one tick away from breaking — used by `DurabilityListener` to short-circuit interactions.
`upgrade(ItemStack stack)`	`Optional<ItemStack>`	Rebuild the stack from the current blueprint if its stored version is older. Preserves UUID, damage, unbreakable, amount, and whitelisted enchantments.
`upgradeInventory(Inventory inv)`	`boolean`	Calls `upgrade` on every slot. Returns `true` if any slot was replaced.

plugin.items().fromItemStack(player.getInventory().getItemInMainHand())
    .ifPresent(instance -> {
        getLogger().info(instance.uniqueId() + " -- "
            + instance.blueprint().id() + " v" + instance.version());
    });

The PDC key is exposed as ItemService.ITEM_KEY for callers that need to write the container directly (useful from PersistentDataType implementations):

ItemService.ITEM_KEY; // namespace = "astralrealms", key = "item"

`SkinService`

Method	Returns	Use
`findById(String id)`	`Optional<SkinBlueprint>`	Resolve a skin by id.
`build(SkinBlueprint blueprint)`	`ItemStack`	Render the physical skin item, stamped with the PDC key `astralitems:skin` = the skin id.
`fromItemStack(ItemStack stack)`	`Optional<SkinBlueprint>`	Reverse lookup from a skin item. Empty for air, meta-less stacks, stacks without the tag, and stacks whose stored id is no longer loaded.
`apply(ItemStack stack, ItemInstance instance, SkinBlueprint blueprint)`	`void`	Write the `astralitems:skin` item data, then paint the skin's `model-key` and `armor-asset-key` onto the stack. Does not persist: call `ItemService.updateItemStack` afterwards.
`reapply(ItemStack stack, @Nullable SkinItemData data)`	`void`	Repaint the visuals of an already-skinned stack after a rebuild. Re-resolves the skin by id (falling back to the persisted model key when the id is gone) and no-ops on null / empty data. Called by `ItemFactory.make`.
`unapply(ItemStack stack, ItemInstance instance)`	`void`	Restore the blueprint display's item model and equippable asset — clearing the asset id when the display declares none — and remove the skin item data. Same persistence caveat.
`findByModelKey(@Nullable Key modelKey)`	`Optional<SkinBlueprint>`	The loaded skin whose `model-key` equals this key. Empty for null.
`findOrphanSkin(ItemStack stack, ItemInstance instance)`	`Optional<SkinBlueprint>`	The skin a stack visually wears but has no data for — see Orphan skins. Empty when the stack's model is the blueprint's own default.
`ids()`	`Collection<String>`	Read-only view of every loaded skin id.
`blueprints()`	`Collection<SkinBlueprint>`	Read-only view of every loaded skin.
`load()`	`void`	Re-scan `skins/` from disk.

`AnvilService`

Method	Returns	Use
`open(Player player)`	`void`	Open the custom packet-level anvil window for the given player.

See Anvil for the recompute pipeline and the AnvilResultEvent hook.

Item upgrade

ItemService.upgrade(ItemStack) is the centrepiece of the version-bump migration story: when a player handles a stack whose stored blueprint version is older than the current blueprint version, upgrade rebuilds the display ItemStack from the new blueprint and transfers:

The ItemInstance UUID and item data bag.
Enchantments — clamped against metadata.available-enchantments.
Damage value.
Unbreakable flag.
Stack amount.

The UpgradeListener invokes it on PlayerDataLoadedEvent (from AstralSync), InventoryOpenEvent, and ChunkLoadEvent (for item frames, containers, and shelves in newly loaded chunks).

Plugins that move items between worlds (e.g. cross-server transfer, bank withdraw) can call upgrade explicitly to ensure the item is refreshed before it lands in the destination inventory.

Creating an item

ItemFactory is a static utility that produces a ready-to-use ItemStack from a blueprint or an explicit ItemInstance. Use it to grant items from custom commands, loot tables, quests, etc.

import com.astralrealms.items.factory.ItemFactory;
import com.astralrealms.items.model.blueprint.ItemBlueprint;
import net.kyori.adventure.key.Key;

ItemBlueprint blueprint = plugin.blueprints()
    .findByKey(Key.key("abyss", "hammer"))
    .orElseThrow();

ItemStack stack = ItemFactory.make(blueprint);
player.getInventory().addItem(stack);

ItemFactory.make(blueprint) generates a fresh UUID, copies the blueprint's version onto the instance, copies the blueprint's default-data into the instance, builds the display ItemStack via the blueprint's ItemStackWrapper, applies metadata.maxStackSize (when > 0), serialises the ItemInstance into the PDC, and refreshes the lore.

For more control — for example, restoring an item with an explicit UUID or pre-populated data — use the explicit form:

import com.astralrealms.items.model.item.ItemInstance;
import com.astralrealms.items.model.data.ScalableItemData;
import com.astralrealms.items.model.data.adapter.ScalableItemDataAdapter;
import java.util.HashMap;
import java.util.UUID;

ItemInstance instance = new ItemInstance(UUID.randomUUID(), blueprint, blueprint.version(), new HashMap<>());
instance.setData(ScalableItemDataAdapter.KEY, new ScalableItemData(5, 0));  // start at level 5
ItemStack stack = ItemFactory.make(instance);

ItemFactory.makeInstance(blueprint) builds an ItemInstance without serialising it to an ItemStack — useful when the caller has its own ItemStack to attach the PDC to.

ItemStack PDC layout

Every AstralItems item carries one PDC entry:

Key	Type	Value
`astralrealms:item`	`ItemInstanceDataType`	`ItemInstance` record

ItemInstanceDataType serialises into a nested PersistentDataContainer with six sub-keys:

Sub-key	Type	Value
`astralitems:unique_id`	`UUIDDataType`	Per-item `UUID`.
`astralitems:blueprint`	`ItemBlueprintDataType`	Blueprint `Key` (string `Key.asMinimalString()`). On read, looked up through `BlueprintService.findByKey`.
`astralitems:version`	`ItemVersionDataType`	Semver string `major.minor.patch`. On read, parsed by `ItemVersion.parse`.
`astralitems:data`	nested PDC	Typed item-data bag — each entry serialised by its registered `ItemDataAdapter`.
`astralitems:stats`	`BYTE_ARRAY`	Rolled item stats, written only when the item has stats.
`astralitems:lore_page_index`	`INTEGER`	Current lore page, written only when greater than `0`.

Item stack supplier

The plugin registers itself with AstralCore's shared item-stack supplier registry under the name astralitems:

CommonRegistries.itemStackSuppliers().register("astralitems", new AstralItemsStackSupplier(this));

That registers it alongside AstralCore's own suppliers (vanilla, ce, …). The key the supplier receives is the blueprint's composite Key — <rarity-id>:<blueprint-id>. The supplier:

get(String key) — builds an ItemStack from the blueprint behind the key.
completions() — every blueprint key, for tab completion.
keyOf(ItemStack) — extracts the blueprint Key from a stack's PDC. Lets other plugins normalise an AstralItems stack back to a registry key.

There are two ways to reference a supplied stack from YAML, and neither is <namespace>:<key>:

%stacksuppliers_<supplier>_<key>% — the placeholder form (ItemStackSupplierPlaceholder). This is what /core give's tab completion emits and the only form that works where an ItemStack placeholder is expected, such as the [give-item] action.
<supplier>-<key> — the dashed form, accepted only by nodes deserialized as an ItemStack (AstralCore's ItemStackTypeSerializer splits on the first -). An ItemStackWrapper block's material: key is not one of them: it only takes a Bukkit Material name or a %placeholder%.

# anywhere an ItemStack placeholder is accepted
actions:
  - "[give-item] %stacksuppliers_astralitems_abyss:hammer%"

Skin stack supplier

AstralItems registers a second supplier, always (no plugin-hook gate), for skin items:

CommonRegistries.itemStackSuppliers().register("items.skins", new ItemsSkinStackSupplier(this));

Supplier name	Provider	Registered	Key	Placeholder form
`astralitems`	`AstralItemsStackSupplier`	always	`<rarity-id>:<blueprint-id>`	`%stacksuppliers_astralitems_<rarity-id>:<blueprint-id>%`
`items.skins`	`ItemsSkinStackSupplier`	always	`<skin-id>`	`%stacksuppliers_items.skins_<skin-id>%`

Note that the supplier name itself contains a dot. get(String) builds the skin item for the id (or null), the (Player, Key, int) overload resolves key.value() and then sets the amount, completions() lists items.skins:<id> for every loaded skin, and keyOf(ItemStack) maps a skin item back to that same Key.

actions:
  - "[give-item] %stacksuppliers_items.skins_example%"

Reacting to events

The plugin fires six custom events — see Events:

HandEquipEvent — main-hand change notification.
ItemHoldEvent/ItemUnholdEvent — an item entering / leaving the main hand, filtered so a meta update of the item already held does not re-fire the pair.
ArmorEquipEvent/ArmorUnEquipEvent — armour-slot change notifications.
AnvilResultEvent — fires each time the custom anvil recomputes its result; listeners can override the result and the level cost.

For most reactive behaviour, prefer authoring a pipeline on the blueprint rather than writing a Bukkit listener.

Firing a virtual event

EventService.fireVirtualEvent(Event) reroutes an event through the dispatcher without going through Bukkit's listener pipeline. It returns true if any hooked listener cancelled the event.

This is the mechanism the hammer, fell-tree, replant-crops, break-leaves, and build-wand links use to ask other plugins (claim, logging, protection) about every block they would break or place in their AoE. Only use it when you need that "ask before acting" semantics — calling Bukkit's normal dispatcher is the right choice everywhere else.

BlockBreakEvent virtual = new BlockBreakEvent(block, player);
boolean cancelled = plugin.events().fireVirtualEvent(virtual);
if (!cancelled) {
    // proceed with the block break
}

Registering custom item data

Custom item data adapters extend the typed bag stored alongside each instance. See Item Data for the ItemDataAdapter<T> contract and registration walkthrough.

Last modified: 03 September 2026