FreeMinecraftModels Pets

FreeMinecraftModels can turn a model into a pet species. Players tame pets with food, breed them, bring them along, tell them to stay, and keep them in a collection they open with /fmm pets. Each species is defined by a <species>.pet.yml file that sits beside its model, so a model pack installs, enables and disables its pets together with its models. What a pet does on its own, from following its owner to circling campfires, comes from the Lua behavior modules its file lists. Server-wide pet settings live in pets.yml.

Requirements

• A pet is a hidden vanilla mob carrying the model, driven by MagmaCore's Mind AI. This needs FreeMinecraftModels' NMS support for the server version and Minecraft 1.21.4 or newer. Without it the console logs a line starting with Pets are off: at startup, and /fmm pets answers Pets are not available on this server.
• FreeMinecraftModels ships no pet species. Pets exist only once a model pack or you add a .pet.yml file.
• Players need the generated resource pack, as for any model.

How a pet is built

• The body is the vanilla mob named by body in the pet file, an allay by default. It is hidden inside the model, silent, and never picks up items. Its maximum health is the pet file's health.
• Clicks land on the model players see, not on the smaller body inside it.
• Pets never target anything, and mobs never target pets.
• FreeMinecraftModels' contact damage is off for pets. A pet hurts something only through the sting module.
• A pet that dies drops nothing and gives no experience.
• Pet bodies are never saved with their chunk. Owned pets are re-created beside their owner, and wild pets wait in data/wild_pets.yml (see Wild pets). A pet body left in a chunk after a crash is removed when the chunk loads.
• The model shows the species name above it, with Baby in front for babies.

Pet modes

pets.yml has two modes:

Mode	What happens
COSMETIC (default)	Only pets that players own exist in the world, apart from passing night migrations. Nothing else spawns wild and nothing can be tamed. Owned pets cannot be hurt by anything
CREATURES	Pet species also live wild in the world, spawned like vanilla farm animals, and players tame them by feeding them. Owned pets can be hurt, within the damage rules

Switch the mode with the Pets button in the /fmm setup toolbar, with /fmm petadmin mode creatures or /fmm petadmin mode cosmetic, or by editing mode in pets.yml and running /fmm reload. The button and the command write the new mode to pets.yml.

Switching to COSMETIC sends the wild pets that are alive into data/wild_pets.yml. They come back when the server switches to CREATURES again. Night migrations fly in both modes, but only CREATURES lets players tame a migrant.

In COSMETIC mode players do not tame pets. /fmm petadmin give <species> adds a pet to the collection of the player who runs it. Breeding works in both modes.

Taming

In CREATURES mode a player tames a wild adult by right-clicking it with one of its species' tamingFood items.

• Each feeding uses one item, except in Creative mode.
• Each feeding tames with the chance tameChance, 1/3 by default, as wolves and cats do. A failed feeding shows smoke and tameFailedMessage.
• A tamed pet joins the player's collection and comes out beside them. It keeps the colour variant it had in the wild and plays its interact animation once.
• When the player already has maxEquippedPets pets out, the new pet goes home to the collection instead.
• A species with an empty tamingFood list cannot be tamed.

A lead works on a pet's body as on a vanilla mob.

Breeding and babies

• When the owner right-clicks an adult pet with one of its breedingFood items, it uses one item and puts the pet in love for loveSeconds, 30 by default.
• Two adults of the same species owned by the same player, both in love and within 8 blocks of each other, have a baby. The baby joins the owner's collection and comes out unless the owner is at maxEquippedPets.
• The baby takes one parent's colour variant. It wears babyModel when the species sets one, otherwise its variant model, and is babyScale of the adult size either way.
• Both parents wait breedingCooldownMinutes, 5 by default, before they can breed again. Feeding a parent during that time shows breedingCooldownMessage.
• A baby grows up babyGrowthMinutes, 20 by default, after it was born. The time counts while the baby is at home too, and the adult appears the next time the baby is out.
• Babies cannot breed, and they play no attack animation when they sting.

The parents play their interact animation when a baby is born.

Following, staying and roaming

With the shipped behaviors, an owned pet that is out stays near its owner. The numbers below are the defaults of the follow_owner, stay, drift and hover modules and of the species' follow and float keys:

• Once the owner is farther than follow.distance (5 blocks), the pet follows, aiming 1.5 blocks behind them, and for a flying species float.hoverHeight above their feet. A flyer follows at 5 blocks a second at follow.speed: 1, and at 8 blocks a second past follow.leashDistance (12). It stops following at that spot, or once it is within 3 blocks (0.6 of the follow distance) of its owner.
• Past follow.teleportDistance (24), the pet teleports beside its owner. It also teleports after 3 seconds in a row without getting anywhere: no path toward the owner, a path that ends short of them at a fence or a shore, or a wall in a flyer's way. A catch-up only ever lands a pet nearer its owner, and never puts a walker or swimmer on its owner's own block.
• Within the follow distance a flyer drifts to random points within follow.roamRadius (5) of the owner and bobs in place between drifts, holding float.hoverHeight above the ground, give or take float.hoverVariance. Walking species wander and now and then look at a nearby player; swimming species swim under water.
• When the owner right-clicks the pet with anything other than its breeding food or a lead, it stays where it is, as a dog does, with a gentle bob. The next such click tells it to follow again. Set follow.stay: false to turn this off. Other players' clicks on an owned pet do nothing.

follow.speed multiplies the speed of every shipped behavior except the migration flight. Flying bodies are steered directly. Other bodies walk or swim to the same points with vanilla pathfinding; see Speeds. Pets that do not swim hover over water and lava surfaces instead of sinking to the bottom.

A wild pet roams in the same way around the place it spawned.

Pets that are out leave the world when their owner quits and come out again beside them on the next join. A pet lost to a chunk unload, a world change or a long teleport comes back beside its owner within a second.

The pets menu

/fmm pets opens the player's collection as a chest menu, titled menuTitle. It shows up to 54 pets.

• Each entry shows the species' icon item, with its iconItemModel when the species sets one. Pets that are out glint.
• The lore shows the species, the variant (when it differs from the species model), the age and whether the pet is with the player.
• Clicking an entry brings the pet along or sends it home. Bringing one more than maxEquippedPets along is refused with maxEquippedMessage.
• A player without pets gets noPetsMessage instead of the menu.

The collection is stored on the player, as JSON in the player's persistent data, so it travels with the player's save file and needs no database. A pet whose species is no longer installed stays in the collection with a barrier icon and does not come out.

Damage and death

Pet	Damage
Owned, COSMETIC mode	Ignores all damage
Owned, CREATURES mode	Ignores damage from its owner. Ignores damage from other players while petsInvulnerableToPlayers is true (the default). Other damage applies
Wild	Takes damage like any mob

A left-click on a pet that cannot be hurt does not count as an attack, so the model does not flash red.

When an owned pet dies, it goes home and can be brought out again from /fmm pets. With petsDiePermanently: true it leaves the collection instead. A wild pet that dies is gone.

Wild pets

Wild pets exist only in CREATURES mode. They live like vanilla farm animals: most come with the world as chunks generate, they stay where they are, and they never despawn.

Stocking new chunks

When a chunk generates, FreeMinecraftModels rolls wildGenerationChance (0.01). On a success it places one group of a species, picked by wildSpawn.weight among the species that may stand there, on the surface around a random column. The roll repeats after each group. Values above 0.9 count as 0.9, so a chunk never fills endlessly. Caps, players, time of day and the mob spawning game rule do not limit this stocking.

Top-ups around players

Every wildSpawnIntervalTicks (400, never less than 20), a pass adds wild pets in loaded chunks within 8 chunks of each player who is not in spectator mode:

• Each chunk is tried with the chance wildSpawnChunkChance (0.01).
• A spot must be more than 24 blocks from the nearest player and from the world spawn, and no more than 128 blocks from that player.
• Top-ups stop once wildPetCapPerPlayer (6) wild pets of all species are within 8 chunks of every player near the spot. Each species' wildSpawn.cap (4) limits that species further.
• Top-ups respect the world's mob spawning game rule and each species' wildSpawn.time.

Migrants do not count toward these caps.

Where wild pets wait

When a wild pet's chunk unloads or stops ticking, its species, variant, position and home go to plugins/FreeMinecraftModels/data/wild_pets.yml. It comes back when a player is within 8 chunks of that loaded chunk. The file is written whenever the worlds save and when FreeMinecraftModels shuts down or reloads.

Wild pets of a species that is no longer installed keep waiting in the file. A live wild pet that another plugin removes is gone, as if it had died.

Night migrations

Now and then a flock of a migrating species crosses the night sky over a player and leaves after the crossing. A species migrates when its locomotion is FLYING, its pet file has a migration: section, and its behaviors run migrate, which the FLYING defaults include. When a species has variants, every variant a migrant may wear must run migrate. A species with a migration: section that does not meet these conditions never launches flocks, and logs a warning when it loads unless its migration.weight is 0 or its migration.enabled is false.

• The schedule looks around every 5 seconds in normal (overworld-type) worlds during the night. Each player gets one roll per night against migrations.chancePerNight (0.15). A won roll picks a moment in the rest of the night, early enough for the whole crossing to end by dawn.
• At that moment the flock starts if the player is under open sky, no other flock is within migrations.viewDistance of them, and fewer than migrations.maxActiveFlocks (3) flocks are in the air. Otherwise it tries again until the night runs out.
• A flock has minFlockSize to maxFlockSize members (8 to 14), flies altitude blocks (28) above the higher of the player and the ground under them, at speed blocks per tick (0.15), on a straight path that passes over the player halfway through durationSeconds (90), or earlier when the world's simulation distance is under 12 chunks, since the flock starts where its members still tick.
• Members are ordinary wild pets of the species wearing their full model and animations, at migration.scale times the species size, lit fully bright, and seen from migrations.viewDistance (160) blocks. Clients still need the chunks under the flock within their render distance.
• In CREATURES mode a player who reaches a migrant can tame it, which takes it out of the flock. When the crossing ends, the members still flying are removed.

/fmm petmigrate [species] sends a flock over you at once, whatever the time, the sky or the other flocks. With a species it starts even when that species has no migration: section, but its members only fly the route when they run migrate. Without one, it picks a migrating species by migration.weight.

Migration section

Key	Default	Meaning
enabled	true	false turns the species' migrations off and keeps the other values
model	empty	A fixed model for every member. Empty picks from the species' variants, like a wild spawn
scale	1	Size of a migrant relative to the species scale
animation	empty	An animation to loop while flying. Empty plays the model's own idle and walk
weight	1	How often this species is picked when several migrate. 0 keeps it out of the night schedule

Behaviors

Everything a pet does on its own comes from behavior modules: Lua files in plugins/FreeMinecraftModels/pet_behaviors/. FreeMinecraftModels ships 15 of them and writes each into that folder on startup and on /fmm reload when no file of its name is there. A deleted shipped module comes back on the next load. A module already in the folder is never overwritten, edited or not, so it keeps the version it was written with: delete your copy and reload to get the one your FreeMinecraftModels version ships.

Each pet runs the modules its species file lists, with that species' settings. /fmm reload rereads the modules and the pet files and brings every pet back on them. To change a module or write your own, see Pet Behavior Modules.

The behaviors list

behaviors:
  - migrate
  - stay
  - follow_owner
  - campfire: { radius: 20, night_only: false }
  - drift
  - hover
  - sting:
      effect: POISON
      damage: 1

• Each entry is a module name, which is its file name without .lua, or the name with settings: inline as name: { setting: value }, or on the lines below, indented two spaces past the name.
• A setting the entry leaves out keeps the module's default. The defaults are listed under Shipped modules and at the top of each .lua file.
• A pet runs only what its list names. Leave a module out and the species never does it.
• The order of the list does not decide which behavior runs. Each module's priority does, and a pet file cannot change it: copy the module and change the priority there. The order matters only when two modules clash, in which case the first is kept.
• A module listed twice runs once, with the first entry's settings, and the console warns.

Defaults without a list

A species file without a behaviors: list runs its locomotion's defaults:

locomotion	Default behaviors
FLYING	migrate, stay, follow_owner, drift, hover
GROUNDED, AMPHIBIOUS	stay, follow_owner, wander, idle_look
AQUATIC	stay, follow_owner, swim
STATIONARY	stay, follow_owner

A list replaces these defaults instead of adding to them, so a list that adds a module must also name the defaults it keeps. behaviors: [] runs no modules at all. A behaviors value that is not a list is ignored with a warning, and the species runs its defaults.

Variant behaviors

Write a variant as a map to give the pets wearing it more modules or other settings:

variants:
  - firefly
  - model: firefly_blue
    weight: 0.5
    behaviors:
      - night_glow: { light: 10 }
      - crop_drizzle

• A variant map takes model, weight (default 1) and behaviors. Any other key is ignored with a warning.
• A pet wearing the variant runs the species' list, or its locomotion's defaults, plus the variant's entries. A module that both lists name keeps its place in the species' list and takes the variant's settings on top of the species' ones. The variant's other modules come after the species' own.
• A baby runs its variant's list, even while it wears babyModel.

Setting values

Each setting has the type of its default: a number, true or false, text, or a list of text.

• A value whose meaning is clear is accepted in another form: a quoted number such as "8", "true" or "false" in any case, and a single word for a one-item list.
• A text setting given a number or true/false takes it as YAML read it, so on and yes become true. Put such words in quotes.
• Write a list with brackets, as in [CAMPFIRE, SOUL_CAMPFIRE], or one item per line starting with - . Text that holds commas or spaces is not read as a list.
• A setting the module does not have, a setting with no value, a list with an empty entry, or a value of the wrong type logs a warning that names the pet file, and the default stays. The creature still loads.

Shipped modules

Module	Priority	Kind	What it does
migrate	1	Behavior	Flies a night migration route
stay	5	Behavior	Holds the spot it was told to stay at
follow_owner	10	Behavior	Keeps up with the owner
campfire	15	Behavior	Circles a lit campfire at night
day_perch	18	Behavior	Rests on leaves or the ground by day
rain_bloom	19	Behavior and sensor	Swells, and drifts more, in the rain
drift	20	Behavior	Flies to random points around its anchor
wander	20	Behavior	Walks to standing spots around its anchor
swim	20	Behavior	Swims to spots under water around its anchor
hover	30	Behavior	Bobs in place between drifts
idle_look	30	Behavior	Looks at a nearby player now and then
night_glow		Sensor	Lights the model at night
sting		Sensors	Stings players or hostile mobs that touch it
crop_drizzle		Sensor	Grows the crops it hovers over
owner_effect		Sensor	Gives its owner a potion effect

A behavior with a lower priority number takes over from a running one with a higher number, so following beats campfires and campfires beat drifting. Sensors never move the pet; they run alongside whatever behavior is running.

A pet's anchor is what it roams around: its owner, or for a wild pet the place it spawned. A pet is settled while it is not told to stay and is wild or within follow.distance of its owner.

Speeds

The speed a module asks for is its speed setting times follow.speed. A flying body flies that many blocks per tick, at most 4; 0.05 is one block a second. A walking or swimming body paths there with vanilla navigation at 4 times that number, as a multiplier of its body type's own movement speed, never under a quarter of it. A speed of 0 stands a walker or swimmer still.

migrate

While the pet flies a night migration, it flies its flock's route at the flock's speed, ahead of every other behavior. It stops when the crossing ends or a player tames the pet. A species whose behaviors do not run it never launches flocks. No settings.

stay

After the owner's stay click, the pet holds the spot with a gentle bob. Each bob rests in the body's own medium: in the air for a flyer, on the ground for a walker, under water for a swimmer, which keeps the depth it was told to stay at.

Setting	Default	Meaning
speed	0.03	See Speeds
bob_ticks	40	Ticks between bobs
bob_radius	0.5	Blocks from the spot a bob may move it

The shipped movement behaviors all wait while a pet is told to stay, so a pet without stay in its list gets no bob.

follow_owner

Keeps an owned pet with its owner, as described in Following, staying and roaming. It reads follow.distance, follow.leashDistance, follow.teleportDistance and float.hoverHeight from the species file.

A catch-up teleport lands within 2 blocks of the owner, in the pet's own medium: its hover band for a flyer, standing ground for a walker, water up to 6 blocks out for a swimmer, and ground or else water for an amphibious body. It only lands a pet at least a block nearer its owner than it already is, and a walker or swimmer at least a block away from them. When nothing fits, it tries again after another stuck_ticks.

Setting	Default	Meaning
speed	0.25	Following speed. See Speeds. At 0 the pet keeps up only through catch-up teleports
leash_urgency	1.6	Speed multiplier past follow.leashDistance
trail_back	1.5	Blocks behind the owner the pet aims for
stuck_ticks	60	Ticks in a row without getting anywhere before the pet teleports beside its owner

drift

For flying species. The pet flies to a random point within follow.roamRadius of its anchor, inside its hover band (float.hoverHeight above the ground, give or take float.hoverVariance), then rests.

Setting	Default	Meaning
speed	0.06	See Speeds
drift_ticks	160	Most ticks one drift lasts
stuck_ticks	20	Ticks without moving before a drift gives up
rest_ticks	60	Ticks the pet rests after a drift
rest_random_ticks	80	Adds a random 0 to this value minus 1 ticks of rest

hover

For flying species. While no other movement behavior runs, the pet bobs in place: every bob_ticks it moves up or down by up to half of float.hoverVariance. A pet more than correct_above blocks off float.hoverHeight above the ground heads straight back to that height instead. It looks for the ground up to 12 blocks down.

Setting	Default	Meaning
speed	0.03	See Speeds
bob_ticks	30	Ticks between bobs
correct_above	1.5	Blocks off its hover height at which it heads straight back

wander

For walking species. The pet walks to a standing spot near its anchor, rests, and goes again. A wild pet picks spots within follow.roamRadius of the place it spawned. An owned pet picks spots within follow.roamRadius of its owner and no farther than 0.8 of follow.distance, so following does not start the moment it arrives. A walk ends within 1.5 blocks of its spot, after walk_ticks, or after stuck_ticks without moving. Over water or a long drop, where nothing fits, it waits out a rest and looks again.

Setting	Default	Meaning
speed	0.15	See Speeds
walk_ticks	120	Most ticks one walk lasts
stuck_ticks	20	Ticks without moving before a walk gives up
rest_ticks	80	Ticks the pet rests after a walk
rest_random_ticks	120	Adds a random 0 to this value minus 1 ticks of rest

idle_look

Now and then the pet looks at the nearest player within range for look_ticks, then rests. It takes only the look, so any behavior that moves the pet takes over, and it never looks at players in Creative or Spectator mode. A range of 0 turns it off. A STATIONARY body never turns its look, so its defaults leave this module out.

Setting	Default	Meaning
range	8	Blocks within which it looks at a player
look_ticks	40	Most ticks one look lasts
rest_ticks	100	Ticks between looks
rest_random_ticks	100	Adds a random 0 to this value minus 1 ticks between looks

swim

For swimming species. The pet swims to a spot in water near its anchor, between min_depth and max_depth blocks under the surface, rests, and goes again. It picks spots around its anchor as wander does, and only in water. A swimmer stranded on land waits there; an owned one gets back into water once its owner moves off and follow_owner's catch-up finds water beside them.

Setting	Default	Meaning
speed	0.15	See Speeds
min_depth / max_depth	0.5 / 3	Blocks under the surface, 0 to 16
swim_ticks	120	Most ticks one swim lasts
stuck_ticks	20	Ticks without moving before a swim gives up
rest_ticks	40	Ticks the pet rests after a swim
rest_random_ticks	60	Adds a random 0 to this value minus 1 ticks of rest

campfire

At night, settled pets drift to the nearest lit campfire within radius blocks and circle slowly in its smoke. An owned pet only takes a fire close enough to its owner that circling it never starts the follow. The pet checks once a second that the fire is still lit.

Setting	Default	Meaning
radius	12	Blocks to look for a fire, 1 to 32
height	2.5	Blocks above the fire the pet circles at
ring	0.8	Radius of the circle
night_only	true	Only between dusk and dawn
wild / pets	true / true	Whether wild pets and owned pets gather
blocks	[CAMPFIRE, SOUL_CAMPFIRE]	Fires that count. Only these two work
soul_variants	[]	Variant models drawn only to soul campfires. Every other variant then takes plain campfires only. Empty means any variant takes any listed fire
search_seconds	5	Seconds between looks for a fire. At least 1
speed	0.06	See Speeds

day_perch

By day a settled pet comes down onto the nearest leaves under it, or the ground right below it, and rests there with a faint bob. It lifts off at dusk, when rain falls on it, and when its owner walks out of follow range. An owned pet only takes a perch within follow.distance of its owner. When it finds nothing to sit on, such as water or a long drop, it looks again 5 seconds later.

Setting	Default	Meaning
height	0.3	Blocks above the leaves or ground it rests at, 0 to 8
search_radius	2	Blocks to the side to look for leaves, 0 to 4
wild / pets	true / true	Whether wild pets and owned pets perch
speed	0.06	Speed while more than a block from the perch. See Speeds
settle_speed	0.03	Speed over the last block

rain_bloom

While rain falls on the pet, it swells and drifts around its anchor more often, higher and faster. It shrinks back when the rain stops or it finds cover. Rain falls on a pet during a storm, under open sky, in a biome warm and wet enough for rain. The swelling is a sensor that runs every 4 ticks; the drifting is a behavior with priority 19, so it takes the place of drift in the rain.

Setting	Default	Meaning
scale_multiplier	1.25	Size in the rain, relative to its normal size, 0.1 to 16
scale_seconds	3	Seconds to swell or shrink
drift_frequency	2.5	How many times shorter its rests between drifts are than rest_ticks and rest_random_ticks give, never under 10 ticks
rise	1	Blocks higher it drifts
speed_multiplier	1.4	How many times as fast it drifts
speed	0.06	Drift speed before speed_multiplier. See Speeds
drift_ticks	120	Most ticks one drift lasts
stuck_ticks	20	Ticks without moving before a drift gives up
rest_ticks / rest_random_ticks	60 / 80	The rest that drift_frequency shortens

night_glow

The model's display bones are lit at a fixed light level at night, whatever the light where the pet is. Worlds without a sun count as night. The sensor checks every 2 seconds. Java players only: Bedrock players see the model at world light.

Setting	Default	Meaning
night_only	true	false glows day and night
light	15	Light level, 0 to 15
lantern_bone	lantern	A model with a bone of this name loops animation while it glows
animation	glow	The animation for the lantern bone

sting

A wild pet stings players who touch its model, except in Creative or Spectator mode. An owned pet stings hostile mobs that come within reach of its model's hitbox, and never a player. Adults play their attack animation as they sting. Touches are checked every 4 ticks and nearby mobs every 10.

Setting	Default	Meaning
wild / pets	true / true	Whether wild pets sting players and owned pets sting hostile mobs
effect	SLOWNESS	Potion effect, by name. NONE for no effect
duration_ticks	60	Effect length in ticks, 1 to 6000
amplifier	0	Effect level; 0 is level I
damage	0	Damage per sting, in half hearts
cooldown_seconds	3	Seconds before the same victim can be stung again by this pet
reach	0.5	Blocks away from the model's hitbox at which an owned pet still stings a mob, 0 to 4. Wild stings need the player to touch the model

An effect name that does not exist logs a warning once per species and name, and the sting applies no effect.

crop_drizzle

While the pet hovers still over a crop, a light rain falls on it, and every interval_seconds the crop may grow one stage. Crops are the blocks in Minecraft's crops tag, nether wart and sweet berry bushes. The pet looks straight down through air only. The growth goes out as a BlockGrowEvent, so protection and farming plugins can refuse it. Wild and owned pets alike.

Setting	Default	Meaning
chance	0.1	Chance per interval that the crop grows, 0 to 1
interval_seconds	5	Seconds between tries. At least 1; it is checked once a second, so a fraction waits for the next whole second
depth	4	Blocks below the pet to look for the crop, 1 to 8

owner_effect

While an owned pet is out and within range blocks of its owner, the owner has a potion effect, such as night vision or water breathing. The effect lasts 15 seconds and is renewed every second, so it never flickers, and it wears off within 15 seconds of the pet going home or the owner leaving its range. It shows its icon but no particles. If the owner already has that effect at least as strong and lasting at least as long, such as from a potion they drank, the pet leaves it alone.

It suits steady effects: night vision, water breathing, speed, haste, fire resistance. Effects that act on their remaining time, such as regeneration, poison and wither, misbehave when renewed every second.

Setting	Default	Meaning
effect	NIGHT_VISION	Potion effect, by name
amplifier	0	Effect level; 0 is level I
range	16	Blocks from the pet

Old world interaction sections

Pet files written before behavior modules may have campfire:, rainBloom:, glow:, sting:, dayPerch: or drizzle: sections. They do nothing now, and each one logs a warning when the file loads:

firefly.pet.yml: the campfire section is ignored now that world interactions are behavior modules; list the campfire module under behaviors: instead (see plugins/FreeMinecraftModels/pet_behaviors/campfire.lua for its settings).

A plain glow: true line gets the same warning, worded the glow setting. When the section was switched off (enabled: false, or glow: set to anything but true), or the file already lists its module, the warning only asks you to remove it.

To keep an interaction, list its module and rename its settings:

Old section	Module	Renamed settings
campfire	campfire	nightOnly to night_only, soulVariants to soul_variants, searchSeconds to search_seconds
rainBloom	rain_bloom	scaleMultiplier to scale_multiplier, scaleSeconds to scale_seconds, driftFrequency to drift_frequency, speedMultiplier to speed_multiplier
glow	night_glow	nightOnly to night_only, lanternBone to lantern_bone
sting	sting	durationTicks to duration_ticks, cooldownSeconds to cooldown_seconds
dayPerch	day_perch	searchRadius to search_radius
drizzle	crop_drizzle	intervalSeconds to interval_seconds

The other settings keep their names. Drop enabled: leaving a module out of the list is how you turn it off. A file without a behaviors: list runs only its locomotion's defaults, so list those too. For a flying species that kept its campfire and glow:

behaviors:
  - migrate
  - stay
  - follow_owner
  - campfire: { radius: 12 }
  - drift
  - hover
  - night_glow

migration: stays a section of the pet file; see Migration section.

Lean and centring

Flying and swimming creatures usually look better when they lean with their travel and turn around their own middle:

• orientation sets how the model leans as it travels. UPRIGHT (the default) only faces where it goes. TOP_FIRST leads with its top, like a jellyfish: it leans into its travel, lies on its side cruising and turns upside down to dive. FRONT_FIRST suits birds and fish: it pitches into climbs and dives and banks into turns. Every style settles back upright when the pet stops. See Travel orientation.
• centerOnBody draws the model with the middle of its cubes on the middle of its hidden body, instead of standing on the body's feet. The model then moves, turns and leans around the body, and its click box sits on what players see. It defaults to true for FLYING and AQUATIC species and false for the others. See Centring a model on its body.

Species file reference

Put <species>.pet.yml anywhere under plugins/FreeMinecraftModels/models/, usually beside the model it uses. FreeMinecraftModels reads every file whose name ends in .pet.yml on startup and on /fmm reload. The file name before .pet.yml is the default species ID.

isEnabled: true
species: firefly
model: firefly
name: '&eFirefly'
body: ALLAY
scale: 1.0
health: 20
icon: GLOW_BERRIES
iconItemModel: ''
tamingFood:
  - GLOW_BERRIES
breedingFood:
  - GLOW_BERRIES
tameChance: 0.34
babyModel: ''
babyScale: 0.5
babyGrowthMinutes: 20
breedingCooldownMinutes: 5
loveSeconds: 30
variants:
  - firefly
  - firefly_blue:0.5
follow:
  distance: 5
  leashDistance: 12
  teleportDistance: 24
  roamRadius: 5
  speed: 1.0
  stay: true
float:
  hoverHeight: 1.5
  hoverVariance: 0.75
locomotion: FLYING
centerOnBody: true
orientation:
  style: FRONT_FIRST
  startSpeed: 0.6
  fullSpeed: 4.0
  maxTilt: 180
  turnSpeed: 180
wildSpawn:
  enabled: true
  weight: 10
  minGroup: 1
  maxGroup: 3
  placement: AIR
  minLight: 0
  maxLight: 15
  cap: 4
  worlds: []
  environments:
    - NORMAL
  biomes:
    - minecraft:plains
  time: NIGHT
  minY: -64
  maxY: 320
behaviors:
  - migrate
  - stay
  - follow_owner
  - campfire: { radius: 12 }
  - drift
  - hover
  - night_glow: { light: 15 }
migration:
  scale: 2.0

Identity and appearance

Key	Default	Meaning
isEnabled	true	false skips the file
species	file name	The species ID, lowercased. Players' saved pets and /fmm petadmin use it, so keep it stable once players own pets. When two files define the same ID, the first by path is kept and the console warns
model	file name	The model the pet wears. The console warns when it is not loaded, and the pet cannot spawn
name	file name	Name shown above the pet and in messages. Supports & colour codes
body	ALLAY	The vanilla mob type carrying the model. Its size is what blocks movement
scale	1	Overall size, at least 0.0625
health	20	Maximum health of the body, at least 1
icon	GLOW_BERRIES	Menu icon item
iconItemModel	empty	An item model (namespace:path) from a resource pack for the menu icon
variants	[]	Colour variants, as model, model:weight, or a map with model, weight and behaviors (see Variant behaviors). A wild spawn picks one by weight, a tamed pet keeps its own and a baby takes a parent's. Empty means only model. Variants should share the same bones and animations

Taming and breeding

Key	Default	Meaning
tamingFood	[]	Item names that tame a wild adult
breedingFood	[]	Item names that put an owned adult in love
tameChance	0.333	Chance that one feeding tames
babyModel	empty	Model worn while a baby, at babyScale. Empty uses the variant model
babyScale	0.5	Baby size relative to scale
babyGrowthMinutes	20	Minutes until a baby is an adult
breedingCooldownMinutes	5	Minutes before parents breed again
loveSeconds	30	How long a fed adult waits for a partner

Movement

The follow and float values are read by the shipped behavior modules, as noted.

Key	Default	Meaning
follow.distance	5	follow_owner follows once the owner is farther than this. Within it, the pet is settled and roams freely
follow.leashDistance	12	Beyond this follow_owner hurries
follow.teleportDistance	24	Beyond this follow_owner teleports the pet to its owner
follow.roamRadius	5	How far from its anchor drift, rain_bloom, wander and swim take the pet
follow.speed	1	Multiplies the speed of every shipped behavior except migrate, at least 0.05
follow.stay	true	Whether a right-click tells the pet to stay
float.hoverHeight	1.5	Blocks above the ground a flying pet holds
float.hoverVariance	0.75	How far it strays from that height
locomotion	FLYING	How the body moves: FLYING, GROUNDED, AQUATIC, AMPHIBIOUS or STATIONARY. It also sets the default behaviors
centerOnBody	true for FLYING and AQUATIC	See Lean and centring
orientation.style	UPRIGHT	UPRIGHT, TOP_FIRST or FRONT_FIRST
orientation.startSpeed	0.6	Blocks per second below which the model stays upright
orientation.fullSpeed	4.0	Blocks per second at which it lines up fully with its travel
orientation.maxTilt	180	Most it leans, in degrees. 180 lets a top-first model turn upside down
orientation.turnSpeed	180	Degrees per second its lean can change

Wild spawning

These keys apply only in CREATURES mode. Empty lists allow everything.

Key	Default	Meaning
wildSpawn.enabled	true	Whether the species lives wild
wildSpawn.weight	10	Weight against the other species that may spawn at the same spot. 0 never spawns. A file with the older chance key (0 to 1) and no weight uses chance times 10
wildSpawn.minGroup / maxGroup	1 / minGroup	Group size
wildSpawn.placement	from locomotion	GROUND, WATER, WATER_SURFACE or AIR. FLYING defaults to AIR, AQUATIC to WATER, the rest to GROUND. AIR needs a solid, dry top block and WATER_SURFACE a water top block, each with two free blocks above
wildSpawn.minLight / maxLight	0 / 15	Light level the spot needs
wildSpawn.cap	4	Most wild pets of this species within 8 chunks of a player, for top-ups
wildSpawn.worlds	[]	World names
wildSpawn.environments	[]	NORMAL, NETHER or THE_END
wildSpawn.biomes	[]	Biome keys such as minecraft:plains
wildSpawn.time	ANY	ANY, DAY or NIGHT, for top-ups
wildSpawn.minY / maxY	-64 / 320	Height range

Behaviors and migration

Key	Default	Meaning
behaviors	the locomotion's defaults	The behavior modules the species runs, with their settings. See Behaviors
migration	none	The species' look in night migrations. See Migration section

The old sections campfire, rainBloom, glow, sting, dayPerch and drizzle are ignored with a warning. See Old world interaction sections.

pets.yml reference

plugins/FreeMinecraftModels/pets.yml is generated on first start. /fmm reload applies changes.

Key	Default	Meaning
mode	COSMETIC	COSMETIC or CREATURES. See Pet modes
maxEquippedPets	0	How many pets a player may have out at once. 0 means no limit
petsInvulnerableToPlayers	true	Whether owned pets ignore damage from players other than their owner
petsDiePermanently	false	Whether a pet that dies leaves its owner's collection
wildGenerationChance	0.01	Chance, 0 to 0.9, that a new chunk gets a group of wild pets, rolled again after each group
wildSpawnIntervalTicks	400	Ticks between top-up passes
wildSpawnChunkChance	0.01	Chance that a top-up pass tries a given chunk near a player
wildPetCapPerPlayer	6	Wild pets of all species within 8 chunks of a player at which top-ups stop
migrations.enabled	true	Whether night migrations run
migrations.chancePerNight	0.15	Chance, 0 to 1, that a player gets a flock on a given night
migrations.minFlockSize / maxFlockSize	8 / 14	Flock size
migrations.altitude	28	Blocks above the player or the ground, whichever is higher
migrations.speed	0.15	Blocks per tick (0.15 is 3 blocks a second)
migrations.durationSeconds	90	Seconds from the flock appearing to its removal
migrations.viewDistance	160	Blocks from which players see a flock
migrations.maxActiveFlocks	3	Most flocks in the air at once across the server
migrations.species	[]	Species IDs that may migrate. Empty means every species that can (see Night migrations)

Messages support & colour codes. $pet is the pet's name, and $amount in maxEquippedMessage is the limit.

Key	Default
tamedMessage	&aYou tamed a $pet&a! It follows you now. &f/fmm pets &amanages your pets.
tameFailedMessage	&7The $pet &7eats it, but is not tamed yet.
stayMessage	&7Your $pet &7stays here.
followMessage	&7Your $pet &7follows you again.
menuTitle	&2Your pets
noPetsMessage	&7You have no pets yet. Tame a wild creature by feeding it its favorite food.
equippedMessage	&a$pet &ais with you.
unequippedMessage	&7$pet &7went home.
maxEquippedMessage	&cYou can only have $amount pets with you at once.
breedingCooldownMessage	&7Your $pet &7is not ready to breed again yet.
bornMessage	&aA $pet &awas born!

Commands and permissions

Command	Permission	Default	Purpose
/fmm pets	freeminecraftmodels.pets	true	Opens your pets menu
/fmm petadmin mode [creatures|cosmetic]	freeminecraftmodels.pets.admin	op	Shows the pet mode, or switches it and saves it to pets.yml
/fmm petadmin list	freeminecraftmodels.pets.admin	op	Lists the loaded species with their file, model, body, taming food and breeding food
/fmm petadmin spawn <species>	freeminecraftmodels.pets.admin	op	Spawns a wild pet over the block you look at, up to 12 blocks away. CREATURES mode only
/fmm petadmin give <species>	freeminecraftmodels.pets.admin	op	Adds an adult of the species to your own collection and brings it out, unless you are at maxEquippedPets
/fmm petmigrate [species]	freeminecraftmodels.pets.admin	op	Sends a migration flock over you now. See Night migrations

All three commands are player-only. freeminecraftmodels.pets gates the pets menu, and every player has it by default. freeminecraftmodels.pets.admin gates /fmm petadmin and /fmm petmigrate, defaults to operators and comes with freeminecraftmodels.*. Taming, breeding and telling a pet to stay need no permission.

Troubleshooting

Search the console for pet behavior, pet_behaviors and .pet.yml to find the warnings about behavior modules. Each names the pet file or module file to fix.

The console says Pets are off. The server version has no FreeMinecraftModels NMS support, or it is older than Minecraft 1.21.4.

The console says Pet <species> (<file>) names model <model>, which is not loaded. The model key names a model ID that did not load. A variant whose model did not load logs nothing; pets of that variant wear the species model instead. Check the model's file name, which is its ID, and the reload log for that model.

The console says Could not spawn pet <species>: <cause>. A pet of that species could not come into the world, for the reason given, such as a model that is not loaded, behaviors that could not start, or a body that could not spawn. Each species and cause is logged once until the next reload, however often the spawn is retried.

The console says the <section> section is ignored now that world interactions are behavior modules. The pet file still has an old world interaction section, or a glow: true line, which the warning calls the glow setting. See Old world interaction sections.

The console says there is no pet behavior <name> in pet_behaviors/. The behaviors list names a module that has no file. Check the spelling; the warning suggests the closest name when there is one. The creature loads without that module.

The console says the pet behavior <name> failed to load. The module file has an error. An earlier warning names the file and, for a Lua error, the line. Fix it and run /fmm reload, or delete a broken shipped module so FreeMinecraftModels writes it again.

The console says the pet behavior <module> has no setting <setting>, or <module>.<setting> must be .... A setting in the behaviors list is misspelled or has the wrong type. The warning lists the module's settings or the type it needs, and the default stays. See Setting values.

The console says cannot run alongside the ones listed before it. Two modules in the list cannot run together, usually because both declare the same memory, behavior or sensor, as a copied module listed beside its original does. The first in the list runs and the other is left out. See Pet Behavior Modules.

No wild pets appear. Check that mode is CREATURES and that /fmm petadmin list shows the species. Then check wildSpawn: enabled, a weight above 0, and the worlds, environments, biomes, light and height it allows. Chunks are stocked once, as they generate, so an explored area fills only through top-ups, which are slow by default and stop at the caps. /fmm petadmin spawn <species> places one to check the pet itself.

Players cannot open /fmm pets. They need freeminecraftmodels.pets, which every player has by default unless a permissions plugin takes it away. See Commands and permissions.

No flock ever crosses the sky. Flocks fly at night in overworld-type worlds over players under open sky, and only for FLYING species with a migration: section whose behaviors run migrate. A species that cannot migrate logs has a migration section, but ... at load, with the fix. /fmm petmigrate <species> sends one at once.

A pet does nothing, or stopped doing something after an update. Check its behaviors list: a pet runs only the modules it names, and a list replaces the defaults. A file whose world interactions were sections runs none of them until it lists their modules.

A pet's glow does not show for Bedrock players. The glow lights Java display bones only.