Wizards of Lua

Fix /wol extract examples:
Modified files from the extracted Journey example are now loaded correctly. Previously, the mod loaded the bundled copy from the JAR instead of the filesystem, so user edits had no effect.

Fix (Journey Mini-Game):

• The Journey spell now terminates properly when a player disconnects from the server.
• Disabled verbose log output by default in the Journey mini-game.
  You can re-enable it by editing config/wizards-of-lua/examples/journey/log_extensions.log and setting logEnabled = true.

• /wol extract examples populates config/wizards-of-lua/examples/ with example projects; currently includes the mini-game “Journey.”
• After extraction run /wol startup to register the example’s dynamic commands.

• Extraction syntax updated: use /wol extract api (replaces the old /wol extract-api).

• tickLimit — Per-tick execution budget (in Lua operations). Default 50,000; higher values do more work per tick (potential TPS impact), lower values yield more often for smoother pacing.
• biome — read-only biome ID at spell.pos (e.g., "plains", "forest"); updates as the spell moves.

Fix: LivingEntity:getItemInHand(hand) no longer throws a NullPointerException when the specified hand is empty.

API Docs: Adjusted example code that handles NBT data to use the new Minecraft 1.21.5 NBT syntax in:

• BlockEntity
• Entity
• Item
• Spell

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

New Function: Server:getWorld(dimension)
Returns a reference to the World for the given dimension name (e.g., "the_nether", "overworld").

New Property: Spell.id
Read-only numeric ID of the spell.

Updated Methods: Spell:execute(...) and Spell:executeSilent(...)
Both now return the command result value (typically the number of affected entities/blocks).

Fix: World:isLoaded(pos)
Corrected a bug where this function could incorrectly return true in some cases; behavior now matches the documentation.

Fix: EventInterceptor:stop()
This method now actually stops the interceptor from receiving further events.

New Events
Added hooks to observe or intercept more gameplay actions:
AfterLivingEntityDamageEvent, BeforeLivingEntityDamageEvent, EntityDespawnEvent, EntitySpawnEvent, PlayerAttackBlockEvent, PlayerChangeWorldEvent, PlayerDisconnectedEvent, PlayerDropSelectedItemEvent, PlayerUseEntityEvent.

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.