Tutorial: build an arena minigame

[PyXiion]

Stacked on #24: the tutorial uses the new event model. Once #24 is merged, this PR's base becomes master.

Tutorial

A nine-chapter tutorial on the site (/tutorial). It grows one script, config/ignis/arena.lua, into a PvP arena where the last player standing wins:

1. Commands and saved settings: register, permissions, mc.data, and the "assigning a table stores a copy" rule.
2. The arena region: regions and block protection with cancellable events and priority.
3. Rounds: a game loop with phases, mc.scheduleRepeating, and a celebration with async.sleep.
4. Fights: knockouts via a cancelled entity.death, and region enter/leave handlers.
5. Boss bar and scoreboard.
6. Statistics and leaderboard: player.data, a leaderboard in mc.data, a hologram.
7. Kits and inventories: the player's items are stashed via serialise, and kits are picked from a chestgui menu.
8. Events for other scripts: mc.emit("arena:win") plus a separate rewards script (diamonds, a Discord webhook via async.fetch).
9. Reloads and crashes: what a reload keeps and removes, uninit, returning items after a crash, debugging.

Each chapter ends with the complete file at that point (site/tutorial/arena/NN-*.lua, embedded via ?raw).

Checks (site/tutorial/test.sh, new tutorial CI job)

• Every line of the code snippets on the pages must appear in that chapter's checkpoint file.
• Every checkpoint file is checked with lua-language-server --check against lua-types/ (Lua 5.2, including hints).
• The game logic runs in lua5.2 against a fake API (test/mock.lua):
  • a smoke test for every chapter;
  • a full scenario on the final version: setup, kits, rounds, knockouts, leaving the region and the server, a stranger entering, reload, a restart with a JSON round trip, crash recovery, and the rewards script.

The tutorial has not been run on a real server. Only the mock and LuaLS verify it.

Bugs found along the way

• lua-types
  • mc.on/region:on overloads listed several events as a union. LuaLS only matched the first one, so e was untyped in player.join, player.leave, tick, entity.death, block.place and others. There is now one overload per event.
  • The chestgui types described methods that don't exist.
  • mc.createItem(id, opts) was missing.
  • Fixed a syntax error in registerBehaviour.
• Script permissions
  • register(..., perm) and player:hasPermission called Permissions.check without a default level. That returns false when no permissions mod answers, so on a server without one, nobody (not even operators) could run a script command that has a permission.
  • They now fall back to op level 4, like /ignis.
• whitelist example: it assigned an empty local table to mc.data and then changed the local one, so entries were not saved until a reload. The storage reference now explains the copy semantics.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X7gxWF7FdViJa9dKAZJiac

---

Generated by Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric	Results
Complexity	0
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}