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
max-active-pets:
default: 1
permissions:
group.roturier: 2
rename-dialog:
title: "Rename %pet_name%"
body: "Enter a new name for %pet_name%:"
name-field: "New Name"
confirm-button: "Rename"
cancel-button: "Cancel"
food-conversion:
"original-item": "apple"
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.
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)
rename-dialog
Field
Type
Description
title
ComponentWrapper
Supports %pet_name%.
body
ComponentWrapper
Supports %pet_name%.
name-field
ComponentWrapper
Supports %pet_name%.
confirm-button
ComponentWrapper
Supports %pet_name%.
cancel-button
ComponentWrapper
Supports %pet_name%.
food-conversion
Field
Type
Description
original-item
String
An item id (e.g. "apple") — originally the item consumed to produce pet food.
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. See Pet Blueprints.
rarities.yml
The rarity ladder (id, display name, color, XP level-expression) referenced by blueprints. See Pet Blueprints.
food/*.yml
One food blueprint per file — id, item template, experience granted. See Pet Food.
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.
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".
Food conversion (unused)
Key
Placeholders
Notes
nothing-to-convert
—
See food-conversion — currently unreachable, no code fires it.
conversion-success
<amount>
Shipped with a raw MiniMessage <amount> tag, not a %amount% placeholder — also currently unreachable.
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%.
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.
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 pet blueprints and food blueprints, then menus and dialogs, then re-registers the pet and food item suppliers. There is no partial/per-file reload — every /pets reload touches all of it.