From f09e10ae49bed761b7afc2331db8643693d2862e Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Fri, 13 Sep 2024 02:51:36 +0100 Subject: [PATCH 01/17] document register_command --- .../core/register_command.lua | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/worldeditadditions_core/core/register_command.lua b/worldeditadditions_core/core/register_command.lua index 6ae81fb..2c07293 100644 --- a/worldeditadditions_core/core/register_command.lua +++ b/worldeditadditions_core/core/register_command.lua @@ -5,7 +5,7 @@ -- ██ ██ ███████ ██████ ██ ███████ ██ ███████ ██ ██ --- WorldEditAdditions chat command registration --- @namespace worldeditadditions_core +-- @module worldeditadditions_core local wea_c = worldeditadditions_core local run_command = dofile(wea_c.modpath.."/core/run_command.lua") @@ -13,7 +13,19 @@ local function log_error(cmdname, error_message) minetest.log("error", "register_command("..cmdname..") error: "..error_message) end ---- TODO: Document this function + +--- Registers a new WorldEditAdditions chat command. +-- @param cmdname string The name of the command to register. +-- @param options table A table of options for the command: +-- - `params` (string) A textual description of the parameters the command takes. +-- - `description` (string) A description of the command. +-- - `privs` (`{someprivilege=true, ....}`) The privileges required to use the command. +-- - `require_pos` (number) The number of positions required for the command. +-- - `parse` (function) A function that parses the raw param_text into proper input arguments to be passed to `nodes_needed` and `func`. +-- - `nodes_needed` (function) A function that returns the number of nodes the command could potential change given the parsed input arguments. +-- - `func` (function) The function to execute when the command is run. +-- - `override=false` (boolean) Whether to override an existing command with the same name. +-- @return boolean True if the command was registered successfully, false otherwise. local function register_command(cmdname, options) --- From 8c4d503f1fcb44832daf417b605cb50edfa85aef Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Fri, 13 Sep 2024 02:52:35 +0100 Subject: [PATCH 02/17] turn wea_core into an EventEmitter; emit command execution pipeline events These are subject to feedback and change - please let me know if they are named sensibly or not! --- worldeditadditions_core/core/run_command.lua | 89 ++++++++++++++++++-- worldeditadditions_core/init.lua | 11 ++- 2 files changed, 91 insertions(+), 9 deletions(-) diff --git a/worldeditadditions_core/core/run_command.lua b/worldeditadditions_core/core/run_command.lua index 78d6f2f..9456bb7 100644 --- a/worldeditadditions_core/core/run_command.lua +++ b/worldeditadditions_core/core/run_command.lua @@ -8,15 +8,77 @@ local human_size = wea_c.format.human_size -- TODO: Reimplement worldedit.player_notify(player_name, msg_text) -local function run_command_stage2(player_name, func, parse_result) +--- Actually runs the command in question. +-- Unfortunately needed to keep the codebase clena because Lua sucks. +-- @internal +-- @param player_name string The name of the player executing the function. +-- @param func function The function to execute. +-- @param parse_result table The output of the parsing function that was presumably called earlier. Will be unpacked and passed to `func` as arguments. +-- @param tbl_event table Internal event table used when calling `worldeditadditions_core.emit(event_name, tbl_event)`. +-- @returns nil +local function run_command_stage2(player_name, func, parse_result, tbl_event) + wea_c.emit("pre-execute", tbl_event) local success, result_message = func(player_name, wea_c.table.unpack(parse_result)) if result_message then - -- TODO: If we were unsuccessfull, then colour the message red + -- TODO: If we were unsuccessful, then colour the message red worldedit.player_notify(player_name, result_message) end + + tbl_event.success = success + tbl_event.result = result_message + wea_c.emit("post-execute", tbl_event) end +--- Command execution pipeline: before `paramtext` parsing but after validation. +-- +-- See `worldeditadditions_core.run_command` +-- @event pre-parse +-- @format { player_name: string, cmddef: table, paramtext: string } + +--- Command execution pipeline: directly after `paramtext` parsing +-- +-- See `worldeditadditions_core.run_command` +-- @event post-parse +-- @format { player_name: string, cmddef: table, paramtext: string, paramargs: table } + +--- Command execution pipeline: after the `nodesneeded` function is called (if provided). +-- +-- See `worldeditadditions_core.run_command` +-- @event post-nodesneeded +-- @format { player_name: string, cmddef: table, paramtext: string, paramargs: table, potential_changes: number } + +--- Command execution pipeline: directly before the command is invoked. +-- +-- See `worldeditadditions_core.run_command` +-- @event pre-execute +-- @format { player_name: string, cmddef: table, paramtext: string, paramargs: table, potential_changes: number } + +--- Command execution pipeline: after the command is executed. +-- +-- See `worldeditadditions_core.run_command` +-- @event post-execute +-- @format { player_name: string, cmddef: table, paramtext: string, paramargs: table, potential_changes: number, success: boolean, result: any } + + --- Runs a command with the given name and options for the given player. +-- Emits several events in the process, in the following order: +-- 1. **`pre-parse`:** Before `paramtext` parsing but after validation. +-- 2. **`post-parse`:** Directly after `paramtext` parsing +-- 3. **`post-nodesneeded`:** If a `nodesneeded` function is provided, this executes after the nodesneeded function is called. +-- 4. **`pre-execute`:** Directly before the command is invoked. +-- 5. **`post-execute`:** After the command is executed. +-- +-- Items #4 and #5 here are actually emitted by the private internal function `run_command_stage2`. +-- +-- The event object passed has the following properties: +-- - `cmddef` (table): The WEA-registered definition of the command +-- - `cmdname` (string): The name of the command, sans-forward slashes +-- - `paramtext` (string): The unparsed `paramtext` the user passed as argument(s) to the command. +-- - `player_name` (string): The name of the player calling the command. +-- - `paramargs` (table): The parsed arguments returned by the parsing function. Available in `post-parse` and later. +-- - `potential_changes` (number): The number of potential nodes that could be changed as a result of running the command. `post-nodesneeded` and later: remember not all commands have an associated `nodesneeded` function. +-- - `success` (boolean): Whether the command executed successfully or not. Available only in `post-execute`. +-- - `result` (any): The `result` value returned by the command function. Value depends on the command executed. Available only in `post-execute`. -- @param cmdname string The name of the command to run. -- @param options table The table of options associated with the command. See worldeditadditions_core.register_command for more information. -- @param player_name string The name of the player to execute the command for. @@ -36,6 +98,15 @@ local function run_command(cmdname, options, player_name, paramtext) return false end + local tbl_event = { + cmddef = options, + cmdname = cmdname, + paramtext = paramtext, + player_name = player_name + } + + wea_c.emit("pre-parse", tbl_event) + local parse_result = { options.parse(paramtext) } local success = table.remove(parse_result, 1) if not success then @@ -43,8 +114,16 @@ local function run_command(cmdname, options, player_name, paramtext) return false end + tbl_event.paramargs = parse_result + weac.emit("post-parse", tbl_event) + + if options.nodes_needed then local potential_changes = options.nodes_needed(player_name, wea_c.table.unpack(parse_result)) + + tbl_event.potential_changes = potential_changes + wea_c.emit("post-nodesneeded", tbl_event) + if type(potential_changes) ~= "number" then worldedit.player_notify(player_name, "Error: The command '"..cmdname.."' returned a "..type(potential_changes).." instead of a number when asked how many nodes might be changed. Abort. This is a bug.") return @@ -59,13 +138,13 @@ local function run_command(cmdname, options, player_name, paramtext) elseif potential_changes > limit then worldedit.player_notify(player_name, "/"..cmdname.." "..paramtext.." may affect up to "..human_size(potential_changes).." nodes. Type //y to continue, or //n to cancel (see the //saferegion command to control when this message appears).") safe_region(player_name, cmdname, function() - run_command_stage2(player_name, options.func, parse_result) + run_command_stage2(player_name, options.func, parse_result, tbl_event) end) else - run_command_stage2(player_name, options.func, parse_result) + run_command_stage2(player_name, options.func, parse_result, tbl_event) end else - run_command_stage2(player_name, options.func, parse_result) + run_command_stage2(player_name, options.func, parse_result, tbl_event) end end diff --git a/worldeditadditions_core/init.lua b/worldeditadditions_core/init.lua index e0613cd..6274a8f 100644 --- a/worldeditadditions_core/init.lua +++ b/worldeditadditions_core/init.lua @@ -1,4 +1,5 @@ ---- WorldEditAdditions-Core +--- WorldEditAdditions core engine +-- This namespace contains the core command processing engine used by WorldEditAdditions and associated parsing, formatting, and utility functions. It does not contain any of the commands themselves - see the namespace/'mod' simply called 'worldeditadditions' for that. -- @namespace worldeditadditions_core -- @release 1.14.5 -- @copyright 2021 Starbeamrainbowlabs and VorTechnix @@ -8,7 +9,9 @@ local modpath = minetest.get_modpath("worldeditadditions_core") -worldeditadditions_core = { +local EventEmitter = dofile(modpath .. "/utils/EventEmitter.lua") + +worldeditadditions_core = EventEmitter.new({ version = "1.15-dev", modpath = modpath, registered_commands = {}, @@ -17,9 +20,9 @@ worldeditadditions_core = { safe_region_limits = {}, -- The default limit for new players on the number of potential nodes changed before safe_region kicks in. safe_region_limit_default = 100000, -} +}) local wea_c = worldeditadditions_core -wea_c.EventEmitter = dofile(modpath.."/utils/EventEmitter.lua") +wea_c.EventEmitter = EventEmitter wea_c.Set = dofile(wea_c.modpath.."/utils/set.lua") From 0561e0284509e3c38faaccd77d5de0f8ad6f158b Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Fri, 13 Sep 2024 02:54:38 +0100 Subject: [PATCH 03/17] pos_marker_manage: fix crash --- worldeditadditions_core/core/pos_marker_manage.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/worldeditadditions_core/core/pos_marker_manage.lua b/worldeditadditions_core/core/pos_marker_manage.lua index 2811439..f7e3dae 100644 --- a/worldeditadditions_core/core/pos_marker_manage.lua +++ b/worldeditadditions_core/core/pos_marker_manage.lua @@ -117,7 +117,7 @@ wea_c.entities.pos_marker:addEventListener("update_entity", function(event) ensure_player(event.player_name) if position_entities[event.player_name][event.i] == nil then - minetest.log("warning", "[wea core:pos_manage:EL/update_entity] position_entities".."["..tostring(event.player_name).."]["..tostring(event.i).."] doesnt exist, event object "..wea.inspect(event).."\nPlease check WEA is up to date and then report this in https://github.com/sbrl/Minetest-WorldEditAdditions/issues/105.") + minetest.log("warning", "[wea core:pos_manage:EL/update_entity] position_entities".."["..tostring(event.player_name).."]["..tostring(event.i).."] doesnt exist, event object "..wea_c.inspect(event).."\nPlease check WEA is up to date and then report this in https://github.com/sbrl/Minetest-WorldEditAdditions/issues/105.") end wea_c.entities.pos_marker.delete( From 48af3e3127e5d5242f623ceec3c67cd6bf45f676 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Fri, 13 Sep 2024 02:58:24 +0100 Subject: [PATCH 04/17] run_command: fix crashes ...oops, should have tested that last commit --- worldeditadditions_core/core/run_command.lua | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/worldeditadditions_core/core/run_command.lua b/worldeditadditions_core/core/run_command.lua index 9456bb7..01df9af 100644 --- a/worldeditadditions_core/core/run_command.lua +++ b/worldeditadditions_core/core/run_command.lua @@ -17,7 +17,7 @@ local human_size = wea_c.format.human_size -- @param tbl_event table Internal event table used when calling `worldeditadditions_core.emit(event_name, tbl_event)`. -- @returns nil local function run_command_stage2(player_name, func, parse_result, tbl_event) - wea_c.emit("pre-execute", tbl_event) + wea_c:emit("pre-execute", tbl_event) local success, result_message = func(player_name, wea_c.table.unpack(parse_result)) if result_message then -- TODO: If we were unsuccessful, then colour the message red @@ -26,7 +26,7 @@ local function run_command_stage2(player_name, func, parse_result, tbl_event) tbl_event.success = success tbl_event.result = result_message - wea_c.emit("post-execute", tbl_event) + wea_c:emit("post-execute", tbl_event) end --- Command execution pipeline: before `paramtext` parsing but after validation. @@ -105,7 +105,7 @@ local function run_command(cmdname, options, player_name, paramtext) player_name = player_name } - wea_c.emit("pre-parse", tbl_event) + wea_c:emit("pre-parse", tbl_event) local parse_result = { options.parse(paramtext) } local success = table.remove(parse_result, 1) @@ -115,14 +115,14 @@ local function run_command(cmdname, options, player_name, paramtext) end tbl_event.paramargs = parse_result - weac.emit("post-parse", tbl_event) + wea_c:emit("post-parse", tbl_event) if options.nodes_needed then local potential_changes = options.nodes_needed(player_name, wea_c.table.unpack(parse_result)) tbl_event.potential_changes = potential_changes - wea_c.emit("post-nodesneeded", tbl_event) + wea_c:emit("post-nodesneeded", tbl_event) if type(potential_changes) ~= "number" then worldedit.player_notify(player_name, "Error: The command '"..cmdname.."' returned a "..type(potential_changes).." instead of a number when asked how many nodes might be changed. Abort. This is a bug.") From da97890e0caa3554f5076fdab54babe4dbc18e23 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 22:13:01 +0100 Subject: [PATCH 05/17] Make weac.table* appear in API docs --- .../utils/table/deepcopy.lua | 2 ++ worldeditadditions_core/utils/table/init.lua | 3 ++- .../utils/table/makeset.lua | 5 ++++ .../utils/table/shallowcopy.lua | 3 +++ .../utils/table/table_apply.lua | 7 +++-- .../utils/table/table_contains.lua | 2 ++ .../utils/table/table_filter.lua | 3 +++ .../utils/table/table_find.lua | 26 +++++++++++++++++++ .../utils/table/table_get_last.lua | 2 ++ .../utils/table/table_map.lua | 3 +++ .../utils/table/table_reduce.lua | 5 ++-- .../utils/table/table_tostring.lua | 3 +++ .../utils/table/table_unique.lua | 5 ++++ .../utils/table/table_unpack.lua | 9 +++++++ 14 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 worldeditadditions_core/utils/table/table_find.lua diff --git a/worldeditadditions_core/utils/table/deepcopy.lua b/worldeditadditions_core/utils/table/deepcopy.lua index 0c7a89a..3353358 100644 --- a/worldeditadditions_core/utils/table/deepcopy.lua +++ b/worldeditadditions_core/utils/table/deepcopy.lua @@ -1,3 +1,5 @@ +--- +-- @module worldeditadditions_core.table -- 4. Supporting recursive structures. diff --git a/worldeditadditions_core/utils/table/init.lua b/worldeditadditions_core/utils/table/init.lua index f09829b..d55c519 100644 --- a/worldeditadditions_core/utils/table/init.lua +++ b/worldeditadditions_core/utils/table/init.lua @@ -4,9 +4,10 @@ -- ██ ██ ██ ██ ██ ██ ██ ██ -- ██ ██ ██ ██████ ███████ ███████ ███████ --- Functions that operate on tables. +--- Functions that operate on tables. -- Lua doesn't exactly come with batteries included, so this is quite an -- extensive collection of functions :P +-- @namespace worldeditadditions_core.table local wea_c = worldeditadditions_core diff --git a/worldeditadditions_core/utils/table/makeset.lua b/worldeditadditions_core/utils/table/makeset.lua index 9fb5910..7d46727 100644 --- a/worldeditadditions_core/utils/table/makeset.lua +++ b/worldeditadditions_core/utils/table/makeset.lua @@ -1,4 +1,9 @@ +--- +-- @module worldeditadditions_core.table + + --- Creates a table that stores data in keys. +-- See also `worldeditadditions_core.Set`. -- @source https://riptutorial.com/lua/example/13407/search-for-an-item-in-a-list -- @param list table The table of values to convert to keys. -- @return table The table of (key => true) pairs. diff --git a/worldeditadditions_core/utils/table/shallowcopy.lua b/worldeditadditions_core/utils/table/shallowcopy.lua index 4434749..d6e1e52 100644 --- a/worldeditadditions_core/utils/table/shallowcopy.lua +++ b/worldeditadditions_core/utils/table/shallowcopy.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Shallow clones a table. -- @source http://lua-users.org/wiki/CopyTable diff --git a/worldeditadditions_core/utils/table/table_apply.lua b/worldeditadditions_core/utils/table/table_apply.lua index 779c1d2..472cea9 100644 --- a/worldeditadditions_core/utils/table/table_apply.lua +++ b/worldeditadditions_core/utils/table/table_apply.lua @@ -1,5 +1,8 @@ ---- SHALLOW ONLY - applies the values in source to overwrite the equivalent keys in target. --- Warning: This function mutates target! +--- +-- @module worldeditadditions_core.table + +--- SHALLOW ONLY - applies the values in source to overwrite the equivalent keys in `target`. +-- Warning: This function mutates `target`! -- @param source table The source to take values from -- @param target table The target to write values to local function table_apply(source, target) diff --git a/worldeditadditions_core/utils/table/table_contains.lua b/worldeditadditions_core/utils/table/table_contains.lua index e69e7cf..71ff075 100644 --- a/worldeditadditions_core/utils/table/table_contains.lua +++ b/worldeditadditions_core/utils/table/table_contains.lua @@ -1,3 +1,5 @@ +--- +-- @module worldeditadditions_core.table --- Looks to see whether a given table contains a given value. -- @param tbl table The table to look in. diff --git a/worldeditadditions_core/utils/table/table_filter.lua b/worldeditadditions_core/utils/table/table_filter.lua index a706904..00f746e 100644 --- a/worldeditadditions_core/utils/table/table_filter.lua +++ b/worldeditadditions_core/utils/table/table_filter.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Filters the items in the given table using the given function. -- The function is executed for each item in the list. If it returns true, the -- item is kept. If it returns false, the item is discarded. diff --git a/worldeditadditions_core/utils/table/table_find.lua b/worldeditadditions_core/utils/table/table_find.lua new file mode 100644 index 0000000..2298303 --- /dev/null +++ b/worldeditadditions_core/utils/table/table_find.lua @@ -0,0 +1,26 @@ +--- +-- @module worldeditadditions_core.table + +--- Finds the first element in the given table that satisfies the given testing function. +-- A port of Javascript's `array.find` to Lua. +-- +-- Uses for .. in ipairs() under-the-hood. +-- +-- @param tbl table The table to search. +-- @param func function The testing function to call on each element. The function should return true/false as to whether the passed value passes the test function. The testing function will be provided with the following arguments: +-- 1. `value` (any): The value being inspected. +-- 2. `i` (number): The index in the table that the value can be found at +-- 3. `tbl` (table): The original table. +-- @return any|nil The first element in the table that satisfies the predicate, or nil if no such element is found. +function table_find(tbl, func) +end + +function table_find(tbl, func) + for i,value in ipairs(tbl) do + if func(value, i, tbl) then + return value + end + end +end + +return table_find \ No newline at end of file diff --git a/worldeditadditions_core/utils/table/table_get_last.lua b/worldeditadditions_core/utils/table/table_get_last.lua index f8caf69..d265897 100644 --- a/worldeditadditions_core/utils/table/table_get_last.lua +++ b/worldeditadditions_core/utils/table/table_get_last.lua @@ -2,6 +2,8 @@ local wea_c = worldeditadditions_core local table_unpack = dofile(wea_c.modpath.."/utils/table/table_unpack.lua") +--- +-- @module worldeditadditions_core.table --- Returns only the last count items in a given numerical table-based list. -- @param tbl table The table to fetch items from. diff --git a/worldeditadditions_core/utils/table/table_map.lua b/worldeditadditions_core/utils/table/table_map.lua index b0f1036..c49441b 100644 --- a/worldeditadditions_core/utils/table/table_map.lua +++ b/worldeditadditions_core/utils/table/table_map.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Executes the given function on every item in the given table. -- Ignores return values that are nil and doesn't insert them into the table. -- @param tbl table The table to operate on. diff --git a/worldeditadditions_core/utils/table/table_reduce.lua b/worldeditadditions_core/utils/table/table_reduce.lua index 3bc0bed..6499e00 100644 --- a/worldeditadditions_core/utils/table/table_reduce.lua +++ b/worldeditadditions_core/utils/table/table_reduce.lua @@ -1,6 +1,7 @@ +--- +-- @module worldeditadditions_core.table - ---- Lua implementation of array.reduce() from Javascript. +--- Lua implementation of `array.reduce()` from Javascript. -- @param tbl The table to iterate over. -- @param func The function to call for every element in tbl. Will be passed the following arguments: accumulator, value, index, table. Of course, the provided function need not take this many arguments. -- @param initial_value The initial value of the accumulator. diff --git a/worldeditadditions_core/utils/table/table_tostring.lua b/worldeditadditions_core/utils/table/table_tostring.lua index da6778e..7ee0bf5 100644 --- a/worldeditadditions_core/utils/table/table_tostring.lua +++ b/worldeditadditions_core/utils/table/table_tostring.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Returns the key value pairs in a table as a single string -- @param tbl table input table -- @param sep string key value seperator diff --git a/worldeditadditions_core/utils/table/table_unique.lua b/worldeditadditions_core/utils/table/table_unique.lua index 8dfc8ac..700f8c9 100644 --- a/worldeditadditions_core/utils/table/table_unique.lua +++ b/worldeditadditions_core/utils/table/table_unique.lua @@ -1,4 +1,9 @@ +--- +-- @module worldeditadditions_core.table + + --- Builds a new table with the elements of the given table appearing at most once. +-- See also `worldeditadditions_core.Set`. -- @param tbl table The table of values to make unique. -- @returns table A new table containing the values of the given table appearing at most once. local function table_unique(tbl) diff --git a/worldeditadditions_core/utils/table/table_unpack.lua b/worldeditadditions_core/utils/table/table_unpack.lua index cc4c643..3261b47 100644 --- a/worldeditadditions_core/utils/table/table_unpack.lua +++ b/worldeditadditions_core/utils/table/table_unpack.lua @@ -1,8 +1,17 @@ +--- +-- @module worldeditadditions_core.table + --- Polyfill for unpack / table.unpack. -- Calls unpack when available, and looks for table.unpack if unpack() isn't -- found. -- This is needed because in Lua 5.1 it's the global unpack(), but in Lua 5.4 -- it's moved to table.unpack(). +-- +-- Important: All unpack calls in WorldEditAdditions **MUST** use this function. +-- @param tbl table The table to unpack +-- @param [offset=0] number The offset at which to start unpacking. +-- @param [count=nil] number The number of items to unpack. Defaults to unpack all remaining items after `offset`. +-- @returns any... The selected items unpacked from the table. local function table_unpack(tbl, offset, count) ---@diagnostic disable-next-line: deprecated if type(unpack) == "function" then From 163f4fc0fdd37f6018a2a03ea29b81d1534546c4 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 22:51:04 +0100 Subject: [PATCH 06/17] weac.table*: fix documentation, table.find --- worldeditadditions_core/utils/table/table_apply.lua | 4 ++-- worldeditadditions_core/utils/table/table_contains.lua | 4 ++-- worldeditadditions_core/utils/table/table_filter.lua | 4 ++-- worldeditadditions_core/utils/table/table_find.lua | 7 ++----- worldeditadditions_core/utils/table/table_get_last.lua | 4 ++-- worldeditadditions_core/utils/table/table_map.lua | 4 ++-- worldeditadditions_core/utils/table/table_reduce.lua | 4 ++-- worldeditadditions_core/utils/table/table_tostring.lua | 4 ++-- worldeditadditions_core/utils/table/table_unique.lua | 4 ++-- worldeditadditions_core/utils/table/table_unpack.lua | 2 ++ 10 files changed, 20 insertions(+), 21 deletions(-) diff --git a/worldeditadditions_core/utils/table/table_apply.lua b/worldeditadditions_core/utils/table/table_apply.lua index 472cea9..97e3e9c 100644 --- a/worldeditadditions_core/utils/table/table_apply.lua +++ b/worldeditadditions_core/utils/table/table_apply.lua @@ -5,10 +5,10 @@ -- Warning: This function mutates `target`! -- @param source table The source to take values from -- @param target table The target to write values to -local function table_apply(source, target) +local function apply(source, target) for key, value in pairs(source) do target[key] = value end end -return table_apply +return apply diff --git a/worldeditadditions_core/utils/table/table_contains.lua b/worldeditadditions_core/utils/table/table_contains.lua index 71ff075..84805bc 100644 --- a/worldeditadditions_core/utils/table/table_contains.lua +++ b/worldeditadditions_core/utils/table/table_contains.lua @@ -5,11 +5,11 @@ -- @param tbl table The table to look in. -- @param target any The target to look for. -- @returns bool Whether the table contains the given target or not. -local function table_contains(tbl, target) +local function contains(tbl, target) for key, value in ipairs(tbl) do if value == target then return true end end return false end -return table_contains +return contains diff --git a/worldeditadditions_core/utils/table/table_filter.lua b/worldeditadditions_core/utils/table/table_filter.lua index 00f746e..b929c83 100644 --- a/worldeditadditions_core/utils/table/table_filter.lua +++ b/worldeditadditions_core/utils/table/table_filter.lua @@ -10,7 +10,7 @@ -- @param tbl table The table of values to filter. -- @param func function:bool The filter function to execute - should return a boolean value indicating whether the item provided as the first argument should be kept -- @returns table A new table containing the values that the given function returned true for. -local function table_filter(tbl, func) +local function filter(tbl, func) local result = {} for i,value in ipairs(tbl) do if func(value, i) then @@ -20,4 +20,4 @@ local function table_filter(tbl, func) return result end -return table_filter +return filter diff --git a/worldeditadditions_core/utils/table/table_find.lua b/worldeditadditions_core/utils/table/table_find.lua index 2298303..fc3b5b2 100644 --- a/worldeditadditions_core/utils/table/table_find.lua +++ b/worldeditadditions_core/utils/table/table_find.lua @@ -12,10 +12,7 @@ -- 2. `i` (number): The index in the table that the value can be found at -- 3. `tbl` (table): The original table. -- @return any|nil The first element in the table that satisfies the predicate, or nil if no such element is found. -function table_find(tbl, func) -end - -function table_find(tbl, func) +function find(tbl, func) for i,value in ipairs(tbl) do if func(value, i, tbl) then return value @@ -23,4 +20,4 @@ function table_find(tbl, func) end end -return table_find \ No newline at end of file +return find \ No newline at end of file diff --git a/worldeditadditions_core/utils/table/table_get_last.lua b/worldeditadditions_core/utils/table/table_get_last.lua index d265897..8de911b 100644 --- a/worldeditadditions_core/utils/table/table_get_last.lua +++ b/worldeditadditions_core/utils/table/table_get_last.lua @@ -9,11 +9,11 @@ local table_unpack = dofile(wea_c.modpath.."/utils/table/table_unpack.lua") -- @param tbl table The table to fetch items from. -- @param count number The number of items to fetch from the end of the table. -- @returns table A table containing the last count items from the given table. -local function table_get_last(tbl, count) +local function get_last(tbl, count) return {table_unpack( tbl, math.max(0, (#tbl) - (count - 1)) )} end -return table_get_last +return get_last diff --git a/worldeditadditions_core/utils/table/table_map.lua b/worldeditadditions_core/utils/table/table_map.lua index c49441b..d0dbae4 100644 --- a/worldeditadditions_core/utils/table/table_map.lua +++ b/worldeditadditions_core/utils/table/table_map.lua @@ -6,7 +6,7 @@ -- @param tbl table The table to operate on. -- @param func function:any|nil The function to execute on every item in the table. -- @returns table A new table containing the return values of the function. -local function table_map(tbl, func) +local function map(tbl, func) local result = {} for i,value in ipairs(tbl) do local newval = func(value, i) @@ -15,4 +15,4 @@ local function table_map(tbl, func) return result end -return table_map +return map diff --git a/worldeditadditions_core/utils/table/table_reduce.lua b/worldeditadditions_core/utils/table/table_reduce.lua index 6499e00..0d95399 100644 --- a/worldeditadditions_core/utils/table/table_reduce.lua +++ b/worldeditadditions_core/utils/table/table_reduce.lua @@ -5,7 +5,7 @@ -- @param tbl The table to iterate over. -- @param func The function to call for every element in tbl. Will be passed the following arguments: accumulator, value, index, table. Of course, the provided function need not take this many arguments. -- @param initial_value The initial value of the accumulator. -local function table_reduce(tbl, func, initial_value) +local function reduce(tbl, func, initial_value) local acc = initial_value for key, value in pairs(tbl) do acc = func(acc, value, key, tbl) @@ -13,4 +13,4 @@ local function table_reduce(tbl, func, initial_value) return acc end -return table_reduce +return reduce diff --git a/worldeditadditions_core/utils/table/table_tostring.lua b/worldeditadditions_core/utils/table/table_tostring.lua index 7ee0bf5..8b9df3a 100644 --- a/worldeditadditions_core/utils/table/table_tostring.lua +++ b/worldeditadditions_core/utils/table/table_tostring.lua @@ -7,7 +7,7 @@ -- @param new_line string key value pair delimiter -- @param max_depth number max recursion depth (optional) -- @return string concatenated table pairs -local function table_tostring(tbl, sep, new_line, max_depth) +local function tostring(tbl, sep, new_line, max_depth) if type(sep) ~= "string" then sep = ": " end if type(new_line) ~= "string" then new_line = ", " end if type(max_depth) == "number" then max_depth = {depth=0,max=max_depth} @@ -28,4 +28,4 @@ end -- Test: -- /lua v1 = { x= 0.335, facing= { axis= "z", sign= -1 } }; print(worldeditadditions.table.tostring(v1)) -return table_tostring +return tostring diff --git a/worldeditadditions_core/utils/table/table_unique.lua b/worldeditadditions_core/utils/table/table_unique.lua index 700f8c9..5e89a95 100644 --- a/worldeditadditions_core/utils/table/table_unique.lua +++ b/worldeditadditions_core/utils/table/table_unique.lua @@ -6,7 +6,7 @@ -- See also `worldeditadditions_core.Set`. -- @param tbl table The table of values to make unique. -- @returns table A new table containing the values of the given table appearing at most once. -local function table_unique(tbl) +local function unique(tbl) local newtbl = {} for i,value in ipairs(tbl) do local seen = false @@ -23,4 +23,4 @@ local function table_unique(tbl) return newtbl end -return table_unique +return unique diff --git a/worldeditadditions_core/utils/table/table_unpack.lua b/worldeditadditions_core/utils/table/table_unpack.lua index 3261b47..f296cd8 100644 --- a/worldeditadditions_core/utils/table/table_unpack.lua +++ b/worldeditadditions_core/utils/table/table_unpack.lua @@ -12,6 +12,8 @@ -- @param [offset=0] number The offset at which to start unpacking. -- @param [count=nil] number The number of items to unpack. Defaults to unpack all remaining items after `offset`. -- @returns any... The selected items unpacked from the table. +-- @example Lua version agnostic unpack +-- print(worldeditadditions_core.table.unpack({1 = "apple", 2 = "orange"})) local function table_unpack(tbl, offset, count) ---@diagnostic disable-next-line: deprecated if type(unpack) == "function" then From 6290c61e2f2b17c42687499bfb4b3167d64a0330 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 22:56:02 +0100 Subject: [PATCH 07/17] typo --- worldeditadditions_core/utils/rotation.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/worldeditadditions_core/utils/rotation.lua b/worldeditadditions_core/utils/rotation.lua index 1525e8f..2b11278 100644 --- a/worldeditadditions_core/utils/rotation.lua +++ b/worldeditadditions_core/utils/rotation.lua @@ -40,7 +40,7 @@ local function rotlist_compile(rotlist) end ---- Applies a given list of rotatiosn rotlist to rotate pos1 and pos2 around a given origin, and returns a pos1/pos2 pair of a region that bounds the rotated area. +--- Applies a given list of rotations rotlist to rotate pos1 and pos2 around a given origin, and returns a pos1/pos2 pair of a region that bounds the rotated area. -- The returned pos1/pos2 are guaranteed to be integer values that fully enclose the rotated region. This function is designed to be used to e.g. find the bounds of a region to pass to a VoxelManip to ensure we grab everything. -- @param pos1 Vector3 Position 1 to rotate. -- @param pos2 Vector3 Position 2 to rotate. From 0915a137f8ed9f1d7b3b4e2410543c7d0c17bb06 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 23:13:00 +0100 Subject: [PATCH 08/17] weac.table: dofile() table_find --- worldeditadditions_core/utils/table/init.lua | 1 + 1 file changed, 1 insertion(+) diff --git a/worldeditadditions_core/utils/table/init.lua b/worldeditadditions_core/utils/table/init.lua index d55c519..90a7df8 100644 --- a/worldeditadditions_core/utils/table/init.lua +++ b/worldeditadditions_core/utils/table/init.lua @@ -23,5 +23,6 @@ wea_c.table = { shallowcopy = dofile(wea_c.modpath.."/utils/table/shallowcopy.lua"), tostring = dofile(wea_c.modpath.."/utils/table/table_tostring.lua"), unique = dofile(wea_c.modpath.."/utils/table/table_unique.lua"), + find = dofile(wea_c.modpath.."/utils/table/table_find.lua"), unpack = dofile(wea_c.modpath.."/utils/table/table_unpack.lua"), } From d49f6d2131770fff94c08e0e6a589dbc38374fa9 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 23:18:37 +0100 Subject: [PATCH 09/17] Lift orientation functions from screwdriver2 mod Ref @12Me21 https://github.com/12Me21/screwdriver2/blob/master/init.lua#L75-L79 Ref @khonkhortisan https://forum.minetest.net/viewtopic.php?p=73195&sid=1d2d2e4e76ce2ef9c84646481a4b84bc#p73195 ....if either of you have an issue with this, please get in touch! The licence seems to allow this lifting and relicencing like this (given it's WTFPL as of the time of typing), but correct me if I'm wrong. For reference, WorldEditAdditions is currently licenced under the Mozilla Public License Version 2.0. --- worldeditadditions_core/init.lua | 1 + worldeditadditions_core/utils/orientation.lua | 72 +++++++++++++++++++ 2 files changed, 73 insertions(+) create mode 100644 worldeditadditions_core/utils/orientation.lua diff --git a/worldeditadditions_core/init.lua b/worldeditadditions_core/init.lua index 6274a8f..d2463ef 100644 --- a/worldeditadditions_core/init.lua +++ b/worldeditadditions_core/init.lua @@ -30,6 +30,7 @@ wea_c.Set = dofile(wea_c.modpath.."/utils/set.lua") wea_c.Vector3 = dofile(wea_c.modpath.."/utils/vector3.lua") wea_c.Mesh, wea_c.Face = dofile(wea_c.modpath.."/utils/mesh.lua") wea_c.rotation = dofile(wea_c.modpath .. "/utils/rotation.lua") +wea_c.orientation = dofile(wea_c.modpath .. "/utils/orientation.lua") wea_c.param2 = dofile(wea_c.modpath .. "/utils/param2.lua") wea_c.Queue = dofile(wea_c.modpath.."/utils/queue.lua") diff --git a/worldeditadditions_core/utils/orientation.lua b/worldeditadditions_core/utils/orientation.lua new file mode 100644 index 0000000..491670c --- /dev/null +++ b/worldeditadditions_core/utils/orientation.lua @@ -0,0 +1,72 @@ + + +-- This file is based on code from the screwdriver2 mod and a forum post on the Minetest forums. By @12Me21 and @khonkhortisan +-- Edited by @sbrl +-- Ref https://github.com/12Me21/screwdriver2/blob/master/init.lua#L75-L79 +-- Ref https://forum.minetest.net/viewtopic.php?p=73195&sid=1d2d2e4e76ce2ef9c84646481a4b84bc#p73195 + +local facedir_cycles = { + x = { { 12, 13, 14, 15 }, { 16, 19, 18, 17 }, { 0, 4, 22, 8 }, { 1, 5, 23, 9 }, { 2, 6, 20, 10 }, { 3, 7, 21, 11 } }, + y = { { 0, 1, 2, 3 }, { 20, 23, 22, 21 }, { 4, 13, 10, 19 }, { 8, 17, 6, 15 }, { 12, 9, 18, 7 }, { 16, 5, 14, 11 } }, + z = { { 4, 5, 6, 7 }, { 8, 11, 10, 9 }, { 0, 16, 20, 12 }, { 1, 17, 21, 13 }, { 2, 18, 22, 14 }, { 3, 19, 23, 15 } }, +} +local wallmounted_cycles = { + x = { 0, 4, 1, 5 }, + y = { 4, 2, 5, 3 }, + z = { 0, 3, 1, 2 }, +} + +-- We have standardised on radians for other rotation operations, so it wouldn't make sense for the API-facing functions in this file to use a number of times or degrees, as this would be inconsistent +function convert_normalise_rad(rad) + local deg = math.deg(rad) + local times = worldeditadditions_core.round(deg / 90) + return math.floor(times) -- ensure it's an integer and not e.g. a float 1.0 +end + +--- Functions to rotate a facedir/wallmounted value around an axis by a certain amount +-- +-- Code lifted from @12Me21 and @khonkhortisan +-- +-- Ref and +-- @namespace worldeditadditions_core.orientation +local orientation = { + --- Facedir: lower 5 bits used for direction, 0 - 23 + -- @param param2 number `param2` value to rotate. + -- @param axis string The name of the axis to rotate around. Valid values: `x`, `y`, `z` + -- @param amount The number of radians to rotate around the given `axis`. Only right angles are supported (i.e. 90° increments). Any value that isn't a 90° increment will be **rounded**! + -- @returns number A new param2 value that is rotated the given number of degrees around the given `axis` + facedir = function(param2, axis, amount_rad) + local amount = convert_normalise_rad(amount_rad) + print("DEBUG:core/orientation:facedir AMOUNT rad "..tostring(amount_rad).." norm "..tostring(amount)) + local facedir = param2 % 32 + for _, cycle in ipairs(facedir_cycles[axis]) do + -- Find the current facedir + -- Minetest adds table.indexof, but I refuse to use it because it returns -1 rather than nil + for i, fd in ipairs(cycle) do + if fd == facedir then + return param2 - facedir + cycle[1 + (i - 1 + amount) % 4] -- If only Lua didn't use 1 indexing... + end + end + end + return param2 + end, + -- Wallmounted: lower 3 bits used, 0 - 5 + wallmounted = function(param2, axis, amount_rad) + local amount = convert_normalise_rad(amount_rad) + print("DEBUG:core/orientation:wallmounted AMOUNT rad " .. tostring(amount_rad) .. " norm " .. tostring(amount)) + + local wallmounted = param2 % 8 + for i, wm in ipairs(wallmounted_cycles[axis]) do + if wm == wallmounted then + return param2 - wallmounted + wallmounted_cycles[axis][1 + (i - 1 + amount) % 4] + end + end + return param2 + end +} +-- From the original codebase (linked above): +--orientation.colorfacedir = orientation.facedir +--orientation.colorwallmounted = orientation.wallmounted +-- ...we'll need to know this later + +return orientation From d29b0376759210e13025eeccaefcefd0f286c463 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 23:23:09 +0100 Subject: [PATCH 10/17] orientation: refactor a bit, docs --- worldeditadditions_core/utils/orientation.lua | 79 +++++++++++-------- 1 file changed, 44 insertions(+), 35 deletions(-) diff --git a/worldeditadditions_core/utils/orientation.lua b/worldeditadditions_core/utils/orientation.lua index 491670c..18cf72c 100644 --- a/worldeditadditions_core/utils/orientation.lua +++ b/worldeditadditions_core/utils/orientation.lua @@ -29,44 +29,53 @@ end -- -- Ref and -- @namespace worldeditadditions_core.orientation -local orientation = { - --- Facedir: lower 5 bits used for direction, 0 - 23 - -- @param param2 number `param2` value to rotate. - -- @param axis string The name of the axis to rotate around. Valid values: `x`, `y`, `z` - -- @param amount The number of radians to rotate around the given `axis`. Only right angles are supported (i.e. 90° increments). Any value that isn't a 90° increment will be **rounded**! - -- @returns number A new param2 value that is rotated the given number of degrees around the given `axis` - facedir = function(param2, axis, amount_rad) - local amount = convert_normalise_rad(amount_rad) - print("DEBUG:core/orientation:facedir AMOUNT rad "..tostring(amount_rad).." norm "..tostring(amount)) - local facedir = param2 % 32 - for _, cycle in ipairs(facedir_cycles[axis]) do - -- Find the current facedir - -- Minetest adds table.indexof, but I refuse to use it because it returns -1 rather than nil - for i, fd in ipairs(cycle) do - if fd == facedir then - return param2 - facedir + cycle[1 + (i - 1 + amount) % 4] -- If only Lua didn't use 1 indexing... - end + +--- Facedir: lower 5 bits used for direction, 0 - 23 +-- @param param2 number `param2` value to rotate. +-- @param axis string The name of the axis to rotate around. Valid values: `x`, `y`, `z` +-- @param amount The number of radians to rotate around the given `axis`. Only right angles are supported (i.e. 90° increments). Any value that isn't a 90° increment will be **rounded**! +-- @returns number A new param2 value that is rotated the given number of degrees around the given `axis` +function facedir(param2, axis, amount_rad) + local amount = convert_normalise_rad(amount_rad) + print("DEBUG:core/orientation:facedir AMOUNT rad "..tostring(amount_rad).." norm "..tostring(amount)) + local facedir = param2 % 32 + for _, cycle in ipairs(facedir_cycles[axis]) do + -- Find the current facedir + -- Minetest adds table.indexof, but I refuse to use it because it returns -1 rather than nil + for i, fd in ipairs(cycle) do + if fd == facedir then + return param2 - facedir + cycle[1 + (i - 1 + amount) % 4] -- If only Lua didn't use 1 indexing... end end - return param2 - end, - -- Wallmounted: lower 3 bits used, 0 - 5 - wallmounted = function(param2, axis, amount_rad) - local amount = convert_normalise_rad(amount_rad) - print("DEBUG:core/orientation:wallmounted AMOUNT rad " .. tostring(amount_rad) .. " norm " .. tostring(amount)) - - local wallmounted = param2 % 8 - for i, wm in ipairs(wallmounted_cycles[axis]) do - if wm == wallmounted then - return param2 - wallmounted + wallmounted_cycles[axis][1 + (i - 1 + amount) % 4] - end - end - return param2 end + return param2 +end + +--- Wallmounted: lower 3 bits used, 0 - 5 +-- @param param2 number `param2` value to rotate. +-- @param axis string The name of the axis to rotate around. Valid values: `x`, `y`, `z` +-- @param amount The number of radians to rotate around the given `axis`. Only right angles are supported (i.e. 90° increments). Any value that isn't a 90° increment will be **rounded**! +-- @returns number A new param2 value that is rotated the given number of degrees around the given `axis` +function wallmounted(param2, axis, amount_rad) + local amount = convert_normalise_rad(amount_rad) + print("DEBUG:core/orientation:wallmounted AMOUNT rad " .. tostring(amount_rad) .. " norm " .. tostring(amount)) + + local wallmounted = param2 % 8 + for i, wm in ipairs(wallmounted_cycles[axis]) do + if wm == wallmounted then + return param2 - wallmounted + wallmounted_cycles[axis][1 + (i - 1 + amount) % 4] + end + end + return param2 +end + +local orientation = { + facedir = facedir, + wallmounted = wallmounted, + -- From the original codebase (linked above): + --colorfacedir = facedir, + --colorwallmounted = wallmounted + -- ...we'll need to know this later } --- From the original codebase (linked above): ---orientation.colorfacedir = orientation.facedir ---orientation.colorwallmounted = orientation.wallmounted --- ...we'll need to know this later return orientation From d78730912794e55e5abbc77e3f8ae6dc011a094b Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 23:25:43 +0100 Subject: [PATCH 11/17] copy, move: add TODO ref being node metadata-aware --- worldeditadditions/lib/copy.lua | 1 + worldeditadditions/lib/move.lua | 2 ++ 2 files changed, 3 insertions(+) diff --git a/worldeditadditions/lib/copy.lua b/worldeditadditions/lib/copy.lua index 33eb39a..d736b28 100644 --- a/worldeditadditions/lib/copy.lua +++ b/worldeditadditions/lib/copy.lua @@ -4,6 +4,7 @@ local Vector3 = wea_c.Vector3 --- -- @module worldeditadditions +-- TODO add `minetest.find_nodes_with_meta(pos1, pos2)` support ref https://github.com/minetest/minetest/blob/5.9.1/doc/lua_api.md?plain=1#L6112 for locked chests, inventories etc. Perhaps for copy add a flag to allow for disabling such support? -- ██████ ██████ ██████ ██ ██ -- ██ ██ ██ ██ ██ ██ ██ diff --git a/worldeditadditions/lib/move.lua b/worldeditadditions/lib/move.lua index 1a06242..32387d1 100644 --- a/worldeditadditions/lib/move.lua +++ b/worldeditadditions/lib/move.lua @@ -5,6 +5,8 @@ local Vector3 = wea_c.Vector3 --- -- @module worldeditadditions +-- TODO add `minetest.find_nodes_with_meta(pos1, pos2)` support ref https://github.com/minetest/minetest/blob/5.9.1/doc/lua_api.md?plain=1#L6112 for locked chests, inventories etc. Perhaps for copy add a flag to allow for disabling such support? + -- ███ ███ ██████ ██ ██ ███████ -- ████ ████ ██ ██ ██ ██ ██ -- ██ ████ ██ ██ ██ ██ ██ █████ From 51d3e0a23e3788223c6ae6f9140ba916ffd7698a Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Wed, 18 Sep 2024 00:37:03 +0100 Subject: [PATCH 12/17] CONTRIBUTING.md: add Lua API link; minor update ...we need to overhaul this with a *bunch* more detail --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e70f4d..791815c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,14 @@ Hey there! So you like WorldEditAdditions enough to consider helping out? That's awesome! This guide should get you up and running in no time. +**Lua API documentation:** ## Code structure The WorldEditAdditions codebase is split into 3 main submods: Name | Description --------------------------------|------------------------ -`worldeditadditions` | The main mod. Core world manipulation implementations should go in here. +`worldeditadditions` | The main mod. Core world manipulation implementations (backed by the `*_core` mod ref core and utility functions) should go in here. `worldeditadditions_commands` | Chat commands. These interact with the core manipulators in `worldeditadditions` mod. `worldeditadditions_farwand` | Everything to do with the far wand tool, and now other tools like the cloud wand, multi-point wand, etc. It's different enough to everything else that it warrants it's own separate mod to avoid muddling things. `worldeditadditions_core` | Core components such as the positioning system (`worldeditadditions_core.pos`), the command registration function, and utility functions go in here. From 8f84188653e6fdff9e373c57b198d7a8b1115056 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Wed, 18 Sep 2024 00:37:35 +0100 Subject: [PATCH 13/17] API.md: create a convenient file for those looking for documentation, as it's a well-known name --- API.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..8a8bd5d --- /dev/null +++ b/API.md @@ -0,0 +1,36 @@ +# API Reference +This file exists to give people looking for it convenient access to the various types of documentation WorldEditAdditions (WEA) provides. + + +## I'm a user of WorldEditAdditions +If you're using WEA in-game, you probably want the chat command reference: + + - [Interactive Chat Command Reference](https://worldeditadditions.mooncarrot.space/Reference/) + - [Source file for the above in the git repository](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md) + +Remember: *Documentation, not code, defines what a program does.* + +In other words, if the documentation ain't right, [open an issue](https://github.com/sbrl/Minetest-WorldEditAdditions/issues/new)! + + +## I'm a mod developer and I want to hook into WorldEditAdditions +That's awesome! WEA provides an extensive library of node and region manipulation functions. It also provides a significantly extensive library of utility functions - many of which Lua should provide built-in like Javascript. + + - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/) + +The Lua API reference is built automatically from code comments using [moondoc](https://github.com/sbrl/moondoc). These code comments have been curated and written to ensure the docs are as detailed as possible. This is an ongoing process however, so if there are any issues with these docs, please get in touch. + +## I want to hack on WorldEditAdditions! +Yay, we always love new people around here! Do see our Lua API docs and our contributing guide: + + - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/) + - [Contributing Guide](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/dev/CONTRIBUTING.md) + - [Discord server](https://discord.gg/FzD73kuhsk) + +We also have a dedicated channel to development questions and chatter in our Discord server. + +## I want to do something else! +Interesting! Do get in touch, as we'd love to hear about it: + + - [GitHub discussion board](https://github.com/sbrl/Minetest-WorldEditAdditions/discussions) + - [Discord server](https://discord.gg/FzD73kuhsk) From 67701f36bc7ef9917ec7f908130a8b290b3d3641 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Wed, 18 Sep 2024 01:14:28 +0100 Subject: [PATCH 14/17] README: add links, update quick reference --- README.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 992fb54..2902c3a 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,8 @@ _(Do you have a cool build that you used WorldEditAdditions to build? [Get in to - [Quick Command Reference](#quick-command-reference) (including links to detailed explanations) - [Using the Far Wand](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#far-wand) - [Using the Cloud Wand](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#cloud-wand) - - [Detailed Chat Command Explanations](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md) + - [Interactive Chat Command Reference](https://worldeditadditions.mooncarrot.space/Reference/) ([git](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md)) + - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/) - [Chat Command Cookbook](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Cookbook.md) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) @@ -27,6 +28,9 @@ _(Do you have a cool build that you used WorldEditAdditions to build? [Get in to ## Quick Command Reference The detailed explanations have moved! Check them out [here](https://worldeditadditions.mooncarrot.space/Reference/) (or edit at [Chat-Command-Reference.md](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md)), or click the links below. +- **Full chat command reference:** +- **Lua API documentation** (for mod developers and hackers)**:** + ### Geometry - [`//spline [ []]`](https://worldeditadditions.mooncarrot.space/Reference/#spline) - [`//dome+ [ ...] [h[ollow]]`](https://worldeditadditions.mooncarrot.space/Reference/#dome) @@ -47,9 +51,11 @@ The detailed explanations have moved! Check them out [here](https://worldeditadd - [`//wcorner `](https://worldeditadditions.mooncarrot.space/Reference/#wcorner) ### Misc + - [`//rotate+ [ ...] [origin|o []]`](https://worldeditadditions.mooncarrot.space/Reference/#rotate) _(new in v1.15)_ - [`//revolve []`](https://worldeditadditions.mooncarrot.space/Reference/#revolve) - [`//copy+ [ [...]]`](https://worldeditadditions.mooncarrot.space/Reference/#copy) - [`//move+ [ [...]]`](https://worldeditadditions.mooncarrot.space/Reference/#move) + - [`//set+ [param|param2|p2|light|l] `](https://worldeditadditions.mooncarrot.space/Reference/#set) _(new in v1.15)_ - [`//replacemix [] [] [ []] [ []] ....`](https://worldeditadditions.mooncarrot.space/Reference/#replacemix) - [`//floodfill [ []]`](https://worldeditadditions.mooncarrot.space/Reference/#floodfill) - [`//scale | [ [ ]]`](https://worldeditadditions.mooncarrot.space/Reference/#scale) **experimental** @@ -72,7 +78,8 @@ The detailed explanations have moved! Check them out [here](https://worldeditadd ### Statistics - [`//count`](https://worldeditadditions.mooncarrot.space/Reference/#count) - [`//basename `](https://worldeditadditions.mooncarrot.space/Reference/#basename) - - [`//ngroups [v[erbose]]`](https://worldeditadditions.mooncarrot.space/Reference/#ngroups) + - [`//ngroups [v[erbose]]`](https://worldeditadditions.mooncarrot.space/Reference/#ngroups) _(new in v1.15)_ + - [`//ndef `](https://worldeditadditions.mooncarrot.space/Reference/#ndef) _(new in v1.15)_ ### Selection - [`//scol [ ] `](https://worldeditadditions.mooncarrot.space/Reference/#scol) @@ -113,6 +120,7 @@ The detailed explanations have moved! Check them out [here](https://worldeditadd ### Extras - [`//y`](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#y) - [`//n`](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#n) + - [`//speed []`](https://worldeditadditions.mooncarrot.space/Reference/#speed) _(new in v1.15)_ ### Tools - [WorldEditAdditions Far Wand](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#far-wand) @@ -191,12 +199,20 @@ The new positioning system now rectifies this issue with the region marker walls If this is not showing for you, please update WorldEditAdditions and try again. +### Where's the documentation? +As linked above: + + - [Interactive Chat Command Reference](https://worldeditadditions.mooncarrot.space/Reference/) ([git](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md)) + - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/) (built with [moondoc](https://github.com/sbrl/moondoc)) + ## Contributing Contributions are welcome! Please state in your pull request(s) that you release your contribution under the _Mozilla Public License 2.0_. Please also make sure that the logic for every new command has it's own file. For example, the logic for `//floodfill` goes in `worldeditadditions/floodfill.lua`, the logic for `//overlay` goes in `worldeditadditions/overlay.lua`, etc. More contributing help can be found in [the contributing guide](CONTRIBUTING.md). +**Lua API Documentation:** + ### Inspiration Want to contribute, but finding it tough to find inspiration of what to implement? Here are some great places to look: @@ -205,7 +221,7 @@ Want to contribute, but finding it tough to find inspiration of what to implemen - WorldEdit for Minecraft - VoxelSniper(-Reimagined) for Minecraft - WorldPainter for Minecraft - - Axiom + - Axiom for Minecraft - **Do some building:** When you put WorldEditAdditions to use in building projects of your own, things will absolutely stand out to you what you want in the creative building process that WorldEditAdditions doesn't yet have. - **Watch others build stuff:** Doesn't even have to be Minetest! There are lots of talented Minecraft builders with videos and series on e.g. YouTube. From their creative building processes, many ideas can be derived. From fbd32a1df96c6b7bfeb2d9df3d147980a43d5283 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Wed, 18 Sep 2024 01:15:05 +0100 Subject: [PATCH 15/17] chat command reference: add *Added in * quotes; document //set+ --- Chat-Command-Reference.md | 169 +++++++++++++++++++++++++++++++++++++- 1 file changed, 165 insertions(+), 4 deletions(-) diff --git a/Chat-Command-Reference.md b/Chat-Command-Reference.md index 1256280..5bc1981 100644 --- a/Chat-Command-Reference.md +++ b/Chat-Command-Reference.md @@ -23,6 +23,8 @@ Other useful links: --> ### `//metaball add | remove | render [] | list | clear | volume` +> Added in v1.14 + Draws two or more [metaballs](https://en.wikipedia.org/wiki/Metaballs). Based on a subcommand system, since each metaball may have a different radius. Calling `//metaball render ` actually makes changes to the world - all others manipulate an internal player-local list of metaballs to be drawn. @@ -111,6 +113,8 @@ Creates a hollow ellipsoid at position 1 with the radius `(rx, ry, rz)`. Works t ``` ### `//ellipsoid2 [ [h[ollow]]]` +> Added in v1.13 + Creates an (optionally hollow) solid ellipsoid that fills the defined region. ```weacmd @@ -145,6 +149,8 @@ Creates a hollow torus at position 1 with the radius major and minor radii. Work ``` ### `//line [ []]` +> Added in v1.10 + Draw a line from position 1 to position 2, optionally with a given thickness. The radius can be thought of as the thickness of the line, and is defined as the distance from a given node to an imaginary line from pos1 to pos2. Defaults to drawing with dirt and a radius of 1. @@ -159,6 +165,8 @@ Floating-point values are fully supported for the radius. ``` ### `//hollow []` +> Added in v1.11 + Replaces nodes inside the defined region with air, but leaving a given number of nodes near the outermost edges alone. In other words, it makes the defined region hollow, while leaving walls around the edges of a given thickness (defaulting to a wall thickness of 1). Note that all air-like nodes are also left alone. @@ -230,6 +238,8 @@ Creates vertical walls of `` around the inside edges of the define ### `//spiral2 [] [ [ [] ] ]` +> Added in v1.13 + Generates both square and circular spiral shapes with the given `` - defaulting to square spirals. The interval defines the gap between the spiral in nodes, and the acceleration defines by how much the interval should be increased (a value of 1 means 1 node per revolution). ``` @@ -243,6 +253,8 @@ Generates both square and circular spiral shapes with the given `` ### `//dome+ [ ...] [h[ollow]]` +> Added in v1.14 + Creates a dome shape (i.e. a hemisphere; half a sphere) with a specified radius of the defined node, optionally specifying the direction it should be pointing in (defaults to the positive y direction). For example, `//dome+ 5 stone y` creates a dome shape pointing upwards, but `//dome+ 5 stone -y` creates a dome shape pointing downwards. @@ -260,6 +272,8 @@ If `h` or `hollow` is specified at the end, then the resulting dome shape is mad ### `//spline [ []]` +> Added in v1.14 + Draws a curved line, using all the currently defined points as control points. The starting and ending widths of the line can be controlled, and the width will be linearly interpolated. **Note:** `//spline` uses the **new** WorldEditAdditions positions! Use the [multipoint wand](#multi-point-wand) to define the control points for the resulting line. @@ -285,6 +299,8 @@ For those interested, WorldEditAdditions uses the [chaikin curve algorithm](http ### `//rotate+ [ ...] [origin|o []]` +> Added in v1.15 + Rotates the defined region using the specified list of rotation operations, optionally around the defined rotation origin. For example, the following: ```weacmd @@ -339,6 +355,8 @@ Floods all connected nodes of the same type starting at _pos1_ with `` +> Added in v1.13 + Sets the edges of the current selection to ``to create an outline of a rectangular prism. Useful for roughing in walls. In other words, creates a wireframe of a box defined by the current selection. @@ -349,6 +367,8 @@ In other words, creates a wireframe of a box defined by the current selection. ``` ### `//wcompass []` +> Added in v1.13 + Creates a compass around pos1 with a single node bead pointing north (+Z). ```weacmd @@ -358,6 +378,8 @@ Creates a compass around pos1 with a single node bead pointing north (+Z). ``` ### `//wcorner ` +> Added in v1.13 + Set the corners of the current selection to ``. Useful for outlining building sites and setting boundaries. ```weacmd @@ -366,6 +388,8 @@ Set the corners of the current selection to ``. Useful for outlini ``` ### `//scale | [ [ ` +> Added in v1.11 + Advanced version of [`//stretch` from WorldEdit](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#stretch-stretchx-stretchy-stretchz) that can scale both up and down at the same time by transparently splitting it into 2 different operations. Scaling up is *always* done before scaling down. Although the syntax looks complicated, it's really quite simple. The key concept to understand is that of the scale factor. It refers to how much the defined region should be scaled up or down by, and can be specified in multiple different ways: @@ -449,6 +473,8 @@ So in the above example, we scale in the positive x and z directions, and the ne ### `//copy+ [ [...]] [aa|airapply]` +> Added in v1.13; param2 support added in v1.14 + Fully backwards-compatible with `//copy` from regular WorldEdit, but allows you to specify multiple axes at once in a single copy operation. Each successive axis in the list is specified in the form ` `, where: - `` is the name of the axis to move the defined region along @@ -487,6 +513,8 @@ Finally, if the word `airapply` (or `aa` for short) is present at the end of the ### `//move+ [ [...]] [aa|airapply]` +> Added in v1.13; param2 support added in v1.14 + Identical to [`//copy+`](#copy), but instead moves the defined region instead of copying it. Note that the integrated `airapply` (`aa` for short) also works as in [`//copy+`](#copy), but remember that if a given target node is not *not* air-like and the integrated `airapply` mode is enabled, the source node is still moved from the source, but destroyed because it is can't be set at the target. @@ -505,6 +533,39 @@ Note that the integrated `airapply` (`aa` for short) also works as in [`//copy+` ``` +### `//set+ [param|param2|p2|light|l] ` +Sets the node, param2, or light level to a fixed value in the defined region. Defaults to setting the node. If `param2`/`p2` is specified, the param2 value associated with nodes is set instead. If `light`/`l` is specified, the light level is set. + +For example, the follow will set the node for every block in the currently defined region: + +```weacmd +//set+ stone +//set+ glass +``` + +See also [`//replacemix`](#replacemix), which extends the simple set functionality implemented in this command with a powerful chance-based find-and-replace system. + +See also [`//nodeapply`](#nodeapply), which implements a wrapper around most WorldEditAdditions commands that filters changes made within the defined region to those affecting a defined set of nodes or nodes with the given group name. + +The following examples set param2 for all blocks in the defined region to a given value: + +```weacmd +//set+ param2 34 +//set+ p2 2 +//set+ param2 0 +``` + +...finally, the following examples set the light level for all blocks within the currently defined region: + +```weacmd +//set+ light 3 +//set+ l 10 +//set+ light 15 +``` + +At an indeterminate point in the future, `//set` may be aliased to this command.Your feedback is valuable on this topic as no decision has yet been reached, so please do start a conversation in our Discord server ([link here on the website homepage](https://worldeditadditions.mooncarrot.space/)) or on the [GitHub discussion board](https://github.com/sbrl/Minetest-WorldEditAdditions/discussions). + + ### `//replacemix [] [] [ []] [ []] ...` Replaces a given node with a random mix of other nodes. Functions like `//mix`. @@ -564,6 +625,8 @@ Here are all the above examples together: ### `//revolve []` +> Added in v1.14 + Makes a given number of copies of the currently defined region (bounded by pos1 and pos2) at a given number of equally spaced points rotated around a given pivot/origin point. For example, `//revolve 4` would make rotated copies of the currently defined region at intervals 0° (the source to copy), 90°, 180°, and 270° around the given pivot point. @@ -587,6 +650,8 @@ For example, `//revolve 4` would make rotated copies of the currently defined re ### `//convolve [[,]] []` +> Added in v1.7 + Advanced version of `//smooth` from we_env, and one of the few WorldEditAdditions commands to have any aliases (`//smoothadv` and `//conv`). Extracts a heightmap from the defined region and then proceeds to [convolve](https://en.wikipedia.org/wiki/Kernel_(image_processing)) over it with the specified kernel. The kernel can be thought of as the filter that will be applied to the heightmap. Once done, the newly convolved heightmap is applied to the terrain. @@ -636,6 +701,8 @@ Note also that columns without any air nodes in them at all are also skipped, so ### `//fillcaves []` +> Added in v1.9 + Fills in all airlike nodes beneath non airlike nodes, which gives the effect of filling in caves. Defaults to filling in with stone, but this can be customised. Note that the *entire* cave you want filling must be selected, as `//fillcaves` only operates within the defined region (ref #50). @@ -649,6 +716,8 @@ Note that the *entire* cave you want filling must be selected, as `//fillcaves` ### `//layers [] [ []] [ []] ...` +> Added in v1.7 + Finds the first non-air node in each column and works downwards, replacing non-air nodes with a defined list of nodes in sequence. Like WorldEdit for Minecraft's `//naturalize` command, and also similar to [`we_env`'s `//populate`](https://github.com/sfan5/we_env). Speaking of, this command has `//naturalise` and `//naturalize` as aliases. Defaults to 1 layer of grass followed by 3 layers of dirt. Since WorldEditAdditions v1.13, a maximum and minimum slope is optionally accepted, and constrains the columns in the defined region that `//layers` will operate on. For example, specifying a value of `20` would mean that only columns with a slop less than or equal to 20° (degrees, not radians) will be operated on. A value of `45..60` would mean that only columns with a slope between 45° and 60° will be operated on. @@ -667,6 +736,8 @@ The list of nodes has a form similar to that of a chance list you might find in ### `//erode [ [ []] [ []] ...]` +> Added in v1.9 + Runs an erosion algorithm over the defined region, optionally passing a number of key - value pairs representing parameters that are passed to the chosen algorithm. This command is **experimental**, as the author is currently on-the-fence about the effects it produces. Works best if you run `//fillcaves` first, or otherwise have no air nodes below the top non-air node in each column. @@ -735,6 +806,8 @@ Usage examples: ### `//noise2d [ []] [ []] ...]` +> Added in v1.13 + Applies 2D noise to the terrain in the defined region. Like `//erode`, this command accepts a number of different key-value parameters and provides a number of different underlying algorithms. In other words, this command changes the height of the terrain according to some noise function (e.g. Perlin noise): @@ -826,6 +899,8 @@ Example invocations: ### `//sculptlist [preview]` +> Added in v1.13 + Lists all the available sculpting brushes for use with `//sculpt`. If the `preview` keyword is specified as an argument, then the brushes are also rendered in ASCII as a preview. See [`//sculpt`](#sculpt). ``` @@ -835,6 +910,8 @@ Lists all the available sculpting brushes for use with `//sculpt`. If the `previ ### `//sculpt [ [ []]]` +> Added in v1.13 + Applies a specified brush to the terrain at position 1 with a given height and a given size. Multiple brushes exist (see [`//sculptlist`](#sculptlist)) - and are represented as a 2D grid of values between 0 and 1, which are then scaled to the specified height. The terrain around position 1 is first converted to a 2D heightmap (as in [`//convolve`](#convolve) before the brush "heightmap" is applied to it. Similar to [`//sphere`](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#sphere-radius-node), [`//cubeapply 10 set`](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#cubeapply-sizesizex-sizey-sizez-command-parameters), or [`//cylinder y 5 10 10 dirt`](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#cylinder-xyz-length-radius1-radius2-node) (all from [WorldEdit](https://content.minetest.net/packages/sfan5/worldedit/)), but has a number of added advantages: @@ -898,6 +975,8 @@ To contribute your new brush back, you can either [open a pull request](https:// ### `//forest [] [] [] [ []] ...` +> Added in v1.9 + Plants and grows saplings to generate a forest. A density value is optionally taken, which controls the overall density of the forest that is generated. The `bonemeal` mod is required - just like for the [`//bonemeal`](#bonemeal-strength-chance) command. The density defaults to 1, acts like a multiplier, and is not affected by the chances of all saplings listed (e.g. you can have a sapling with a chance of 1-in-50, and the overall density of the forest will be unaffected). For example, 2 results in a forest twice as dense as the default, and 0.5 a forest half as dense as the default density. @@ -1013,6 +1092,8 @@ Returns the absolute canonical name of a node, given an alias or partial node na ### `//ngroups [v[erbose]]` +> Added in v1.15 + Lists the groups that a given node is a member of. For example: ```weacmd @@ -1048,6 +1129,8 @@ Finally, the customary misc examples: ``` ### `//ndef ` +> Added in v1.15 + Short for *Node Definition*. Prints the definition table for the node with the given name. In other words. the output could look a little like this: ``` @@ -1130,6 +1213,8 @@ This command is intended for debugging and development purposes, but if you're i --> ### `//unmark` +> First overridden in v1.14 + Hides the in-game UI that indicates where the current positions and region are located. This hides both the WorldEditAdditions *and* the WorldEdit UI if displayed, but does **not** change or remove any points that are registered. @@ -1141,6 +1226,8 @@ Should more than 2 points be defined, they are all hidden. ``` ### `//mark` +> WorldEditAdditions-native version first implemented in v1.14 + Shows the in-game UI that indicates where the current positions and region are located once more. Should more than 2 points be defined, they are all shown once more. @@ -1153,28 +1240,34 @@ Often used after calling [`//unmark`](#unmark) ### `//pos1` +> WorldEditAdditions-native version first implemented in v1.14 + +**Aliases:** `//1` + Sets pos1 to the location of the calling player. This is, as with all other WorldEditAdditions commands, seamlessly synchronised with WorldEdit, allowing you to use any combination of WorldEditAdditions and WorldEdit commands and tools without them desynchronising from one another. -**Aliases:** `//1` - ```weacmd //pos2 ``` ### `//pos2` +> WorldEditAdditions-native version first implemented in v1.14 + +**Aliases:** `//2` + Sets pos1 to the location of the calling player. This is, as with all other WorldEditAdditions commands, seamlessly synchronised with WorldEdit, allowing you to use any combination of WorldEditAdditions and WorldEdit commands and tools without them desynchronising from one another. -**Aliases:** `//2` - ```weacmd //pos2 ``` ### `//pos ` +> Added in v1.14 + Sets position with the given index `` to the location of the calling player. Should the index be less than or equal to 2, then as with all other WorldEditAdditions commands, seamlessly synchronised with WorldEdit, allowing you to use any combination of WorldEditAdditions and WorldEdit commands and tools without them desynchronising from one another. @@ -1191,6 +1284,8 @@ If no index is specified, an error is returned and nothing is done. ``` ### `//reset` +> WorldEditAdditions-native version first implemented in v1.14 + Clears all positions defined and the defined region. This also synchronises with WorldEdit, as all other WorldEditAdditions commands do. @@ -1201,6 +1296,13 @@ This also synchronises with WorldEdit, as all other WorldEditAdditions commands ### `//scol [ ] ` +> Added in v1.12 + +> [!WARNING] +> This command has been deprecated in v1.15 in favour of [`//srel`](#srel). +> +> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not. + Short for _select column_. Sets the pos2 at a set distance along 1 axis from pos1. If the axis isn't specified, defaults the direction you are facing. Implementation thanks to @VorTechnix. ```weacmd @@ -1210,6 +1312,13 @@ Short for _select column_. Sets the pos2 at a set distance along 1 axis from pos ### `//srect [ []] ` +> Added in v1.12; deprecated in favour of [`//srel`](#srel) in v1.15 + +> [!WARNING] +> This command has been deprecated in v1.15 in favour of [`//srel`](#srel). +> +> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not. + Short for _select rectangle_. Sets the pos2 at a set distance along 2 axes from pos1. If the axes aren't specified, defaults to positive y and the direction you are facing. Implementation thanks to @VorTechnix. ```weacmd @@ -1220,6 +1329,13 @@ Short for _select rectangle_. Sets the pos2 at a set distance along 2 axes from ### `//scube [ [ []]] ` +> Added in v1.12 + +> [!WARNING] +> This command has been deprecated in v1.15 in favour of [`//srel`](#srel). +> +> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not. + Short for _select cube_. Sets the pos2 at a set distance along 3 axes from pos1. If the axes aren't specified, defaults to positive y, the direction you are facing and the axis to the left of facing. Implementation thanks to @VorTechnix. ```weacmd @@ -1231,6 +1347,8 @@ Short for _select cube_. Sets the pos2 at a set distance along 3 axes from pos1. ### `//scloud <0-6|stop|reset>` +> Added in v1.12 + Short for _select point cloud_. Sets pos1 and pos2 to include the nodes you punch. Numbers 1-6 designate how many nodes you want to punch before the operation ends. 0 or stop terminate the operation so that any further nodes you punch won't be added to selection. Reset terminates operation if one is running and resets the selection area. ```weacmd @@ -1258,6 +1376,8 @@ Short for _select relative_. Sets the pos2 at set distances along 3 axes relativ ``` ### `//sshift [ [ ]]` +> Added in v1.13 + Short for _selection shift_. Shifts the WorldEdit region along 3 axes. The axis arguments accept `x, y, z` as well as `up, down, left, right, front, back`. Left, right, front and back are relative to player facing direction. Negative (`-`) can be applied to the axis, the length or both. Implementation thanks to @VorTechnix. ```weacmd @@ -1268,6 +1388,8 @@ Short for _selection shift_. Shifts the WorldEdit region along 3 axes. The axis ``` ### `//smake [ []]` +> Added in v1.12 + Short for _selection make_. Modifies existing selection by moving pos2. Allows you to make the selection an odd or even length on one or more axes or set two or more axes equal to each other or the longest, shortest or average of them. Implementation thanks to @VorTechnix. Usage examples: @@ -1317,6 +1439,13 @@ Name | Description ``: If `` == equal | Overrides `` and sets all `` axes equal to itself ### `//sfactor []` +> Added in v1.13 + +> [!WARNING] +> This command has been deprecated in v1.15 in favour of [`//srel`](#srel). +> +> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not. + Short for _selection factor_; alias: `//sfac`. Built specifically for use with `//maze`, this command sets targeted axes equal to the nearest multiple of `` based on the ``. Usage examples: @@ -1335,6 +1464,8 @@ Value | Description `average`/`avg` | Takes the average of all axes specified in `` and then for each specified axis grows or shrinks it, depending on whether it is less than or greater than the average, to the nearest multiple of `` ### `//sstack` +> Added in v1.12 + Displays the contents of your per-user selection stack. This stack can be pushed to and popped from rather like a stack of plates. See also `//spush` (for pushing to the selection stack) and `//spop` (for popping from the selection stack). ```weacmd @@ -1342,6 +1473,8 @@ Displays the contents of your per-user selection stack. This stack can be pushed ``` ### `//spush` +> Added in v1.12 + Pushes the currently defined region onto your per-user selection stack. Does not otherwise alter the defined region. If the stack is full (currently the limit is set to 100 regions in the stack), then it will complain at you but otherwise will have no effect. @@ -1353,6 +1486,8 @@ Note that pos2 does _not_ need to be defined in order to use this. if it isn't d ``` ### `//spop` +> Added in v1.12 + Pops a selection off your per-user selection stack and applies it to the currently defined region. If pos2 from the item popped from the stack is nil, then pos2 is explicitly unset. If the stack is empty, this has no effect. ```weacmd @@ -1380,6 +1515,8 @@ Alias for [`//count`](#count). ### `//mface` +> Added in v1.13 + Returns the horizontal (X/Z) axis or axes the player is looking along. Aliases: `//mfacing`. @@ -1389,6 +1526,8 @@ Aliases: `//mfacing`. ### `//midpos` +> Added in v1.13 + Returns the coordinates of the centre of the current selection. ``` @@ -1397,6 +1536,8 @@ Returns the coordinates of the centre of the current selection. ### `//msize` +> Added in v1.13 + Returns the lengths of the current selection on the X, Y and Z axes. ``` @@ -1468,6 +1609,8 @@ In addition, this also allows for including a double forward slash in the argume ### `//many ` +> Added in v1.9 + Executes a single chat command many times in a row. Uses `minetest.after()` to yield to the main server thread to allow other things to happen at the same time, so technically you could have multiple `//many` calls going at once (but multithreading support is out of reach, so only a single one will be executing at the same time). Note that this isn't necessarily limited to executing WorldEdit / WorldEditAdditions commands. Combine with `//multi` (see above) execute multiple commands at once for even more power and flexibility! @@ -1479,6 +1622,8 @@ Note that this isn't necessarily limited to executing WorldEdit / WorldEditAddit ### `//ellipsoidapply ` +> Added in v1.9 + Executes the given command, and then clips the result to the largest ellipsoid that will fit inside the defined region. The specified command must obviously take 2 positions - so for example `//set`, `//replacemix`, and `//maze3d` will work, but `//sphere`, `//torus`, and `//floodfill` won't. For advanced users, `//multi` is also supported - but make sure your modifications stay within the defined region - otherwise they will not be affected by the ellipsoidal clipping operation. @@ -1493,6 +1638,8 @@ For advanced users, `//multi` is also supported - but make sure your modificatio ### `//airapply ` +> Added in v1.13 + Like [`//ellipsoidapply`](#ellipsoidapply), but instead only keeps changes that replace airlike nodes, and discards any other changes made. As with `//ellipsoidapply` for advanced users `//multi` is also supported - but make sure your modifications stay within the defined region - otherwise they be kept regardless, as `//airapply` only applies the masking to the nodes in the defined region. @@ -1504,6 +1651,8 @@ As with `//ellipsoidapply` for advanced users `//multi` is also supported - but ### `//nodeapply [] [... ] -- ` +> Added in v1.15 + **Aliases:** `//napply` It's got `apply` in the name, so as you might imagine it works the same as [`//ellipsoidapply`](#ellipsoidapply), [`//airapply`](#airapply), [`//noiseapply2d`](#noiseapply2d), etc. Only changes made by the given command that replace nodes on the list given will be replaced. For example: @@ -1546,6 +1695,8 @@ More misc examples to end this command description, as is customary: ### `//noiseapply2d ` +> Added in v1.13 + Like [`//ellipsoidapply`](#ellipsoidapply), but instead only keeps changes where a noise function (defaults to `perlinmt`, see [`//noise2d`](#noise2d)) returns a value greater than a given threshold value. Also takes a scale value that controls the scale of the noise - -higher values result in smaller "blobs". If you're operating on small areas, then a value of at least 10 is advised as "blobs" are by default on the scale of ~50 nodes. @@ -1560,6 +1711,8 @@ Any suggestions on how to provide more customisability without making this comm ``` ### `//for ... do // %% ` +> Added in v1.13 + For a given list of values, executes the specified command for each value, replacing `%%` with each value. Implementation thanks to @VorTechnix. To better illustrate what happens, consider the following command: @@ -1608,6 +1761,8 @@ This command is intended for development and modding. You will not normally need ### `//speed []` +> Added in v1.15 + Adjusts your player movement speed to the specified value. In other words: ```weacmd @@ -1664,6 +1819,8 @@ Note this only affects **you**, and **not any other player**. See also [`//speed`](#speed). ### Far Wand +> Added in v1.7 + The far wand (`worldeditadditions:farwand`) is a variant on the traditional WorldEdit wand (`worldedit:wand`). It looks like this: ![A picture of the far wand](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/main/worldeditadditions_farwand/textures/worldeditadditions_farwand.png) It functions very similarly to the regular WorldEdit wand, except that it has a _much_ longer range - which can be very useful for working on large-scale terrain for example. It also comes with an associated command to control it. @@ -1695,6 +1852,8 @@ You can change the maximum range with the `maxdist` subcommand: Note that the number there isn't in blocks (because hard maths). It is however proportional to the distance the wand will raycast looks for nodes, so a higher value will result in it raycasting further. ### Cloud Wand +> Added in v1.11 + The cloud wand (`worldeditadditions:cloudwand`) is a another variant the above _Far Wand_. It looks like this: ![A picture of the far wand](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/main/worldeditadditions_farwand/textures/worldeditadditions_cloudwand.png) Unlike the other 2 wands, this wand functions in an additive manner. Left-click on a node to expand the currently defined region (creating a new one if one isn't defined already) to include that node. Right click to clear the currently defined region. @@ -1705,6 +1864,8 @@ Note that punching out the positions **does not unset them**. Use `//reset` to r ### MultiPoint Wand +> Added in v1.14 + The third type of wand provided by WorldEditAdditions is completely different, in that it allows you to select up to **999 points** at once! It looks like this: ![A picture of the multi-point wand](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/main/worldeditadditions_farwand/textures/worldeditadditions_multiwand.png) It is important to note that (at present) the points selected by this wand **are not compatible with normal points**. This will change in the future, but requires a lot of work to implement. From 17390ab064cf76ba1af4998f9594d4f241adbdbc Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Wed, 18 Sep 2024 01:15:26 +0100 Subject: [PATCH 16/17] Changelog: bugfix //speed entry link --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a81b158..116b30b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ Note to self: See the bottom of this file for the release template text. - Added [`//nodeapply`](https://worldeditadditions.mooncarrot.space/Reference/#nodeapply), a generalisation of [`//airapply`](https://worldeditadditions.mooncarrot.space/Reference/#airapply) that works with a defined list of nodes. Check out [the reference](https://worldeditadditions.mooncarrot.space/Reference/#nodeapply) - it has some cool tricks to it! (thanks for suggesting, @kliv91 from the Discord server!) - Added [`//ngroups`](https://worldeditadditions.mooncarrot.space/Reference/#ngroups), which lists the groups that a given node is a member of. Useful when paired with [`//nodeapply`](https://worldeditadditions.mooncarrot.space/Reference/#nodeapply)! - Added [`//rotate+`](https://worldeditadditions.mooncarrot.space/Reference/#rotate) to rotate regions through arbitrary series of potentially non-axis-aligned rotations. **Does not support slabs/stairs yet,** but this is on the todo list! -- Added [`//speed`](https://worldeditadditions.mooncarrot.space/Reference/#rotate) to adjust your own movement speed +- Added [`//speed`](https://worldeditadditions.mooncarrot.space/Reference/#speed) to adjust your own movement speed - Also added an associated [movement speed adjustment tool](https://worldeditadditions.mooncarrot.space/Reference/#movement), which looks like this: ![A picture of the move speed adjustment tool. It looks like a monarch butterfly.](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/dev/worldeditadditions_farwand/textures/worldeditadditions_movement.png) - Added [`//set+`](https://worldeditadditions.mooncarrot.space/Reference/#set) for setting nodes and param2/light levels quickly. - NOTE TO SELF: Setting light values doesn't appear to be working very well for some reason From 5fd0c3dad3ad4ad7cf53b9e6861d936a0d0de01d Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Mon, 30 Sep 2024 22:01:22 +0100 Subject: [PATCH 17/17] core/pos: implement set_multi as a convenient alternative to multiple set() calls /cc @VorTechnix & https://github.com/sbrl/Minetest-WorldEditAdditions/pull/112/files?diff=unified&w=1 --- worldeditadditions_core/core/pos.lua | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/worldeditadditions_core/core/pos.lua b/worldeditadditions_core/core/pos.lua index 442fc57..77728d6 100644 --- a/worldeditadditions_core/core/pos.lua +++ b/worldeditadditions_core/core/pos.lua @@ -218,9 +218,20 @@ local function set2(player_name, pos) return set(player_name, 2, pos) end +--- Sets multiple positions for the given player. +-- @param player_name string The name of the player to set the positions for. +-- @param pos_list table A table of Vector3 positions to set, where the key is the index and the value is the position. +local function set_multi(player_name, pos_list) + for i,pos_new in pairs(pos_list) do + set(player_name, i, pos_new) + end +end --- Sets the all the positions for the given player. -- You probably want push_pos, not this function. +-- +-- WARNING: Will DELETE all points registered for the given player! +-- -- @param player_name string The name of the player to set the positions for. -- @param pos_list Vector3 The table of positions to set. -- @returns bool Whether the operation was successful or not (players aren't allowed more than positions_count_limit number of positions at a time). @@ -319,6 +330,7 @@ anchor = wea_c.EventEmitter.new({ set = set, set1 = set1, set2 = set2, + set_multi = set_multi, set_all = set_all, unmark = unmark, mark = mark,