Guides

A plugin's own creatures

A plugin can make any of the game's creatures, dress and tune it, and drive it: wildlife it scatters, a camp's guards, a trader that walks a route. The Rust types are in rustmc_plugin::creature; a Wasm guest sends the JSON below.

Making one

{"call": "spawn_creature", "world": "minecraft:overworld", "kind": "minecraft:zombie", "at": [10.5, 64, -3.5],
 "options": {"name": "Scientist", "name_visible": true, "yaw": 90,
             "equipment": {"mainhand": {"item": "minecraft:iron_sword", "count": 1, "components": {"minecraft:custom_data": "{gun:1b}"}},
                           "head": {"item": "minecraft:iron_helmet", "count": 1}},
             "attributes": {"minecraft:max_health": 40, "minecraft:attack_damage": 6, "minecraft:follow_range": 24},
             "health": 30, "persistent": true, "ai": "plugin", "silent": false, "invulnerable": false, "baby": false,
             "sight_range": 16, "sees_creatures": false}}

Every option may be left out. It answers the creature's entity id, or null for a world the server does not have. An unknown kind, slot, item, component or attribute is an error, and nothing is made.

• ai is whose decisions it acts on: vanilla (its own goals or brain), none (NoAI: it stands, falls and is hurt, and decides nothing) or plugin (it carries out orders). Change it later with set_creature_ai.
• attributes are base values, as /attribute <id> <attribute> base set sets them; a new max_health fills its health. follow_range is how far a plugin-driven attacker keeps up a fight.
• persistent stops the game despawning it for being far from everybody.

The plugin owns it, and it is never saved: it is gone after a restart, when its chunk unloads (creature_gone), and when the plugin is unloaded. A plugin that keeps a population makes it again as it starts and as players come near.

can_spawn_at ({"world", "kind", "at": [x, y, z]}, a block) answers whether a creature of a kind could stand with its feet in that block by its kind's spawn placement -- on solid ground with room for its body and no fluid at its feet, in water for a fish -- with no light, biome or crowd rules.

Orders

A creature whose ai is plugin does what it was last told, each tick, with the server's own pathfinding and its own attack. creature_order takes the order's name and its fields:

speed is the game's speed modifier on the creature's own movement_speed (one by default): one is its walking pace, a panicking animal runs at about one and a half. An attack is the creature's own: a melee blow by its attack_damage and reach on its kind's cooldown, chasing at its kind's chase speed, or its kind's projectile for one that shoots (a skeleton with a bow, a blaze). A creature with no attack_damage walks up and does nothing.

A move_to is reached within a block or two of the point: the navigation's path ends at the block next to it, as the game's walks do. blocked is a creature that had a way and stopped moving for three seconds; no_path one that never had a way, or had only one that falls short.

Every order but idle ends with exactly one creature_order_done: with its outcome, replaced when another order took its place, died, or removed when the creature left the world another way. creature_state ({"entity"}) answers where any creature is and how it is: kind, world, position, health, max_health, ai, owner, order, target, and path -- none, walking, reached, blocked or no_path.

Orders move the creatures that walk: everything the game walks on land, and the swimmers and fliers only as far as their walk does. A fish or a bat ordered about does not swim or fly there.

What the owner hears

Only the owner hears these (list them in the manifest's events like any other): creature_order_done, creature_sees (with a sight_range), creature_damaged after each blow, and creature_gone. Every creature's death is mob_death, which now says the cause. See the event reference.

Drops

set_creature_drops ({"entity", "drops": [{"item", "count", "components"}], "experience": 3}) replaces what one of the plugin's creatures leaves when it dies -- its loot table and everything it carried -- and, with experience, what it is worth to a player's kill. "drops": null gives it back its own. The world's mob_drops rule still decides whether anything drops at all.

From docs/api/guide/creatures.md in the RustMC repository at bbd81209ad.