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
# Texture of the floating pet entity; use modelengine:id for ModelEngine
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

Display

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

name: "&6Tiger" # Display name of the pet
description: "&8&oLevel up by dealing melee damage" # Shown in the pet GUIs
# Texture of the floating pet entity; use modelengine:id for ModelEngine
entity-texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTA5NWZjYzFlM2Q3Y2JkMzUwZjE5YjM4OTQ5OGFiOGJiOTZjNjVhZDE4NWQzNDU5MjA2N2E3ZDAzM2FjNDhkZSJ9fX0="
icon: player_head texture:eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTA5NWZjYzFlM2Q3Y2JkMzUwZjE5YjM4OTQ5OGFiOGJiOTZjNjVhZDE4NWQzNDU5MjA2N2E3ZDAzM2FjNDhkZSJ9fX0= # Icon shown in GUIs
trail: # A particle trail left behind by the pet as it follows the player
  enabled: false # If the pet should leave a particle trail
  particle: flame # The particle to spawn, as an eco particle string
  gap: 2 # How many ticks to wait between each particle of the trail
  amount: 1 # How many particles to spawn each time
  y-offset: 0.0 # How far above the centre of the pet to spawn the trail

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://plugins.auxilor.io/all-plugins/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

Placeholders in `level-up-effects`

These resolve inside the chain, and describe the level-up that just happened. The chain runsonce per level gained, so an XP grant large enough to cross several levels runs it once foreach level rather than once for the whole grant.

Placeholder	Resolves to
`%level%`	The level just reached.
`%level_numeral%`	The level just reached, as a Roman numeral.
`%previous_level%`	The level before this one, i.e. `%level%` minus 1.
`%previous_level_numeral%`	The previous level, as a Roman numeral.

To react to a pet level-up from an effect somewhere else, use the level_up_pet trigger instead.

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

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.

How to Make a Pet

Quick start

Naming and IDs

The structure of a pet

Display

Progression

Placeholders and descriptions

Level up

Placeholders in level-up-effects

Effects

Spawn egg

Internal placeholders

Where to go next

Placeholders in `level-up-effects`