Entities from Lua

An entity object is what world:entities(), world:entity(id), the entity field of an event and world:spawn(...) give you. Players answer to the same object through world:entity(player_entity_id), for the subset that applies to them. Dropped items (minecraft:item) are listed by world:entities() too and answer to nbt, nbt_value, nbt_set, merge_nbt, push, teleport and velocity.

local zombie = world:spawn_as("minecraft:zombie", 0, 64, 0, 90, "plugin")
zombie.max_health = 40
zombie.health = 40
zombie:add_effect("minecraft:speed", 600, 1)
zombie:set_equipment("head", helmet_nbt)
zombie:move_to(10, 64, 10, 1.2)

Properties#

Read them as fields; the ones marked rw can be assigned.

e:get(name) and e:set(name, value) reach any property by name, including the ones that are not fields: loot_table (string) and loot_seed (integer). e:call(operation, args...) runs an operation by name, such as is_breed_item(item), which tells whether an item is the animal's breeding food.

Damage and death#

e:damage(6, "minecraft:magic", attacker.id)  -- through armour, the invulnerability window and events
e:kill()                                     -- the death sequence
e:knockback(0.5, attacker.x, attacker.z)     -- away from (x, z)
e:push(0, 1, 0)                              -- adds to the velocity

damage(amount, cause?, attacker_id?) takes a vanilla damage type path (generic by default). All of them return whether they did something.

Effects and attributes#

Equipment and riding#

e:equipment(slot) returns the stack as NBT bytes (or nil) and e:set_equipment(slot, stack_nbt) writes it, nil clearing the slot. Slots are mainhand, offhand, feet, legs, chest, head, body and saddle. e:drop_chance(slot) and e:set_drop_chance(slot, chance) read and set the chance it drops.

e:mount(vehicle_id) rides another entity, e:dismount() gets off and e:eject() throws every rider off.

Movement of mobs#

Mob goals#

A mob can carry goals a plugin owns next to the vanilla ones, in the same selector: priority, flags and interruption work as in vanilla, and a mob without plugin goals pays nothing. Mobs that run on a brain (villagers) do not run them.

A vanilla goal key is the vanilla goal class name in snake case without Goal; the minecraft: prefix is optional. A running goal that is removed stops on the next AI turn. The entity.goal event drives a plugin goal.

e:add_goal("my:wave", 3, "look")
on("entity.goal", function(ev)
    if ev.key == "my:wave" and ev.phase == "can_use" then ev.result = true end
end)

Mob state#

Vindicators named Johnny attack any living thing, evokers cast the wololo spell on blue sheep, fish schools follow a leader, witches drink helpful potions by themselves, and players shear sheep, mooshrooms, snow golems, bogged and copper golems, as in vanilla.

These properties are read with e:get(name) and written with e:set(name, value). A read answers nil, and a write false, on an entity the property does not apply to. Nothing here changes what a mob does by default.

Four more fields are plain properties: age_locked (an animal's age no longer moves), burns_in_day, despawn_in_peaceful (-1 default, 0 never, 1 despawns in peaceful) and nav_open_doors. aggressive (the arms-up flag) is also a field, and melee goals raise it while they attack, so zombies hold their arms up.

hook_bite_in starts the luring phase when written, as the bobber would. hook_phase is 0 flying, 1 hooked entity, 2 bobbing, and hook_hooked is the hooked entity id or -1. boat_status runs from 0 in water to 4 in air. fox_flags uses the bits 4 crouching, 8 interested, 16 pouncing, 64 faceplanted and 128 defending; panda_flags uses 2 sneeze, 4 roll, 8 sit and 16 on back. copper_weathering_tick is -2 waxed, -1 unset, else a game tick.

A second set of mob properties: creeper_ignited, creeper_igniter (id, -1 none), evoker_wololo (id of the sheep, -1 none), polar_standing, strider_shivering, turtle_laying_egg, turtle_going_home, parrot_dancing, wither_portals, cube_wander (false: a slime, magma cube or sulfur cube never hops by itself), boost_total and boost_time (pig and strider item boost), boost_active (r), witch_drinking (r), witch_use_ticks, bat_target ("x,y,z" or nil), guardian_moving (r) and cart_detonate (w, the speed squared a tnt minecart blows up with).

Sulfur cubes have a fuse (integer, rw): the ticks left on the lit fuse, -1 when it is not primed. When it runs out the cube explodes with power 3, breaking blocks only with mob_griefing and requiring tnt_explodes. Fire, an explosion, flint and steel, a fire charge or a powered position light it, and a cube holding an item shrugs off plain hits. Turtles lay eggs, go home and travel in water with the vanilla goals: has_egg and home_pos are set with nbt_set ("bool" and "pos" as "x,y,z"). A wandering trader stops drinking its invisibility potion or milk when Paper.CanDrinkPotionDisabled or Paper.CanDrinkMilkDisabled is true. Non-player entities in a nether portal frame travel at once and rest 300 ticks; the wither does not unless wither_portals is true.

Operations go through e:call(name, args...).

Projectiles, items and decorations#

Every property below reads as what vanilla does until a plugin writes it. e:get(name) and e:set(name, value) reach them.

Item entities take these keys through nbt_set: CanMobPickup and CanPlayerPickup (short 0 or 1; 0 stops mobs that gather items, or players, from picking it up) and FrictionState (1 removes ground friction). An armor stand takes BasaltNoMove and BasaltNoTick (true stops it from moving, or from ticking at all), and a falling block that lives over 600 ticks drops as an item unless BasaltNoExpire is true. Experience orbs keep SpawnReason, SourceEntity and TriggerEntity, and interactions keep attack and interaction as {player, timestamp}.

Ghast fireballs set fires where they explode when mob_griefing is on, arrow punch from the weapon pushes mobs and players, and primed TNT honours its explosion_power (4 by default).

Entity NBT#

e:nbt(path?) returns the whole entity NBT, or the compound at a dotted path. e:nbt_value(path) returns one scalar. e:nbt_set(path, type, value) writes into the extra data (type is bool, byte, short, int, long, float, double, string, uuid or pos) and e:merge_nbt(nbt) merges a compound: live fields are updated and the rest is kept as extra data. A uuid value is a uuid string, saved as four ints; a pos value is "x,y,z", saved as three ints. e:call("nbt_remove", path) removes a key at a dotted path and returns whether it did. Every change to the saved data is sent again to the players who can see the entity, and a bee takes its saved fields back into its live state.

World calls#

Events#

The events of mobs, projectiles and vehicles (entity.damage, entity.drops, entity.target, entity.goal, entity.move, vehicle.damage...) are listed with their fields in the entity, item and inventory events.

on("entity.drops", function(e)
  e.exp = e.exp * 2
end)