Host calls

Entities and display entities

Reading and changing any entity, spawning entities (including per-viewer display entities), riding, and damage.

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.

position

fn position(entity: EntityId) -> Option<Vec3>

Where somebody is.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<Vec3>, encoded as in conventions.

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

world_of

fn world_of(entity: EntityId) -> Option<World>

Which world somebody is in.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<World>, encoded as in conventions.

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

rotation

fn rotation(entity: EntityId) -> Option<(f32, f32)>

Which way somebody faces: yaw (degrees clockwise from +Z, as the game counts it) and pitch. A player or a creature; None for an entity that is not there.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<(f32, f32)>, encoded as in conventions.

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

is_sneaking

fn is_sneaking(entity: EntityId) -> bool

Whether somebody is crouching.

Its own question rather than a pose, because one rule in the game turns on it and nothing else does: MagmaBlock.stepOn asks isSteppingCarefully, which is isShiftKeyDown, and a magma block is the only hazard anywhere a player can simply decline. A host that cannot tell answers false, which hurts them -- the safe way round, because the alternative is a floor of magma that never does anything.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

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

is_on_ground

fn is_on_ground(entity: EntityId) -> bool

Whether somebody is standing on something.

Asked because a rule that reads the block underfoot has to know there is an underfoot. Entity.applyEffectsFromBlocks returns before it looks at anything when onGround() is false, so a player jumping over a magma block, or swimming above one, is not stepping on it. Without this a rule reads the block below a body in mid-air and charges them for standing on it.

Client-reported, like everything else about where somebody is; a host that cannot tell answers false, which spares them rather than hurting them.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

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

has_effect

fn has_effect(entity: EntityId, effect: &str) -> bool

Whether a status effect is on somebody at this moment.

Presence and not the amplifier, because that is the whole of the question the caller that needed it asks: fire resistance stops fire damage outright and does not stop more of it at level two.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "has_effect", "entity": 42, "effect": "minecraft:speed"}

add_effect

fn add_effect(entity: EntityId, effect: &str, ticks: i32, amplifier: i32) -> bool

Gives a creature or a player an effect (minecraft:regeneration) for ticks, at amplifier (nought is level I), as /effect give does: an instant one is spent at once, a longer one replaces a weaker or shorter one. Whether it was given: false for an effect this server does not have, an entity that is not there, or ticks or an amplifier out of range (1 to 1,000,000 ticks; 0 to 255).

Wasm request

Shape and limits, as the router words its errors: "ticks is required".

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "add_effect", "ticks": 100, "entity": 42, "effect": "minecraft:speed"}

add_effect_shown

fn add_effect_shown(entity: EntityId, effect: &str, ticks: i32, amplifier: i32, shown: EffectShown) -> bool

add_effect, drawn as shown says: without particles (a plugin's own slow-down, which nobody else should see), without the icon, or ambient as a beacon's is. The flags last as long as the effect, through a change of world, and an effect given again replaces them.

Wasm request

Shape and limits, as the router words its errors: "… should be true or false"; "ticks is required".

Router notes: Each flag defaults to /effect give's: particles and the icon, not ambient.

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "add_effect_shown", "ticks": 100, "entity": 42, "effect": "minecraft:speed"}

remove_effect

fn remove_effect(entity: EntityId, effect: &str) -> bool

Takes one effect off a creature or a player, as /effect clear <target> <effect> does: its attribute modifiers go with it and the client is told. Whether there was one to take.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "remove_effect", "entity": 42, "effect": "minecraft:speed"}

set_attribute_modifier

fn set_attribute_modifier(entity: EntityId, attribute: &str, id: &str, amount: f64, operation: &str) -> Result<bool, String>

Puts a modifier on one of somebody's attributes, as /attribute <target> <attribute> modifier add does but replacing one of the same id rather than refusing: id is a namespaced name the plugin owns (myplugin:aiming), operation is add_value, add_multiplied_base or add_multiplied_total. The client is told within the tick, so a slow-down is felt at once. Ok(false) for somebody who is not there or an attribute they do not have; an error for an attribute the game does not have, an operation it does not, an id that is not namespaced, or an amount that is not a number.

Saved with the player, as the game saves every modifier, so a modifier for a moment (aiming, carrying) is the plugin's to take off -- on a player's leaving too, or it is still there when they come back.

Wasm request

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

{"call": "set_attribute_modifier", "entity": 42, "attribute": "minecraft:movement_speed", "id": "spawn", "amount": 4.0}

remove_attribute_modifier

fn remove_attribute_modifier(entity: EntityId, attribute: &str, id: &str) -> bool

Takes a modifier off by its id. Whether there was one.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "remove_attribute_modifier", "entity": 42, "attribute": "minecraft:movement_speed", "id": "spawn"}

enchantment_level

fn enchantment_level(entity: EntityId, slot: &str, enchantment: &str) -> i32

What level of an enchantment somebody is wearing in one equipment slot.

The slot is named the way the game's own slots field names it -- "feet", "legs", "chest", "head", "mainhand", "offhand" -- and the slot is not optional, because an enchantment only does anything in the slots it lists. Frost Walker's is ["feet"], so a Frost Walker helmet, which only a command can make, freezes nothing and stops nothing; a plugin that asked "anywhere on this player" would give it powers the game does not.

Nought for a slot this host does not know, an item that is not enchanted, or somebody who has gone -- all three mean the same thing to a caller and none is an error.

Wasm request

Reply: {"ok": ...} holding the Rust return value i32, encoded as in conventions.

{"call": "enchantment_level", "entity": 42, "slot": "mainhand", "enchantment": "minecraft:sharpness"}

attribute

fn attribute(entity: EntityId, attribute: &str) -> Option<f64>

An attribute's current value on somebody -- base, /attribute modifiers, effects and the modifiers their worn enchantments put there -- or None for an attribute this entity does not have, or an entity that has gone.

The value, not an enchantment level, because that is what the game reads: Respiration is an oxygen_bonus modifier, and LivingEntity.decreaseAirSupply asks the attribute, so /attribute @s minecraft:oxygen_bonus base set 3 is as good as a helmet.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<f64>, encoded as in conventions.

{"call": "attribute", "entity": 42, "attribute": "minecraft:movement_speed"}

air

fn air(entity: EntityId) -> Option<i32>

How many ticks of breath somebody has left, or None if they have gone.

Engine state, exposed the way the world border's size is, and for the same reason. The air supply is Entity's own DATA_AIR_SUPPLY_ID -- a synched entity data field the client draws its bubble bar from and the player file writes down. A plugin that kept its own map of breath would have to own that packet and that save format, and would have to be told when somebody left or the map would leak. What is the rule is how fast it is spent, when it comes back, and what running out costs; that is the plugin's, and this is not.

It goes negative, and a caller that clamps it at nought breaks drowning: the game spends the counter past zero and only hurts at minus twenty.

Wasm request

Router notes: null rather than nought for a body the host does not know. A guest told nought would spend the next tick refilling a breath that belongs to nobody.

Reply: {"ok": ...} holding the Rust return value Option<i32>, encoded as in conventions.

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

set_air

fn set_air(entity: EntityId, ticks: i32) -> bool

Sets it. Returns whether there was anybody to set it on.

Not clamped: the full breath (Entity.getMaxAirSupply, 300 for a player) is the caller's to respect.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "set_air", "entity": 42, "ticks": 100}

fire_ticks

fn fire_ticks(entity: EntityId) -> Option<i32>

How long somebody stays alight, in ticks, or None if they have gone.

The same argument as air: remainingFireTicks is the field the client's flame overlay is drawn from -- setSharedFlagOnFire runs off it every tick -- and it is written to the player file. The engine owns the number and the packet; the plugin owns when it starts, what it costs and when it stops.

Negative is not "no fire", it is a grace period. clearFire is min(0, remaining) rather than = 0, and fireIgnite climbs a negative counter by one a tick before the eight seconds land. A host that reported a negative counter as nought would make a player catch alight on the first tick of contact every time.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<i32>, encoded as in conventions.

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

set_fire_ticks

fn set_fire_ticks(entity: EntityId, ticks: i32) -> bool

Sets it. Returns whether there was anybody to set it on.

The host redraws the flame when the counter crosses nought: the plugin sets the number and the server sends the client what it needs.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "set_fire_ticks", "entity": 42, "ticks": 100}

ticks_frozen

fn ticks_frozen(entity: EntityId) -> Option<i32>

How frozen somebody is, in ticks, or None if they have gone.

The same argument as air and fire_ticks: Entity.DATA_TICKS_FROZEN is a synched field the client fades the frost overlay in from -- getPercentFrozen is this over a hundred and forty -- and the player file writes it down as TicksFrozen. The engine owns the number and the packet; the rule owns how fast it climbs, what stops it and what being full of it costs.

Never negative, unlike the fire counter: the game clamps it at nought on the way down, so there is no grace period here to preserve.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<i32>, encoded as in conventions.

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

set_ticks_frozen

fn set_ticks_frozen(entity: EntityId, ticks: i32) -> bool

Sets it. Returns whether there was anybody to set it on.

Not clamped at the hundred and forty (getTicksRequiredToFreeze): the ceiling is the caller's to respect.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "set_ticks_frozen", "entity": 42, "ticks": 100}

worn

fn worn(entity: EntityId, slot: &str) -> Option<String>

What somebody is wearing in one equipment slot, as an item id.

The slot is named the way enchantment_level names it -- "feet", "legs", "chest", "head", "mainhand", "offhand". None for an empty slot, a slot this host does not know, or somebody who has gone; a rule that reads it is asking what is there, and all three of those mean nothing is.

Wasm request

Router notes: The slot is named as enchantment_level names it: head, chest, legs, feet, mainhand, offhand.

Reply: {"ok": ...} holding the Rust return value Option<String>, encoded as in conventions.

{"call": "worn", "entity": 42, "slot": "head"}

is_in_rain

fn is_in_rain(entity: EntityId) -> bool

Whether rain is falling on somebody where they stand. Entity.isInRain.

Its own question rather than "is it raining", because the two differ for everybody standing under anything: the game asks whether this position can see the sky, and a plugin cannot work that out from a weather flag. A host that cannot tell answers false, which leaves a burning player burning -- the visible way round, rather than putting fires out indoors for no reason anybody could see.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

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

may_interact

fn may_interact(entity: EntityId, world: &World, at: BlockPos) -> bool

Entity.mayInteract(level, pos): whether this body may change the block there. A player is refused under spawn protection and outside the world border (ServerLevel.mayInteract); anything else always may. A host that cannot tell answers false, which leaves the block as it is.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "may_interact", "entity": 42, "world": "minecraft:overworld", "at": [10, 64, -3]}

damage

fn damage(entity: EntityId, amount: f32, cause: &str) -> ()

Hurts somebody, by a named cause. The host decides what armour does about it.

Wasm request

Reply: {"ok": ...} holding the Rust return value (), encoded as in conventions.

{"call": "damage", "entity": 42, "amount": 4.0, "cause": "minecraft:generic"}

exhaust_for

fn exhaust_for(entity: EntityId, cause: &str) -> ()

Charges somebody the hunger this damage source costs.

A cause rather than an amount, and that is deliberate. How hungry a blow makes somebody is a number in the game's damage-type registry, which the engine already reads -- it is the same table that says whether armour is in the way. A plugin handed only exhaust(amount) would keep its own copy of that number, and a copy is a thing that drifts silently when the game changes its mind: nothing fails, the player just gets hungry at the wrong rate.

Not folded into damage, because most of the game's damage sources charge nothing and the ones that do are charged by the block that caused them rather than by the blow. Every existing call site in this server spends the two separately.

Wasm request

Reply: {"ok": ...} holding the Rust return value (), encoded as in conventions.

{"call": "exhaust_for", "entity": 42, "cause": "minecraft:generic"}

spawn_entity

fn spawn_entity(world: &World, kind: &str, at: Vec3, yaw: f32, pitch: f32, nbt: &str) -> Result<Option<EntityId>, String>

Makes an entity, as /summon would with the same tag (nbt, SNBT; empty for none), and answers its id: a creature, an armour stand, a mannequin, an interaction box, or a display (minecraft:item_display, block_display, text_display, whose fields -- item, block_state, text, transformation, billboard and the rest -- are the game's own). A display's item is {id, count} and may carry the components that pick its model, minecraft:custom_model_data and minecraft:item_model, and nothing else. A mannequin (minecraft:mannequin) is drawn as a player: profile is whose skin (a name, {name:"Steve"} or {id:[I;a,b,c,d]}, which the viewer's client looks up), pose is standing, crouching, swimming, fall_flying or sleeping, with hidden_layers, main_hand, immovable and the entity's own NoGravity and Invulnerable; an error, making nothing, for a profile, pose, layer or hand the game would not read. What a plugin makes is never saved with the world, and goes when its chunk unloads.

Wasm request

Shape: With a non-null viewers list this is spawn_entity_for: only those players see it.

Router notes: With viewers, for those players only.

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

{"call": "spawn_entity", "world": "minecraft:overworld", "to": [10.5, 64.0, -2.5], "kind": "minecraft:zombie"}

raycast

fn raycast(from: &RayFrom, max_distance: f64, filter: &RayFilter) -> Result<Option<RayHit>, String>

Casts a ray, run by the server so it costs the plugin no fuel: from a point or a player's eyes, up to max_distance blocks (at most 512), against blocks' collision shapes (a slab stops it at its top, an open trapdoor not at all; fluids never) and entities' boxes, as RayFilter allows; the first thing met, or None. A player's box is their pose's (standing 1.8 high, crouching 1.5, swimming 0.6), its top half block their head; a creature's is its type's size. With rewind_ms players are tested where they were that long ago, from a second of positions the server keeps. Spectators are never hit. An error for a direction of nought or a distance that is not a positive number.

Wasm request

Shape: Two forms. From a player's eyes: player alone (no from). From a point: world, from and direction. blocks and entities (default true), players_only (default false), exclude (entity ids) and rewind_ms filter what is hit.

Shape and limits, as the router words its errors: "exclude holds entity ids, not …"; "exclude should be a list of entity ids"; "rewind_ms should be a whole number of milliseconds, not …".

Reply: {"ok": ...} holding the Rust return value Result<Option<RayHit>, String>, encoded as in conventions; objects in it carry type, at, face, point, distance, entity, part, kind, height, eye_height. An Err arrives as {"error": "..."}.

{"call": "raycast", "max_distance": 5.0}

spawn_entity_for

fn spawn_entity_for(plugin: &str, world: &World, kind: &str, at: Vec3, yaw: f32, pitch: f32, nbt: &str, viewers: &[PlayerId]) -> Result<Option<EntityId>, String>

spawn_entity for some players only: a display (item_display, block_display, text_display), an interaction or a mannequin, whose spawn, movement and data go to viewers and to nobody else -- a building preview, a marker meant for one player. Viewers are kept by who they are, so one who leaves and comes back, or changes world and returns, sees it again; it reaches a viewer whenever they are in its world with its chunk in view, and leaves their client when they are not. set_display, move_entity, remove_entity, position and world_of work on it as on any entity; set_entity_viewers changes who sees it. It is not ticked, saved or collided with, and goes when the plugin is unloaded. An error for another kind, a bad tag, more than 256 viewers or more than 4096 such entities a plugin.

Wasm request

Shape: spawn_entity with a non-null viewers list is routed here too.

Router notes: With viewers, for those players only. 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_entity_for", "world": "minecraft:overworld", "to": [10.5, 64.0, -2.5], "kind": "minecraft:zombie"}

set_entity_viewers

fn set_entity_viewers(plugin: &str, entity: EntityId, viewers: &[PlayerId]) -> Result<bool, String>

Replaces who sees an entity spawn_entity_for made: those taken off are sent its removal, those added are sent it whole. false for an entity that is not the 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_entity_viewers", "entity": 42, "viewers": [7]}

entity_viewers

fn entity_viewers(entity: EntityId) -> Option<Vec<PlayerId>>

The online players who see an entity spawn_entity_for made; None for one that is not such an entity.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<Vec<PlayerId>>, encoded as in conventions.

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

set_display

fn set_display(entity: EntityId, nbt: &str) -> Result<bool, String>

Changes a display's fields (SNBT: {text:"Hi",billboard:"center"}), as /data merge entity would, and shows everybody watching. An error for a field a display does not have; false for no display there.

Wasm request

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

{"call": "set_display", "entity": 42, "nbt": "{}"}

move_entity

fn move_entity(entity: EntityId, to: Vec3, yaw: f32, pitch: f32) -> bool

Puts an entity somewhere else in its world, facing yaw and pitch. A display glides there over its teleport_duration. Any creature or display, not only the plugin's own; false for none there.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "move_entity", "entity": 42, "to": [10.5, 64.0, -2.5]}

attach_entity

fn attach_entity(entity: EntityId, leader: Option<EntityId>, offset: Vec3) -> bool

Makes entity follow leader, offset from it ([right, up, forward] in blocks, with the leader facing forward): whenever the leader is moved (move_entity), the follower is put at its offset from it, turned with its facing, and sent there in the same call. None stops it following. A plugin's vehicle's rig and seats follow its root, so moving the root moves them all. A display, an interaction or a creature, either way; false for anything else, the entity itself, or a leader with 64 followers already.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

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

move_entities

fn move_entities(moves: &[(EntityId, Vec3, f32, f32)]) -> usize

Moves several entities at once, each as move_entity does: a plugin's vehicle moving its root, its rig and every seat each tick in one call. How many were moved.

Wasm request

Shape and limits, as the router words its errors: "moves should be a list of [entity, x, y, z, yaw]"; "at most 1024 moves, not …".

Router notes: {"moves": [[entity, x, y, z, yaw], ...]}: compact, as a vehicle sends it every tick.

Reply: {"ok": ...} holding the Rust return value usize, encoded as in conventions.

{"call": "move_entities", "moves": []}

remove_entity

fn remove_entity(entity: EntityId) -> bool

Takes an entity out of the world without a death: any creature, display, boat or cart, or item lying on the ground, not only the plugin's own. False for none there.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

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

mount

fn mount(rider: EntityId, vehicle: EntityId) -> bool

Puts rider on vehicle, as /ride <rider> mount <vehicle> does: a player, a creature or a display on a creature, a display, a boat or a minecart -- however many are already on it, so a display rig and extra seats stack onto one mount. A player goes in front of whoever is aboard when nobody in front is a player (Entity.addPassenger), so the first player on a vehicle carrying a rig is its driver. Whoever is first steers what a player steers in the game: a boat, a saddled horse, camel, donkey or mule, a harnessed happy ghast, a saddled nautilus, a pig or strider whose rider holds its stick. A rider on something else gets off it first. An entity_mounted event goes first, and a plugin may cancel it. False, changing nothing, for a rider or vehicle not there, a player as the vehicle, the two in different worlds, the rider already on it, or a vehicle that is riding the rider.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "mount", "rider": 7, "vehicle": 42}

dismount

fn dismount(rider: EntityId) -> bool

Takes rider off whatever it is riding, as a player crouching does: entity_dismounted goes first and a plugin may cancel it. False for one riding nothing, or a cancelled one.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "dismount", "rider": 7}

vehicle_of

fn vehicle_of(entity: EntityId) -> Option<EntityId>

What an entity is riding; None for nothing, or an entity not there.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<EntityId>, encoded as in conventions.

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

passengers

fn passengers(entity: EntityId) -> Option<Vec<EntityId>>

Who is on an entity, in order: the first is the one who steers. An empty list for an entity carrying nobody; None for one that cannot carry anybody here (a player) or is not there.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<Vec<EntityId>>, encoded as in conventions.

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

set_passengers

fn set_passengers(vehicle: EntityId, riders: &[EntityId]) -> Result<bool, String>

Puts exactly riders on vehicle, in that order, as /ride would one by one but with the order kept as given: the first steers, and the client seats each at its place in the list (a happy ghast's four, a camel's two; past the last, at the last). Those taken off get off where they are; each change raises entity_mounted or entity_dismounted, told and not asked. Ok(false) for a vehicle that is not there or is a player; an error, changing nothing, for a rider that is not there or is in another world, the vehicle itself or anything it rides, a rider named twice, or more than 16 riders.

Wasm request

Shape and limits, as the router words its errors: "riders should be a list of entity ids".

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

{"call": "set_passengers", "vehicle": 42, "riders": [43]}

entity_velocity

fn entity_velocity(entity: EntityId) -> Option<Vec3>

How fast an entity is going, in blocks a tick: a creature's or a boat's own velocity, a player's as player_motion has it, and for a vehicle its driver's client moves (a ridden boat, horse or happy ghast), the distance between the last two positions the client reported, over the ticks between them. None for an entity not there.

Wasm request

Reply: {"ok": ...} holding the Rust return value Option<Vec3>, encoded as in conventions.

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

set_entity_velocity

fn set_entity_velocity(entity: EntityId, velocity: Vec3) -> bool

Pushes an entity: sets its velocity, in blocks a tick, and sends it to everybody watching -- ClientboundSetEntityMotionPacket, what an explosion or a wind charge sends. A vehicle its driver's client moves is moved by that client: the push reaches it and the client's own physics carries it on from there (a boat's water drag, a horse's friction), so a push every tick is how a plugin makes a boat go faster than paddling does. False for an entity not there, or a velocity that is not a number or is more than 10 blocks a tick on an axis.

Wasm request

Reply: {"ok": ...} holding the Rust return value bool, encoded as in conventions.

{"call": "set_entity_velocity", "entity": 42, "velocity": [0.0, 0.5, 0.0]}

players_in

fn players_in(world: &World, min: Vec3, max: Vec3) -> Vec<(PlayerId, Vec3)>

The players in world whose box meets the box between the corners min and max (in either order), with where each stands. Overlapping as the game's AABB.intersects has it: a box that only touches a face does not count, so a player standing exactly on the box's top is not in it. Spectators are not counted.

Wasm request

Reply: {"ok": ...} holding the Rust return value Vec<(PlayerId, Vec3)>, encoded as in conventions; objects in it carry player, at.

{"call": "players_in", "world": "minecraft:overworld", "min": [0, 60, 0], "max": [15, 70, 15]}

entities_in

fn entities_in(world: &World, centre: Vec3, radius: f64, kinds: &[String]) -> Result<Vec<EntityNear>, String>

The creatures and players in world whose box comes within radius of centre (the nearest point of the box, so a tall creature beside a blast is reached by its legs), with where each stands and the box that was tested: for a blast hurting what is near it. Only the kinds listed (minecraft:zombie, minecraft:player), or every kind for an empty list. Boats and carts only when their kind is listed by name (minecraft:oak_boat): a plugin looking for its own lost boat finds it, and a blast asking for everything is not told of hulls it never hurt before. Spectators are not counted. An error for a radius that is negative, not a number, or past MAX_NEAR_RADIUS (constants), or for a kind this version does not have.

Wasm request

Shape and limits, as the router words its errors: "kinds should be a list of entity types".

Reply: {"ok": ...} holding the Rust return value Result<Vec<EntityNear>, String>, encoded as in conventions; objects in it carry entity, kind, at, width, height, eye_height. An Err arrives as {"error": "..."}.

{"call": "entities_in", "world": "minecraft:overworld", "centre": [0.0, 64.0, 0.0], "radius": 8.0}

entity_unit

fn entity_unit(entity: EntityId) -> Option<f64>

One draw from a creature's own stream, in 0.0..1.0.

RandomSource on the entity, and the whole point is that it is the creature's. Every rule above that draws — the enchantment cost, the arrow's scatter, the piglin's hunt cooldown, the witch's weakness roll — has to draw from the body it is about, so that a world replayed from the same save makes the same creature the same way. A plugin handed a shared generator produces a server whose creatures differ after every restart, which is a bug nobody can reproduce.

A draw and not a seed. Handing out the seed would let a plugin rewind a creature's stream, and two plugins sharing one creature would then interleave: the second's first draw depends on how many the first took. Taking the draw here keeps the stream's ownership where the state is.

None for an entity the host has lost, which a caller must treat as "do not decide" rather than as nought — nought is the lowest roll and would make every gated thing happen.

Wasm request

Router notes: Each call advances the creature's stream, which is the point rather than a side effect: a guest asking twice gets two numbers, exactly as two rules in the server do. A cached answer here would make a plugin's draws correlate.

Reply: {"ok": ...} holding the Rust return value Option<f64>, encoded as in conventions.

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

damage_saying

fn damage_saying(entity: EntityId, amount: f32, cause: &str, died: &str) -> ()

damage, saying what to put in chat if it kills a player: the death message is their name, a space, and died (left the world gives Steve left the world). It is what they see on their death screen and everybody sees in chat (as far as the show_death_messages rule and their team allow), in place of the game's own for the cause. damage alone reports every such death as <name> died.

For a creature the message is not used, and the blow is dealt as minecraft:generic whatever cause says.

Wasm request

Reply: {"ok": ...} holding the Rust return value (), encoded as in conventions.

{"call": "damage_saying", "entity": 42, "amount": 4.0, "cause": "minecraft:generic", "died": "%1$s fell into the void"}

damage_by

fn damage_by(entity: EntityId, amount: f32, cause: &str, attacker: Option<EntityId>, skip_cooldown: bool) -> Result<bool, String>

Hurts an entity -- a player or a creature -- by a named damage type, struck by attacker: the blow is theirs as a sword's is, so a kill is credited to them (the death message names them, a creature's loot and experience are a player kill's) and the victim remembers who hit it last. An attacker who is no longer there leaves the blow nobody's.

skip_cooldown lands the blow whatever the victim's hurt cooldown -- the ten ticks after a blow in which another lands only for what it adds (invulnerableTime) -- as a damage type in #bypasses_cooldown would: for a weapon that strikes faster than twice a second. The blow itself starts the cooldown again, as any blow does.

Answers whether it landed: false for a blow armour, a shield, the cooldown, creative mode or a plugin's damage veto stopped, or for an entity that is not there. An error for an amount that is negative or not a number.

Wasm request

Shape and limits, as the router words its errors: "attacker should be an entity id".

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

{"call": "damage_by", "entity": 42, "amount": 4.0, "cause": "minecraft:generic"}

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