Host calls

Plugin creatures

Creatures a plugin spawns, owns and gives orders to.

Generated by tools/gen_api_docs.py; do not edit by hand. See host calls for how a call is made and how values are encoded. Each example shows the shape of a Wasm request with its required fields; the values in it are illustrative.

spawn_creature

fn spawn_creature(plugin: &str, world: &World, kind: &str, at: Vec3, options: &crate::creature::CreatureOptions) -> Result<Option<EntityId>, String>

Makes one of the game's creatures for this plugin, dressed and tuned as options says (CreatureOptions): a name, equipment with data components, attribute bases, persistent, silent and invulnerable, and its mind -- its own vanilla one, none, or the plugin's (creature_order). The plugin owns it: only it orders it, hears its creature_* events and sets its drops. It is never saved with the world, and it goes when its chunk unloads (creature_gone) and when the plugin is unloaded. Ok(None) for a world the server does not have, or a position that is not a number; an error for a kind that is not a creature, an equipment slot, item or component the game does not have, an attribute it does not, or more than MAX_CREATURES creatures.

Wasm request

Shape: options is an object, every field optional: yaw, name, name_visible, equipment (slot to {item, count, components}), attributes (attribute to base value), health, persistent, ai (vanilla, none or plugin), silent, invulnerable, baby, sight_range, sees_creatures.

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<Option<EntityId>, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "spawn_creature", "world": "minecraft:overworld", "at": [10, 64, -3], "kind": "minecraft:zombie"}

set_creature_ai

fn set_creature_ai(plugin: &str, entity: EntityId, ai: crate::creature::Ai) -> Result<bool, String>

Changes whose decisions one of this plugin's creatures acts on. Taken off plugin, its order ends (replaced); put on it, it starts idle. Ok(false) for a creature that is not there or not this plugin's.

Wasm request

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "set_creature_ai", "entity": 42, "ai": "plugin"}

creature_order

fn creature_order(plugin: &str, entity: EntityId, order: &crate::creature::Order) -> Result<bool, String>

Tells one of this plugin's plugin-driven creatures what to do from its next tick until it is told something else (Order); an order it was carrying out ends replaced. Each order but idle ends with one creature_order_done event. Ok(false) for a creature that is not there or not this plugin's; an error for one whose mind is not the plugin's, or an order that cannot be carried out (a speed or distance that is not a positive number, a patrol of no points or more than MAX_PATROL_POINTS).

Wasm request

Shape: order picks the form, and each form reads its own fields: idle; move_to {to, speed=1}; follow {target, distance=3, speed=1}; attack {target}; flee {from (entity id or [x, y, z]), distance=16, speed=1.25}; wander {centre, radius=10, speed=1}; patrol {points, looped=false, speed=1}; look_at {at (entity id or [x, y, z])}.

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "creature_order", "entity": 42, "order": "idle"}

creature_state

fn creature_state(entity: EntityId) -> Option<crate::creature::CreatureState>

How a creature is: where it is, its health, its mind, its owner, the order it is carrying out and whom at, and how its walk is going. Any creature, the world's own included; None for one that is not there.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<crate::creature::CreatureState>, encoded as in conventions; objects in it carry kind, world, position, health, max_health, ai, owner, order, target, path.

{"call": "creature_state", "entity": 42}

set_creature_drops

fn set_creature_drops(plugin: &str, entity: EntityId, drops: Option<&crate::creature::CreatureDrops>) -> Result<bool, String>

Decides what one of this plugin's creatures leaves when it dies, instead of its loot table and its equipment, and what experience it is worth; None gives it back its own. Whether it is this plugin's creature, there.

Wasm request

Shape and limits, as the router words its errors: "experience should be a whole number, not …"; "drops should be a list of …, or null for the creature's own".

Router notes: plugin is never sent by a Wasm guest: the server fills it in from the manifest name.

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "set_creature_drops", "entity": 42}

can_spawn_at

fn can_spawn_at(world: &World, kind: &str, at: BlockPos) -> Result<bool, String>

Whether a creature of kind could be put with its feet in the block at, by the game's spawn placement for the kind (SpawnPlacements): standing on something solid with room for its body and no fluid at its feet, in water for a fish, in lava for a strider. No light, biome or crowd rules -- where wildlife lives is the plugin's to say. False in a chunk that is not loaded; an error for a kind that is not a creature.

Wasm request

Reply: {"ok": ...} holding the Rust return value Result<bool, String>, encoded as in conventions. An Err arrives as {"error": "..."}.

{"call": "can_spawn_at", "world": "minecraft:overworld", "at": [10, 64, -3], "kind": "minecraft:zombie"}

From docs/api/reference/host-calls/creatures.md in the RustMC repository at bbd81209ad.