Wizards of Lua

• New Field: Server.players
  A Player[] @Read-Only list of references to all currently online players.
• New Function: Player:sendCommandTree()
  Sends the current command tree to the player's Minecraft client, forcing Brigadier to rebuild and resend the set of available commands (useful after permission changes).
• Dynamic Commands: permission-based suggestion filtering
  Fixed an issue where Brigadier suggestions for dynamic commands could appear even if the player lacked permission. Suggestions are now correctly filtered by the player’s permission level. Thanks to Nurio for reporting this issue.

• Docs: Field Annotations Reviewed (revised)
  Re-reviewed and updated documentation for every field to ensure clarity on whether accessing a value returns a reference or a copy. No fields missing this time.

• Fix: Client crash upon dropping an item (#21)
  Resolved the crash that occurred when dropping an item on the client. Thanks to Nurio for reporting this issue.

• Docs: Class Section Formatting
  Updated all API docs so that each class description appears above the ---@class tag, in accordance with our documentation standards.

• Docs: Field Documentation Reviewed

  • Reviewed and revised documentation for every field to clearly indicate whether accessing it returns a reference or a copy.
  • Added missing @Read-Only tags for all immutable properties.

• Docs: Example Code
  Added more illustrative code snippets throughout the API docs to demonstrate common usage patterns and clarify behavior.

• Note: Run /wol extract-api to update the config/wizards-of-lua/api folder with the latest API documentation.

• Dynamic Commands: New Enum-String Placeholder
  Added support for an enum-string placeholder (%s[opt1|opt2|…]) that restricts string inputs to a given set, enabling built-in tab-completion and automatic validation of allowed values.

• Standard io Module Support
  Wizards of Lua now officially supports Lua’s standard io module, allowing scripts to create, read, and update files in the server’s world folder.

• New Class: Structure
  Represents a captured box-shaped region of the world.

• New Class: Server
  Provides server-level operations:

  • Server:loadStructure(name) — Load a saved Structure by name.
  • Server:saveStructure(name, structure) — Save a Structure to disk.

• New Functions on Spell

  • Spell:copyStructure(oppositeCorner [, includeEntities, ignoreBlockId]) — Captures a box-shaped region into a Structure object.
  • Spell:pasteStructure(structure [, originPos, ignoreBlockIds]) — Pastes a Structure at the spell’s position.
  • Spell:setYaw(direction) — Sets the spell’s yaw to face a given compass direction ("north", "south", "west", "east").

• New Properties on Spell

  • Spell.facing — Read-only compass direction the spell is oriented toward ("north", "east", "south", "west").
  • Spell.server — Reference to the Server object for accessing server-level operations (filesystem, version, structures).

• Updated Method: Spell:move
  Now accepts relative directions ("forward", "back", "left", "right") in addition to absolute directions to execute relative movement.

• New Property: Entity.facing
  Exposes the entity’s current compass direction.

• New Event: SpellFinishEvent
  Fired immediately before a spell completes execution, allowing interceptors to perform cleanup tasks.

• Refactoring:
  Under-the-hood refactoring of the internal spell lifecycle management for improved stability and consistency.

• New Feature: Dynamic Commands
  Register, inspect and remove custom commands at runtime via the WizardsOfLua module API:

  • WizardsOfLua.setCommand({ id, level, pattern, code }) to add a command.
  • WizardsOfLua.listCommands() to list all dynamic commands.
  • WizardsOfLua.removeCommand(id) to unregister a command.
    Patterns use Brigadier-style syntax with named or unnamed placeholders—see the API docs for full details and examples.

• Fix: PrintRedirector & LogRedirector now strip carriage return characters from their output.

• Fix: Wol commands updated to include intermediate permission checks.

• Fix: Examples section: bug in Auto-Toggle Gamemode Field fixed.

• New Property: Entity.extra
  Introduces a persistent extra table on every entity for custom data, saved as NBT into the entity’s NBT storage on disk.
• New Method: Entity:putExtra(...)
  Merges a table into an entity’s extra field for persisting values.
• New Events: ChunkLoadEvent, ChunkUnloadEvent
  Fired whenever a chunk loads into or unloads from memory.
• New Field: World.spawnPos
  Exposes the world’s spawn point as a Vec3.
• Updated Event: ChatMessageEvent
  Now cancelable. Return false in an interceptor callback to prevent broadcasting.
• Updated API Docs: AfterPlayerRespawnEvent
  Added example usage demonstrating how to queue and handle the event.

• New Event: PermissionCheckEvent
  Can now intercept permission checks and override the default permission system (e.g. LuckPerms) from within Lua.

  • In intercept callbacks, assign evt.allowed = true to grant or false to deny.
  • Leaving evt.allowed as nil defers to the default permission logic.

• Refined event handling in interceptors
  Returning nil from an interceptor callback is now permitted and treated as true, so the event will continue (i.e., not be canceled).

• Fix:

  • WolStartupCommand and WolExtractApiCommand permissions were not assigned correctly; now fixed.

• New Class: PlayerInventory
  The player's inventory can now be accessed programmatically through the Player.inventory property.

  • Slot indices follow vanilla layout:
    • 0–8: hotbar
    • 9–35: main inventory
    • 36–39: armor slots (feet → head)
    • 40: offhand
  • Use player.inventory[i] to read/write items.
  • Access the currently selected hotbar index via inventory.selectedSlot.
  • New method: PlayerInventory:clear() wipes all slots.

• New Method: Item:copy()
  Creates a deep copy of the item.
  Useful for duplicating stacks or preserving originals before modification.

• New Methods for Equipment Handling on LivingEntity:

  • LivingEntity:getEquipment(slot)
    Returns the Item in a specific equipment slot.
  • LivingEntity:setEquipment(slot, item)
    Places an item into the specified slot.

Slot Names: "mainhand", "offhand", "feet", "legs", "chest", "head", "body"
(Use lowercase names as strings.)

• Command Permissions Support
  Wizards of Lua now supports Minecraft-style permission nodes for all commands.
  • Each command (e.g., /lua, /wol extract-api) is gated by a permission node such as wizardsoflua.lua or wizardsoflua.wol.extract-api.
  • By default, these commands require operator level 2.
  • On servers using permission plugins like LuckPerms, access can be granted per node.
  • See the full list of permission nodes and required levels.

• Semantic Versioning introduced. This project now follows the MAJOR.MINOR.PATCH format.
• Removed Command: wol printMode has been removed.
• Output Behavior:
  • The Lua print(...) function now sends its output as standard command feedback.
  • New log(...) function introduced for logging messages. Output is routed based on the log field in the WizardsOfLua module.
• New Class: Trace
  • Use Trace objects to programmatically capture command output.
• Updated Function: Spell:execute(...)
  • No longer returns a value.
  • Command output is now sent as standard command feedback.
  • To capture feedback, pass a Trace object as the optional second argument.
  • Now supports multiple calls within the same game tick.
• New Function: Spell:executeSilent(...)
  • Executes a command without sending output as feedback.
  • Supports the same Trace capture as Spell:execute(...).
• Changes in Module WizardsOfLua:
  • Removed deprecated printMode field.
  • Added new log field to control the output target of log(...).

• Fix error: Registry entry (wizardsoflua:print_mode) is missing from local registry (minecraft:command_argument_type)

• New command: /wol spell list
• New command: /wol printMode
• New module WizardsOfLua to read and write configuration settings.
• New event: PlayerAttackEntityEvent
• New example: Vertical Minecart using ladders
• New example: Safezone spell
• Fix Player: rename incorrect class name - ServerPlayerEntity -> Player
• New field: Player.permissionLevel
• Add documentation of commands
• Vec3: Add documentation for Vec3(x,y,z)
• Remove Done. output after spell creation.

• Frequently Asked Questions: add FAQ markdown file
• World: add "dimension" property

• Fix Vec3: revert removal of type declaration
• /wol startup: the server should be the spell.owner

• Add Entity.uuid
• Fix Player: mainHandItem should be nil rather than ItemStack.EMPTY

• Add Placeholder API support

• Improved Wizards of Lua API docs

• Startup: kill any active spells on startup (Singleplayer)
• Wizards of Lua API: more examples, better explanation

• Fix LuaEntity: invalid downcast to ItemEntity in "putNbt" function
• Remove LuaPig: undocumented class, existed for testing only.

• Item: add optional constructor parameter "nbt"
• Item: add "putNbt" function
• ItemEntity: add optional constructor parameter "nbt"