# Lua mods (LuaJIT) The game embeds **LuaJIT 2.1**. Mods run on the machine that hosts the world: the dedicated server (`MinecraftPE-server.exe`), a single player world, or a client that hosts a LAN game. A client that only joins a server runs no mods. ``` mods/ my_mod/ main.lua <- loaded at startup (alphabetical order) other.lua <- require("other") tiny.lua <- a single file mod works too ``` Every mod runs in its own environment (`MOD.name`, `MOD.dir` describe it), so globals do not leak between mods. `require("x")` loads `mods//x.lua` first. The full Lua 5.1 standard library, `io`, `os`, `bit` and `ffi` are available – mods are trusted code, only install mods you trust. ## Events ```lua mc.on("start", function() end) -- all mods loaded, world is up mc.on("stop", function() end) mc.on("tick", function() end) -- 20 times per second mc.on("join", function(player) end) mc.on("leave", function(player) end) mc.on("chat", function(player, message) end) -- return false to cancel mc.on("block_break", function(player, x, y, z, tile) end)-- return false to cancel mc.on("use_item", function(player, x, y, z, face, itemId, itemData) end) -- right click on a block, false cancels ``` ## Commands ```lua mc.command("home", { description = "Go home", op = false }, function(ctx) ctx.player:teleport(0, 70, 0) return "Welcome home!" -- a returned string is sent to the player end) ``` `ctx` has `player`, `args` (array of strings) and `name`. Names are what is typed after the first slash: `mc.command("/set", ...)` is `//set` in game. `op = true` restricts the command to operators (`ops.txt`). ## Players `mc.players()`, `mc.player("name")`, `mc.broadcast(text)` | method | | |---|---| | `p.name`, `p.id`, `p.data` | `data` is a free table for your mod | | `p:pos()` → x, y, z | feet position | | `p:block_pos()` → x, y, z | integer block of the feet | | `p:look()` → yaw, pitch | | | `p:facing()` → 0..3, dx, dz | south, west, north, east | | `p:teleport(x, y, z [, yaw, pitch])` | | | `p:say(text)` | private message | | `p:is_op()` | | | `p:held()` → id, data, count | | | `p:give(id [, count [, data]])` | | | `p:target([distance])` → x, y, z, face | block in the crosshair | | `p:gamemode()` | 0 survival, 1 creative | ## World ```lua mc.world.get_block(x, y, z) -- id, data mc.world.set_block(x, y, z, id, data) -- normal change (updates neighbours, notifies clients) mc.world.set_block(x, y, z, id, data, true) -- "silent": no updates; call mc.world.flush() afterwards mc.world.flush() -- relight + resend every chunk touched by silent writes mc.world.height(x, z) -- highest solid block, -1 if none mc.world.is_loaded(x, z) -- block coordinates mc.world.ensure_loaded(x, z, radiusInChunks) mc.world.spawn_mob(mc.mob.pig, x, y, z) -- returns entity id mc.world.drop_item(id, count, data, x, y, z) mc.world.explode(x, y, z, radius) mc.world.butcher(x, y, z, radius, includeFriendly) -- radius 0 = everywhere, returns count mc.world.get_time() / set_time(t) / seed() ``` The world is infinite: chunks around players are generated, saved and unloaded on demand. Use `ensure_loaded` before touching far-away coordinates. ## Names and ids `mc.block.parse("stone")`, `mc.block.parse("35:14")`, `mc.block.parse("red_wool")` → id, data `mc.block.name(id)`, `mc.item.wooden_axe`, `mc.mob.zombie`, … ## Scheduler and utilities ```lua local id = mc.after(40, function() ... end) -- ticks mc.every(20, function() ... end) mc.cancel(id) mc.log("text") mc.save_table("mods/data/x.lua", tbl) / mc.load_table(path, default) ``` # Bundled mods * **worldedit** – a port of EngineHub's WorldEdit command set (see below). * **hello** – the smallest possible example. ## WorldEdit Give yourself the wand with `//wand` (a wooden axe): left click = position 1, right click = position 2. Operators only. Implemented commands: `//wand //pos1 //pos2 //hpos1 //hpos2 //chunk //sel //expand //contract //shift //outset //inset //trim //size //count //distr` `//set //replace //overlay //center //naturalize //walls //faces //hollow //smooth //move //stack //line` `//sphere //hsphere //cyl //hcyl //cone //pyramid //hpyramid` `//copy //cut //paste //rotate //flip /clearclipboard /schematic save|load|list|delete` `/undo /redo /clearhistory //fill //fillr //drain /fixwater /fixlava /removeabove /removebelow /removenear /replacenear` `/snow /thaw /green /extinguish /butcher //limit /toggleplace /we` `/unstuck /ascend /descend /ceil /thru /jumpto /up` `/tool (repl, info, farwand, navwand, selwand, deltree, floodfill, none) /brush (sphere, cylinder, set, smooth, raise, lower, gravity, extinguish, butcher) /mask /material /range /size // /sp` Patterns: `stone`, `35:14`, `red_wool`, `50%stone,50%dirt`. Masks: `stone,dirt`, `!air`, `#existing`, `#solid`. Flags work like in the original (`//sphere -h stone 5`).