Lua API Reference

Complete method reference for the Lua scripting API. All methods are called via context.table:method() syntax.

Global methods (marked GLOBAL) come from Magmacore, the shared core library. They apply to FreeMinecraftModels scripts and other MagmaCore ScriptInstance consumers. EliteMobs boss powers reuse the same Lua sandbox but expose boss-specific context tables and method names; EliteMobs NPC scripts run on the same MagmaCore runtime and receive the full shared context plus the NPC-only context.npc table. See the EliteMobs sections below and NPC Scripts for those variants.

EliteMobs methods (marked ELITEMOBS) are specific to EliteMobs boss power scripts and NPC scripts.

FMM methods (marked FMM) are specific to FreeMinecraftModels item and prop scripts.

Where a method requires a Bukkit enum (Sound, Particle, Material, etc.), see the Spigot Javadocs for valid values. Enum names are passed as uppercase strings (e.g., "DIAMOND_SWORD", "ENTITY_ARROW_SHOOT").

---

Entity Table GLOBAL

Base fields present on all entity tables — players, mobs, props, anything.

Properties

Field	Type	Description
uuid	string	Entity UUID
entity_type	string	Entity type (lowercase)
is_valid	bool	Entity still exists in the world
is_dead	bool	Entity is dead
is_player	bool	Is a player
is_hostile	bool	Is a Monster
is_passive	bool	Is an Animal
current_location	location	Entity position (x, y, z, yaw, pitch, world)
world	string	World name

Plugin-specific enrichers may add extra top-level fields when the relevant plugin is installed. See the bridge sections below for EliteMobs and FreeMinecraftModels fields.

Methods

Method	Args	Returns	Description
teleport(location)	location table	nil	Teleport entity
remove()	—	nil	Remove entity from world
set_silent(enabled)	bool	nil	Set silent
set_invulnerable(enabled)	bool	nil	Set invulnerable
set_gravity(enabled)	bool	nil	Set gravity
set_glowing(enabled)	bool	nil	Set glowing

Bridge: entity.elite

Added by EliteMobs' entity enricher when EliteMobs is installed. The enricher adds these top-level flags:

Field	Type	Description
is_elite	bool	Is an EliteMobs entity
is_custom_boss	bool	Is an EliteMobs custom boss
is_significant_boss	bool	Custom boss with health multiplier over 1 (designed encounter)

entity.elite is only present when is_elite is true.

Field	Type	Description
level	int	Elite mob level
name	string	Elite display name
health	double	Current health
max_health	double	Max health
is_custom_boss	bool	Is a custom boss (also available at top level)
health_multiplier	double	Config-defined health multiplier
damage_multiplier	double	Config-defined damage multiplier
remove()	method	Remove the elite entity

Bridge: entity.model

Added by FreeMinecraftModels' entity enricher when FMM is installed. The enricher adds these top-level flags:

Field	Type	Description
is_modeled	bool	Has an FMM model
is_prop	bool	Is an FMM prop

entity.model is only present when is_modeled is true.

Field	Type	Description
model_id	string	Model blueprint name
is_dynamic	bool	Whether this is an FMM DynamicEntity (true) or a static prop (false)
play_animation(name, blend?, loop?)	method	Play animation. blend defaults to false, loop defaults to false
stop_animations()	method	Stop all animations
remove()	method	Remove the modeled entity

Bridge: player permissions

Added by FreeMinecraftModels' entity enricher when FMM is installed. These fields appear only on player entity tables:

Field / Method	Args	Returns	Description
has_permission(node)	string	bool	Whether the player has the given permission node
is_op	—	bool	Whether the player is a server operator

---

Living Entity Table GLOBAL

Extends Entity Table. Applied to all living entities (mobs and players).

Properties

Field	Type	Description
health	double	Current health
maximum_health	double	Max health
name	string	Entity display name
is_alive	bool	Entity is not dead

Methods

Method	Args	Returns	Description
damage(amount)	double	nil	Deal damage to entity
push(x, y, z)	double, double, double	nil	Add velocity vector
set_facing(x, y, z)	double, double, double	nil	Set look direction
add_potion_effect(type, duration, amplifier)	string (PotionEffectType), int, int	nil	Apply potion effect by name
remove_potion_effect(type)	string (PotionEffectType)	nil	Remove potion effect by name
get_scale()	—	number	Current entity scale (defaults to 1.0 on servers without generic.scale attribute)
set_scale(value)	double	nil	Set entity scale via generic.scale attribute (no-op on servers before 1.20.5)

---

context.player GLOBAL

Player entity table. Inherits all Entity and Living Entity fields.

Properties

Field	Type	Description
game_mode	string	survival, creative, adventure, spectator

Methods

Method	Args	Returns	Description
send_message(text)	string	nil	Send chat message. Supports color codes
get_held_item()	—	table or nil	Returns type, amount, display_name fields, or nil if empty hand. type is an uppercase Bukkit Material name
consume_held_item(amount?)	int (default 1)	nil	Reduce held item stack by amount
has_item(material, amount?)	string (Material), int (default 1)	bool	Check inventory for material
get_target_entity(range?)	num (default 50)	entity or nil	Raycast for entity player is looking at
get_eye_location()	—	location	Player eye position
get_look_direction()	—	vector	Unit direction vector
send_block_change(x, y, z, material, ticks?)	int, int, int, string (Material), int (optional)	bool	Send fake block. Auto-resets after ticks if given
reset_block(x, y, z)	int, int, int	bool	Reset fake block to real
sleep(x, y, z)	num, num, num	nil	Bed sleep animation at location
wake_up()	—	nil	Wake from sleep
show_boss_bar(text, color?, progress, ticks?)	string, string (BarColor, default WHITE), num, int (optional)	nil	Display boss bar. Auto-hides after ticks. Supports color codes
hide_boss_bar()	—	nil	Remove boss bar
show_action_bar(text, ticks?)	string, int (optional)	nil	Show action bar. Repeats if ticks greater than 0. Supports color codes
show_title(title, subtitle?, fadeIn, stay, fadeOut)	string, string (default empty), int, int, int	nil	Show title screen. Supports color codes

---

context.world GLOBAL

World operations for FreeMinecraftModels scripts and other Magmacore-backed ScriptInstance runtimes. EliteMobs boss powers start from this same base table and layer the EliteMobs context.world additions and overrides listed below.

context.world methods come in two interchangeable forms: coordinate-style (x, y, z) and location-table-style (the *_at_location variants). Both forms are available on the generic surfaces, and EliteMobs boss powers keep the shared base methods while adding boss-specific location-table helpers.

Properties

Field	Type	Description
name	string	World name

Methods

Method	Args	Returns	Description
get_block_at(x, y, z)	int, int, int	string	Material name (lowercase). Returns "air" if the chunk is unloaded
set_block_at(x, y, z, material)	int, int, int, string (Material)	bool	Queue block placement if material is valid; unloaded chunks are skipped
get_highest_block_y(x, z)	int, int	int	Y of highest non-air block
spawn_particle(particle, x, y, z, count?, dx?, dy?, dz?, speed?)	string (Particle), num, num, num, int?=1, num?=0, num?=0, num?=0, num?=0	nil	Spawn particle effect
play_sound(sound, x, y, z, volume?, pitch?)	string (Sound), num, num, num, float?=1, float?=1	nil	Play sound
strike_lightning(x, y, z)	num, num, num	nil	Strike lightning
get_time()	—	int	World time in ticks
set_time(ticks)	long	nil	Set world time
get_nearby_entities(x, y, z, radius)	num, num, num, num	table	Array of entity tables
get_nearby_players(x, y, z, radius)	num, num, num, num	table	Array of player entity tables
spawn_entity(type, x, y, z)	string (EntityType), num, num, num	entity or nil	Spawn vanilla entity; returns nil if the entity type is invalid
raycast(fx, fy, fz, dx, dy, dz, max?)	num, num, num, num, num, num, num?=50	table	Returns hit_entity, hit_location, hit_block fields
place_temporary_block(x, y, z, material, ticks?, require_air?)	int, int, int, string (Material), int?=0, bool?=false	bool	Queue block replacement that auto-reverts after ticks. Returns false if material is invalid or the chunk is unloaded
drop_item(x, y, z, material, amount?)	num, num, num, string (Material), int?=1	entity or nil	Drop item entity naturally at location; returns nil if material is invalid
spawn_firework(x, y, z, colors, type?, power?)	num, num, num, table, string (FireworkEffect.Type)?=BALL, int?=1	nil	Spawn firework
strike_lightning_at_location(loc)	location	nil	Strike lightning
play_sound_at_location(loc, sound, volume?, pitch?)	location, string (Sound), float?=1, float?=1	nil	Play sound
spawn_particle_at_location(loc, particle, count?, dx?, dy?, dz?, speed?)	location, string (Particle), int?=1, num?=0, num?=0, num?=0, num?=0	nil	Spawn particle effect
get_block_at_location(loc)	location	string	Material name (lowercase). Returns "air" if the chunk is unloaded
set_block_at_location(loc, material)	location, string (Material)	bool	Queue block placement if material is valid; unloaded chunks are skipped
place_temporary_block_at_location(loc, material, ticks?, require_air?)	location, string (Material), int?=0, bool?=false	bool	Queue block replacement that auto-reverts after ticks. Returns false if material is invalid or the chunk is unloaded
get_highest_block_y_at_location(loc)	location	int or nil	Y of highest non-air block

---

em helpers GLOBAL

Global helper constructors exposed on the em table in all MagmaCore Lua runtimes.

Constructors

Method	Args	Returns	Description
em.create_location(x, y, z, world?, yaw?, pitch?)	num, num, num, string?, num?, num?	location	Location table with x, y, z, optional world, yaw, pitch, and an in-place add(dx, dy, dz) method
em.create_vector(x, y, z)	num, num, num	vector	Vector table with x, y, z

Zone Builders

Zone builders return plain zone definition tables. Spheres, domes, cylinders, and cuboids include :set_center(location). Cones and ray zones include :set_origin(location) and :set_destination(location).

Method	Args	Returns	Description
em.zone.create_sphere_zone(radius)	num	zone	{ kind = "sphere", radius = ... }
em.zone.create_dome_zone(radius)	num	zone	{ kind = "dome", radius = ... }
em.zone.create_cylinder_zone(radius, height)	num, num	zone	{ kind = "cylinder", radius = ..., height = ... }
em.zone.create_cuboid_zone(x, y, z)	num, num, num	zone	Cuboid half-extents
em.zone.create_cone_zone(length, radius)	num, num	zone	Cone definition with origin/destination setters
em.zone.create_static_ray_zone(length, thickness)	num, num	zone	Static ray definition
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	num, num, num	zone	Rotating ray definition
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	num, num, num	zone	Translating ray definition

---

context.boss ELITEMOBS

Boss entity table for EliteMobs Lua power scripts. Inherits all EliteMobs Living Entity methods. Properties refresh via dedicated getters.

Properties

Field	Type	Description
name	string	Boss display name
uuid	string	Elite entity UUID
health	double	Current health (snapshot)
maximum_health	double	Max health (snapshot)
current_location	location	Boss position (snapshot)
level	int	Boss level
damager_count	int	Number of players who damaged this boss
is_in_combat	bool	Boss is in combat
exists	bool	Boss entity exists

Methods

Method	Args	Returns	Description
is_alive()	—	bool	Whether boss entity is alive (live check)
get_health()	—	double	Current health (live)
get_maximum_health()	—	double	Max health (live)
get_location()	—	location	Current position (live)
restore_health(amount)	double	nil	Heal the boss
despawn()	—	nil	Remove boss entity
get_damager_count()	—	int	Live damager count
add_tag(tag, ticks?)	string, int?=0	nil	Add tag, auto-remove after ticks if set
remove_tag(tag)	string	nil	Remove tag
has_tag(tag)	string	bool	Check tag
reset_custom_name()	—	nil	Reset name to config default
play_sound_at_self(sound, volume?, pitch?)	string (Minecraft sound key, e.g. "entity.wither.spawn"), float?=1, float?=1	nil	Play sound at boss
play_sound_at_entity(sound, volume?, pitch?)	string (Minecraft sound key, e.g. "entity.wither.spawn"), float?=1, float?=1	nil	Play sound at boss (alias)
spawn_particle_at_self(particle, count?)	string (Particle) or table, int?=1	nil	Spawn particle at boss
play_model_animation(name)	string	nil	Play FMM model animation (requires FMM model)
has_mount()	-	bool	Whether this boss is riding a mount entity
get_mount()	-	entity or nil	Current mount entity reference, marked with is_mount = true
set_mount(entity)	entity table	bool	Makes the boss ride the given entity
clear_mount()	-	bool	Makes the boss leave its current vehicle
dismount()	-	bool	Alias for clear_mount()
navigate_to_location(location, speed?, force?, timeout?)	location, double?=1, bool?=false, int?=0	nil	Pathfind to location
send_message(text, range?)	string, double?=20	nil	Send message to nearby players. Supports color codes
get_nearby_players(range)	double	table	Array of player tables within range
get_target_player()	—	player or nil	Current mob target if it's a player
get_nearby_players_in_zone(zone)	zone table	table	Players inside the zone shape
get_ender_dragon_phase()	—	string or nil	EnderDragon.Phase name
set_ender_dragon_phase(phase)	string (EnderDragon.Phase)	nil	Set ender dragon phase
summon_reinforcement(file, zone?, level?)	string, zone or nil, int?=0	entity or nil	Spawn reinforcement boss
summon_projectile(type, origin, dest, speed?, options?)	string (EntityType), location, location, double?=1, table	entity or nil	Spawn tracked projectile; returns nil if the type or locations are invalid

summon_projectile options

Option	Type	Default	Description
custom_damage	number	—	Override projectile damage
detonation_power	string	—	Explosive power level
yield	number	—	Fireball yield
incendiary	bool	true	Fireball sets fire
gravity	bool	—	Enable gravity
glowing	bool	false	Set glowing
invulnerable	bool	false	Set invulnerable
persistent	bool	true	Set persistent
duration	int	0	Auto-remove after ticks
effect	string	—	EntityEffect to play on spawn
spawn_at_origin	bool	false	Spawn at origin instead of launching from boss
direction_only	bool	false	Set direction without velocity (fireballs)
track	bool	true	Register as elite projectile
on_land	function	—	Callback when projectile lands: function(location, entity)
max_ticks	int	6000	Max ticks before forced landing callback

Zone/Particle Methods

Method	Args	Returns	Description
spawn_particles_in_zone(zone, particle, ...)	zone, particle spec, coverage?=1.0	nil	Fill zone with particles
spawn_particles_in_zone_border(zone, particle, ...)	zone, particle spec, coverage?=1.0	nil	Outline zone with particles
get_particles_from_self_toward_zone(zone, particle, speed?)	zone, string, double?=0.1	table	Directional particles from boss to zone
get_particles_toward_self(zone, particle, speed?)	zone, string, double?=0.1	table	Directional particles from zone to boss
spawn_particles_with_vector(particles)	table	nil	Spawn directional particle array

Special Power Support

Method	Args	Returns	Description
start_tracking_fireball_system(speed?)	double?=0.5	nil	Start tracking fireball AI
handle_spirit_walk_damage(cause)	string (DamageCause)	nil	Handle spirit walk damage by cause
shield_wall_is_active()	—	bool	Whether shield wall is active
initialize_shield_wall(charges?)	int?=1	nil	Activate shield wall
shield_wall_absorb_damage(player, damage)	entity table, double	bool	Attempt to absorb damage
deactivate_shield_wall()	—	nil	Deactivate shield wall
start_zombie_necronomicon(target, file)	entity table, string	nil	Start necronomicon on target

---

context.npc ELITEMOBS NPC

NPC table for EliteMobs NPC Lua scripts. NPC scripts live in plugins/EliteMobs/npc_scripts/ and attach through an NPC config scripts: list. NPC scripts run on the same MagmaCore runtime as every other surface and receive the full shared context — context.world, context.zones, context.scheduler, context.cooldowns, context.log, context.event, context.player, context.state — plus the NPC-only context.npc table documented here.

Properties

Field	Type	Description
name	string	NPC display name
filename	string	NPC config filename
uuid	string	Runtime NPC UUID
activation_radius	double	Configured activation radius
current_location	location	Snapshot location when the NPC entity exists
entity_type	string	Bukkit entity type when the NPC entity exists

Methods

Method	Args	Returns	Description
is_valid()	-	bool	Whether the NPC backing entity is still valid
get_location()	-	location	Current NPC location, or spawn fallback
get_eye_location()	-	location	Current eye location, or spawn fallback
get_activation_radius()	-	double	Current configured activation radius
get_nearby_players(radius)	double	table	Player tables near the NPC
face_direction_or_location(target)	vector or location	nil	Face a direction or look toward a location
say_greeting(player?)	player, UUID, name, or nil	nil	Send a configured greeting. Defaults to the triggering player when available
say_dialog(player?)	player, UUID, name, or nil	nil	Send configured dialog. Defaults to the triggering player when available
say_farewell(player?)	player, UUID, name, or nil	nil	Send configured farewell text. Defaults to the triggering player when available
play_model_animation(name)	string	nil	Play a custom model animation if available; safe no-op otherwise

NPC-specific hooks include on_spawn, on_remove, on_game_tick, on_npc_interact, on_npc_proximity_enter, and on_npc_proximity_leave. See EliteMobs NPC Scripts for the complete workflow and cooldown details.

---

EliteMobs Living Entity Table ELITEMOBS

Entity tables created inside EliteMobs power scripts (from context.boss, event data, zone callbacks, and world queries) use an extended living entity table with additional methods beyond the global Living Entity. context.boss inherits all of these.

Properties

Field	Type	Description
name	string	Entity display name
uuid	string	Entity UUID
entity_type	string	Entity type name
is_player	bool	Is a player
is_monster	bool	Is a Monster
is_elite	bool	Is an EliteMobs entity
is_valid	bool	Entity still exists
is_mount	bool	True when this entity table represents a boss mount
health	double	Current health (snapshot)
maximum_health	double	Max health (snapshot)
current_location	location	Entity position (snapshot)
game_mode	string	Game mode (UPPERCASE in EliteMobs: SURVIVAL, CREATIVE, ADVENTURE, SPECTATOR)

Methods

Method	Args	Returns	Description
is_alive()	—	bool	Whether entity is alive (live check)
is_ai_enabled()	—	bool	Whether AI is enabled
is_frozen()	—	bool	Whether boss is frozen (CustomBossEntity only)
is_on_ground()	—	bool	Whether entity is on the ground
is_healing()	—	bool	Whether elite is healing
get_location()	—	location	Current position (live)
get_eye_location()	—	location	Eye position (live)
get_height()	—	double	Entity height
get_health()	—	double	Current health (live)
get_maximum_health()	—	double	Max health (live)
get_velocity()	—	vector	Current velocity vector
deal_damage(amount)	double	nil	Deal generic damage
deal_custom_damage(amount)	double	nil	Deal custom boss attack damage from the power's boss
deal_damage_from_boss(amount)	double	nil	Deal damage attributed to the power's boss entity
restore_health(amount)	double	nil	Heal entity (uses EliteMobs heal if elite)
play_sound_at_entity(sound, volume?, pitch?)	string (Minecraft sound key, e.g. "entity.ender_dragon.growl"), float?=1, float?=1	nil	Play sound at entity
play_sound_at_self(sound, volume?, pitch?)	string (Minecraft sound key, e.g. "entity.ender_dragon.growl"), float?=1, float?=1	nil	Play sound at entity (alias)
spawn_particle_at_self(particle, count?)	string (Particle) or table, int?=1	nil	Spawn particle at entity
spawn_particles_at_location(loc, particle, count?)	location, particle spec, int?=1	nil	Spawn particles at location
teleport_to_location(location)	location	nil	Teleport entity
set_velocity_vector(vector)	vector	nil	Set velocity
set_gravity(enabled)	bool	nil	Set gravity
apply_push_vector(vector, additive?, delay?)	vector, bool?=false, int?=1	nil	Apply velocity after delay. additive adds to existing velocity
push_relative_to(location, force?, extraX?, extraY?, extraZ?)	location, double?=1, double?=0, double?=0, double?=0	nil	Push entity away from location
set_custom_name(name)	string	nil	Set custom display name. Supports color codes
reset_custom_name()	—	nil	Reset name to EliteMobs default
set_custom_name_visible(visible)	bool	nil	Toggle name visibility
set_ai_enabled(enabled, duration?)	bool, int?=0	nil	Set AI state. Auto-reverts after duration ticks
set_awareness_enabled(enabled, duration?)	bool, int?=0	nil	Set mob awareness. Auto-reverts after duration ticks
face_direction_or_location(target)	vector or location	nil	Face a direction or look toward a location
play_model_animation(name)	string	nil	Play FMM model animation (requires FMM model)
is_inside_vehicle()	-	bool	Whether the entity is riding another entity
has_vehicle()	-	bool	Whether the entity has a vehicle
get_vehicle()	-	entity or nil	Current vehicle entity reference
set_vehicle(entity)	entity table	bool	Makes this entity ride the given vehicle
leave_vehicle()	-	bool	Makes this entity leave its current vehicle
has_passengers()	-	bool	Whether this entity has passengers
get_passenger_count()	-	int	Number of passengers
get_passengers()	-	table	Array of passenger entity references
add_passenger(entity)	entity table	bool	Adds a passenger to this entity
remove_passenger(entity)	entity table	bool	Removes a passenger from this entity
eject_passengers()	-	bool	Ejects all passengers
set_scale(scale, duration?)	double, int?=0	nil	Set entity scale. Auto-reverts to 1.0 after duration ticks
set_invulnerable(enabled, duration?)	bool, int?=0	nil	Set invulnerable. Auto-reverts after duration ticks
set_healing(enabled)	bool	nil	Set elite healing state
navigate_to_location(location, speed?, force?, timeout?)	location, double?=1, bool?=false, int?=0	nil	Pathfind to location (CustomBossEntity only)
add_tag(tag, ticks?)	string, int?=0	nil	Add tag, auto-remove after ticks
remove_tag(tag)	string	nil	Remove tag
has_tag(tag)	string	bool	Check tag
overlaps_box_at_location(center, halfX?, halfY?, halfZ?)	location, double?=0.5, double?=halfX, double?=halfX	bool	Whether entity bounding box overlaps a box at location
remove_elite()	—	nil	Remove via EliteMobs removal pipeline
apply_potion_effect(type, duration, amplifier?)	string (PotionEffectType), int, int?=0	nil	Apply potion effect
set_equipment(slot, material, options?)	string (EquipmentSlot), string (Material), table	nil	Set equipment slot item
set_fire_ticks(ticks)	int	nil	Set fire ticks
add_visual_freeze_ticks(ticks?)	int?=1	nil	Add freeze visual ticks
place_temporary_block(material, ticks?, requireAir?)	string (Material), int?=0, bool?=false	nil	Place temporary block at entity location

set_equipment options

Option	Type	Default	Description
unbreakable	bool	false	Make item unbreakable
enchantments	table	—	Array of {type = "ENCHANT_NAME", level = 1} tables

EliteMobs Player Methods

Players in EliteMobs scripts have all EliteMobs living entity methods plus:

Method	Args	Returns	Description
send_message(text)	string	nil	Send chat message. Supports color codes
show_action_bar(text)	string	nil	Show action bar text. Supports color codes
show_title(title, subtitle?, fadeIn?, stay?, fadeOut?)	string, string?="", int?=10, int?=40, int?=10	nil	Show title screen. Supports color codes
show_boss_bar(title, color?, style?, duration?)	string, string (BarColor)?=WHITE, string (BarStyle)?=SOLID, int?=40	nil	Show boss bar. Auto-hides after duration ticks. Supports color codes
run_command(command)	string	nil	Run command as player

EliteMobs Entity Reference Table

Non-living entities (projectiles, falling blocks, fireworks) returned from EliteMobs spawn methods get a lightweight reference table:

Field / Method	Args	Returns	Description
name	—	string	Entity name
uuid	—	string	Entity UUID
entity_type	—	string	Entity type name
is_player	—	bool	Always false
is_elite	—	bool	Always false
is_valid()	—	bool	Whether entity is still valid (live check)
current_location	—	location	Position (snapshot)
get_location()	—	location	Current position (live)
get_velocity()	—	vector	Current velocity vector
is_on_ground()	—	bool	Whether entity is on the ground
teleport_to_location(location)	location	nil	Teleport entity
set_velocity_vector(vector)	vector	nil	Set velocity
set_direction_vector(vector)	vector	nil	Set direction (fireballs only)
set_yield(amount)	double	nil	Set fireball yield
set_gravity(enabled)	bool	nil	Set gravity
detonate()	—	nil	Detonate firework
remove()	—	nil	Remove entity
unregister(reason?)	string?=OTHER	nil	Unregister from EliteMobs entity tracker

---

context.players ELITEMOBS

Player query table available in EliteMobs power scripts. Provides helper methods to find players relative to the boss.

Method	Args	Returns	Description
current_target()	—	player or nil	Event actor if player, or boss's current mob target if player
nearby_players(radius)	double	table	Array of player tables within radius of boss
all_players_in_world()	—	table	Array of all player tables in the boss's world

---

context.entities ELITEMOBS

Entity query table available in EliteMobs power scripts. Provides helper methods to find entities relative to the boss. All queries exclude the boss itself.

Method	Args	Returns	Description
get_nearby_entities(radius, filter?)	double, string?="living"	table	Entities within radius. "all"/"entities" returns every entity (including non-living); any other value returns living entities filtered by category: "player(s)", "elite(s)", "mob(s)", or default = all living
get_entities_in_box(center, halfX, halfY, halfZ, filter?)	location, double, double, double, string?="living"	table	Living entities inside an axis-aligned box (same filter values as above; non-all modes only)
get_all_entities(filter?)	string?="living"	table	All living entities in the boss's world (same filter values)
get_direct_target_entity()	—	entity or nil	Direct target entity from the triggering event
get_boss_spawn_location()	—	location	The boss's original spawn location

---

context.vectors ELITEMOBS

Vector math utilities available in EliteMobs power scripts.

Method	Args	Returns	Description
get_vector_between_locations(from, to, options?)	location, location, table	vector	Vector from source to destination. Options can modify the result
rotate_vector(vector, pitch?, yaw?)	vector, double?=0, double?=0	vector	Rotate vector by pitch and yaw (degrees)
normalize_vector(vector)	vector	vector	Normalize to unit length

---

context.state GLOBAL

A plain Lua table that persists for the script instance's entire lifetime. Use it to store flags, counters, task IDs, toggle states, and any data you need to share between hooks. context.state is the script-owned persistent table; most other context tables are rebuilt or lazily recreated as needed. FMM caches context.prop per prop for performance, but its live fields such as current_location still refresh on read.

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

---

context.cooldowns GLOBAL

Cooldown management. Local cooldowns are per-script-instance; global cooldowns are shared across all scripts on the same entity/owner. If no key is provided, defaults to the script's filename.

Method	Args	Returns	Description
local_ready(key?)	string (optional)	bool	Whether the local cooldown has expired
local_remaining(key?)	string (optional)	int	Remaining ticks on local cooldown (0 if ready)
check_local(key?, duration)	string (optional), int	bool	If ready, starts cooldown and returns true; otherwise false
set_local(duration, key?)	long, string (optional)	nil	Set local cooldown for duration ticks
global_ready()	—	bool	Whether the global cooldown has expired
set_global(duration)	long	nil	Set global cooldown for duration ticks

In EliteMobs power scripts, local cooldowns are shared across all powers on the same boss entity, and global cooldowns use the boss's built-in power cooldown system.

EliteMobs NPC scripts use the shared cooldown order check_local(key?, duration); see NPC Scripts.

---

context.scheduler GLOBAL

Task scheduling. All tasks are automatically cancelled when the script shuts down.

Global (Magmacore) variant

FreeMinecraftModels scripts and EliteMobs NPC scripts use this shared variant. The EliteMobs-style names below are aliases on the same scheduler, so either naming style is valid on the generic surfaces.

Method	Args	Returns	Description
run_later(ticks, callback)	int, function	int	Run callback after ticks. Returns task ID
run_repeating(delay, interval, callback)	int, int, function	int	Run callback every interval ticks after initial delay. Returns task ID
cancel(taskId)	int	nil	Cancel a scheduled task

EliteMobs variant

Method	Args	Returns	Description
run_after(ticks, callback)	int, function	int	Run callback after ticks. Returns task ID
run_every(ticks, callback)	int, function	int	Run callback every N ticks. Returns task ID
cancel_task(taskId)	int	nil	Cancel a scheduled task

---

context.log GLOBAL

Logging utilities for debugging scripts.

Global (Magmacore / FMM) variant

Method	Args	Returns	Description
info(message)	string	nil	Log info message
warn(message)	string	nil	Log warning message
error(message)	string	nil	Log error/warning message

EliteMobs variant

Method	Args	Returns	Description
info(message)	string	nil	Log info message
warn(message)	string	nil	Log warning message
debug(message)	string	nil	Log debug message (appears as info with debug prefix)

---

context.zones GLOBAL

Zone creation and monitoring for FreeMinecraftModels scripts and other Magmacore-backed ScriptInstance runtimes. EliteMobs boss powers use the EliteMobs context.zones variant below.

Global (Magmacore) variant

Method	Args	Returns	Description
create_sphere(x, y, z, radius)	num, num, num, num	int	Create sphere zone, returns handle
create_cylinder(x, y, z, radius, height)	num, num, num, num, num	int	Create cylinder zone, returns handle
create_cuboid(x, y, z, xSize, ySize, zSize)	num, num, num, num, num, num	int	Create cuboid zone, returns handle
watch(handle, on_enter?, on_leave?)	int, function?, function?	bool	Enable zone tracking. Function arguments enable on_zone_enter / on_zone_leave; function bodies are not invoked directly. Zone hooks receive context.player / context.event.player for the player that crossed the boundary
unwatch(handle)	int	nil	Stop tracking zone

EliteMobs variant

Method	Args	Returns	Description
get_entities_in_zone(zone, options?)	zone table, table	table	Get entities inside zone. Options: filter, mode
get_locations_in_zone(zone, options?)	zone table, table	table	Get locations inside zone. Options: coverage, mode
zone_contains(zone, location, mode?)	zone table, location, string?="full"	bool	Whether location is inside zone ("full" or "border")
watch_zone(zone, callbacks, options?)	zone table, table, table?	nil	Watch zone for enter/leave. Callbacks: {on_enter = fn, on_leave = fn}. Options support filter and mode

---

context.event GLOBAL

Event data table for the hook that triggered the current script execution. Present during event-driven hooks and generic MagmaCore zone enter/leave hooks that provide a player actor; not present during on_game_tick, scheduled callbacks, or lifecycle hooks without a player.

Global (Magmacore) variant

Field / Method	Type	Description
is_cancelled	bool	Cancellation state when context was built; not refreshed after cancel() / uncancel()
cancel()	method	Cancel the event when the underlying Bukkit event is cancellable
uncancel()	method	Un-cancel the event when the underlying Bukkit event is cancellable
player	entity table	Player involved in the event (if any)

Generic zone hooks populate player but are not backed by a cancellable Bukkit event, so cancel() and uncancel() are not present there.

For the EliteMobs event table (which provides damage amounts, damage causes, etc.), see EliteMobs Event Table.

---

context.script ELITEMOBS

Bridge to the EliteMobs Elite Script system. Lets Lua powers use the YAML-based targeting, zone, and relative vector systems via Lua tables with the same field names as Elite Script YAML configs.

Methods

Method	Args	Returns	Description
target(spec)	table	target handle	Create a target handle from an Elite Script target spec table
zone(spec)	table	zone handle	Create a zone handle from an Elite Script zone spec table
relative_vector(spec, location?, zone?)	table, location, zone handle	vector handle	Create a relative vector from an Elite Script vector spec
damage(target, amount?, multiplier?)	target handle, double?=0, double?=1	nil	Deal damage to all entities in target
push(target, vector, additive?)	target handle, vector or vector handle, bool?=false	nil	Push target entities with velocity
set_facing(target, vector)	target handle, vector or vector handle	nil	Set target entities facing direction
spawn_particles(target, particles)	target handle, table or string	nil	Spawn particles at target locations

Target Handle

Returned by context.script:target(spec). The spec table uses the same keys as Elite Script YAML target configs (e.g., {targetType = "NEARBY_PLAYERS", range = 20}).

Method	Args	Returns	Description
entities()	—	table	Array of entity tables at target
locations()	—	table	Array of location tables at target
first_entity()	—	entity or nil	First entity at target
first_location()	—	location or nil	First location at target

Zone Handle

Returned by context.script:zone(spec). The spec table uses the same keys as Elite Script YAML zone configs (e.g., {shape = "SPHERE", radius = 5, target = {targetType = "SELF"}}).

Method	Args	Returns	Description
full_target(coverage?)	number	target handle	Target handle for zone interior locations
border_target(coverage?)	number	target handle	Target handle for zone border locations
full_locations(coverage?)	number	table	Array of interior locations
border_locations(coverage?)	number	table	Array of border locations
full_entities()	—	table	Entities inside zone
border_entities()	—	table	Entities on zone border
contains(location, mode?)	location, string?="full"	bool	Whether location is in zone
watch(callbacks, mode?)	table, string?="full"	int	Watch for enter/leave. Returns task ID

Vector Handle

Returned by context.script:relative_vector(spec). The spec table uses the same keys as Elite Script YAML relative vector configs.

Method	Args	Returns	Description
resolve()	—	vector	Compute the vector for the current context

---

context.world (EliteMobs) ELITEMOBS

Boss-specific world table for EliteMobs power scripts. Boss powers start with the generic MagmaCore world table, so coordinate helpers such as get_block_at(...), set_block_at(...), and spawn_particle(...) remain available. The methods below are EliteMobs additions or boss-specific overrides, mainly location-table forms and boss helpers.

Block Queries

Method	Args	Returns	Description
get_block_type_at_location(loc)	location	string or nil	Material name
get_highest_block_y_at_location(loc)	location	int or nil	Highest block Y
get_blast_resistance_at_location(loc)	location	double	Blast resistance value
is_air_at_location(loc)	location	bool	Block is air
is_passable_at_location(loc)	location	bool	Block is passable
is_passthrough_at_location(loc)	location	bool	Block is not solid
is_on_floor_at_location(loc)	location	bool	Air with solid block below
is_standing_on_material(loc, material)	location, string (Material)	bool	Block below matches material

Block Manipulation

Method	Args	Returns	Description
set_block_at_location(loc, material, requireAir?)	location, string (Material), bool?=false	nil	Place block. If requireAir is true, only replaces air
place_temporary_block_at_location(loc, material, ticks?, requireAir?)	location, string, int?=0, bool?=false	nil	Place block, auto-remove after ticks. If requireAir is true, only replaces air

Spawning

Method	Args	Returns	Description
spawn_boss_at_location(file, loc?, level?)	string, location?=boss loc, int?=boss level	entity or nil	Spawn custom boss
spawn_custom_boss_at_location(file, loc, options?)	string, location, table	entity or nil	Spawn boss with options (level, silent, add_as_reinforcement, velocity)
spawn_entity_at_location(type, loc, options?)	string (EntityType), location, table	entity or nil	Spawn vanilla entity with options (velocity, duration, effect, on_land, max_ticks)
spawn_falling_block_at_location(loc, material, options?)	location, string (Material), table	entity or nil	Spawn falling block (drop_item, hurt_entities, velocity, on_land)
spawn_reinforcement_at_location(file, loc, level?, velocity?)	string, location, int?=0, vector	entity or nil	Spawn reinforcement tied to boss
spawn_fireworks_at_location(loc, config)	location, table	entity or nil	Spawn firework
spawn_splash_potion_at_location(loc, config)	location, table	entity or nil	Spawn splash potion

Effects and Utility

Method	Args	Returns	Description
play_sound_at_location(loc, sound, volume?, pitch?)	location, string (Minecraft sound key, e.g. "entity.blaze.shoot"), float?=1, float?=1	nil	Play sound
spawn_particle_at_location(loc, particle, count?)	location, string (Particle) or table, int?=1	nil	Spawn particles
strike_lightning_at_location(loc)	location	nil	Strike lightning (bypasses EM protection)
run_empowered_lightning_task_at_location(loc)	location	nil	Empowered lightning effect
generate_fake_explosion(locations, center?)	table of locations, location	nil	Visual explosion without damage
spawn_fake_gold_nugget_at_location(loc, velocity, gravity?)	location, vector, bool?=false	fake projectile or nil	Spawn visual gold nugget projectile
run_fake_gold_nugget_damage(projectiles)	table	nil	Run damage check on fake projectiles
set_world_time(time) or (loc, time)	long, or location + long	nil	Set world time
set_world_weather(weather, duration?) or (loc, weather, duration?)	string (CLEAR, RAIN, PRECIPITATION, THUNDER), int?=6000	nil	Set weather
run_console_command(command)	string	nil	Execute console command
generate_player_loot(times?)	int?=1	nil	Run this many player-loot rolls for damagers
drop_bonus_coins(multiplier?)	double?=2	nil	Drop bonus coins at boss

context.settings (EliteMobs)

Method	Args	Returns	Description
warning_visual_effects_enabled()	—	bool	Whether warning VFX are enabled in config

EliteMobs Event Table

The context.event table is passed to damage and spawn hooks. Fields vary by event type.

Field / Method	Type	Present When	Description
damage_amount	double	Damage events	Raw damage amount
damage_cause	string	Damage events	DamageCause name
damager	entity table	Damage-by-entity events	Entity that dealt the damage
projectile	entity table	Projectile damage events	Projectile that dealt the damage
spawn_reason	string	Spawn event	Spawn reason name
entity	entity table	Death/zone events	Relevant entity
cancel_event()	method	Most events	Cancel the event
set_damage_amount(amount)	method (double)	Damage events	Override damage amount
multiply_damage_amount(multiplier)	method (double)	Damage events	Multiply current damage

---

context.item FMM

Accessed in FMM item scripts. Resolves the specific scripted item from the player's equipped slots via PDC tag.

Read methods inspect the currently equipped matching item when called. Write methods queue their mutation onto the Bukkit main thread and return nil.

Properties

Field	Type	Description
id	string	Item's script identifier

Methods

Method	Args	Returns	Description
material()	—	string	Material name
get_amount()	—	int	Stack size
set_amount(n)	int	nil	Queue setting stack size
consume(n?)	int?=1	nil	Queue decrement by n, remove if zero
get_uses()	—	int	PDC-stored use counter
set_uses(n)	int	nil	Queue setting PDC use counter
get_durability()	—	table or nil	Returns current and max fields, or nil if no durability bar
get_durability_percentage()	—	number or nil	0.0--1.0 remaining fraction, or nil
use_durability(amount, can_break?)	int, bool?=false	nil	Queue reducing durability by flat amount. When false, clamps to 1 remaining
use_durability_percentage(fraction, can_break?)	number, bool?=false	nil	Queue reducing durability by fraction of max (0.0--1.0)
get_name()	—	string or nil	Display name
set_name(s)	string	nil	Queue setting display name. Supports color codes
get_lore()	—	table	Array of lore strings
set_lore(table)	table	nil	Queue setting lore from array of strings

---

context.prop FMM

Accessed in FMM prop scripts. Inherits all Entity fields from the backing armor stand.

Properties

Field	Type	Description
model_id	string	Blueprint model name
current_location	location	Prop's current position

Methods

Method	Args	Returns	Description
play_animation(name, blend?, loop?)	string, bool?=true, bool?=true	bool	Play named animation
stop_animation()	—	nil	Stop all current animations
hurt_visual()	—	nil	Red tint flash, no damage
pickup()	—	nil	Queue removing prop and dropping placement item
has_mount_points()	—	bool	Whether prop has mount point bones
mount(player)	entity table	bool	Queue mount check; true means basic references were valid
dismount(player)	entity table	bool	Queue dismount check; true means basic references were valid
get_passengers()	—	table	Array of entity tables for mounted players
spawn_elitemobs_boss(file, x, y, z)	string, num, num, num	entity or nil	Spawn EliteMobs boss (requires EliteMobs)
open_inventory(player, title, rows?)	entity table, string, int?=3	bool	Queue opening persistent chest inventory (rows clamped 1--6). Title supports color codes
place_book(player)	entity table	bool	Queue storing the player's held written/writable book on prop
read_book(player)	entity table	bool	Queue opening the stored book for reading
take_book(player)	entity table	bool	Queue returning the stored book to player
has_book()	—	bool	Whether a book is stored
drop_inventory()	—	bool	Queue dropping all stored items and clearing storage
drop_book()	—	bool	Queue dropping stored book and clearing storage
is_viewing_inventory(player)	entity table	bool	Whether player has this prop's inventory open
set_persistent_data(key, value)	string, string	bool	Store string in prop's PDC
get_persistent_data(key)	string	string or nil	Retrieve string from prop's PDC

---

Color Codes

All methods marked as supporting color codes use Magmacore's ChatColorConverter. These formats can be mixed freely in any string:

Legacy codes

Use & followed by a color/format character:

Code	Color	Code	Format
&0	Black	&l	Bold
&1	Dark Blue	&m	Strikethrough
&2	Dark Green	&n	Underline
&3	Dark Aqua	&o	Italic
&4	Dark Red	&r	Reset
&5	Dark Purple
&6	Gold
&7	Gray
&8	Dark Gray
&9	Blue
&a	Green
&b	Aqua
&c	Red
&d	Light Purple
&e	Yellow
&f	White

Hex colors

Exact RGB color using 6-digit hex:

&#FF5500          -- ampersand prefix
<#FF5500>         -- tag syntax

Gradients

Smoothly interpolate between two or more colors across the text:

<gradient:#FF0000:#0000FF>This text fades red to blue</gradient>
<g:#FF0000:#00FF00:#0000FF>Three-color gradient</g>

The short form g works identically to gradient. You can chain as many color stops as you want.

Rainbow

Cycle through the full hue spectrum at full saturation. An optional numeric argument shifts the starting hue (phase offset):

<rainbow>Full rainbow text</rainbow>
<r:0.5>Rainbow with a shifted starting hue</r>

---

Common Types

location

{ x = number, y = number, z = number, yaw = number, pitch = number, world = string }

vector

{ x = number, y = number, z = number }

entity table

Any table with a uuid field. Player and entity tables from context work directly:

context.player                              -- valid entity table
context.world:get_nearby_entities(x,y,z,r)  -- returns array of entity tables

---

Next Steps

• Scripting Engine: How the engine works — sandbox, scheduling, cooldowns, zones
• EliteMobs: Getting Started | NPC Scripts | Hooks & Lifecycle | Boss & Entities | World & Environment | Zones & Targeting | Examples
• FreeMinecraftModels: Getting Started | Prop & Item API | Examples