How to Make a Pet

Pets are upgradable companions that float around a player and grant buffs while active. Each pet is one config file that levels up as the player earns pet XP from the triggers you pick. This page covers building a pet from scratch, the structure of its config, and how to test it.

Quick start

Open /plugins/EcoPets/pets/.
Copy _example.yml and rename it to your pet's ID, e.g. tiger.yml.
Set the name, description, icon, and entity-texture.
Set xp-requirements (or xp-formula) and xp-gain-methods so the pet can level up.
Add effects for the buffs the pet grants while active.
Run /ecopets reload.
Give yourself the pet with /ecopets give <player> <id>, then open /pets and activate it to confirm it works.

Naming and IDs

The file name without .yml is the pet's ID. You use this ID in commands, effects, and placeholders. See the Item Lookup System for how IDs resolve across eco plugins.

The structure of a pet

A pet config breaks into a few distinct parts:

Part	What it controls
Display	The name, description, icon, and the in-world pet entity
Progression	The XP needed per level and how the pet earns XP
Placeholders and descriptions	Custom placeholders and the effect/reward text shown in GUIs
Level up	Messages and effects fired when the pet levels up
Effects	The buffs the pet grants while active, plus activation conditions
Spawn egg	An optional craftable or giveable egg that unlocks the pet

Here is one complete pet with every part in place:

# === Display: name, icon, and in-world appearance ===
name: "&6Tiger" # Display name of the pet
description: "&8&oLevel up by dealing melee damage" # Shown in the pet GUIs
# The texture of the pet entity in game
# Option 1: A base64 skull texture value
# Option 2: A vanilla or custom item (prefix with item:)
# entity-texture: item:diamond_sword
# Option 3: A ModelEngine model (prefix with modelengine:)
# entity-texture: modelengine:my_model
entity-texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTA5NWZjYzFlM2Q3Y2JkMzUwZjE5YjM4OTQ5OGFiOGJiOTZjNjVhZDE4NWQzNDU5MjA2N2E3ZDAzM2FjNDhkZSJ9fX0="
icon: player_head texture:eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTA5NWZjYzFlM2Q3Y2JkMzUwZjE5YjM4OTQ5OGFiOGJiOTZjNjVhZDE4NWQzNDU5MjA2N2E3ZDAzM2FjNDhkZSJ9fX0= # Icon shown in GUIs

# === Progression: XP needed per level and how it is earned ===
xp-requirements: # XP to reach each level from level 1; list length is the max level
  - 50
  - 125
  - 200
  - 300
  - 500
  - 750
  - 1000
  - 1500
  - 2000
  - 3500
  - 5000
  - 7500
  - 10000
xp-gain-methods: # How the pet earns XP
  - id: melee_attack
    multiplier: 0.5 # Multiplies the value from the trigger; use "value" for a flat amount
    conditions: [ ]

# === Placeholders and descriptions: custom text shown in GUIs ===
level-placeholders: # Custom placeholders for descriptions; no % in the id, %level% is allowed in value
  - id: "damage_multiplier"
    value: "%level%"
effects-description: # Text shown by %effects%, keyed by the minimum level it shows from
  1:
    - "&8» &8Gives a &a+%damage_multiplier%%&8 bonus to"
    - "   &8melee damage"
rewards-description: # Same as above, but shown by %rewards%
  1:
    - "&8» &8Gives a &a+%damage_multiplier%%&8 bonus to"
    - "   &8melee damage"

# === Level up: messages and effects fired on level up ===
level-up-messages: # Sent on level up, keyed by the minimum level it shows from
  1:
    - "&8» &8Gives a &a+%damage_multiplier%%&8 bonus to"
    - "   &8melee damage"
level-up-effects: # Effects run on level up; %level% is the level just reached
  - id: give_item
    args:
      items:
        - diamond
    every: 5 # Run every 5 levels
    require: '%level% = 5' # Only run at or above level 5

# === Effects: buffs granted while the pet is active ===
effects: # The buffs the pet grants while active; %level% is available
  - id: damage_multiplier
    args:
      multiplier: '%level% * 0.01 + 1'
    triggers:
      - melee_attack
conditions: [ ] # Conditions for the effects to run; %level% is available
activate-conditions: [ ] # Conditions required to activate the pet

# === Spawn egg: optional item that unlocks the pet ===
spawn-egg:
  enabled: true # Whether the pet has a spawn egg
  item: blaze_spawn_egg unbreaking:1 hide_enchants
  name: "&6Tiger&f Pet Spawn Egg"
  lore:
    - ""
    - "&8&oPlace on the ground to"
    - "&8&ounlock the &r&6Tiger&8&o pet!"
  craftable: false # Whether the egg can be crafted
  recipe: [ ]
  recipe-permission: ecopets.craft.tiger # Optional; permission needed to craft the egg
  withdrawable: true # Allow players to withdraw this pet into a tradeable egg via the GUI
  withdraw-price: # Optional cost to withdraw; omit or set enabled: false for free
    enabled: false
    type: coins
    value: 10000
    display: "%value% coins"

Display

Sets the pet's name, description, GUI icon, and the texture of the floating entity.

name: "&6Tiger" # Display name of the pet
description: "&8&oLevel up by dealing melee damage" # Shown in the pet GUIs
# The texture of the pet entity in game
# Option 1: A base64 skull texture value
# Option 2: A vanilla or custom item (prefix with item:)
# entity-texture: item:diamond_sword
# Option 3: A ModelEngine model (prefix with modelengine:)
# entity-texture: modelengine:my_model
entity-texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTA5NWZjYzFlM2Q3Y2JkMzUwZjE5YjM4OTQ5OGFiOGJiOTZjNjVhZDE4NWQzNDU5MjA2N2E3ZDAzM2FjNDhkZSJ9fX0="
icon: player_head texture:eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTA5NWZjYzFlM2Q3Y2JkMzUwZjE5YjM4OTQ5OGFiOGJiOTZjNjVhZDE4NWQzNDU5MjA2N2E3ZDAzM2FjNDhkZSJ9fX0= # Icon shown in GUIs

Progression

Controls the XP needed for each level and how the pet earns that XP. Pick one of two ways to define level requirements: a fixed list, or an infinite formula.

xp-requirements: # XP to reach each level from level 1; list length is the max level
  - 50
  - 125
  - 200
  - 300
  - 500

xp-formula: (2 ^ %level%) * 25 # XP per level, where %level% is the level being calculated; see https://hub.auxilor.io/wiki/eco/math
max-level: 100 # Optional; with a formula there is no max level unless you set one

XP is earned through xp-gain-methods, each a trigger with a multiplier or flat value and optional conditions.

xp-gain-methods:
  - id: melee_attack
    multiplier: 0.5 # Multiplies the value from the trigger; use "value" for a flat amount
    conditions: [ ]

Placeholders and descriptions

Defines custom placeholders and the effect and reward text shown in the GUIs.

level-placeholders: # Custom placeholders for descriptions; no % in the id, %level% is allowed in value
  - id: "damage_multiplier"
    value: "%level%"
effects-description: # Text shown by %effects%, keyed by the minimum level it shows from
  1:
    - "&8» &8Gives a &a+%damage_multiplier%%&8 bonus to"
    - "   &8melee damage"
rewards-description: # Same as above, but shown by %rewards%
  1:
    - "&8» &8Gives a &a+%damage_multiplier%%&8 bonus to"
    - "   &8melee damage"

Level up

Sets the message a player sees and the effects that fire when the pet levels up.

level-up-messages: # Sent on level up, keyed by the minimum level it shows from
  1:
    - "&8» &8Gives a &a+%damage_multiplier%%&8 bonus to"
    - "   &8melee damage"
level-up-effects: # Effects run on level up; %level% is the level just reached
  - id: give_item
    args:
      items:
        - diamond
    every: 5 # Run every 5 levels
    require: '%level% = 5' # Only run at or above level 5

Effects

The buffs the pet grants while active, plus the conditions that gate the effects and activating the pet.

effects: # The buffs the pet grants while active; %level% is available
  - id: damage_multiplier
    args:
      multiplier: '%level% * 0.01 + 1'
    triggers:
      - melee_attack
conditions: [ ] # Conditions for the effects to run; %level% is available
activate-conditions: [ ] # Conditions required to activate the pet

You can make a pet auto-deactivate when its activate-conditions stop being met in Plugin Config.

Spawn egg

An optional item that unlocks the pet when placed, which you can give out or make craftable.

spawn-egg:
  enabled: true # Whether the pet has a spawn egg
  item: blaze_spawn_egg unbreaking:1 hide_enchants
  name: "&6Tiger&f Pet Spawn Egg"
  lore:
    - ""
    - "&8&oPlace on the ground to"
    - "&8&ounlock the &r&6Tiger&8&o pet!"
  craftable: false # Whether the egg can be crafted
  recipe: [ ]
  recipe-permission: ecopets.craft.tiger # Optional; permission needed to craft the egg
  withdrawable: true # Allow players to withdraw this pet into a tradeable egg via the GUI
  withdraw-price: # Optional cost to withdraw; omit or set enabled: false for free
    enabled: false
    type: coins
    value: 10000
    display: "%value% coins"

Withdrawal

Set withdrawable: true to let players withdraw their active pet into a tradeable spawn egg from the pet GUI. The egg carries the pet's current level and XP; whoever redeems it unlocks the pet at the baked level. A confirm GUI prevents accidental withdrawals.

withdrawable: true # Allow players to withdraw this pet into a tradeable egg via the GUI
withdraw-price: # Optional cost to withdraw; omit or set enabled: false for free
  enabled: false
  type: coins
  value: 10000
  display: "%value% coins"

Set withdraw-price.type to coins for an economy cost, or to <id>_pet_level to charge pet levels instead. Remove the withdraw-price block entirely (or set enabled: false) to make withdrawal free.

The egg lore supports these extra placeholders when displaying a withdrawn egg:

Placeholder	Value
`%level%`	The baked level stored in the egg
`%current_xp%`	The baked XP stored in the egg
`%level_numeral%`	The baked level as a Roman numeral
`%level_+N%` / `%level_-N%`	The baked level offset by N, e.g. `%level_+1%`

Internal placeholders

These placeholders are available inside this pet's config (descriptions, messages, effect args).

Placeholder	Value
`%level%`	The player's pet level. Useful for scaling effects
`%level_numeral%`	The player's pet level shown as numerals
`%level_x%`	The player's pet level, +/- a value, e.g. `%level_-1%` is the current level minus 1
`%level_x_numeral%`	The player's pet level, +/- a value, shown as numerals

Where to go next

Configuring effects: Configuring an Effect for the buffs your pet grants.
Plugin config: Plugin Config to customise the GUIs and pet entity.
Default pets: the shipped configs on GitHub.
Community configs: browse user-made pets on lrcdb.