Mob Configuration

Register AI-driven mob entities — creatures, bosses, mounts, and NPCs — in your mod's catalog.

Mobs are AI-driven entities — neutral/hostile creatures, bosses, mounts, NPCs. This is the catalog file that registers them. Server and client each load their own copy of this file independently (some fields are server-only, some client-only — see Fields).

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

mob-config: mob-config.yaml

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/mob-config.yaml

The file is a single list of mob entries:

mobs:
  - name: my_mob
    spawn-group: Neutral
    hitbox:
      width: 2.0
      height: 3.0

Names are automatically prefixed with your mod name unless you write one already containing a colon.

Minimal Example

mobs:
  - name: my_mob
    hitbox:
      width: 2.0
      height: 3.0

Fields

A mob entry groups its settings into a few blocks. The top-level keys:

AoE zones are not declared here. Define them in aoe-zone-config.md and trigger them by name from a mob’s Lua — zones are registered globally per mod, and any entity can trigger any zone.

Movement

Server-only. All fields optional; omit the whole block to take every default.

Why this block’s words differ from the mount: block’s. A rideable mob has two movement blocks, and they deliberately use different vocabulary: movement: here uses walk-speed / jump-velocity / jump-acceleration, while mount: uses max-speed / jump-strength. That is not an inconsistency to reconcile — they drive two different systems. The movement: fields are engine physics: the pathfinder and jump code apply them directly, so walk-speed really is a velocity and jump-velocity really is the launch impulse. The mount: fields are inputs to a Lua steering script — the engine only stores them and hands them back through get_max_speed() / get_jump_strength(); nothing moves unless the mount’s server-update reads them. So a mob wandering on its own AI obeys movement:; the same mob being ridden obeys whatever its mount script does with max-speed/jump-strength.

movement:
  walk-speed: 5.0
  jump-acceleration: 100.0
  jump-velocity: 10.0
  max-velocity: { x: 50.0, y: 50.0 }
  complex-pathing: false
  flying: false
  phases-terrain: false
  fly-speed: 5.0

Setting flying: true is all a mob needs to fly — the engine handles the rest automatically: it pathfinds through the air around obstacles, and the flyer gets natural aerial motion (a gentle idle hover bob, organic weaving, easing out of a hover, and banking/tilting toward its heading). None of that motion is configurable per-mob today; drive attack patterns from a server-update script using the velocity setters and mob_path_to.

Setting phases-terrain: true likewise handles the rest automatically: the mob is gravity-exempt like a flyer and its pathfinder tunnels straight through solid blocks toward its target, so a burrowing mob will dig through rock to reach a player. It gets the same aerial motion treatment as a flyer. A burrowing boss whose segments should dive and surface on cue can flip phasing per-phase from a server-update script with entity:set_phasing(...).

Scripts

Lua hooks live under a single scripts: block. Each value is the path to a Lua file, relative to your mod’s folder:

scripts:
  server-update: /mobs/my_mob/scripts/server_update.lua
  client-on-interact: /mobs/my_mob/scripts/client_interact.lua

Each script file returns its function — there is no function name to declare:

-- /mobs/my_mob/scripts/server_update.lua
local ai = require("MyMod.mobs.my_mob_ai")

return function(entity, delta_time_ns)
  -- ...
end

If you need to point at a file another way, the long form is a mapping with a path field (server-update: { path: /mobs/my_mob/scripts/server_update.lua }); the shorthand string above is equivalent.

server-on-death receives the mob and runs before it is removed from the world, so the hook can still read its position, lua_data, and riders. The mounted/dismounted hooks receive (rider, mob), and mirror the standalone mount’s hooks of the same names — a rideable mob and a mount are scriptable the same way.

Natural Spawning

spawn-rules controls whether and where a mob spawns naturally. A mob with no spawn-rules key at all is never added to the natural-spawn pool — it can still be created via Lua or placed by a structure, but the natural spawner will never pick it.

The natural spawner only draws from mob types that have a matching entry in the server’s mob-limits (in server_config.yaml). If a mob has spawn-rules but its spawn-group isn’t listed there — commonly a typo in spawn-group — it silently never spawns. The server logs a warning at load naming any such group, so watch the log if a spawn isn’t appearing.

Why this looks nothing like tree/structure spawning. Mob natural spawning is a runtime system: the server periodically attempts spawns in loaded chunks, gated by these live-world spawn-rules (nearby players, time of day, current biome) and capped by mob-limits. That’s deliberately different from how trees, structures, and sky-island features are placed — those are worldgen placements, decided deterministically per chunk from a spacing grid plus a spawn-chance roll (see Tree Configuration). The two systems share almost no fields because they answer different questions (“is this spot currently safe to spawn on?” vs. “how densely should this be pre-placed?”), so don’t expect a mob-style spawn-rules block on a tree.

spawn-rules:
  enabled: true
  check-spawn-clearance: true
  must-spawn-on-ground: true
  valid-spawn-blocks:
    - MyMod:grass
  distance-from-player: 20.0
  biome-restrictions: [Forest, Plains]
  time-of-day: night_time

Time of day

time-of-day takes a single keyword, a group keyword expanding to several, or a list of keywords:

time-of-day: night_time          # a group
time-of-day: [dawn, dusk]        # a list of single phases

A value outside these lists is warned about and the restriction is dropped, so the mob spawns at any time — check the log if a night-only mob appears at noon.

Valid spawn blocks

Each entry is either a bare block name, or a mapping that adds constraints on the placed block’s live state:

valid-spawn-blocks:
  - MyMod:grass              # any grass block
  - name: MyMod:water        # only water at a full fluid level
    fluid-level: 1.0
  - name: MyMod:oak_slab     # only a bottom half-slab
    block-shape:
      type: slab
      divisions: 2

Only the properties you write are compared — everything else is left free, so - MyMod:grass matches every grass block whatever state it is in. The mapping form accepts:

Two entries may name the same block with different constraints (full water and half-full water), and both are kept.

A malformed entry — an unknown key, a missing name, an unresolvable block, or a bad value — fails the whole mob rather than being skipped. Dropping an entry would quietly widen the rule: lose them all and the list reads as empty, which means “spawn anywhere” instead of the narrow list you wrote.

Mount

Adding a mount: block makes this mob rideable. Its max-speed, jump-strength, and seats are the same fields a standalone mount declares — just nested under mount: here (a mob is a creature first, so its rideability lives in its own block, kept separate from the mob’s own movement), rather than at the top level (where the whole entry is the mount). seats uses the exact same shape; a mob’s mount: block additionally supports taming (below), which standalone mounts don’t need.

mount:
  max-speed: 80.0
  jump-strength: 12.0
  seats:
    - x-offset: 0.0
      y-offset: 2.5
      rider-hidden: false
      constrained: false
  taming:
    enabled: true
    taming-threshold: 100.0
    food-items:
      - item: MyMod:berries
        progress: 25.0

Like mounts, a ridden mob does not move on its own — its update script reads the rider’s input (entity:get_rider_input_x() / get_rider_input_y()) together with get_max_speed() / get_jump_strength() and sets the mob’s velocity. See mount-config.md’s Steering a mount for the pattern.

The mount’s server-on-mounted / server-on-dismounted hooks live in the mob’s scripts: block with every other hook, not inside mount:.

Taming

Players interact with an untamed mob to feed it; each interaction adds the matching food item’s progress toward taming-threshold. Once reached, the mob becomes rideable and remembers who tamed it.

Multi-Part Bodies (body)

A body: block turns a mob into a multi-part boss: one controller (this mob — the head or core) plus a set of part mobs that the engine spawns, positions, and coordinates as one logical boss. Each part is itself an ordinary mob entry (its own hitbox, texture, etc.), so parts are hit and rendered like any mob — the body: block just links them. It is shape-agnostic: the same block expresses a trailing worm, a fixed cluster, or a fully script-driven arrangement.

# A trailing worm (segments follow the head)
- name: deep_serpent
  spawn-group: Boss
  hitbox: { width: 4.0, height: 4.0 }
  health: { max: 500.0, takes-damage: true }
  display-boss-healthbar: true
  body:
    formation: trail-chain
    part-spacing: 2.0
    damage-model: shared
    parts:
      - name: serpent_segment
        count: 12

Formations

• trail-chain — parts trail the controller in a chain, each part-spacing blocks behind the previous one along the controller’s recent path. The worm case. count is the chain length.
• fixed-offset — each part holds its offset from the controller (a rigid cluster). Give each part its own offset; the x offset is mirrored automatically when the boss faces left, so parts stay on the correct side as it turns.
• script — the engine does not position parts; a Lua update script places them with entity:set_location(...) for bespoke shapes or movement. Use get_body_parts() (below) to reach them.

Damage models

• shared — every part is a damage sensor: hits it takes are forwarded into the controller’s single health pool, so the boss healthbar (put display-boss-healthbar: true on the controller) reads as one pool no matter which part is struck. Part health values in config are ignored for shared parts.
• per-part — parts keep their own health and are damaged independently; the boss dies when the controller dies. (Severing/regrowing parts is planned for a later version.)

Reaching parts from Lua

In the controller’s scripts, entity:get_body_parts() returns its part entities (spawn order — head→tail for a chain); on a part, entity:get_body_controller() returns the head/core. Use these to, e.g., fire an attack from a specific segment.

Not persisted. A body-group boss and its parts are runtime-only: they are not saved, so summon/spawn them fresh (e.g. via a summon item) rather than relying on them surviving a world reload. This keeps autosave from leaving orphaned parts on disk.

Complete Example

mobs:
  - name: forest_wolf
    spawn-group: Hostile
    hitbox:
      width: 2.0
      height: 2.0
    movement:
      walk-speed: 8.0
    health:
      max: 20.0
      regen-per-second: 0
      takes-damage: true
    scripts:
      server-update: /mobs/forest_wolf/scripts/server_update.lua
      client-update: /mobs/forest_wolf/scripts/client_update.lua
    spawn-rules:
      check-spawn-clearance: true
      must-spawn-on-ground: true
      valid-spawn-blocks:
        - MyMod:grass
      time-of-day: night_time
    drop-table:
      drops:
        - item: MyMod:wolf_pelt
          min-amount: 1
          max-amount: 2
          chance: 0.6