hypermcpe/mods/README.md
Kirill Sokolov 110cb2a896 Infinite world, LuaJIT mod API, WorldEdit port, skins and music
- Infinite world: streamed chunk cache, multi-region storage (old chunks.dat
  still loads), per-chunk entity/tile entity persistence, client chunk
  streaming, protocol version 10, view-distance server property
- LuaJIT mod host (mods/, lua/prelude.lua) with events, commands, world and
  player API; WorldEdit command set ported to it (mods/worldedit)
- /skin command, SetSkinPacket and bundled skins
- OGG music player (data/music is ignored, tools/convert-music.ps1)
- package-windows.ps1 builds client and dedicated server for Windows

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 21:08:09 +03:00

5 KiB
Raw Permalink Blame History

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/<mod>/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

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

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

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

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).