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

120 lines
5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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