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>
This commit is contained in:
Kirill Sokolov 2026-10-20 21:08:09 +03:00
parent db9f6c9f32
commit 110cb2a896
68 changed files with 5064 additions and 844 deletions

120
mods/README.md Normal file
View file

@ -0,0 +1,120 @@
# 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`).