Configuration

AstralPets is steered by two files in plugins/AstralPets/: config.yml (behavioural settings, below) and messages.yml (player-facing text, backed by the PetsMessages enum). Pet content itself — blueprints, rarities and food — is not in config.yml; it lives in its own files and is covered on the Pet Blueprints and Pet Food pages. Everything is reloaded together with /pets reload.

`config.yml`

pet-menu-title: "%pet_name%'s Menu"

max-pet-name-length: 16

maximum-presets: 5

skin-confirmation-delay: "10s"

max-active-pets:
  default: 1
  permissions:
    group.roturier: 2

`pet-menu-title`

Field	Type	Description
`pet-menu-title`	ComponentWrapper	Title of the native chest inventory opened for a pet's storage (`PetInventoryMenu`, opened by the `open-pet-container` action). Supports `%pet_name%`. Inventory size is `pet.inventory().size()` rounded up to a full row (min 9, max 54 slots); any slots beyond the pet's own storage size are filled with a `BARRIER` placeholder. Default: `"%pet_name%'s Menu"`.

`max-pet-name-length`

Field	Type	Description
`max-pet-name-length`	int	Default `16`. Enforced by `rename-pet`: a submitted name longer than this is rejected with `pet-name-too-long`, which receives this value as `%maxLength%`. An empty name instead cancels the rename with `pet-rename-cancelled` rather than checking the length.

`maximum-presets`

Field	Type	Description
`maximum-presets`	int	How many presets one player may keep. Checked by `create-preset` before saving; at the cap the player gets `preset-limit-reached`. Default in the shipped file: `5`.

`skin-confirmation-delay`

Field	Type	Description
`skin-confirmation-delay`	Duration	How long a player has to right-click a second time to actually apply a skin. Applying is irreversible and spends the item, so the first click only asks. Zero or negative turns the confirmation off and applies on the first click. A config written before this setting existed defaults to 10 seconds, not to no confirmation.

`max-active-pets`

Caps how many pets a player can have active (equipped) at once, independent of how many pets they own. Checked by the equip-pet action before marking a new pet active; over the cap, the player gets active-pets-limit-reached.

Field	Type	Description
`default`	int	Default `1`. Used when the player holds none of the permissions below.
`permissions`	`Map<String, Integer>`	Permission-node-keyed overrides, e.g. `group.roturier: 2`.

The effective cap, MaxPets#maxPets(Player), is the highest value among every permission the player holds, falling back to default if none match:

maxPets(player) = max { value for (permission, value) in permissions
                         if player.hasPermission(permission) }
               .orElse(default)

Removed blocks

Two blocks that older config.yml files still carry are no longer read at all:

Block	Status
`rename-dialog`	Removed from `PetsConfiguration`. The rename UI is a `DialogBlueprint` (`dialogs/rename.yml`) like every other dialog.
`food-conversion`	Never had a matching component; a leftover of a deleted `ConvertPetFoodAction`, along with the `nothing-to-convert`/`conversion-success` messages, which are also gone from `messages.yml`.

Leaving either in place is harmless — Configurate ignores keys the record does not declare — but they do nothing.

Content files

Pet definitions, rarities and food are configured outside config.yml, each loaded from its own file(s) in the plugin's data folder:

File(s)	Contents
`blueprints/*.yml`	One pet blueprint per file — id, default name, display item, entity template, rarity, effects, max level, accepted skins. See Pet Blueprints.
`rarities.yml`	The rarity ladder (id, display name, `color`, `accent-color`, XP `level-expression`) referenced by blueprints. See Pet Blueprints.
`skins/*.yml`	One skin per file — the look a pet can permanently take on, and the item that grants it. See Pet Skins.
`food/*.yml`	One food blueprint per file — id, item template, experience granted. See Pet Food.
`menus/*.yml`	The `pets-main`, `pet` and `pokedex` menus (standard AstralCore menus).
`dialogs/*.yml`	The `rename`, `preset-create` and `preset-delete` dialogs.
`transformers/*.yml`	Plugin-scoped transformers that render the effect and level-gauge lines a blueprint's lore calls — see Rendering effects.

`messages.yml`

messages.yml is backed by the PetsMessages enum (implementing MessageEnum), loaded via AstralPets#loadEnum. Every value is a MiniMessage ComponentWrapper. The shipped file is French.

Pet lifecycle

Key	Placeholders	Sent when
`pet-added`	`%pet_name%`	A player right-clicks a pet-spawn item, consuming it and adding the pet to their collection (`PetListener`).
`pet-removed`	`%pet_name%`	`pickup-pet` — the pet is converted back into an item and removed from the player's data.
`pet-spawned`	`%pet_name%`	`spawn-pet` succeeded (`EntityService`).
`pet-despawned`	`%pet_name%`	The pet's entity is unregistered, e.g. via `despawn-pet` (`PetDespawnEvent` handling).
`pet-spawn-cancelled`	—	`spawn-pet` — the spawn event was cancelled by another listener.
`pet-spawn-denied-here`	—	`spawn-pet` — blocked at this location by the WorldGuard `pets` flag.
`cannot-equip-identical-pet`	—	`equip-pet` — the player already has an active pet of the same blueprint.

Rename

Key	Placeholders	Sent when
`pet-rename-cancelled`	—	An empty name was submitted to `rename-pet`.
`pet-renamed`	`%oldName%`, `%newName%`	Rename succeeded; both values are `Component`s registered directly.
`pet-name-too-long`	`%maxLength%`	The submitted name exceeds `max-pet-name-length`.

Leveling

Key	Placeholders	Sent when
`pet-level-up`	`%pet_name%`, `%level%`	Once per level gained while feeding a pet (`PetService#gainExperience`); can fire multiple times in one feed.
`pet-max-level`	`%pet_name%`	The pet is already at its blueprint's `max-level` — feeding it further has no effect.
`pet-cannot-be-rode`	`%pet_name%`, `%requiredLevel%`	`ride-pet` attempted on a pet whose `rideable` effect hasn't reached the required level.
`experience-gain-indicator`	`%experience%`, `%experienceToNextLevel%`	Not a chat message — rendered as a short-lived floating text display above the player's view after each feed. Default: `"%experience%/%experienceToNextLevel% XP"`.

Skins

Key	Placeholders	Sent when
`pet-skin-applied`	`%pet_name%`, `%skin_name%`	A skin was applied to a pet.
`pet-skin-already-applied`	`%pet_name%`	The pet already wears this skin (skins stack, but only one of each).
`pet-skin-not-supported`	`%pet_name%`, `%skin_name%`	The pet's blueprint does not list this skin.
`pet-skin-conflict`	`%skin_name%`, `%conflict_*%`	The pet wears a skin this one conflicts with; `%conflict_*%` is the skin already worn.
`pet-skin-confirm`	`%skin_name%`, `%confirmSeconds%`	The first right-click, asking the player to confirm.

Presets

Key	Placeholders	Sent when
`preset-created`	`%preset_name%`	`create-preset` saved the active pets.
`preset-already-exists`	`%preset_name%`	A preset of that name already exists.
`preset-limit-reached`	—	The player is at `maximum-presets`.
`preset-enabled`	`%preset_name%`	`apply-preset` swapped the active pets.
`preset-deleted`	`%preset_name%`	`delete-preset` removed a preset.
`preset-not-found`	—	`delete-preset` on a preset the player no longer has. The shipped text names `%preset_name%`, which is not registered for this message.

Miscellaneous

Key	Placeholders	Sent when
`pet-generated-money`	`%pet_name%`, `%amount%`	The async economy-effect task pays out a `money` pet effect; also renders `%img_icons:coins%`.
`active-pets-limit-reached`	—	See `max-active-pets`.
`pet-not-found`	—	`spawn-pet`/`despawn-pet`/`pickup-pet` referenced a pet id the player doesn't own.
`unexpected-error`	—	An exception was thrown while building the item stack during `pickup-pet`.

Admin — give

Key	Placeholders	Sent when
`give-success`	`%blueprint_name%`, `%player_name%`	`/pets give` delivered successfully.
`give-failed`	`%blueprint_name%`, `%player_name%`	Mailbox delivery failed or the item stack couldn't be built.
`give-food-success`	`%food_item_name%`, `%player_name%`	`/pets food` delivered successfully.
`give-food-failed`	`%food_item_name%`, `%player_name%`	Same failure modes as `give-failed`.
`give-skin-success`	`%skin_name%`, `%player_name%`	`/pets skin` delivered successfully.
`give-skin-failed`	`%skin_name%`, `%player_name%`	Same failure modes as `give-failed`, plus a skin that declares no `item`.

Admin — reload

Key	Placeholders	Sent when
`reloading`	—	Sent to the command sender before `/pets reload` starts.
`reloaded-successfully`	—	Reload completed without an exception.
`reload-failed`	—	An exception was thrown during reload; the stack trace is logged to console.

Reloading

/pets reload calls AstralPets#loadConfiguration(), which reloads, in order: config.yml and rarities.yml, then messages.yml, then skins, pet blueprints (followed by the blueprint-skin cross-check) and food blueprints, then menus, dialogs and transformers, then re-registers the pet, food and skin item suppliers. There is no partial/per-file reload — every /pets reload touches all of it.

Last modified: 25 September 2026