Lua Scripting: Getting Started

This page teaches you to write your first Lua script for a FreeMinecraftModels prop or custom item, from an empty file all the way to a working interactive script. By the end you will understand hooks, context, the prop and item APIs, and the general shape of every script file.

Once you are comfortable with the basics, continue with the companion pages:

Prop & Item API -- the context.prop, context.item, context.event, context.world, and other context APIs
Examples & Patterns -- complete working scripts for props and items you can study and adapt
Troubleshooting -- common errors, debugging tips, and the QC checklist

Experimental Feature

Lua prop and item scripts are currently experimental. Hook names, helper methods, and behavior can still change as FreeMinecraftModels evolves, so test carefully before using them on a production server.

Relationship To EliteMobs Lua

FreeMinecraftModels shares the same Lua engine (Magmacore) as EliteMobs. If you already write Lua powers for EliteMobs, the core concepts -- hooks, context, api_version, scheduler, zones, and the sandbox -- are identical. The difference is:

EliteMobs scripts run on bosses and have hooks like on_boss_damaged_by_player, on_enter_combat, etc.
FMM prop scripts run on props and have hooks like on_right_click, on_left_click, on_projectile_hit, etc.
FMM item scripts run on custom items and have hooks like on_equip, on_attack_entity, on_consume, on_game_tick, etc.

The context.world, context.zones, context.scheduler, context.state, and context.log APIs are the same across both plugins. This page covers what is specific to FMM props and items.

What Prop Scripts Are

Prop scripts are standalone .lua files that live in the plugins/FreeMinecraftModels/scripts/ folder. They are referenced from a YAML config file that sits alongside the model file, and they run whenever the prop is spawned into the world.

What Prop Scripts Are Good At

Prop scripts shine when you need:

Interactive props that respond to player clicks (doors, levers, buttons)
Invulnerable decorative props that cannot be broken by players
Proximity triggers that detect when players enter or leave an area
Animated props that play animations on interaction or on a timer
Sound-emitting props that play sounds when clicked or approached
Any prop behavior that requires logic beyond static decoration

If your prop is purely decorative and needs no interaction, you do not need a script.

What Item Scripts Are

Item scripts use the same .lua file format and the same scripts/ folder as prop scripts. The difference is that they are attached to custom items -- models that have a material: field set in their YML config file. While prop scripts run when a prop entity is spawned in the world, item scripts run when a player equips the custom item (main hand, off hand, or armor slot) and stop when the item is unequipped.

How Item Scripts Work

Activation: A script instance is created when a player equips a custom FMM item. Scripts are per-player per-item-type -- one ScriptInstance per (player, itemId) pair.
Deactivation: The script instance is destroyed when the item is unequipped (moved out of the active slot, dropped, or the player disconnects).
Item identification: Custom items are identified by the fmm_item_id PDC (PersistentDataContainer) key, which is different from the prop's model_id. To get a properly tagged item, use /fmm giveitem <id> or the admin menu.
Context: Item hooks receive context with context.player, context.item, context.world, context.state, context.scheduler, context.log, and (where applicable) context.event.

What Item Scripts Are Good At

Item scripts shine when you need:

Custom weapons with special abilities (frost swords, magic wands)
Tools with unique right-click or shift-click actions
Consumable items with custom effects
Armor with passive effects while worn
Items that track usage or have limited durability
Any held-item behavior beyond vanilla mechanics

Who This Page Is For

This page is written for three kinds of readers:

Someone who already knows EliteMobs Lua scripting and wants to learn the FMM-specific hooks and APIs
Someone who is new to Lua scripting and needs a complete, exact-name reference for props
Someone using AI to draft prop scripts and needing enough detail to tell when the AI invented something fake

You do not need to become a full Lua developer before writing useful prop scripts. For most practical prop scripts, the only things you really need are:

How to place a valid hook in the returned table
How to read values from context
How to stop early with if ... then return end
How to call a few helper methods exactly

Tiny Lua Primer

You don't need to be a Lua expert to write FMM scripts. Most scripts only use a handful of concepts: variables (local x = 5), functions (function foo() end), if checks (if x then ... end), tables ({key = value}), and nil (Lua's "nothing" value). The syntax is lightweight — no semicolons, no curly braces, just end to close blocks.

For a complete walkthrough with examples, see the MagmaCore Lua Scripting Engine — Tiny Lua Primer. That primer is shared across all Nightbreak plugins, so learning it once applies everywhere.

Where Files Live

Script Files

Place .lua files in the central scripts folder:

plugins/
  FreeMinecraftModels/
    scripts/
      invulnerable.lua
      interactive_door.lua
      proximity_sound.lua

FMM discovers all .lua files in plugins/FreeMinecraftModels/scripts/ at startup.

Model Files and Config Files

Each model file can have a sibling .yml config file in the same directory:

plugins/
  FreeMinecraftModels/
    models/
      torch_01.fmmodel
      torch_01.yml          <-- script config for torch_01
    scripts/
      invulnerable.lua      <-- referenced by torch_01.yml

The .yml config is what connects a model to its scripts.

Config File Format

The YAML config file that sits next to a model file has these fields:

isEnabled: true
voxelize: false
solidify: false
scripts:
  - invulnerable.lua

For custom items (models that players can hold or equip), you also set the material field and optionally name, lore, and enchantments:

isEnabled: true
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in eternal ice"
  - "&7Slows enemies on hit"
enchantments:
  - "SHARPNESS,5"
  - "UNBREAKING,3"
scripts:
  - frost_sword.lua

Field	Type	Default	Notes
`isEnabled`	boolean	`true`	Whether scripts are active for this prop/item
`scripts`	list of strings	`[]`	Filenames of `.lua` scripts in the `scripts/` folder
`voxelize`	boolean	`false`	Snap placement to 90-degree rotation and block grid alignment
`solidify`	boolean	`false`	Place packet-only barrier blocks in the prop's footprint (requires `voxelize`)
`material`	string	`""`	A valid Bukkit Material name (e.g. `DIAMOND_SWORD`). Setting this turns the model into a custom item that players can hold or equip, which activates the item scripting system
`name`	string	`""`	Display name for the custom item. Supports `&` color codes
`lore`	list of strings	`[]`	Lore lines shown in the item tooltip. Supports `&` color codes
`enchantments`	list of strings	`[]`	Enchantments applied to the item. Format: `"ENCHANTMENT_NAME,LEVEL"` (e.g. `"SHARPNESS,5"`)

You can attach multiple scripts to the same prop. Each script is its own independent instance.

Item ID and Script Limit

The item ID is derived from the YML filename without its extension. For example, frost_sword.yml produces an item ID of frost_sword. This is the ID used by /fmm giveitem and the fmm_item_id PDC key.
Items only use the first script in the scripts: list. Unlike props, which run all listed scripts as independent instances, custom items ignore any scripts after the first entry.
The .lua extension is auto-appended to script filenames if you omit it, so frost_sword and frost_sword.lua are equivalent in the scripts: list.

Lazy Config Generation

When a prop spawns and no sibling .yml file exists, FMM automatically creates a default config file with isEnabled: true and an empty scripts: list. This happens asynchronously, so the prop will not have scripts on its first spawn -- only after the config is created and you edit it to add script filenames.

This means:

Place your model file in models/
Spawn the prop once (FMM creates the .yml automatically)
Edit the generated .yml to add your script filenames
Respawn the prop or reload (scripts are now active)

Hook Reference

Every Lua prop script file returns a table. Each key in that table (besides api_version and priority) must be one of the hooks listed below. The runtime calls the matching function whenever the corresponding game event fires.

Hook	Fires when	Notes
`on_spawn`	The prop is spawned into the world	Runs once when the script is bound
`on_game_tick`	Once every server tick (50 ms)	Only active if the script defines this hook
`on_destroy`	The prop is removed from the world	Cleanup hook
`on_left_click`	A player left-clicks (hits) the prop	`context.event` is the damage event
`on_right_click`	A player right-clicks the prop	`context.event` is the interaction event
`on_projectile_hit`	A projectile hits the prop	`context.event` is the projectile hit event
`on_zone_enter`	A player enters a watched zone	Requires a zone watch to be set up
`on_zone_leave`	A player leaves a watched zone	Requires a zone watch to be set up

Item Hook Reference

Item scripts return a table just like prop scripts, with api_version = 1 and hook functions. The following hooks are available for item scripts. All item hooks receive context with context.player, context.item, and (where applicable) context.event.

Combat Hooks

Hook	Fires when	Notes
`on_attack_entity`	The player attacks an entity while holding the item	`context.event` is the damage event
`on_kill_entity`	The player kills an entity while holding the item	`context.event` is the death event
`on_take_damage`	The player takes damage while the item is equipped	`context.event` is the damage event
`on_shield_block`	The player blocks damage with a shield	`context.event` is the damage event
`on_shoot_bow`	The player shoots a bow	`context.event` is the bow shoot event
`on_projectile_hit`	A projectile shot by the player hits something	`context.event` is the projectile hit event
`on_projectile_launch`	The player launches a projectile	`context.event` is the projectile launch event

Interaction Hooks

Hook	Fires when	Notes
`on_right_click`	The player right-clicks while holding the item	`context.event` is the interact event
`on_left_click`	The player left-clicks while holding the item	`context.event` is the interact event
`on_shift_right_click`	The player shift+right-clicks while holding the item	`context.event` is the interact event
`on_shift_left_click`	The player shift+left-clicks while holding the item	`context.event` is the interact event
`on_interact_entity`	The player right-clicks an entity while holding the item	`context.event` is the entity interact event

Equipment Hooks

Hook	Fires when	Notes
`on_equip`	The item is equipped (moved into an active slot)	Good place to initialize state
`on_unequip`	The item is unequipped (moved out of an active slot)	Good place to clean up
`on_swap_hands`	The player swaps the item between main and off hand	`context.event` is the swap event
`on_drop`	The player drops the item	`context.event` is the drop event

Utility Hooks

Hook	Fires when	Notes
`on_break_block`	The player breaks a block while holding the item	`context.event` is the block break event
`on_consume`	The player consumes the item (food/potion)	`context.event` is the consume event
`on_item_damage`	The item takes durability damage	`context.event` is the item damage event
`on_fish`	The player uses a fishing rod	`context.event` is the fish event
`on_death`	The player dies while the item is equipped	`context.event` is the death event

Lifecycle Hook

Hook	Fires when	Notes
`on_game_tick`	Every server tick while the item is equipped	Use sparingly -- runs 20 times per second

Minimal File Contract

Every Lua prop script must return a table.

Required and Optional Top-Level Fields

Field	Required	Type	Notes
`api_version`	Yes	Number	Currently must be `1`
`priority`	No	Number	Execution priority. Lower values run first. Defaults to `0`
supported hook keys	No	Function	Must use one of the exact hook names listed in the Hook Reference

Validation Rules

The file must return a table.
api_version is required and must currently be 1.
priority must be numeric if present.
Every extra top-level key must be a supported hook name.
Every hook key must point to a function.
Unknown top-level keys are rejected.

Helper functions and local constants should live above the final return, not inside the returned table.

Your First Working Prop Script, Built Slowly

Before Step 1: Set Up the Config

Place your model file (e.g. my_prop.fmmodel) in plugins/FreeMinecraftModels/models/
Spawn the prop once to generate the .yml config
Create your script file in plugins/FreeMinecraftModels/scripts/first_test.lua
Edit plugins/FreeMinecraftModels/models/my_prop.yml:

isEnabled: true
scripts:
  - first_test.lua

Respawn the prop or reload the server

Step 1: Make the File Load

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

If this loads without errors in the console, you proved:

The file is valid Lua
FMM found it in the scripts/ folder
The config correctly references it
The returned table shape is correct

Step 2: Make the Prop Do One Visible Thing

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Prop script loaded for: " .. (context.prop.model_id or "unknown"))
  end
}

Check the server console. If you see the log message, your hook is firing.

Step 3: React to a Player Click

return {
  api_version = 1,

  on_right_click = function(context)
    context.log:info("Prop was right-clicked!")
  end
}

Right-click the prop in-game. If the console shows the message, the click hook is working.

Step 4: Cancel Damage to Make the Prop Invulnerable

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

This is the pattern used by the premade invulnerable.lua script. It cancels the damage event so the prop's backing armor stand cannot be destroyed.

Step 5: Play an Animation on Click

return {
  api_version = 1,

  on_right_click = function(context)
    context.prop:play_animation("open", true, false)
  end
}

This plays the "open" animation on the prop model, blended and non-looping.

What Is `context`?

Every hook function receives one argument called context. Think of it as a toolbox that FMM hands you each time something happens -- it contains everything you need to interact with the prop, the world, zones, and more.

You don't create context yourself -- FMM creates it and passes it to your hook. For full details on the shared context APIs (context.state, context.log, context.scheduler, context.world, context.zones), see the MagmaCore Lua Scripting Engine page.

Key `context` APIs

Here is a summary of what is available. For full details, see Prop API.

context.prop -- (Prop scripts only) The prop entity. Provides model_id, current_location, play_animation(), and stop_animation().
context.item -- (Item scripts only) The custom item. Provides id, material(), get_amount(), set_amount(), consume(), get_uses(), set_uses(), get_name(), set_name(), get_lore(), set_lore(), get_durability(), get_durability_percentage(), use_durability(), and use_durability_percentage(). See Prop & Item API for full details.
context.player -- (Item scripts only) The player holding the item. Provides all player entity fields and methods plus UI methods like show_boss_bar(), show_action_bar(), and show_title().
context.event -- The Bukkit event that triggered this hook. Available in click, combat, and interaction hooks. Provides cancel(), uncancel(), and is_cancelled. Is nil in hooks that have no event (like on_spawn, on_game_tick, and on_equip).
context.state -- A plain Lua table that persists for the script instance's lifetime. See context.state.
context.log -- Console logging. See context.log.
context.scheduler -- Delayed and repeating tasks. See context.scheduler.
context.world -- World interaction: particles, sounds, block queries, lightning, nearby entities. See context.world.
context.zones -- Create and watch spatial zones (spheres, cylinders, cuboids). See context.zones.

Method Syntax: `:` vs `.`

For an explanation of : vs . method syntax in Lua, see the MagmaCore Lua Scripting Engine page. Both forms are accepted by the FMM API.

Copy-Paste Starter Templates

Smallest Valid Prop Script

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Invulnerable Prop Template

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

Interactive Prop Template

return {
  api_version = 1,

  on_spawn = function(context)
    context.state.is_active = false
  end,

  on_right_click = function(context)
    context.state.is_active = not context.state.is_active

    if context.state.is_active then
      context.prop:play_animation("activate", true, true)
    else
      context.prop:stop_animation()
    end
  end
}

Smallest Valid Item Script

return {
  api_version = 1,

  on_equip = function(context)
  end
}

Item with Right-Click Action Template

return {
  api_version = 1,

  on_equip = function(context)
    context.state.on_cooldown = false
  end,

  on_right_click = function(context)
    if context.state.on_cooldown then return end

    -- Your action here
    context.player:send_message("&aItem activated!")

    -- Set cooldown
    context.state.on_cooldown = true
    context.scheduler:run_later(40, function()
      context.state.on_cooldown = false
    end)
  end
}

Larger File Layout

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    context.state.task_id = nil
  end,

  on_right_click = function(context)
    do_something(context)
  end,

  on_destroy = function(context)
    if context.state.task_id ~= nil then
      context.scheduler:cancel(context.state.task_id)
    end
  end
}

First Real Workflow

When building a brand-new prop script, use this order:

Create the .lua file and make on_spawn work.
Add the script filename to the prop's .yml config.
Change to the actual hook you want (e.g. on_right_click).
Add a log message first, before animations or effects.
Add one real effect (animation, sound, particle).
Only after that, add helpers, state, scheduler logic, or zones.

That order makes debugging dramatically easier because only one thing changes at a time.

Premade Scripts

FMM ships with four premade Lua scripts:

invulnerable.lua -- Cancels left-click damage events, making the prop indestructible. This is the simplest useful prop script.
pickupable.lua -- Lets players pick up a prop by hitting it three times. Each hit plays a hurt animation on the prop, and on the third hit the prop is removed and drops its placement item for the player to collect.
storage_double.lua -- Turns a prop into a double chest (54 slots). Right-click opens a persistent inventory GUI. Plays open/close animations and sounds. Contents are saved to the prop and survive server restarts. On destroy, all contents are dropped.
storage_single.lua -- Same as storage_double but with 3 rows (27 slots) instead of 6.

You can find more examples on the Examples & Patterns page.

Lua Sandbox

Prop and item scripts run inside the same sandboxed LuaJ environment as EliteMobs. The sandbox restrictions are identical. For the full list of removed globals and available standard library functions, see the MagmaCore Lua Scripting Engine page.

Next Steps

Prop & Item API -- full context.prop, context.item, context.event, context.world, context.zones, and context.scheduler reference
Examples & Patterns -- complete working scripts for props and items with walkthroughs
Troubleshooting -- common issues, debugging tips, and a QC checklist

If you are also writing EliteMobs Lua powers, the shared APIs (context.world, context.zones, context.scheduler, context.state, context.log) work identically. See the EliteMobs Lua documentation for the boss-specific APIs.

What Prop Scripts Are​

What Prop Scripts Are Good At​

What Item Scripts Are​

How Item Scripts Work​

What Item Scripts Are Good At​

Who This Page Is For​

Tiny Lua Primer​

Where Files Live​

Script Files​

Model Files and Config Files​

Config File Format​

Lazy Config Generation​

Hook Reference​

Item Hook Reference​

Combat Hooks​

Interaction Hooks​

Equipment Hooks​

Utility Hooks​

Lifecycle Hook​

Minimal File Contract​

Required and Optional Top-Level Fields​

Validation Rules​

Your First Working Prop Script, Built Slowly​

Before Step 1: Set Up the Config​

Step 1: Make the File Load​

Step 2: Make the Prop Do One Visible Thing​

Step 3: React to a Player Click​

Step 4: Cancel Damage to Make the Prop Invulnerable​

Step 5: Play an Animation on Click​

What Is context?​

Key context APIs​

Method Syntax: : vs .​

Copy-Paste Starter Templates​

Smallest Valid Prop Script​

Invulnerable Prop Template​

Interactive Prop Template​

Smallest Valid Item Script​

Item with Right-Click Action Template​

Larger File Layout​

First Real Workflow​

Premade Scripts​

Lua Sandbox​

Next Steps​