Content

Entities

A custom entity is a real Minecraft mob that wears one of your models: a temple guard, a rhino, a boss. Its AI and pathing are a vanilla mob's, so it fights, wanders and dies like one, but it looks like your model, plays an animation for whatever it is doing, and has the stats, sounds and name you give it.

# entities/mobs.yml
rhino:
  type: POLAR_BEAR        # required. Chosen for behaviour: the looks are replaced
  model: zoo:rhino        # assets/models/rhino.bbmodel, or an item id
  name: "&7Rhino"
  health: 40
  damage: 6
  speed: 1.2
  scale: 1.0
  height: 1.4
  head-bone: head
  tags: [zoo]
  animations:
    spawn: appear
    idle: idle
    walk: walk
    run: gallop
    attack: charge
    hurt: flinch
    death: fall
  sounds:
    ambient: zoo:grunt
    hurt: zoo:ouch
    death: entity.cow.death
  drops:
    - {item: minecraft:leather, min: 1, max: 3}
    - {item: zoo:horn, chance: 0.25}
  xp: 5

To make one:

1. In your content folder (here zoo), save the Blockbench model as assets/models/rhino.bbmodel.
2. Write the mob in entities/, as above. model: zoo:rhino names that file (<content folder>:<file>). You don't need an item for it.
3. Run /rp reload, then /rp spawn zoo:rhino spawns one where you stand. /rp entities lists them all.

model: can also name an item that wears the model, and several mobs can wear one model. If it names neither a model nor an item, the mob spawns as the plain vanilla mob and /rp reload warns about it.

Needs RP Engine 0.2.51 or newer; skills, the options under More options, drop tables and spawners need 0.2.53.

Everything a mob takes#

The fields that came over from MythicMobs (armour, equipment, levels, factions, templates and the rest) are under More options.

Choosing the type#

Pick type for how it should behave, not how it should look. A zombie hunts players, a polar bear wanders and fights back, an iron golem guards, a pig wanders and runs when hit, an allay drifts, a phantom swoops, an armour stand does nothing at all. It must be a mob that can be spawned.

It is genuinely that mob: every other plugin sees it as one, and tags are how the rest of your server finds yours: @e[tag=zoo] in a command block, a condition in another plugin, or a /kill that clears one kind and not another.

A custom mob is never bred, tamed, ridden, sheared, milked or traded with, never spawns as a baby or with a jockey, and never turns into something else (a drowned zombie, a struck pig). A name tag and a lead still work on it, unless prevent: says otherwise.

How the model is worn#

The mob's own body is made invisible, not removed, so players hit it where the model appears to be.

The model stands on the ground the mob stands on: its bottom (pixel 0 in Blockbench) is at the mob's feet, whatever the type and size. scale: sizes only the model. height: sizes the hitbox, and its width grows with it; that needs 1.20.5 or newer, and older servers keep the mob's own box.

A custom mob you spawn never despawns, unless you say so with despawn:. One that spawned on its own despawns like the mob it replaced. Whenever a mob wearing a model goes without dying (despawned, removed on peaceful, removed by another plugin), its model goes within a tick or two.

Facing#

At turn: 0 the side Blockbench calls North (-Z) is the front, as in ModelEngine, so a model made for ModelEngine walks forwards unchanged.

Mobs made in Studio are turned for you. /rp bind and MythicMobs' rpmodel have no turn:, so a model you put on somebody else's mob should be drawn facing North.

The head#

head-bone: names a bone that turns toward whatever the mob is targeting, as an h_ bone does. The bone has to move in at least one animation: a bone that never moves is drawn as part of the still body and has nothing of its own to turn.

A model's other bones work too: b_ bones are hitboxes of their own, p_ bones are seats, and tag_name is where the name floats. See Bones that do something.

Hurt flash#

When it takes damage the model goes red for about a third of a second, as a vanilla mob does (a red outline instead for a still model, or on servers older than 1.21.4). hurt-flash: false turns it off.

Animations#

animations: maps each state to one of the model's animations, by name. The states, most important first:

When several apply, the one higher in the list plays. A once animation plays to its end and the mob goes back to what it was doing; only a more important one cuts it short, so a mob hit mid-bite keeps biting, and a mob killed mid-bite falls over.

A blank loop falls through: with no run it walks, with no walk it idles, with no idle it stands in its rest pose. A blank once-animation simply doesn't play, and neither does a state naming an animation the model doesn't have.

Animations can also be played from a skill (animate), and a skill can change which animation a state plays from then on (defaultstate), for a boss that limps once it is badly hurt.

Sounds#

  sounds:
    ambient: zoo:grunt      # every 8 to 20 seconds while somebody is near
    hurt: zoo:ouch
    death: entity.cow.death # a vanilla sound event works too
    attack: zoo:snort
    step: zoo:thud

Each is a sound from a pack (zoo:grunt) or a vanilla sound event. Setting any of them silences the mob's own sounds, so a rhino built on a polar bear does not growl like one.

Its name#

The name floats just above the model, not over the hidden body: at the model's top, or at its tag_name bone if it has one, whatever the type and scale:.

name-visible: true shows it always. false shows it only to a player whose crosshair is on the mob, within reach and not through a block, as vanilla does for a named mob. Unlike a vanilla name it is not drawn through walls, so it never vanishes inside the model. & colours and <fx:...> Text Effects work in it.

A name can carry live values, kept current until a name tag renames the mob:

name: "&6Golem King &7{hp}/{max_hp}"

A name tag, /data or a plugin renaming the mob changes it within half a second, and the name goes the moment the mob dies.

Boss bars#

golem:
  type: RAVAGER
  model: mypack:golem
  name: "&2Moss Golem"
  boss-bar: {color: GREEN, style: SEGMENTED_10, range: 40}

A boss bar with the mob's name (its name tag's, else its id) and health, shown to every player within range blocks.

boss-bar: true is all the defaults. A skill can also put up bars of its own with barcreate, for a boss with a shield bar beside its health.

A mob that shoots#

archer:
  type: SKELETON
  model: mypack:mushroom
  ranged:
    projectile: snowball   # arrow, snowball, small_fireball, fireball, wither_skull, trident
    damage: 3              # per hit; 0 keeps the projectile's own
    range: 18              # blocks, 2 to 64
    cooldown: 2            # seconds between shots, 0.25 to 60, when RP Engine shoots

ranged: snowball is shorthand for the projectile alone, with the rest at their defaults (arrow, the projectile's own damage, 16 blocks, 2 seconds).

A skeleton, stray or bogged (on 1.21.4 and newer) shoots with its own AI: it keeps its distance, strafes and aims like a skeleton, at the skeleton's own pace, so cooldown is not used. Any other type shoots every cooldown seconds while its target is in range and in sight.

Either way its attack animation and sound play as each shot leaves, not when it lands. A fireball or a wither skull explodes without breaking blocks, and nobody can pick up a custom mob's arrows.

Spawning on its own#

desert_ghoul:
  type: HUSK
  model: mypack:ghoul
  spawning:
    worlds: [world]
    biomes: [desert, "*badlands*"]
    replaces: [HUSK, ZOMBIE]
    chance: 0.1
    time: night
    min-light: 0
    max-light: 7
    min-group: 1
    max-group: 2
    max-per-chunk: 2

It takes the place of natural spawns rather than adding to them: when a matching vanilla mob spawns, yours replaces it (with up to max-group - 1 more beside it). So the server's mob caps, difficulty and spawn rules still apply, and peaceful spawns nothing.

Without replaces: it can stand in for any natural spawn of its own kind: a hostile type for monsters, an animal for animals, a water creature for water creatures. An iron golem, an allay or a villager needs replaces:, because nothing spawns naturally as one. Biome tags (#is_forest) are not read, and warn at load. Night is game time 12300 to 23850.

A mob that spawned on its own despawns when nobody is near, as the mob it replaced would have.

More options#

These are MythicMobs' mob options, under RP Engine's names. If you are bringing mobs across from MythicMobs, Porting your MythicMobs mobs has the whole mapping.

knight:
  extends: brute                 # everything brute says, then this
  type: ZOMBIE
  armor: 12                      # armour points, 0 to 30
  armor-toughness: 4             # 0 to 20
  equipment:                     # worn for real: armour counts, a weapon hits harder
    head: minecraft:iron_helmet
    hand: {item: zoo:axe, drop-chance: 0.1}
  damage-modifiers: {FIRE: 0, PROJECTILE: 0.5, MELEE: 1.5}
  invincible: false              # true: takes nothing but the void and /kill
  collidable: true               # false: players and mobs walk through it
  gravity: true
  despawn: never                 # never, natural or chunk
  faction: undead                # never targets another mob of its faction
  level: 1to5                    # rolled per mob; or a number
  per-level: {health: 10, damage: 1, armor: 0.5, speed: 0.02, power: 0.25}
  prevent: [leash, rename]       # name tags and leads stop working on it
  kill-messages: ["{player} met the knight"]
  mount: zoo:warhorse            # rides this, spawned under it

despawn: natural is the default for a mob that spawned on its own; never is the default for everything else (a command, an egg, a spawner or a plugin).

Templates#

extends: builds a mob on another one, as MythicMobs' Template: does (template: reads the same):

• a key the mob writes itself wins;
• a map (sounds:, animations:, boss-bar:) is merged key by key;
• a list is replaced, except skills:, which is the template's lines followed by the mob's own.

A template marked abstract: true needs no type: and is never a mob itself, so a shared base doesn't show up in /rp entities. Templates can extend templates; a loop is a load warning.

undead_base:
  abstract: true
  burns: true
  faction: undead
  sounds: {hurt: zoo:rattle}
  skills:
  - potion{type=WITHER;duration=60} @trigger ~onAttack 0.2
 
skeleton_knight:
  extends: undead_base
  type: SKELETON
  model: zoo:skeleton_knight
  health: 60

Equipment#

equipment: takes head, chest, legs, feet, hand and offhand, each a pack's item or a vanilla one, with an optional drop-chance (default 0, rolled on top of drops:). MythicMobs' list form (- iron_helmet HEAD) and its slot numbers work too.

A mob wearing a model shows none of it, since the model is what is seen. On 1.21.4 and newer each piece is worn but drawn as nothing, so its armour and damage still count. Older servers cannot hide a worn item, so there a modelled mob wears nothing (armor: still works). A mob with no model wears its equipment as any mob does.

Damage modifiers#

damage-modifiers: multiplies each kind of damage the mob takes, by Bukkit's cause names (FIRE, FIRE_TICK, LAVA, PROJECTILE, ENTITY_ATTACK, FALL, BLOCK_EXPLOSION and the rest) or MythicMobs' groups MELEE, EXPLOSION and BURNING. 0 makes it immune to that cause: the hit is cancelled, so it doesn't even flinch. The list form - FIRE 0 works too.

Levels#

level: is rolled for each mob as it spawns, a number or a range (1to5), unless /rp spawn, a spawner or a skill's summon{level=3} says which. Each level above the first adds per-level:'s amounts:

The level shows in its name as {level}, in a skill as <caster.level>, and the level{l=3to5} condition tests it.

Spawning one#

An egg used on a vanilla spawner hatches the mob there and leaves the spawner alone. Mobs made in Studio arrive when you push or publish the pack, and are spawned as studio:<id>, exactly like the ones in your content folder.

From your own plugin, engine.mobs().spawn(...); see the Plugin API.

On Bedrock#

Bedrock players joining through Geyser see a custom mob as its model too, sized by scale:, turned by turn:, playing the same animations and flashing red when hit. A dying mob tips over the way a Bedrock mob does rather than playing death, and its name sits over the hitbox. See Bedrock and Geyser.