Lua API Reference

This reference describes the MagmaCore, FreeMinecraftModels, and EliteMobs Lua table builders and runtime contexts. Shared tables and EliteMobs boss-power tables have different contracts; use the section for the script you are writing.

Most table methods accept both table.method(...) and table:method(...). Global em.create_*, em.zone.create_*, and em.location.* functions require dot syntax, as do the boss-event damage setters identified below. Shared live fields are lazy lookups: read them again to refresh their value, and avoid assigning to them because that shadows the lookup. A location or other snapshot already stored in a Lua variable does not update itself.

Methods described as color-processed use the shared color-code syntax, including chat, titles, bars, custom names, and prop inventory titles.

Entity Table

The MagmaCore entity table is the base for generic entity values; Living Entity, Player, and FreeMinecraftModels Prop tables inherit it.

Properties

Field	Type	Description
uuid	string	Entity UUID.
entity_type	string	Lowercase Bukkit entity type.
is_valid	bool	Live validity value.
is_dead	bool	Live dead state.
current_location	table/nil	Live {x, y, z, yaw, pitch, world} location.
world	string/nil	Live world name.
is_player	bool	Whether the entity is a player.
is_hostile	bool	Whether the entity implements Bukkit Monster.
is_passive	bool	Whether the entity implements Bukkit Animals.
is_on_ground	bool	Live ground state.
is_flying	bool	Live player flight state; false for other entity types.
in_block	bool	Arrow-only live embedded state.
attachment_location	table/nil	Center of the block containing an embedded arrow's current location; nil when the arrow is not in a block.
attachment_block	table/nil	Center of the actual block hit by an arrow owned by an active enchantment action. Returns nil without a valid recorded embedded hit, or after the arrow moves away, changes world, or its action ends. Identifies the struck block; it does not provide a collision-safe movement destination.

Methods

Method	Args	Returns	Description
teleport(location)	table	nil	Teleport to a location table.
remove()	—	nil	Remove the entity if it is still valid.
set_silent(enabled)	bool	nil	Set the silent state.
set_invulnerable(enabled)	bool	nil	Set the invulnerable state.
set_gravity(enabled)	bool	nil	Set the gravity state.
set_glowing(enabled)	bool	nil	Set the glowing state.
set_velocity(x, y, z)	number, number, number	nil	Replace velocity; components must be finite.
set_fall_distance(distance)	number	nil	Set a finite, nonnegative fall distance.
set_shooter(uuid)	string	bool	Projectile-only method; assign a resolved entity that implements Bukkit ProjectileSource.
set_direction(x, y, z)	number, number, number	nil	Fireball-only method; set a finite, nonzero flight direction.
set_pickup(status)	string	nil	Arrow-only method; ALLOWED, DISALLOWED, or CREATIVE_ONLY.
can_receive_hostile_effect(actor_uuid)	string	bool	Check whether the target can receive a hostile effect from the online player. Providers can apply their own combat restrictions.
has_clear_movement_path(location)	table	bool	Preflight a same-world pull against collision, world bounds, and loaded chunks. Non-player entities also reject protected regions. Does not move the entity.
movement_path_status(location)	table	string	Return clear, blocked, protected, or unavailable; protected applies to non-player entities. Collision checks conservatively sweep the entity's bounding box.

Shared location arguments require x, y, and z. An omitted world uses the entity's world; an unresolved world name also retains that fallback. The separate em.location.* queries require a loaded world and default missing coordinates to zero. Neither movement preflight nor can_receive_hostile_effect is automatically applied to direct teleport, velocity, or damage calls.

A clear player path does not authorize entry or combat. Actual player movement remains subject to native movement listeners, including region entry restrictions; ordinary build protection alone does not prevent player travel.

can_receive_hostile_effect requires a valid online player actor and a valid, living, same-world nonplayer target. It rejects armor stands, invulnerable entities, NPC-tagged entities, and tamed animals. EliteMobs can add combat authorization restrictions. Invalid UUID strings can raise errors in set_shooter and set_owner; invalid pickup enum names also raise errors.

Entity Table: EliteMobs Enrichment

The EliteMobs enricher adds these values to MagmaCore entity tables. Tracking flags and the presence of elite are determined when the table is built; only fields identified as live refresh on access. FreeMinecraftModels's optional EliteMobs adapter adds elite information but does not add elite_player.

Properties

Field	Type	Description
is_elite	bool	Whether EliteMobs tracked the entity when the table was built.
is_custom_boss	bool	Whether the tracked elite is a custom boss.
is_significant_boss	bool	Whether it is a custom boss with a health multiplier above 1.
elite	table/nil	Nested EliteMobs data, present only for a resolved elite.
elite.level	int	Elite level snapshot.
elite.name	string/nil	Elite display name snapshot.
elite.health	number	Live health.
elite.max_health	number	Live maximum health.
elite.is_custom_boss	bool	Whether the elite is a custom boss.
elite.health_multiplier	number	Configured health multiplier snapshot.
elite.damage_multiplier	number	Configured damage multiplier snapshot.
elite_player	table/nil	Player-only table, resolved lazily when EliteMobs player data exists.
elite_player.tier	number	Player combat tier calculated from skill XP without refreshing enchantment queries.

Methods

Method	Args	Returns	Description
elite.remove()	—	nil	Remove the elite through the EliteMobs removal pipeline.

Entity Table: FreeMinecraftModels Enrichment

The FreeMinecraftModels enricher adds these snapshot values; model exists only when is_modeled is true when the table is built. Player-only values appear only on player tables. Model and permission methods query the underlying objects when called. In EliteMobs scripts, EliteMobs's optional FreeMinecraftModels adapter adds is_modeled, is_prop, and model, but not is_op or has_permission.

Properties

Field	Type	Description
is_modeled	bool	Whether FreeMinecraftModels resolves a modeled entity.
is_prop	bool	Whether the entity is an armor-stand-backed FreeMinecraftModels prop.
model	table/nil	Nested model data, present only for a modeled entity.
model.model_id	string/nil	Model blueprint identifier.
model.is_dynamic	bool	Whether the modeled entity is dynamic.
is_op	bool	Player-only server-operator state snapshot.

Methods

Method	Args	Returns	Description
model.play_animation(name, blend?=false, loop?=false)	string, bool?=false, bool?=false	bool	Return whether playback was accepted, including queued or suppressed attack requests; terminal death rejects playback.
model.stop_animations()	—	nil	Clear queued playback and return to idle when available; terminal death is unaffected.
model.remove()	—	nil	Remove the modeled entity.
has_permission(node)	string	bool	Player-only permission check.

Living Entity Table

The MagmaCore living entity table inherits every Entity Table property and method.

Properties

Field	Type	Description
health	number	Live health.
maximum_health	number	Live maximum health.
name	string/nil	Live Bukkit entity name.
is_alive	bool	Live inverse of Bukkit's dead state.

Methods

Method	Args	Returns	Description
damage(amount)	number	nil	Deal Bukkit damage.
push(x, y, z)	number, number, number	nil	Immediately add a vector to the current velocity.
set_facing(x, y, z)	number, number, number	nil	Teleport in place with the supplied facing direction.
add_potion_effect(type, duration, amplifier)	string (PotionEffectType), int, int	nil	Add a potion effect when the type resolves.
remove_potion_effect(type)	string (PotionEffectType)	nil	Remove a potion effect when the type resolves.
get_scale()	—	number	Return the effective scale attribute including modifiers, or 1.0 when unavailable.
set_scale(value)	number	nil	Set the scale attribute's base value when supported by the server.
set_ai(enabled)	bool	nil	Enable or disable living-entity AI.
set_owner(player_uuid)	string	bool	Tame a tameable entity for an online player; also clear wolf anger. False for unsupported entities or unavailable players.
has_potion_effect(type)	string	bool	Check a Bukkit potion-effect name; false when the name does not resolve.

Player Table

The MagmaCore player table inherits every Living Entity Table property and method.

In FMM scripts, the player table also exposes is_holding_elitemobs_item(filename). It checks the main-hand item's EliteMobs filename tag, independent of its display name or translation, and returns false for an empty hand, a different item, or an unavailable EliteMobs integration. Pass the custom-item filename including .yml, for example player:is_holding_elitemobs_item("shroomwhispers_shears.yml").

Properties

Field	Type	Description
game_mode	string	Lowercase Bukkit game mode snapshot.

Methods

Method	Args	Returns	Description
send_message(text)	string	nil	Send text processed by MagmaCore's color parser.
chat(text)	string	nil	Make the player chat through Bukkit, including executing slash-prefixed commands as that player. Text passes through the color parser.
get_held_item()	—	table/nil	Return a {type, amount, display_name} snapshot for the main-hand item, or nil for an empty hand. type is uppercase; an unnamed item's display name falls back to its material name.
consume_held_item(amount?=1)	int?=1	nil	Queue reducing whichever stack is in the main hand when the task runs; does not return a payment result or retain the checked item. Supply a positive amount; negative values are not rejected.
has_item(material, amount?=1)	string (Material), int?=1	bool	Test whether the inventory contains the requested amount.
get_target_entity(range?=50)	number?=50	table/nil	Trace from the eye against blocks and entities, excluding the player, with entity ray size 0.5; ignore fluids and passable blocks.
get_eye_location()	—	table	Return the eye location.
get_look_direction()	—	table	Return a unit {x, y, z} direction.
send_block_change(x, y, z, material, ticks?=-1)	int, int, int, string (Material), int?=-1	bool	Queue a client-only block and optionally reset it after positive ticks; invalid or non-block materials return false. True means queued.
reset_block(x, y, z)	int, int, int	bool	Queue restoring the real block for this player.
sleep(x, y, z)	number, number, number	nil	Queue placing a real white bed and attempting sleep; after waking or disconnecting, restore the original BlockData. Block-entity contents are not restored.
wake_up()	—	nil	Queue waking the player when sleeping.
show_boss_bar(text, color?=WHITE, progress, ticks?=-1)	string, string (BarColor)?=WHITE, number, int?=-1	nil	Replace the player's active solid boss bar; clamp progress to 0..1, use white for an invalid color, and optionally hide after positive ticks. Pass nil for the color to supply progress in its required third position.
hide_boss_bar()	—	nil	Remove the player's active Lua boss bar.
show_action_bar(text, ticks?=-1)	string, int?=-1	nil	Send once, or repeat every 40 ticks until a positive duration ends.
show_title(title, subtitle?="", fade_in, stay, fade_out)	string, string?="", int, int, int	nil	Show a title with color-processed title and subtitle text.

Shared bars belong to the player within the host plugin's MagmaCore copy. They are not isolated by script: a new show_boss_bar replaces the player's current bar, and a new show_action_bar cancels the current repeating action bar. An expiry timer removes only the bar or action bar that started it, so an older expiry no longer clears a newer one. These UI timers and queued block changes are not owned by context.scheduler. Block changes and resets read the player's world when their tasks execute; do not depend on them restoring the intended block after a world change. Sleep cleanup first checks after 20 ticks, then every 10 ticks.

World Table

The MagmaCore world table is exposed as context.world and captures its world when built. EliteMobs boss powers inherit it and apply the overrides documented later. Nearby queries return one-based arrays using axis-aligned boxes with radius as each half-extent; they do not exclude the script owner or filter player game modes.

Properties

Field	Type	Description
name	string	World name snapshot.

Methods

Method	Args	Returns	Description
get_block_at(x, y, z)	int, int, int	string	Return a lowercase Material name, or air without loading an unloaded chunk.
set_block_at(x, y, z, material)	int, int, int, string (Material)	bool	Queue block placement; invalid materials return false and unloaded chunks are skipped by the queued task.
get_highest_block_y(x, z)	int, int	int	Return the highest block Y.
spawn_particle(particle, x, y, z, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	string (Particle), number, number, number, int?=1, number?=0, number?=0, number?=0, number?=0	nil	Spawn a particle; invalid names do nothing.
play_sound(sound, x, y, z, volume?=1, pitch?=1)	string (Sound), number, number, number, number?=1, number?=1	nil	Play a registered sound or lowercase namespaced resource-pack sound key.
strike_lightning(x, y, z)	number, number, number	nil	Strike lightning.
get_time()	—	int	Return world time in ticks.
set_time(ticks)	int	nil	Set world time.
get_nearby_entities(x, y, z, radius)	number, number, number, number	table	Return nearby Entity or Living Entity tables.
get_nearby_players(x, y, z, radius)	number, number, number, number	table	Return nearby Player tables.
spawn_entity(type, x, y, z)	string (EntityType), number, number, number	table/nil	Spawn a vanilla entity; unknown enum names return nil, but valid nonspawnable types can raise errors.
raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, max_distance?=50, fluid_mode?=NEVER, blocks_only?=false, loaded_only?=false)	six numbers, number?, string?, bool?, bool?	table/nil	Return hit_entity, hit_location, and hit_block; fluid modes are NEVER, SOURCE_ONLY, ALWAYS. With loaded_only, refuse unloaded chunks in the ray's bounding rectangle and return nil.
place_temporary_block(x, y, z, material, ticks?=0, require_air?=false)	int, int, int, string (Material), int?=0, bool?=false	bool	Place a temporary block; invalid materials or unloaded chunks return false.
drop_item(x, y, z, material, amount?=1)	number, number, number, string (Material), int?=1	table/nil	Drop an item naturally and return its Entity Table; invalid materials return nil.
spawn_firework(x, y, z, colors, type?=BALL, power?=1)	number, number, number, table, string (FireworkEffect.Type)?=BALL, int?=1	nil	Queue a firework using Bukkit Color constant names, defaulting to white when none resolve.
strike_lightning_at_location(location)	table	nil	Strike lightning in the location table's world.
play_sound_at_location(location, sound, volume?=1, pitch?=1)	table, string (Sound), number?=1, number?=1	nil	Play a registered sound or lowercase namespaced resource-pack sound key.
spawn_particle_at_location(location, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0	nil	Spawn through this world table. Supply a location in the same world.
get_block_at_location(location)	table	string	Return a lowercase material name, or air for an invalid location or unloaded chunk.
set_block_at_location(location, material)	table, string (Material)	bool	Queue block placement in the location table's world.
place_temporary_block_at_location(location, material, ticks?=0, require_air?=false)	table, string (Material), int?=0, bool?=false	bool	Place a temporary block in the location table's world.
get_highest_block_y_at_location(location)	table	int/nil	Return the highest block Y, or nil for an invalid location.
terrain_impact_at_location(location, options?)	table, table?	table/nil	Show a temporary visual terrain impact; options: radius=4.5 (0.5–6), intensity=1 (0–1), duration_ticks=35 (1–200), view_range=48 (1–96), seed; returns a handle or nil.
terrain_impact(x, y, z, options?)	number, number, number, table?	table/nil	Show the same visual impact at coordinates in this world.
impact.is_active()	—	bool	Check whether the terrain-impact handle is active; impact.id is its string identifier.
impact.remove()	—	bool	Remove an active impact; false if already inactive or removal fails.
get_entity(uuid)	string	table/nil	Resolve a valid entity in this world's loaded entity registry. Use a valid UUID string.
block_is_passable(x, y, z)	int, int, int	bool/nil	Return block passability, or nil for unloaded chunks or out-of-height coordinates.
location_is_protected(location)	table	bool	Query registered protection providers, defaulting an omitted world to this world.
spawn_dust(location, count, red, green, blue)	table, int, int, int, int	nil	Spawn fixed-size DUST with RGB components from 0 to 255, spread 0.1 per axis; skips unloaded chunks. Use a location in this world.

A raycast that hits nothing returns an empty table with nil hit fields. A block hit includes hit_block = {x, y, z, material} with lowercase material. The combined trace uses entity ray size 0.5 and no entity filter. loaded_only=true checks the whole bounding rectangle and can refuse a ray even when the unloaded chunk is away from its exact path. Invalid fluid names raise errors.

Shared particle names are uppercased before lookup. These positional particle methods have no data argument, so particles requiring data can raise errors; use spawn_dust for shared RGB dust. Highest-block queries and spawning methods have no general loaded-chunk guard. Block placement methods do not automatically check region protection. A true placement result is not proof that a queued edit or a require_air check succeeded.

Temporary blocks with positive ticks save the original BlockData and restore it when the timer ends, when the chunk or world unloads, or when the plugin shuts down. Restoration happens only while the block still holds the temporary block, so a later edit is not overwritten. Placing a temporary block again on a block that still holds one restarts its timer and keeps the first saved original. Blocks with block entities, such as chests and signs, unloaded chunks, and blocks already held by another temporary-block owner are skipped. Breaking a temporary block drops nothing and ends tracking without restoring; placing a block there also ends tracking. Nonpositive ticks place the block permanently without tracking. These operations are not a script-scoped rollback system.

Shared EliteMobs world additions

EliteMobs registers these helpers on its shared world tables, including NPC scripts. They require the destination chunk to be loaded. The shared spawn_boss_at_location signature requires both a location and level; boss powers override it with the optional-argument form listed later.

Method	Args	Returns	Description
lightning_effect_at_location(location)	table	nil	Show lightning without its normal damage, using the EliteMobs lightning-spawn bypass.
spawn_npc_at_location(file, location)	string, table	table/nil	Spawn a configured NPC and return a handle with remove(), or nil if spawning is invalid.
spawn_boss_at_location(file, location, level)	string, table, int	table/nil	Spawn a configured custom boss and return a shared Living Entity Table, or nil if unavailable.

context.world: FreeMinecraftModels Additions

FreeMinecraftModels registers these on its own MagmaCore world table, so they appear on context.world in FreeMinecraftModels prop scripts. Every method returns false when EliteMobs is not enabled or the player does not resolve. The loot helpers fall back to the player's location when their location argument is missing or unusable.

Methods

Method	Args	Returns	Description
start_elitemobs_transport(player, route_id)	player, string	bool	Start a saved EliteMobs transport route for a same-world player; false when the player or integration is unavailable.
drop_elitemobs_procedural_loot(player, level, location?)	table/string, int, table?	bool	Drop one procedurally generated EliteMobs item for the player; returns false when procedural item drops are disabled.
drop_elitemobs_random_loot(player, level, location?)	table/string, int, table?	bool	Roll the EliteMobs loot tables for the player at the given level.
drop_elitemobs_custom_loot(player, file, level, location?)	table/string, string, int, table?	bool	Drop a specific EliteMobs custom item file for the player; returns false when the file does not resolve.

The player argument accepts a player table, a UUID string, or an exact player name. The location argument accepts a location table or an entity table carrying current_location. Procedural loot follows EliteMobs's direct-inventory setting, including dropping overflow at the player; it is not always dropped at the requested location.

em Helper Table

MagmaCore exposes this table globally before any script hook runs. Its constructors create data only; they do not register a watch, load a world, or validate a complete shape. Use dot syntax for the global functions. Returned location and zone methods also accept colon syntax, mutate their table, and return that same table. Zone setters retain the supplied location table by reference.

Properties

The helper constructors return the compact data tables below.

Field	Type	Description
location.x	number	X coordinate returned by em.create_location.
location.y	number	Y coordinate returned by em.create_location.
location.z	number	Z coordinate returned by em.create_location.
location.world	string/nil	World name when supplied to em.create_location.
location.yaw	number/nil	Yaw when supplied to em.create_location.
location.pitch	number/nil	Pitch when supplied to em.create_location.
vector.x	number	X component returned by em.create_vector.
vector.y	number	Y component returned by em.create_vector.
vector.z	number	Z component returned by em.create_vector.
zone.kind	string	sphere, dome, cylinder, cuboid, cone, static_ray, rotating_ray, or translating_ray.
zone.radius	number/nil	Sphere, dome, cylinder, or cone radius.
zone.height	number/nil	Cylinder height.
zone.x	number/nil	Cuboid X size.
zone.y	number/nil	Cuboid Y size.
zone.z	number/nil	Cuboid Z size.
zone.length	number/nil	Cone or ray length.
zone.thickness	number/nil	Static-ray thickness.
zone.point_radius	number/nil	Rotating- or translating-ray point radius.
zone.animation_duration	number/nil	Rotating- or translating-ray animation duration.
zone.origin	table/nil	Location set by set_center or set_origin.
zone.destination	table/nil	Location set by set_destination.

Methods

Method	Args	Returns	Description
em.create_location(x, y, z, world?, yaw?, pitch?)	number, number, number, string?, number?, number?	table	Return a location table.
em.create_vector(x, y, z)	number, number, number	table	Return an {x, y, z} vector table.
location.add(dx?=0, dy?=0, dz?=0)	number?=0, number?=0, number?=0	table	Add in place and return the same location table.
em.zone.create_sphere_zone(radius)	number	table	Return a sphere definition with set_center(location).
em.zone.create_dome_zone(radius)	number	table	Return a dome definition with set_center(location).
em.zone.create_cylinder_zone(radius, height)	number, number	table	Return a cylinder definition with set_center(location).
em.zone.create_cuboid_zone(x, y, z)	number, number, number	table	Return a cuboid definition with set_center(location).
em.zone.create_cone_zone(length, radius)	number, number	table	Return a cone definition with set_origin(location) and set_destination(location).
em.zone.create_static_ray_zone(length, thickness)	number, number	table	Return a static-ray definition with origin and destination setters.
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	number, number, number	table	Return a rotating-ray definition with origin and destination setters.
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	number, number, number	table	Return a translating-ray definition with origin and destination setters.
zone.set_center(location)	table	table	Set the center as zone.origin and return the same zone table.
zone.set_origin(location)	table	table	Set the origin and return the same zone table.
zone.set_destination(location)	table	table	Set the destination and return the same zone table.
em.location.is_in_dungeon(location)	table	bool	Test registered dungeon regions and owners reporting the dungeon kind.
em.location.is_protected(location)	table	bool	Test built-in WorldGuard/GriefPrevention adapters and plugin-registered protection owners.
em.location.owned_by(location, namespace)	table, string	bool	Test ownership by a plugin namespace.
em.location.owners(location)	table	table	Return an array of owner namespace strings.
em.location.kinds_at(location)	table	table	Return an array of ownership kind strings.
em.location.has_kind(location, kind)	table, string	bool	Test an ownership kind.

For em.location.*, world must be a loaded-world name or a table with name; there is no owner-world fallback. Missing or unresolved worlds return false or an empty array, and missing coordinates default to zero. Ownership namespaces are case-sensitive; kind tags are case-insensitive. Ownership alone implies neither dungeon membership nor protection. Queries reflect registered providers, not every possible protection plugin; a failing registered region adapter reports protected. Owner and kind arrays have no guaranteed order.

Mind program context

Native Mind callbacks use this context instead of the ordinary power/NPC context. File-backed behavior programs also load from plugins/EliteMobs/behaviors/; see boss behavior configuration. EliteMobs integrations register ai.program and ai.module definitions through EliteMindService; placing these definitions in the ordinary powers directory does not register a Mind program.

Field	Type	Description
tick, generation	number	Current game tick and runtime generation.
entity	table	Shared Living Entity Table for the actor.
memory, perception, actuator, actions	table	Callback-scoped services below.

Method	Args	Returns	Description
memory.get(key)	string	value/nil	Read a declared memory key.
memory.set(key, value, ttl_ticks?)	string, value, int?	nil	Set a declared memory using its configured type, optionally with an expiry.
memory.forget(key)	string	nil	Remove a declared memory.
memory.contains(key)	string	bool	Check for a declared memory value.
perception.current_target()	—	table/nil	Return the current target as a shared Living Entity Table.
perception.nearest_player(radius)	number	table/nil	Return the nearest player in range.
perception.can_see(entity_or_uuid)	table/string	bool	Check line of sight to a living entity.
perception.navigation()	—	table	Return destination_active, navigation_in_progress, consecutive_stuck_ticks, optional destination, and optional last_progress with tick and position.
actuator.move_to(location, speed?=1)	table, number?=1	bool	Request navigation to a same-world location with a finite, positive speed; false when pathfinding did not start.
actuator.stop_moving()	—	nil	Stop navigation.
actuator.look_at(location)	table	nil	Look toward a location.
actuator.jump()	—	nil	Request a jump.
actuator.set_target(entity_or_uuid)	table/string	bool	Set a living target; false if it cannot be resolved.
actuator.clear_target()	—	nil	Clear the target.
actuator.attack(entity_or_uuid)	table/string	bool	Request an attack; false if the target cannot be resolved.
actuator.stop_all()	—	nil	Stop the movement, target, and attack that this behavior's held controls cover.
actions.request(identifier, payload?)	string, table?	string	Request a semantic action and return its lowercase result; payload values support scalars, entity UUID tables, and world/x/y/z position tables.

Each callback builds service sections on first access and reuses them within that callback. Memory keys must be declared; undeclared keys raise an error. A successful actuator.set_target or actuator.attack return means that a living target resolved and the request was forwarded, not that navigation or an attack completed. Action payloads accept the supported scalar or entity/position values, not arbitrary nested Lua tables. Action identifiers must be lowercase namespaced keys of at most 128 characters; payloads hold at most 16 entries with lowercase keys of at most 64 characters, and string values are limited to 256 characters. Every actuator method except stop_all, and actions.request, raises an error unless the calling behavior holds the matching control. Sensors cannot use the actuator or actions at all. Lua-authored behavior programs are described in Behavior Programs.

ai global

MagmaCore installs this global in every Lua environment. The constructors only tag the table they receive; EliteMobs compiles the tagged tables from behavior program files.

Field	Type	Description
ai.controls.move, look, jump, target, attack, use_item, action	string	Control names for a behavior's controls array; use_item has no Lua actuator method.

Method	Args	Returns	Description
ai.program(definition)	table	table	Tag a program definition with id, revision, optional modules, memories, sensors, behaviors, budget, and runaway.
ai.module(definition)	table	table	Tag a module definition with id, revision, optional dependencies, memories, sensors, and behaviors.
ai.sensor(definition)	table	table	Tag a sensor with id, interval?=1, and sense(c).
ai.behavior(definition)	table	table	Tag a behavior with id, priority?=0, controls, can_start, can_continue, start, tick, and stop(c, reason).

context.mind_action: EliteMobs Power Hook

Available during on_mind_action(context). The hook returns "accepted", "deferred", or "rejected"; attached powers are visited in attachment order until one accepts.

Field	Type	Description
key	string	Namespaced semantic action identifier.
payload	table	Lua copy of the action payload; editing it does not change the original request. UUID values are strings and positions are {world, x, y, z} tables.
game_tick, generation	number	Action tick and runtime generation.

context.state

Every MagmaCore script instance receives a plain Lua table that persists for that instance's lifetime. Use it for counters, flags, task IDs, and values shared between hooks.

context.state.counter = (context.state.counter or 0) + 1

context.log

MagmaCore, FreeMinecraftModels, and EliteMobs NPC Methods

Method	Args	Returns	Description
info(message)	string	nil	Log an informational message with the shared Lua prefix.
warn(message)	string	nil	Log a warning.
error(message)	string	nil	Log through the shared warning channel.

EliteMobs Boss-Power Methods

Method	Args	Returns	Description
info(message)	string	nil	Log an informational boss-power message.
warn(message)	string	nil	Log a warning.
debug(message)	string	nil	Log an informational message with the Lua-power debug prefix.

context.scheduler

Scheduled tasks belong to the script instance and are cancelled when it shuts down. Both naming families below are available on shared MagmaCore surfaces and EliteMobs boss powers.

Callbacks receive a fresh context, normally without event or a triggering player. Capture needed values or UUIDs before scheduling, then resolve the current entity. Retaining the original context does not safely retain its lazily resolved event. While paused, due one-shot tasks wait and repeating tasks skip runs without replaying them. Callback errors close the script. Shutdown cancels owned tasks and watches; it does not undo arbitrary entity/world edits or cancel every helper's independent timer.

Method	Args	Returns	Description
run_later(ticks, callback)	int, function	int	Run once after the delay and return the Bukkit task ID.
run_repeating(delay, interval, callback)	int, int, function	int	Run repeatedly after an initial delay and return the task ID.
cancel(task_id)	int	nil	Cancel an owned task.
run_after(ticks, callback)	int, function	int	Alias for run_later.
run_every(interval, callback)	int, function	int	Run repeatedly with no initial delay and return the task ID.
cancel_task(task_id)	int	nil	Alias for cancel.

context.cooldowns

Omitting a local key uses __lua: followed by the script filename. Explicit keys are used exactly as supplied. Shared MagmaCore local stores belong to the script's owner adapter: FMM creates a separate adapter per prop script, while all scripts on one EliteMobs NPC share an adapter and can collide on an explicit local key. FMM global cooldowns are shared across scripts on the same prop; NPC global cooldowns are shared on that NPC adapter.

EliteMobs boss powers use the boss's shared store for local keys and its built-in power cooldown for global state. Local timers, plus shared MagmaCore global timers, measure real elapsed time at 50 ms per tick, including pauses and low server TPS. Boss global cooldowns count server ticks and keep the later expiry: a shorter set_global never shortens an active global cooldown, and a non-positive duration does nothing. Checking or setting a local cooldown does not check or set the global cooldown automatically.

Method	Args	Returns	Description
local_ready(key?)	string?	bool	Test whether the keyed local cooldown is ready.
local_remaining(key?)	string?	int	Return remaining ticks, or 0 when ready.
check_local(key, duration)	string/nil, int	bool	If ready, start the cooldown and return true. Pass nil for the default key.
set_local(duration, key?)	int, string?	nil	Set or clear the local cooldown; a non-positive duration clears it.
global_ready()	—	bool	Test whether the owner's global cooldown is ready.
set_global(duration)	int	nil	Set the global cooldown in ticks. On shared MagmaCore surfaces, a non-positive duration clears it.

context.zones: Shared MagmaCore Surface

FreeMinecraftModels scripts, EliteMobs NPC scripts, and other default MagmaCore consumers receive integer zone handles in the current script owner's world.

Method	Args	Returns	Description
create_sphere(x, y, z, radius)	number, number, number, number	int/nil	Register a sphere and return its handle, or nil when the owner has no world.
create_cylinder(x, y, z, radius, height)	number, number, number, number, number	int/nil	Register a cylinder and return its handle, or nil when the owner has no world.
create_cuboid(x, y, z, x_size, y_size, z_size)	number, number, number, number, number, number	int/nil	Register a cuboid and return its handle, or nil when the owner has no world.
watch(handle, on_enter?, on_leave?)	int, function?, function?	bool/nil	Enable boundary tracking for a known handle. Function presence enables the corresponding on_zone_enter or on_zone_leave hook; the supplied function body is not called directly.
unwatch(handle)	int	nil	Stop tracking and remove the handle.

Generic watches test player location points. Cuboid sizes are half-extents in this path (zero Z substitutes nonzero X); this does not establish the same volume as EliteMobs entity-overlap or sampled-location queries. Zones retain their creation coordinates and world while each tick scans players in the owner's current world. Generic zone hooks expose the crossing player through context.player and context.event.player.

Creation starts membership tracking immediately, before watch installs hook dispatchers. Installing a watcher later does not emit an entry for a player already tracked inside. Omitting a callback in a second watch call does not clear a previously installed dispatcher. Disconnects and unwatch do not guarantee a leave hook. Zone checks run before on_game_tick.

context.event: Shared MagmaCore Surface

This table exists while a shared hook has a current Bukkit event or actor. It is absent from scheduled callbacks and hooks without either value.

Field or Method	Type	Description
is_cancelled	bool	Cancellation state captured when the event subtable was first resolved; calling cancel() or uncancel() does not refresh this field.
cancel()	method	Cancel the current event. Present only when it implements Bukkit Cancellable.
uncancel()	method	Un-cancel the current event. Present only when it implements Bukkit Cancellable.
player	table	Living Entity Table for the current actor when one is available.

Generic zone hooks provide an actor but no cancellable Bukkit event, so they expose is_cancelled = false and player without cancel() or uncancel().

context.item

Enchantment action scripts expose this table when their captured source has an inventory slot and item. It addresses that exact slot and checks the current item's material and metadata against the snapshot, ignoring damage and stack amount. It does not search the player's inventory or track an item's unique identity: an equivalent replacement in the captured slot also matches. It can be nil for consumed ammunition. This is distinct from the retired FreeMinecraftModels equipped-item runtime.

Method	Args	Returns	Description
get_durability()	—	table/nil	Remaining {current, max} durability; nil for unavailable or nondamageable items.
get_durability_percentage()	—	number/nil	Remaining durability divided by the material's maximum; normally 0..1, but externally over-damaged metadata can fall outside that range.
use_durability(amount, can_break?=false)	int, bool?	bool	Change damage; negative amounts repair. By default retain at least one durability; can_break=true can consume the stack.
use_durability_percentage(fraction, can_break?=false)	number, bool?	bool	Apply ceil(max_durability * fraction) damage with the same break policy.
consume(amount)	positive int	bool	Consume from the captured stack only when enough items remain.

Durability uses the material's maximum, not a custom max-damage component. These direct changes do not apply vanilla wear calculations, Unbreaking, unbreakable checks, or player item-damage events. Percentage changes require finite values and an integer-range result; negative fractions repair. Breaking consumes the entire captured stack. For the action lifecycle and complete context, see authored enchantments.

context.prop

FreeMinecraftModels prop scripts receive this table, which inherits the MagmaCore Entity Table when a backing entity exists.

Properties

Field	Type	Description
model_id	string/nil	Model blueprint name, or nil when no blueprint exists.
current_location	table/nil	Live prop location.

Methods

Method	Args	Returns	Description
play_animation(name, blend?=true, loop?=true)	string, bool?=true, bool?=true	bool	Play the named animation.
stop_animation()	—	nil	Clear queued playback and return to idle when available; the terminal death state is unaffected.
hurt_visual()	—	nil	Play the red-tint hurt visual without damage.
pickup()	—	nil	Queue permanent removal and drop a placement item.
has_mount_points()	—	bool	Test whether the prop has mount-point bones.
mount(player)	table	bool	Queue mounting a resolved player on the first available seat.
dismount(player)	table	bool	Queue dismounting a resolved player from this prop.
get_passengers()	—	table	Return mounted player Entity Tables.
spawn_elitemobs_boss(file, x, y, z)	string, number, number, number	table/nil	Spawn an EliteMobs custom boss when EliteMobs is enabled.
open_inventory(player, title, rows?=3)	table, string, int?=3	bool	Queue opening persistent storage with rows clamped from 1 to 6.
place_book(player)	table	bool	Queue storing one held written or writable book when the prop has none.
read_book(player)	table	bool	Queue opening a stored written book.
take_book(player)	table	bool	Queue returning the stored book to the player.
has_book()	—	bool	Test whether the prop stores a book.
drop_inventory()	—	bool	Queue clearing persistent storage and dropping its items.
drop_book()	—	bool	Queue clearing and dropping the stored book.
is_viewing_inventory(player)	table	bool	Test whether the player is viewing this prop's tracked inventory.
set_persistent_data(key, value)	string, string	bool	Store a string under the prop-scoped fmm_lua_ key.
get_persistent_data(key)	string	string/nil	Return the stored string, or nil.

For queued prop operations, true means the initial player/backing-entity checks passed, not that a seat was available, a book was stored, or a GUI opened. take_book removes storage before inserting the book and does not drop inventory overflow. All viewers of one prop share a single live inventory, saved when the last viewer closes it; while it is open, later calls reuse its title and size. Stored contents larger than the requested rows open at their stored size, so no slots are dropped. Prop data is stored on the backing armor stand; a newly generated placement item is not a promise to preserve that data through pickup.

In on_projectile_hit, prop scripts also receive context.projectile, a shared Entity Table for the projectile. The hook does not fire when another plugin already cancelled the hit. context.event wraps the cancellable FreeMinecraftModels hit event, and context.event.player is the shooter when it is a living entity, including mobs; context.player is set only when a player fired the projectile.

context.npc

EliteMobs NPC scripts inherit the shared MagmaCore contexts and add this NPC-specific table.

Properties

Field	Type	Description
name	string	Configured NPC display name.
filename	string	NPC configuration filename.
uuid	string	Runtime NPC UUID.
activation_radius	number	Configured activation radius.
current_location	table	Location snapshot, present only while the backing living entity exists.
entity_type	string	Uppercase Bukkit entity type, present only while the backing living entity exists.

Methods

Method	Args	Returns	Description
is_valid()	—	bool	Test whether the NPC is valid.
remove()	—	nil	Remove the NPC through its owning lifecycle.
get_location()	—	table	Return the current NPC location, falling back to its spawn location. The table also includes a direction vector.
get_eye_location()	—	table	Return the current eye location, falling back to the spawn location. The table also includes a direction vector.
get_activation_radius()	—	number	Return the current configured activation radius.
get_nearby_players(radius)	number	table	Return same-world Player Tables within a 3D radius of the NPC's feet, without a game-mode filter.
face_direction_or_location(target)	table	nil	Face a vector direction or same-world location; ignored while patrol movement is active.
say_greeting(player?)	table/string?	nil	Send the configured greeting, defaulting to the triggering player when available. A player table, UUID, or name is accepted.
say_dialog(player?)	table/string?	nil	Send configured dialog with the same player resolution.
say_farewell(player?)	table/string?	nil	Send the configured farewell with the same player resolution.
play_model_animation(name)	string	nil	Play a model animation when a custom model exists.
patrol_pause()	—	bool	Pause the configured patrol.
patrol_resume()	—	bool	Resume the configured patrol after a scripted hold or walk.
walk_to(x, y, z)	number, number, number	bool	Walk to an authored-origin offset, then resume patrol.
hold(x, y, z)	number, number, number	bool	Walk to an authored-origin offset and remain there.
teleport(x, y, z)	number, number, number	bool	Teleport to an entity-ticking authored-origin offset.

EliteMobs Power Location Table

EliteMobs boss-power tables return this location shape from get_location(), get_eye_location(), current_location, and other location results. A missing location returns an empty table.

Properties

Field	Type	Description
x, y, z	number	Coordinates.
yaw, pitch	number	Rotation.
world	string/nil	World name when the location has a world.
direction	table	Unit {x, y, z} facing vector.

Methods

Method	Args	Returns	Description
add(dx?=0, dy?=0, dz?=0)	number?=0, number?=0, number?=0	table	Add to the coordinates in place and return the same table; direction is not updated.

EliteMobs Power Entity Reference Table

EliteMobs boss-power methods return this lightweight table for non-living entities such as projectiles, fireworks, and falling blocks.

Properties

Field	Type	Description
name	string	Entity name snapshot.
uuid	string	Entity UUID.
entity_type	string	Uppercase Bukkit entity type snapshot.
is_player	bool	Always false.
is_elite	bool	Always false.
is_mount	bool	False unless a boss marks a returned mount table true.
current_location	table	Location snapshot.

Methods

Method	Args	Returns	Description
is_valid()	—	bool	Test live validity.
get_location()	—	table	Return the live location.
get_velocity()	—	table	Return the live velocity.
is_on_ground()	—	bool	Test the live ground state.
teleport_to_location(location)	table	nil	Teleport when the location resolves.
set_velocity_vector(vector)	table	nil	Set velocity when the vector resolves.
set_direction_vector(vector)	table	nil	Set a fireball direction when applicable.
set_yield(amount)	number	nil	Set fireball yield when applicable.
set_gravity(enabled)	bool	nil	Set gravity.
detonate()	—	nil	Detonate when the entity is a firework.
remove()	—	nil	Remove the entity.
unregister(reason?=OTHER)	string?=OTHER	nil	Unregister using DEATH, PHASE_BOSS_RESET, PHASE_BOSS_PHASE_END, CHUNK_UNLOAD, WORLD_UNLOAD, SHUTDOWN, EFFECT_TIMEOUT, BOSS_TIMEOUT, NPC_TIMEOUT, OTHER, UNSPECIFIED_WATCHDOG_REMOVAL, REMOVE_COMMAND, KILL_COMMAND, REINFORCEMENT_CULL, ENTITY_REPLACEMENT, or ARENA_RESET.
is_inside_vehicle()	—	bool	Test whether the entity is riding a vehicle.
has_vehicle()	—	bool	Test whether a vehicle exists.
get_vehicle()	—	table/nil	Return the current vehicle reference.
set_vehicle(vehicle)	table	bool	Make this entity ride the resolved vehicle.
leave_vehicle()	—	bool	Leave the current vehicle.
has_passengers()	—	bool	Test whether passengers exist.
get_passenger_count()	—	int	Return the passenger count.
get_passengers()	—	table	Return passenger references.
add_passenger(passenger)	table	bool	Add the resolved passenger.
remove_passenger(passenger)	table	bool	Remove the resolved passenger.
eject_passengers()	—	bool	Eject every passenger.

EliteMobs Power Living Entity Table

EliteMobs boss-power living values use this separate table; the Boss and EliteMobs Power Player tables inherit it.

Properties

Field	Type	Description
name	string	Entity name snapshot.
uuid	string	Entity UUID.
entity_type	string	Uppercase Bukkit entity type snapshot.
is_player	bool	Whether the entity is a player.
is_monster	bool	Whether the entity implements Bukkit Monster.
is_elite	bool	Whether EliteMobs tracks the entity.
is_mount	bool	Whether the tracked custom boss is a mount.
is_valid	bool	Validity snapshot.
health	number	Health snapshot.
maximum_health	number	Maximum-health snapshot.
current_location	table	Location snapshot.

Methods

Method	Args	Returns	Description
is_alive()	—	bool	Test live validity and death state.
is_ai_enabled()	—	bool	Return the live AI state.
is_frozen()	—	bool	Return the EliteMobs custom-boss frozen setting, or false.
get_location()	—	table	Return the live location.
get_eye_location()	—	table	Return the live eye location.
get_height()	—	number	Return Bukkit entity height.
get_health()	—	number	Return live health.
get_maximum_health()	—	number	Return live maximum health.
get_velocity()	—	table	Return live velocity.
deal_damage(amount)	number	nil	Deal generic Bukkit damage.
deal_custom_damage(amount)	number	nil	Submit raw custom damage from the boss to a living target; skips the boss itself, invulnerable or dead targets, and players outside Survival/Adventure. Subject to instance policy and damage-event cancellation.
deal_damage_from_boss(amount)	number	nil	Deal Bukkit damage attributed to the power's boss.
restore_health(amount)	number	nil	Heal through EliteMobs when tracked, otherwise clamp Bukkit health to maximum.
play_sound_at_entity(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	Play a registered or custom namespaced sound at the entity. The second argument may instead be {volume, pitch}.
play_sound_at_self(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	Alias that plays at the entity. The second argument may instead be {volume, pitch}.
spawn_particle_at_self(particle, count?=1)	string (Particle)/table, int?=1	nil	Spawn a particle string or particle-spec table at the entity.
spawn_particles_at_location(location, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0	nil	Spawn a particle at a location.
teleport_to_location(location)	table	nil	Teleport when the location resolves.
set_velocity_vector(vector)	table	nil	Set velocity when the vector resolves.
set_gravity(enabled)	bool	nil	Set gravity.
is_on_ground()	—	bool	Test the live ground state.
apply_push_vector(vector, additive?=false, delay?=1)	table, bool?=false, int?=1	nil	Apply velocity after a delay, optionally adding to current velocity.
set_custom_name(name)	string	nil	Set a color-processed custom name.
reset_custom_name()	—	nil	Restore the EliteMobs name when tracked, otherwise the Bukkit name.
set_custom_name_visible(visible)	bool	nil	Set custom-name visibility.
set_ai_enabled(enabled, duration?=0)	bool, int?=0	nil	Set AI as an owned change; positive ticks restore the replaced value. true ends this power's active AI change, if any, instead of applying a new value.
set_awareness_enabled(enabled, duration?=0)	bool, int?=0	nil	Set mob awareness as an owned change; positive ticks restore the replaced value. true ends this power's active awareness change, if any, instead of applying a new value.
face_direction_or_location(target)	table	nil	Face a vector or same-world location.
play_model_animation(name)	string	nil	Play a custom-model animation when available.
set_scale(scale, duration?=0)	number, int?=0	nil	Set the base scale as an owned change; positive ticks restore the replaced value.
set_invulnerable(enabled, duration?=0)	bool, int?=0	nil	Set invulnerability as an owned change; positive ticks restore the replaced value.
remove_elite()	—	nil	Remove a tracked elite through the EliteMobs removal pipeline.
is_healing()	—	bool	Test the tracked elite's healing state.
set_healing(enabled)	bool	nil	true marks a tracked elite as healing when it is not already; false clears only healing this power set. Power shutdown clears healing it still owns.
navigate_to_location(location, speed?=1, force?=false, timeout?=0)	table, number?=1, bool?=false, int?=0	nil	Navigate a tracked custom boss.
add_tag(tag, duration?=0)	string, int?=0	nil	Add a tag and remove it after positive ticks.
remove_tag(tag)	string	nil	Remove a tag.
has_tag(tag)	string	bool	Test an entity, elite, or player tag.
push_relative_to(location, force?=1, extra_x?=0, extra_y?=0, extra_z?=0)	table, number?=1, number?=0, number?=0, number?=0	nil	Immediately replace velocity with a normalized outward vector times force, plus world-axis offsets. Supply a source in the same world.
overlaps_box_at_location(center, half_x?=0.5, half_y?=half_x, half_z?=half_x)	table, number?=0.5, number?, number?	bool	Test the entity bounding box against the requested box.
is_inside_vehicle()	—	bool	Test whether the entity is riding a vehicle.
has_vehicle()	—	bool	Test whether a vehicle exists.
get_vehicle()	—	table/nil	Return the current vehicle reference.
set_vehicle(vehicle)	table	bool	Make this entity ride the resolved vehicle.
leave_vehicle()	—	bool	Leave the current vehicle.
has_passengers()	—	bool	Test whether passengers exist.
get_passenger_count()	—	int	Return the passenger count.
get_passengers()	—	table	Return passenger references.
add_passenger(passenger)	table	bool	Add the resolved passenger.
remove_passenger(passenger)	table	bool	Remove the resolved passenger.
eject_passengers()	—	bool	Eject every passenger.
apply_potion_effect(type, duration, amplifier?=0)	string (PotionEffectType), int, int?=0	nil	Resolve an uppercased Bukkit potion name and apply it when instance policy permits. Amplifiers are zero-based.
set_equipment(slot, material, options?)	string (EquipmentSlot), string (Material), table?	nil	Set equipment; options support unbreakable and enchantments entries with type and level.
damage_equipment(slot, amount)	string, int	int	Apply 1–64 durability damage to HAND, OFF_HAND, HEAD, CHEST, LEGS, or FEET; returns actual damage, respects player damage-event cancellation and unbreakable items, and can break the item.
set_fire_ticks(ticks)	int	nil	Set fire ticks when instance policy permits.
add_visual_freeze_ticks(ticks?=1)	int?=1	nil	Add to Minecraft freeze ticks when instance policy permits; this can cause freezing damage and is not an AI or movement lock.
place_temporary_block(material, ticks?=0, require_air?=false)	string (Material), int?=0, bool?=false	nil	Place a temporary block at the entity.

AI, awareness, scale, and invulnerability changes are owned by the calling power. Each records the value it replaced. A positive duration restores that value after the given ticks; a duration of 0 keeps the change until the power shuts down, which also restores it. When several powers change the same property, ending one change restores the most recent remaining change, or the original value when none remain. If another plugin or command changes the property in the meantime, its value is kept and nothing is restored. Pausing a power does not end these changes. Delayed apply_push_vector and tag-removal timers still run independently of the script-owned scheduler. reset_custom_name restores a tracked elite's name; for an ordinary Bukkit entity it uses the entity's current name, not a saved original name.

EliteMobs Power Player Table

EliteMobs boss-power player values inherit every EliteMobs Power Living Entity property and method.

Properties

Field	Type	Description
game_mode	string	Uppercase Bukkit game mode snapshot.

Methods

Method	Args	Returns	Description
send_message(text)	string	nil	Send color-processed chat text.
show_action_bar(text)	string	nil	Send a color-processed action bar.
show_title(title, subtitle?="", fade_in?=10, stay?=40, fade_out?=10)	string, string?="", int?=10, int?=40, int?=10	nil	Show a color-processed title.
show_boss_bar(title, color?=WHITE, style?=SOLID, duration?=40)	string, string (BarColor)?=WHITE, string (BarStyle)?=SOLID, int?=40	nil	Show a boss bar and remove it after positive ticks.
run_command(command)	string	nil	Run a command as the player.

context.boss

EliteMobs boss powers receive this table, which inherits every EliteMobs Power Living Entity property and method and overrides the rows listed here with elite-level semantics.

Properties

Field	Type	Description
name	string	Elite display name or script filename snapshot.
uuid	string	Elite UUID.
health	number	Elite health snapshot.
maximum_health	number	Elite maximum-health snapshot.
current_location	table	Elite location snapshot.
level	int	Elite level snapshot.
damager_count	int	Damager-count snapshot.
is_in_combat	bool	Combat-state snapshot.
exists	bool	Elite existence snapshot.

Methods

Method	Args	Returns	Description
is_alive()	—	bool	Test the living entity and EliteMobs existence state.
get_health()	—	number	Return live elite health.
get_maximum_health()	—	number	Return live elite maximum health.
get_location()	—	table	Return the live elite location.
restore_health(amount)	number	nil	Heal through the EliteMobs entity.
add_tag(tag, duration?=0)	string, int?=0	nil	Add an elite tag and remove it after positive ticks.
remove_tag(tag)	string	nil	Remove an elite tag.
has_tag(tag)	string	bool	Test an elite tag.
reset_custom_name()	—	nil	Restore the elite display name.
play_sound_at_self(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	Play a registered or custom namespaced sound at the elite location. The second argument may instead be {volume, pitch}.
play_sound_at_entity(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	Alias that plays at the elite location. The second argument may instead be {volume, pitch}.
spawn_particle_at_self(particle, count?=1)	string (Particle)/table, int?=1	nil	Spawn a particle at the elite location.
play_model_animation(name)	string	nil	Play the custom boss model animation when available.
navigate_to_location(location, speed?=1, force?=false, timeout?=0)	table, number?=1, bool?=false, int?=0	nil	Navigate a custom boss.
get_damager_count()	—	int	Return the live damager count.
despawn()	—	nil	Remove the elite with reason OTHER.
remove()	—	nil	Alias for despawn().
patrol_pause()	—	bool	Pause the configured patrol.
patrol_resume()	—	bool	Resume the configured patrol after a scripted hold or walk.
walk_to(x, y, z)	number, number, number	bool	Walk to an authored-origin offset, then resume patrol.
hold(x, y, z)	number, number, number	bool	Walk to an authored-origin offset and remain there.
teleport(x, y, z)	number, number, number	bool	Teleport to an entity-ticking authored-origin offset.
get_ender_dragon_phase()	—	string/nil	Return the EnderDragon.Phase name, or nil.
set_ender_dragon_phase(phase)	string (EnderDragon.Phase)	nil	Set a valid ender-dragon phase.
has_mount()	—	bool	Test whether the boss has a live mount vehicle.
get_mount()	—	table/nil	Return the mount reference marked with is_mount = true.
set_mount(mount)	table	bool	Make the boss ride the resolved entity.
clear_mount()	—	bool	Leave the current vehicle.
dismount()	—	bool	Alias for clear_mount().
start_tracking_fireball_system(speed?=0.5)	number?=0.5	nil	For a monster boss, fire tracking fireballs at Survival/Adventure players within 20 blocks on each axis on the next tick and every 160 ticks while it has a target. The power owns this task: pausing pauses it, and losing the target or shutting down stops it. Speed must be finite and positive.
handle_spirit_walk_damage(cause)	string (DamageCause)	nil	Run Spirit Walk damage handling.
shield_wall_is_active()	—	bool	Test the shield-wall state.
initialize_shield_wall(openingDirection?=1)	int?=1	nil	Initialize directional pools equal to the boss level. Opening: 1 north, 2 east, 3 south, 4 west; other integers protect all sides. Already-active walls are unchanged.
shield_wall_absorb_damage(player, damage)	table, number	bool	Subtract damage from the attacker's side if that pool was positive; true means the script should cancel the damage event itself. Does not cancel it automatically.
deactivate_shield_wall()	—	nil	Stop the independent wall task and remove its state and visuals. Lua closure alone does not deactivate it.
start_zombie_necronomicon(target, chant)	table, string	nil	Start the independent controller for a living target. The string is display text, not a filename; summons fixed necronomicon zombie/skeleton files at the caster's level.
send_message(text, range?=20)	string, number?=20	nil	Send color-processed text to players within range.
get_nearby_players(range)	number	table	Return nearby EliteMobs Power Player tables.
get_nearby_elites(radius)	number	table	Return at most 32 living tracked elites in the same world, excluding this boss, nearest first with UUID tie-breaks; radius must be greater than 0 and at most 64.
get_target_player()	—	table/nil	Return the current mob target when it is a player.
get_nearby_players_in_zone(zone)	table	table	Return players contained by the zone.
spawn_particles_in_zone(zone, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0, coverage?=1)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0, number?=1	nil	Sample the zone interior and spawn particles.
spawn_particles_in_zone_border(zone, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0, coverage?=1)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0, number?=1	nil	Sample the zone edge and spawn particles.
get_particles_from_self_toward_zone(zone, particle, speed?=0.1)	table, string (Particle), number?=0.1	table	Build directional particle specs from the boss toward sampled zone points.
get_particles_toward_self(zone, particle, speed)	table, string (Particle), number	table	Build directional particle specs toward the boss; the live builder currently reads speed from the final supplied argument.
spawn_particles_with_vector(particles)	table	nil	Spawn an array of directional particle specs.
summon_reinforcement(file, zone_or_location?, duration?=0)	string, table?, int?=0	table/nil	Summon a reinforcement at a sampled zone point, location, or the boss; positive duration removes it after that many ticks.
summon_projectile(type, origin, destination, speed?=1, options?)	string (EntityType), table, table, number?=1, table?	table/nil	Spawn a projectile; options support custom_damage, detonation_power, yield, incendiary, gravity, glowing, invulnerable, persistent, duration, EntityEffect effect, spawn_at_origin, direction_only, track, on_land, and max_ticks.

context.players: EliteMobs Boss Powers

Method	Args	Returns	Description
current_target()	—	table/nil	Return the event actor when it is a player, otherwise the boss's current mob target when it is a player.
nearby_players(radius)	number	table	Return Player Tables within the radius of the boss.
all_players_in_world()	—	table	Return all Player Tables in the boss's current world.

context.entities: EliteMobs Boss Powers

The collection queries exclude the boss itself. Living filters accept player/players, elite/elites, mob/mobs, or any other value for all living entities. They do not impose a Survival/Adventure or dungeon-instance membership filter. The direct-target lookup returns the hook's supplied target independently of those collection filters.

Method	Args	Returns	Description
get_nearby_entities(radius, filter?="living")	number, string?	table	Living filters use a 3D feet-location radius. all or entities instead uses Bukkit's axis-aligned box query and includes non-living entities.
get_entities_in_box(center, half_x, half_y, half_z, filter?="living")	table, number, number, number, string?	table	Return living entities whose feet locations lie inside the box, including its boundary.
get_all_entities(filter?="living")	string?	table	Return matching living entities in the boss's world.
get_direct_target_entity()	—	table/nil	Return the direct target supplied by the current hook.
get_boss_spawn_location()	—	table	Return the boss's original spawn location.

context.vectors: EliteMobs Boss Powers

Method	Args	Returns	Description
get_vector_between_locations(source, destination, options?)	table, table, table?	table	Return the vector between same-world locations, or {x=0,y=0,z=0} for invalid or cross-world input. Options support normalize, multiplier, and vector offset.
rotate_vector(vector, pitch?=0, yaw?=0)	table, number?=0, number?=0	table	Return the vector rotated by pitch and yaw in degrees.
normalize_vector(vector)	table	table	Return a unit vector; a zero vector remains zero.

context.zones: EliteMobs Boss Powers

EliteMobs boss powers replace the shared integer-handle zone surface with Elite Script zone-definition queries.

Entity membership, point containment, and sampled particle locations are separate shape operations and can differ at boundaries. coverage changes sampled locations, not entity selection. watch_zone captures a shape and calls each supplied callback with an entity table, not a context; it starts checking after one tick and reports entities already inside as entries. Stopping a watch does not emit leave callbacks.

Method	Args	Returns	Description
get_entities_in_zone(zone, options?)	table, table?	table	Return matching living entities. Options support filter and mode = "full" or "border".
get_locations_in_zone(zone, options?)	table, table?	table	Return sampled locations. Options support coverage and mode = "full" or "border".
zone_contains(zone, location, mode?="full")	table, table, string?	bool	Test whether the location is in the full shape or border.
watch_zone(zone, callbacks, options?)	table, table, table?	nil	Watch with {on_enter, on_leave} callbacks. Options support filter and mode; the owned watch stops with the script.

context.script: EliteMobs Boss Powers

This bridge accepts the same table keys as Elite Script target, zone, and relative-vector YAML configuration.

Methods

Method	Args	Returns	Description
target(spec)	table	target handle	Create a target handle.
zone(spec)	table	zone handle	Create a zone handle.
relative_vector(spec, location?, zone?)	table, table?, zone handle?	vector handle	Create a relative-vector handle, defaulting its action location to the boss.
damage(target, amount?=0, multiplier?=1)	target handle, number?=0, number?=1	nil	Submit Bukkit damage attributed to the boss. Player hits enter EliteMobs combat scaling with the multiplier; nonplayer hits do not apply that multiplier.
push(target, vector, additive?=false)	target handle, table/vector handle, bool?=false	nil	After one owned tick, replace or add velocity for the captured targets; one resolved vector is used for all targets, and a missing/nonfinite vector becomes zero.
set_facing(target, vector)	target handle, table/vector handle	nil	Face resolved target entities along the vector.
spawn_particles(target, particles)	target handle, table/string	nil	Spawn the particle specification at resolved target locations.

These calls do not run an Elite Script action list, conditions, cooldowns, warning delays, or repetition automatically. Target handles retain their originating event/direct-target context; avoid reusing event-dependent handles across unrelated hooks. first_entity() means the resolver's first result, not necessarily the nearest entity.

Target Handle Methods

Method	Args	Returns	Description
entities()	—	table	Resolve and return Entity Tables.
locations()	—	table	Resolve and return location tables.
first_entity()	—	table/nil	Return the first resolved entity.
first_location()	—	table/nil	Return the first resolved location.

Zone Handle Methods

Method	Args	Returns	Description
full_target(coverage?)	number?	target handle	Create a target handle for the shape interior.
border_target(coverage?)	number?	target handle	Create a target handle for the border.
full_locations(coverage?)	number?	table	Resolve sampled interior locations.
border_locations(coverage?)	number?	table	Resolve sampled border locations.
full_entities()	—	table	Resolve entities inside the shape.
border_entities()	—	table	Resolve entities on the border.
contains(location, mode?="full")	table, string?	bool	Test full-shape or border membership.
watch(callbacks, mode?="full")	table, string?	int	Start an owned {on_enter, on_leave} watch and return its task ID.

Relative-Vector Handle Methods

Method	Args	Returns	Description
resolve()	—	table	Resolve the vector for the current context.

EliteMobs Power Event Table

EliteMobs boss-power event values expose fields and methods conditionally by event type.

Properties

Field	Type	Description
damage_amount	number/nil	Damage-event amount snapshot.
damage_cause	string/nil	DamageCause name when the damage event exposes one.
damager	table/nil	Raw damage-by-entity damager reference; for a projectile hit this is the projectile, not its shooter.
projectile	table/nil	Projectile reference when the damager is a projectile.
spawn_reason	string/nil	Elite spawn reason.
entity	table/nil	Damaged reinforcement, death, or zone-event entity, depending on the hook.
is_damage_transfer	bool/nil	Player-to-elite damage only: whether this hook is processing an explicitly transferred hit.

Methods

Method	Args	Returns	Description
cancel_event()	—	nil	Cancel an EliteDamageEvent or other cancellable event.
set_damage_amount(amount)	number	nil	Replace EliteDamageEvent damage; call with dot syntax.
multiply_damage_amount(multiplier)	number	nil	Multiply EliteDamageEvent damage; call with dot syntax.
get_damage_amount()	—	number	Return the current EliteDamageEvent amount after modifications.
transfer_damage(target, amount)	entity reference, number	bool	Player-to-elite damage only: submit finite nonnegative damage to another live elite allowed by instance policy. Zero, cancelled inputs, nested transfers, and the original target return false; a nonelite recipient is an error. True means submitted, not guaranteed damage. Does not subtract or cancel the original damage.

context.world: EliteMobs Additions and Overrides

EliteMobs boss powers inherit the shared World Table, including the shared EliteMobs lightning-effect and NPC-spawn helpers, then add or override the methods below. Inherited coordinate methods keep their shared behavior. Boss-specific location methods use the boss location converter: absent/non-table locations fall back to the boss, missing coordinates default to zero, and an explicitly named world must resolve.

Methods

Method	Args	Returns	Description
play_sound_at_location(location, sound, volume?=1, pitch?=1)	table, string (Sound), number?=1, number?=1	nil	Override that accepts registered or custom namespaced sounds through EliteMobs support.
spawn_particle_at_location(location, particle, count?=1)	table, string (Particle)/table, int?=1	nil	Override that accepts an EliteMobs particle-spec table.
set_block_at_location(location, material, require_air?=false)	table, string (Material), bool?=false	nil	Override that places the block permanently through the temporary-block manager, without a timer or tracking.
place_temporary_block_at_location(location, material, ticks?=0, require_air?=false)	table, string (Material), int?=0, bool?=false	nil	Override that uses EliteMobs temporary-block placement.
get_block_type_at_location(location)	table	string/nil	Return an uppercase Material name, or nil for an invalid location.
get_highest_block_y_at_location(location)	table	int/nil	Override that returns the highest block Y, or nil.
get_blast_resistance_at_location(location)	table	number	Return block blast resistance, defaulting to 0 for an invalid location.
is_air_at_location(location)	table	bool	Test whether the target block is air.
is_passable_at_location(location)	table	bool	Test Bukkit passability.
is_passthrough_at_location(location)	table	bool	Test whether the material is not solid.
is_on_floor_at_location(location)	table	bool	Test for a non-solid target with a solid block below.
is_standing_on_material(location, material)	table, string (Material)	bool	Test the block below.
strike_lightning_at_location(location)	table	nil	Override that enables the EliteMobs lightning bypass before striking.
run_empowered_lightning_task_at_location(location)	table	nil	Independently emit 60 warning iterations, then real lightning and a downward fireball of yield 5. Damaging; Lua pause/closure does not cancel it.
set_world_time(time) / set_world_time(location, time)	int/table, int?	nil	Set the boss world's time or the supplied location world's time.
set_world_weather(weather, duration?=6000) / set_world_weather(location, weather, duration?=6000)	string/table, string/int?, int?=6000	nil	Set CLEAR, PRECIPITATION, RAIN, or THUNDER.
run_console_command(command)	string	nil	Dispatch a command as the console.
spawn_boss_at_location(file, location?, level?)	string, table?, int?	table/nil	Spawn a custom boss at the supplied or current location and supplied or current level.
spawn_custom_boss_at_location(file, location, options?)	string, table, table?	table/nil	Spawn a custom boss; options support silent, level, add_as_reinforcement, and velocity.
spawn_entity_at_location(type, location, options?)	string (EntityType), table, table?	table/nil	Spawn a vanilla entity; options support velocity, duration, EntityEffect effect, on_land, and max_ticks.
spawn_falling_block_at_location(location, material, options?)	table, string (Material), table?	table/nil	Spawn a falling block; options support drop_item, hurt_entities, velocity, and on_land.
spawn_reinforcement_at_location(file, location, duration?=0, velocity?)	string, table, int?=0, table?	table/nil	Summon a reinforcement tied to the boss; positive duration removes it after that many ticks.
spawn_fireworks_at_location(location, options)	table, table	table/nil	Spawn a firework; options support effects, type, flicker, trail, colors, fade_colors, power, velocity, and shot_at_angle, with FireworkEffect.Type names for type.
spawn_splash_potion_at_location(location, options)	table, table	table/nil	Spawn a splash potion; effects entries accept PotionEffectType type, duration, amplifier, and overwrite, plus top-level velocity.
generate_fake_explosion(locations, source?)	table, table?	nil	Remove real blocks and create damaging falling debris when explosion regeneration is enabled. Restoration starts after 1200 ticks; Lua closure does not undo it. Keep positions in the boss world.
spawn_fake_gold_nugget_at_location(location, velocity, gravity?=false)	table, table, bool?=false	table/nil	Spawn a fake gold-nugget projectile.
run_fake_gold_nugget_damage(projectiles)	table	nil	Run the fake-projectile damage pass.
generate_player_loot(times?=1)	int?=1	nil	Generate player loot for eligible damagers.
drop_bonus_coins(multiplier?=2)	number?=2	nil	Drop bonus coins for eligible damagers.

EliteMobs Fake Projectile Table

spawn_fake_gold_nugget_at_location returns this table when spawning succeeds.

Methods

Method	Args	Returns	Description
get_location()	—	table	Return the fake projectile location.
set_gravity(enabled)	bool	nil	Set fake-projectile gravity.
remove()	—	nil	Remove the fake projectile.
is_removed()	—	bool	Test whether it was removed.

context.settings

EliteMobs boss powers receive this settings table from the same world-table builder.

Methods

Method	Args	Returns	Description
warning_visual_effects_enabled()	—	bool	Return the current warning-visual-effects setting.