Developer API

Maven coordinates

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

Plugin handle and services

AstralPets is annotated @Getter (Lombok, fluent — no get prefix), so every field below is a same-named accessor:

Registered actions

AstralPets registers 8 actions into AstralCore's action registry (AstralPets#onEnable), usable in any menu, dialog, or actions: list. Arguments are positional, space-separated, and placeholder-resolved at runtime — same convention as AstralCore's own actions.

pet-id in every action except rename-pet is a PlaceholderWrapper<UUID> — a placeholder chain that resolves to the pet's UUID, typically %pet_id% when the action runs from a context whose placeholder subject is already a Pet (e.g. an item in a menu built from %pets_all%/%pets_actives%).

Registered ItemStack suppliers

AstralPets registers two ItemStackSupplier namespaces with AstralPaperAPI.registerItemStackSupplier, making pets and pet food resolvable anywhere AstralCore's CommonRegistries.itemStackSuppliers() registry is consulted:

The /give command (AstralCore's GiveItemCommand) resolves its <itemId> argument with Key.key(itemId) and matches it against every registered supplier's completions(), so both keys work there directly:

Inside an action, dialog, or menu, use the stacksuppliers complex placeholder (ItemStackSupplierPlaceholder) rather than the bare key string — a raw pets:simple literal does not resolve through PlaceholderWrapper<ItemStack> (ItemStackAdapter only accepts an ItemStackPlaceholder, an ItemStack, or an ItemStackWrapper as its input object — a plain String falls through to its AdapterDeserializationException default case), but a full %...% placeholder does, because ItemStackSupplierPlaceholder hands back an ItemStackPlaceholder object, not text:

Both suppliers' completions() are rebuilt on reload() — called once at startup after blueprints load, and again on /pets reload. keyOf(ItemStack) is the reverse lookup: it reads the stack's PDC and returns the pets:<id>/pets.food:<id> key, or null if the stack isn't one of this plugin's items.

Cross-server player data

PetSnapshotAdapter (key astralpets:player_data) is registered with SyncAPI in AstralPets#onEnable, making PetPlayerData a cross-server-synced snapshot for every online player:

equippedSince on each active Pet is a relative offset while the player is offline: apply() (on data load) turns it back into an absolute timestamp, and unload() turns it back into a relative offset before the snapshot is persisted — so effects that scale with "time equipped" keep counting correctly across a server hop.

PetPlayerData itself implements ComplexPlaceholder (namespace pets, sub-keys pets, activePets, selectedPet, hasSelectedPet), but the instance registered globally at root scope is a separate class, PetsPlaceholder — same namespace, different sub-keys (blueprints, equipped, actives, all), reading the executing player's PetPlayerData internally. See Placeholders for the full, consolidated pets_*/pet_* surface.

Mutating PetPlayerData directly (as opposed to going through the actions above) bypasses the equip cap, the identical-blueprint check, and the equip/unequip events — reserve it for admin tooling.

Events

All events extend PetEvent (itself extending AstralCore's AbstractEvent extends org.bukkit.event.Event) and expose pet() — a Lombok fluent getter, no get prefix. Entity-level events additionally extend PetEntityEvent, adding entity() (the PetEntity).

Custom pet effects

Pet effects implement PetEffect:

Implementations are @ConfigSerializable records so a blueprint's effects: list can deserialize straight into them via Configurate — e.g. MoneyPetEffect(Map<Integer, Double> values, Duration interval). The type: key in a blueprint's effect entry is looked up in PetEffectsRegistry:

See Pet Effects for what each built-in type id does in-game and its YAML shape.

WorldGuard integration

WorldGuardHook is only constructed (AstralPets#worldGuardHook) when the WorldGuard plugin is present at onLoad; it registers a custom state flag named pets (default ALLOW) with WorldGuard's FlagRegistry. If a flag named pets already exists under a different type, registration fails and a warning is logged — worldGuardHook()/WorldGuardHook.FLAG_INSTANCE stay usable regardless as long as the conflict didn't happen.

isPetsAllowed returns true whenever FLAG_INSTANCE is null (no WorldGuard, or a registration conflict) — the check only ever denies when the flag explicitly resolves to DENY at that location. Two call sites gate on it:

• spawn-pet checks it directly at the player's location before calling EntityService#spawn, sending PET_SPAWN_DENIED_HERE on denial.

• PetWorldGuardListener re-checks it on every PetSpawnEvent (ignoreCancelled = true) and cancels the event if denied — this is the actual enforcement chokepoint, since every spawn path (manual, on-join respawn, world change, region re-entry) routes through that event, not just the action.

A PetsWGSessionHandler (registered on WorldGuardHook#onEnable) additionally despawns a player's pet entities the moment they cross into a DENY region mid-session, and auto-respawns their selectedPet when they leave one — the movement itself is never blocked, only the pet entity is managed.

Permission nodes

See Commands for the full per-subcommand breakdown.