--- Full code example, see below for explaination
+ --- Full code example, see below for explanation
Commands.new_command('repeat-name', 'Will repeat you name a number of times in chat.')
-:add_param('repeat-count', false, 'number-range-int', 1, 5) -- required int in range 1 to 5 inclusive
+:add_param('repeat-count', 'number-range-int', 1, 5) -- required int in range 1 to 5 inclusive
:add_param('smiley', true, function(input, player, reject) -- optional boolean default false
if not input then return end
- if input:lower() == 'true' or input:lower() == 'yes' then
- return true
- else
- return false
- end
+ input = input:lower()
+ if input == 'true' or input == 'yes' then return true end
+ return false
end)
-:set_defaults{ smiley=false }
-:set_flag('admin_only', true) -- command is admin only
+:set_defaults{ smiley = false }
+:set_flag('admin_only') -- command is admin only
:add_alias('name', 'rname') -- allow alias: name and rname
:register(function(player, repeat_count, smiley, raw)
game.print(player.name..' used a command with input: '..raw)
@@ -284,89 +282,85 @@
Command.print(1..msg)
end
end)
- --- Example Command:
--- How for the fun part making the commands, the commands can be set up with any number of params and flags that you want,
--- you can add aliases for the commands and set default values for optional params and of course register your command callback
--- in our example we will just have a command that will repeat the users name in chat X amount of times and only allow admins to use it.
+ --- Example Command Explanation:
+-- Making commands basics, the commands can be set up with any number of params and flags that you want,
+-- you can add aliases for the commands and set default values for optional params and of course register your command callback.
+-- In our example we will have a command that will repeat the users name in chat X amount of times and only allow admins to use it.
--- First we create the new command, nb this will not register the command to the game this is done at the end, we will call
--- the command "repeat-name" and set the help message as follows:
+-- First we create the new command, note this will not register the command to the game this is done at the end.
+-- We will call the command "repeat-name" and set the help message as follows:
Commands.new_command('repeat-name', 'Will repeat you name a number of times in chat.')
--- Now for our first param we will call "repeat-count" and it will be a required value between 1 and 5 inclusive:
-:add_param('repeat-count', false, 'number-range-int', 1, 5)
+-- Now for our first param, we have named it "repeat-count" and it will be a required value, between 1 and 5 inclusive:
+-- By using "number-range-int" we are saying to use this parser to convert our input text, common ones exist in config.expcore.command_general_parse
+:add_param('repeat-count', 'number-range-int', 1, 5)
--- Our second param we need a custom parse for but we have not defined it, this is an option for when it is unlikely for
--- any other command to use the same input type; however in our case it will just be a boolean which should be noted as being
--- included in the general command parse config. As for the param its self it will be called "smiley" and will be optional with
--- a default value of false:
+-- Our second param needs a custom parser, meaning it isnt defined with add_parser, this is an option for when it is unlikely for
+-- any other command to use the same input type. In the example it is a boolean type and we are just showing it here as part of the example.
+-- As for the param its self it will be called "smiley" and will be optional with a default value of false:
:add_param('smiley', true, function(input, player, reject)
- -- since it is optional the input can be nil, in which case we just return
+ -- Since it is optional the input can be nil, in which case we just return
if not input then return end
- -- if it is not nil then we check for a truthy value
- if input:lower() == 'true' or input:lower() == 'yes' then
- return true
- else
- -- note that because we did not return nil or reject then false will be passed to command callback, see example parse
- return false
- end
+ -- If it is not nil then we check for a truthy value
+ if input == 'true' or input == 'yes' then return true end
+ -- Note that because we did not return nil or reject then false will be passed to command callback, see example parse
+ return false
end)
--- Once all params are defined you can now define some default values if you have optional params, the default value will be used only
--- when no value is given as input, if an invalid value is given then the command will still fail and this value will not be used, the
--- default can also be a function which is passed the player using the command and returns a value. Here we set the default for "smiley" to false:
+-- Once all params are defined you can add some default values for your optional params, the default value will be used only
+-- when no value is given as input, if an invalid value is given then the command will fail and the default will not be used, the
+-- default can also be a function which is passed the player as an argument and should return a value to be the default.
+-- Here we set the default for "smiley" to false:
:set_defaults{smiley=false}
-- Another example of defaults if we have: item, amount[opt], player[opt]
:set_defaults{
- amount = 50, -- more than one value can be set at a time
- player = function(player)
- return player -- default is the player using the command
- end
-}
+ amount = 50, -- More than one value can be set at a time
+ player = function(player) return player end -- Default is the player using the command
+}
--- Now the params are set up we can alter how the command works, we can set auth flags, add aliases to this command or enable "auto concat"
--- which is when you want all extra words to be concatenated onto the end of the last param, useful for reason or messages:
-:set_flag('admin_only', true) -- in our case we want "admin_only" to be set to true so only admins can use the command
-:add_alias('name', 'rname') -- we also add two aliases here: "name" and "rname" which point to this command
--- :enable_auto_concat() we do not use this in our case but this can also be used to enable the "auto concat" feature
+-- Now the params are set up we can alter how the command works, we can set auth flags, add aliases, or enable "auto concat":
+:set_flag('admin_only') -- In our case we want "admin_only" to be set to true so only admins can use the command
+:add_alias('name', 'rname') -- We also add two aliases here: "name" and "rname" which point to this command
+-- :enable_auto_concat() -- We do not use this in our case but this can also be used to enable the "auto concat" feature
-- And finally we want to register a callback to this command, the callback is what defines what the command does, can be as complex as you
--- want it to be to as simple as our example; the command receives two params plus all that you have defines:
+-- want it to be, or as simple as our example; the command receives two params plus all param you have defined:
-- 1) the player who used the command
-- 2) in our case repeat_count which will be a number
-- 3) in our case smiley which will be a boolean
-- 4) the raw input; this param is always last as is always present as a catch all
:register(function(player, repeat_count, smiley, raw)
- -- this is to show the value for raw as this is an example command, the log file will also show this
+ -- This is to show the value for raw as this is an example command, the log file will also show this
game.print(player.name..' used a command with input: '..raw)
local msg = ') '..player.name
+
if smiley then
- -- this is where that smiley param is used
- msg = ':'..msg
+ msg = ':'..msg
end
+
for 1 = 1, repeat_count do
-- this print function will return ANY value to the user in a desync safe manor, this includes if the command was used through rcon
Command.print(1..msg)
end
- -- see below for what else can be used here
+ -- See below for what can be used here
end)
--- Other values that can be returned from register
-Commands.print(any, colour[opt]) -- this will return any value value to the user including if it is ran through rcon console
-Commands.error(message[opt]) -- this returns a warning to the user, aka an error that does not prevent execution of the command
-return Commands.error(message[opt]) -- this returns an error to the user, and will halt the command execution, ie no success message is returned
-Commands.success(message[opt]) -- used to return a success message however don't use this method see below
-return Commands.success(message[opt]) -- will return the success message to the user and your given message, halts execution
-return <any> -- if any value is returned then it will be returned to the player via a Commands.success call
+-- Values that can be returned from register callback
+Commands.print(any, colour[opt]) -- This will return any value value to the user including if it is ran through rcon console
+Commands.error(message[opt]) -- This returns a warning to the user, aka an error that does not prevent execution of the command
+return Commands.error(message[opt]) -- This returns an error to the user, and will halt the command execution, ie no success message is returned
+Commands.success(message[opt]) -- Used to return a success message however don't use this method, see below
+return Commands.success(message[opt]) -- Will return the success message to the user and your given message, halts execution
+return <any> -- If any value is returned then it will be returned to the player via a Commands.success call
--- Example Authenticator:
-- The command system is best used when you can control who uses commands;
--- to do this would would need to define an authenticator which is ran every time a command is run;
+-- to do this you need to define an authenticator which is ran every time a command is run;
-- in this example I will show a simple one that requires certain commands to require the user to be a game admin.
-- For our admin only example we will set a flag to true when we want it to be admin only;
--- when we define the command will will use :set_flag('admin_only', true);
+-- when we define the command will will use :set_flag('admin_only');
-- then inside the authenticator we will test if the flag is present using: if flags.admin_only then
-- When the authenticator is called by the command handler it will be passed 4 arguments:
@@ -380,11 +374,11 @@
-- 1) when the "admin_only" flag is not set, which we take assume that any one can use it
-- 2) when the "admin_only" flag is set, and the player is admin
--- When want to prevent exicution of the command we must reject it, listed is how that can be done:
+-- When want to prevent execution of the command we must reject it, listed is how that can be done:
-- 1) return false -- this is the most basic rejection and should only be used while testing
-- 2) return reject -- returning the reject function is as a fail safe in case you forget to call it, same as returning false
--- 3) reject() -- this will block execution without to allowing further code to be ran in your authenticator
--- 4) reject('This command is for admins only!') -- Using reject as a function allows a error message to be returned
+-- 3) reject() -- this will block execution while allowing further code to be ran in your authenticator
+-- 4) reject('This command is for admins only!') -- using reject as a function allows a error message to be returned
-- 5) return reject() -- using return on either case above is best practice as you should execute all your code before rejecting
-- Example Code:
@@ -398,15 +392,15 @@
return true
end
end)
- --- Example Parse:
+ --- Example Parser:
-- Before you make a command it is important to understand the most powerful feature of this command handler;
-- when you define a command you are able to type the params and have then be parsed and validated before your command is executed;
--- This module should is paired with a general command parse but you may want to create your own.
+-- This module should be paired with a general command parse but you may want to create your own.
-- For our example we will create a parse to accept only integer numbers in a given range:
-- 1) we will give it the name "number-range-int" this is the "type" that the input is expected to be
-- 2) when we define the type we will also define the min and max of the range so we can use the function more than once
-:add_param('repeat_count', false, 'number-range-int', 5, 10) -- "repeat_count" is required "number-range-int" in a range 5 to 10 inclusive
+:add_param('repeat_count', 'number-range-int', 5, 10) -- "repeat_count" is a required "number-range-int" in a range 5 to 10 inclusive
-- The command parse will be passed 3 arguments plus any other which you define, in our case:
-- 1) input - the input that has been given by the user for this param, the role of this function is to transform this value
@@ -468,23 +462,23 @@
defines
- Values returned by the signal functions to cause the command system to react
+ Constant values used by the command system
commands
- Custom command data will be stored here
+ An array of all custom commands that are registered
- authorization
- Custom function are stored here which control who can use what commands
+ authenticators
+ An array of all custom authenticators that are registered
- parse_functions
+ parsers
Used to store default functions which are common parse function such as player or number in range
_prototype
- Used to store functions which gets added to new custom commands
+ The command prototype which stores all command defining functions
@@ -495,28 +489,53 @@
- authorization_fail_on_error
- Set true to have authorize fail if a callback fails to run, more secure
+ authorization_failure_on_error
+ When true any authenticator error will result in authorization failure, more secure
+
+
+ print
+ Returns a value to the player, different to success as this does not signal the end of your command
- Authenication
+ Authentication
- add_authenticator(callback)
- Adds an authorization callback, function used to check if a player if allowed to use a command
+ add_authenticator(authenticator)
+ Adds an authorization function, function used to check if a player if allowed to use a command
- remove_authenticator(callback)
- Removes an authorization callback
+ remove_authenticator(authenticator)
+ Removes an authorization function, can use the index or the function value
authorize(player, command_name)
- Mostly used internally, calls all authorization callbacks, returns if the player is authorized
+ Mostly used internally, calls all authenticators, returns if the player is authorized
+
+
+
+
+
+ Parse
+
+
+
+
+ add_parse(name, parser)
+ Adds a parse function which can be called by name (used in add_param)
+nb: this is not required as you can use the callback directly this just allows it to be called by name
+
+
+ remove_parse(name)
+ Removes a parse function, see add_parse for adding them, cant be done during runtime
+
+
+ parse(name, input, player, reject)
+ Intended to be used within other parse functions, runs a parse and returns success and new value
@@ -538,60 +557,38 @@
- Parse
-
-
-
-
- add_parse(name, callback)
- Adds a parse function which can be called by name (used in add_param)
-nb: this is not required as you can use the callback directly this just allows it to be called by name
-
-
- remove_parse(name)
- Removes a parse function, see add_parse for adding them
-
-
- parse(name, input, player, reject)
- Intended to be used within other parse functions, runs a parse and returns success and new value
-
-
-
-
-
Creation
new_command(name, help)
- Creates a new command object to added details to, note this does not register the command to the game api
+ Creates a new command object to added details to, this does not register the command to the game api
- Commands._prototype:add_param(name[, optional=false][, parse=pass function through][, ...])
+ Commands._prototype:add_param(name[, optional=false][, parse][, ...])
Adds a new param to the command this will be displayed in the help and used to parse the input
Commands._prototype:set_defaults(defaults)
- Add default values to params, only as an effect if the param is optional, if default value is a function it is called with acting player
+ Add default values to params, only as an effect if the param is optional, if default value is a function it is called with the acting player
Commands._prototype:set_flag(name[, value=true])
- Adds a tag to the command which is passed via the flags param to the authenticators, can be used to assign command roles or type
+ Adds a flag to the command which is passed via the flags param to the authenticators, can be used to assign command roles or usage type
- Commands._prototype:add_alias(any)
- Adds an alias, or multiple, that will also be registered with the same callback, eg /teleport can be used as /tp
+ Commands._prototype:add_alias(...)
+ Adds an alias, or multiple, that will be registered to this command, eg /teleport can be used as /tp
Commands._prototype:enable_auto_concat()
- Enables auto concatenation of any params on the end so quotes are not needed for last param
-nb: this will disable max param checking as they will be concatenated onto the end of that last param
-this can be useful for reasons or longs text, can only have one per command
+ Enables auto concatenation for this command, all params after the last are added to the last param, useful for reasons or other long text input
+nb: this will disable max param checking as they will be concatenated onto the end of that last param
Commands._prototype:register(callback)
- Adds the callback to the command and registers all aliases, params and help message with the game api
+ Adds the callback to the command and registers: aliases, params and help message with the base game api
nb: this must be the last function ran on the command and must be done for the command to work
@@ -603,23 +600,22 @@ nb: this must be the last function ran on the command and must be done for the c
- error([error_message=''][, play_sound=utility/wire_pickup])
- Sends an error message to the player and when returned will stop exicution of the command
-nb: this is for non fatal errors meaning there is no log of this event, use during register callback
-
-
- internal_error(success, command_name, error_message)
- Sends an error to the player and logs the error, used with pcall within command handler please avoid direct use
-nb: use error(error_message) within your callback to trigger do not trigger directly as code exictuion may still continue
-
-
success([value])
- Sends a value to the player, followed by a command complete message
-nb: returning any value from your callback will trigger this function, return this function to prevent duplicate messages
+ Sends a value to the player, followed by a command complete message, returning a value will trigger this automatically
print(value, colour)
Sends a value to the player, different to success as this does not signal the end of your command
+
+
+ error([error_message=''][, play_sound=utility/wire_pickup])
+ Sends an error message to the player and when returned will stop execution of the command
+nb: this is for non fatal errors meaning there is no log of this event, use during register callback
+
+
+ internal_error(success, command_name, error_message)
+ Sends an error to the player and logs the error, used internally please avoid direct use
+nb: use error(error_message) within your callback to trigger do not trigger directly as code execution may still continue
run_command(command_event)
@@ -697,7 +693,7 @@ nb: returning any value from your callback will trigger this function, return th
- Values returned by the signal functions to cause the command system to react
+ Constant values used by the command system
@@ -773,7 +769,7 @@ nb: returning any value from your callback will trigger this function, return th
- Custom command data will be stored here
+ An array of all custom commands that are registered
@@ -793,14 +789,14 @@ nb: returning any value from your callback will trigger this function, return th
- Custom function are stored here which control who can use what commands
+ An array of all custom authenticators that are registered
@@ -820,8 +816,8 @@ nb: returning any value from your callback will trigger this function, return th
@@ -854,7 +850,7 @@ nb: returning any value from your callback will trigger this function, return th
- Used to store functions which gets added to new custom commands
+ The command prototype which stores all command defining functions
@@ -877,14 +873,41 @@ nb: returning any value from your callback will trigger this function, return th
- Set true to have authorize fail if a callback fails to run, more secure
+ When true any authenticator error will result in authorization failure, more secure
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #
+ print
+
+
+
+
+
+ Returns a value to the player, different to success as this does not signal the end of your command
@@ -902,19 +925,19 @@ nb: returning any value from your callback will trigger this function, return th
- Authenication
+ Authentication
-
-
-
Adds an authorization callback, function used to check if a player if allowed to use a command
+ Adds an authorization function, function used to check if a player if allowed to use a command
@@ -928,13 +951,13 @@ nb: returning any value from your callback will trigger this function, return th
-
- callback
+ authenticator
:
(function)
- the callback you want to register as an authenticator
+ The function you want to register as an authenticator
@@ -948,7 +971,7 @@ nb: returning any value from your callback will trigger this function, return th
-
(number)
- the index it was inserted at use to remove the callback, if anon function used
+ The index it was inserted at, used to remove the authenticator
@@ -959,11 +982,11 @@ nb: returning any value from your callback will trigger this function, return th
Usage:
- -- Test if a command is admin only and if the player is admin
+ -- If the admin_only flag is set, then make sure the player is an admin
local admin_authenticator =
Commands.add_authenticator(function(player, command, flags, reject)
- if flags.admin_only then
- return player.admin or reject('This command is for admins only!')
+ if flags.admin_only and not player.admin then
+ return reject('This command is for admins only!')
else
return true
end
@@ -975,13 +998,13 @@ Commands.add_authenticator(function(player, command
-
-
Removes an authorization callback
+ Removes an authorization function, can use the index or the function value
@@ -995,13 +1018,13 @@ Commands.add_authenticator(function(player, command
-
- callback
+ authenticator
:
(function or number)
- the callback to remove, an index returned by add_authenticator can be passed
+ The authenticator to remove, either the index return from add_authenticator or the function used
@@ -1015,7 +1038,7 @@ Commands.add_authenticator(function(player, command
-
(boolean)
- if the callback found and removed successfuly
+ If the authenticator was found and removed successfully
@@ -1026,7 +1049,7 @@ Commands.add_authenticator(function(player, command
Usage:
- -- Removing the admin authenticator, can not be done dueing runtime
+ -- Removing the admin authenticator, can not be done during runtime
Commands.remove_authenticator(admin_authenticator)
@@ -1041,7 +1064,7 @@ Commands.add_authenticator(function(player, command
-
-
Mostly used internally, calls all authorization callbacks, returns if the player is authorized
+ Mostly used internally, calls all authenticators, returns if the player is authorized
@@ -1061,7 +1084,7 @@ Commands.add_authenticator(function(player, command
(LuaPlayer)
- the player that is using the command, passed to callbacks
+ The player who is using the command, passed to authenticators
@@ -1077,7 +1100,7 @@ Commands.add_authenticator(function(player, command
(string)
- the command that is being used, passed to callbacks
+ The name of the command being used, passed to authenticators
@@ -1091,22 +1114,22 @@ Commands.add_authenticator(function(player, command
-
(boolean)
- true player is authorized
+ true Player is authorized
-
(string)
- commands const for success
+ commands Define value for success
Or
-
(boolean)
- false player is unauthorized
+ false Player is unauthorized
-
(string or locale_string)
- the reason given by the authenticator
+ The reason given by the failed authenticator
@@ -1121,151 +1144,6 @@ Commands.add_authenticator(function(player, command
local authorized, status = Commands.authorize(game.player, 'repeat-name')
-
-
- Getters
-
- -
-
-
- #
- get([player])
-
-
- -
-
-
-
Gets all commands that a player is allowed to use, game commands are not included
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- player
-
- :
-
- (LuaPlayer)
-
- the player that you want to get commands of, nil will return all commands
-
- (optional)
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (table)
- all commands that that player is allowed to use, or all commands
-
-
-
-
-
-
-
-
-
- Usage:
- -- Get the command you are allowed to use
-local commands = Commands.get(game.player)
- -- Get all commands that are registered
-local commands = Commands.get()
-
-
-
- -
-
-
- #
- search(keyword[, player])
-
-
- -
-
-
-
Searches command names and help messages to find possible commands, game commands are included
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- keyword
-
- :
-
- (string)
-
- the word which you are trying to find in your search
-
-
-
-
-
-
-
- -
-
- player
-
- :
-
- (LuaPlayer)
-
- the player to get allowed commands of, if nil all commands are searched
-
- (optional)
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (table)
- all commands that contain the key word, and allowed by player if player given
-
-
-
-
-
-
-
-
-
- Usage:
- -- Get all commands which "repeat"
-local commands = Commands.search('repeat')
- -- Get all commands which "repeat" and you are allowed to use
-local commands = Commands.search('repeat', game.player)
-
-
Parse
@@ -1274,7 +1152,7 @@ Commands.add_authenticator(function(player, command
-
@@ -1301,7 +1179,7 @@ nb: this is not required as you can use the callback directly this just allows i
(string)
- the name of the parse, should be the type like player or player_alive, must be unique
+ The name of the parse, should describe a type of input such as number or player, must be unique
@@ -1311,13 +1189,13 @@ nb: this is not required as you can use the callback directly this just allows i
-
- callback
+ parser
:
(function)
- the callback that is ran to parse the input
+ The function that is ran to parse the input string
@@ -1331,7 +1209,7 @@ nb: this is not required as you can use the callback directly this just allows i
-
(boolean)
- was the parse added will be false if the name is already used
+ Was the parse added, will be false if the name is already used
@@ -1342,14 +1220,14 @@ nb: this is not required as you can use the callback directly this just allows i
Usage:
- -- Adding a parse to validate ints in a given range
+ -- Adding a parse to validate integers in a given range
Commands.add_parse('number-range-int', function(input, player, reject, range_min, range_max)
local rtn = tonumber(input) and math.floor(tonumber(input)) or nil -- converts input to number
if not rtn or rtn < range_min or rtn > range_max then
- -- the input is either not a number or is outside the range
+ -- The input is either not a number or is outside the range
return reject('Number entered is not in range: '..range_min..', '..range_max)
else
- -- returns the input as a number rather than a string, thus the param is now the correct type
+ -- Returns the input as a number rather than a string, thus the param is now the correct type
return rtn
end
end)
@@ -1366,7 +1244,7 @@ nb: this is not required as you can use the callback directly this just allows i
-
-
Removes a parse function, see add_parse for adding them
+ Removes a parse function, see add_parse for adding them, cant be done during runtime
@@ -1386,7 +1264,7 @@ nb: this is not required as you can use the callback directly this just allows i
(string)
- the name of the parse to remove
+ The name of the parse to remove
@@ -1439,7 +1317,7 @@ nb: this is not required as you can use the callback directly this just allows i
(string)
- the name of the parse to call, must be registered parse
+ The name of the parse to call, must be a registered parser
@@ -1455,7 +1333,7 @@ nb: this is not required as you can use the callback directly this just allows i
(string)
- string the input to pass to the parse, must be a string but not necessarily the original input
+ The input to pass to the parse, must be a string but not necessarily the original input
@@ -1471,7 +1349,7 @@ nb: this is not required as you can use the callback directly this just allows i
(LuaPlayer)
- the player that is using the command
+ The player that is using the command, pass directly from your arguments
@@ -1487,7 +1365,7 @@ nb: this is not required as you can use the callback directly this just allows i
(function)
- the reject function that was passed by the command hander
+ The reject function, pass directly from your arguments
@@ -1501,7 +1379,7 @@ nb: this is not required as you can use the callback directly this just allows i
-
(any)
- the new value for the input, may be nil, if nil then either there was an error or input was nil
+ The new value for the input, if nil is return then either there was an error or the input was nil
@@ -1512,9 +1390,163 @@ nb: this is not required as you can use the callback directly this just allows i
Usage:
- -- Parsing a int in a given range
-local parsed_input = Commands.parse('number-range-int', '7', player, reject, 1, 10) -- valid range 1 to 10
-
+ -- Parsing an int after first checking it is a number
+Commands.add_parse('number', function(input, player, reject)
+ local number = tonumber(input)
+ if number then return number end
+ return reject('Input must be a number value')
+end)
+
+Commands.add_parse('number-int', function(input, player, reject)
+ local number = Commands.parse('number', input, player, reject)
+ if not number then return end
+ return math.floor(number)
+end)
+
+
+
+
+ Getters
+
+ -
+
+
+ #
+ get([player])
+
+
+ -
+
+
+
Gets all commands that a player is allowed to use, game commands are not included
+
+
+
+ Parameters:
+
+
+
+
+
+
+
+ -
+
+ player
+
+ :
+
+ (LuaPlayer)
+
+ The player that you want to get commands of, nil will return all commands
+
+ (optional)
+
+
+
+
+
+
+
+
+ Returns:
+
+ -
+ (table)
+ All commands that that player is allowed to use, or all commands
+
+
+
+
+
+
+
+
+
+ Usage:
+ -- Get the commands you are allowed to use
+local commands = Commands.get(game.player)
+ -- Get all commands that are registered
+local commands = Commands.get()
+
+
+
+ -
+
+
+ #
+ search(keyword[, player])
+
+
+ -
+
+
+
Searches command names and help messages to find possible commands, game commands are included
+
+
+
+ Parameters:
+
+
+
+
+
+
+
+ -
+
+ keyword
+
+ :
+
+ (string)
+
+ The word which you are trying to find in your search
+
+
+
+
+
+
+
+ -
+
+ player
+
+ :
+
+ (LuaPlayer)
+
+ The player to get allowed commands of, if nil all commands are searched
+
+ (optional)
+
+
+
+
+
+
+
+
+ Returns:
+
+ -
+ (table)
+ All commands that contain the key word, and allowed by the player if a player was given
+
+
+
+
+
+
+
+
+
+ Usage:
+ -- Get all commands which "repeat"
+local commands = Commands.search('repeat')
+ -- Get all commands which "repeat" and you are allowed to use
+local commands = Commands.search('repeat', game.player)
@@ -1531,7 +1563,7 @@ nb: this is not required as you can use the callback directly this just allows i
-
-
Creates a new command object to added details to, note this does not register the command to the game api
+ Creates a new command object to added details to, this does not register the command to the game api
@@ -1551,7 +1583,7 @@ nb: this is not required as you can use the callback directly this just allows i
(string)
- the name of the command to be created
+ The name of the command to be created
@@ -1567,7 +1599,7 @@ nb: this is not required as you can use the callback directly this just allows i
(string)
- the help message for the command
+ The help message for the command
@@ -1580,8 +1612,8 @@ nb: this is not required as you can use the callback directly this just allows i
Returns:
-
- (Commands._prototype)
- this will be used with other functions to generate the command functions
+ (table)
+ This will be used with other functions to define the new command
@@ -1593,8 +1625,7 @@ nb: this is not required as you can use the callback directly this just allows i
Usage:
-- Define a new command
-local command =
-Commands.new_command('repeat-name', 'Will repeat you name a number of times in chat.')
+Commands.new_command('repeat-name', 'Will repeat you name a number of times in chat.')
@@ -1602,7 +1633,7 @@ Commands.new_command('repeat-name',
#
- Commands._prototype:add_param(name[, optional=false][, parse=pass function through][, ...])
+ Commands._prototype:add_param(name[, optional=false][, parse][, ...])
-
@@ -1628,7 +1659,7 @@ Commands.new_command('repeat-name', string)
- the name of the new param that is being added to the command
+ The name of the new param that is being added to the command
@@ -1644,7 +1675,7 @@ Commands.new_command('repeat-name', boolean)
- is this param required for this command, these must be after all required params
+ Is this param optional, these must be added after all required params
(default: false)
@@ -1661,9 +1692,9 @@ Commands.new_command('repeat-name', string or function)
- this function will take the input and return a new (or same) value
+ This function will take the input and return a new value, if not given no parse is done
- (default: pass function through)
+ (optional)
@@ -1676,8 +1707,9 @@ Commands.new_command('repeat-name', any)
- extra args you want to pass to the parse function; for example if the parse is general use
+ Extra args you want to pass to the parse function; for example if the parse is general use
(optional)
@@ -1691,8 +1723,8 @@ Commands.new_command('repeat-name', Commands._prototype)
- pass through to allow more functions to be called
+ (table)
+ Pass through to allow more functions to be called
@@ -1703,9 +1735,9 @@ Commands.new_command('repeat-name',
-- Adding a param which has an parse defined
-command:add_param('repeat-count', false, 'number-range-int', 1, 5)
- -- Adding a param which has a custom parse, see Commands.add_parse for details
+ -- Adding a required param which has a parser pre-defined
+command:add_param('repeat-count', 'number-range-int', 1, 5)
+ -- Adding an optional param which has a custom parse, see Commands.add_parse for details
command:add_param('smiley', true, function(input, player, reject)
if not input then return end
return input:lower() == 'true' or input:lower() == 'yes' or false
@@ -1723,7 +1755,7 @@ Commands.new_command('repeat-name',
- Add default values to params, only as an effect if the param is optional, if default value is a function it is called with acting player
+ Add default values to params, only as an effect if the param is optional, if default value is a function it is called with the acting player
@@ -1743,7 +1775,7 @@ Commands.new_command('repeat-name', table)
- table which is keyed by the name of the param and the value is the default value
+ A table which is keyed by the name of the param and the value is the default value for that param
@@ -1756,8 +1788,8 @@ Commands.new_command('repeat-name', Commands._prototype)
- pass through to allow more functions to be called
+ (table)
+ Pass through to allow more functions to be called
@@ -1789,7 +1821,7 @@ Commands.new_command('repeat-name',
- Adds a tag to the command which is passed via the flags param to the authenticators, can be used to assign command roles or type
+ Adds a flag to the command which is passed via the flags param to the authenticators, can be used to assign command roles or usage type
@@ -1809,7 +1841,7 @@ Commands.new_command('repeat-name', string)
- the name of the tag to be added, set to true if no value is given
+ The name of the flag to be added, set to true if no value is given
@@ -1825,7 +1857,7 @@ Commands.new_command('repeat-name', any)
- the tag that you want can be anything that the authenticators are expecting
+ The value for the flag, can be anything that the authenticators are expecting
(default: true)
@@ -1839,8 +1871,8 @@ Commands.new_command('repeat-name', Commands._prototype)
- pass through to allow more functions to be called
+ (table)
+ Pass through to allow more functions to be called
@@ -1862,13 +1894,13 @@ Commands.new_command('repeat-name',
-
-
Adds an alias, or multiple, that will also be registered with the same callback, eg /teleport can be used as /tp
+ Adds an alias, or multiple, that will be registered to this command, eg /teleport can be used as /tp
@@ -1882,13 +1914,13 @@ Commands.new_command('repeat-name',
- any
+ ...
:
(string)
- ... amount of aliases that you want this command to be callable with
+ Any amount of aliases that you want this command to be callable with
@@ -1901,8 +1933,8 @@ Commands.new_command('repeat-name', Commands._prototype)
- pass through to allow more functions to be called
+ (table)
+ Pass through to allow more functions to be called
@@ -1928,9 +1960,8 @@ Commands.new_command('repeat-name',
- Enables auto concatenation of any params on the end so quotes are not needed for last param
-nb: this will disable max param checking as they will be concatenated onto the end of that last param
-this can be useful for reasons or longs text, can only have one per command
+ Enables auto concatenation for this command, all params after the last are added to the last param, useful for reasons or other long text input
+nb: this will disable max param checking as they will be concatenated onto the end of that last param
@@ -1940,8 +1971,8 @@ this can be useful for reasons or longs text, can only have one per command
Returns:
-
- (Commands._prototype)
- pass through to allow more functions to be called
+ (table)
+ Pass through to allow more functions to be called
@@ -1967,7 +1998,7 @@ this can be useful for reasons or longs text, can only have one per command
-
-
Adds the callback to the command and registers all aliases, params and help message with the game api
+
Adds the callback to the command and registers: aliases, params and help message with the base game api
nb: this must be the last function ran on the command and must be done for the command to work
@@ -1988,7 +2019,7 @@ nb: this must be the last function ran on the command and must be done for the c
(function)
- the callback for the command, will receive the player running command, and params added with add_param
+ The callback for the command, will receive the player running command, and any params added with add_param
@@ -2006,8 +2037,8 @@ nb: this must be the last function ran on the command and must be done for the c
Usage:
- -- Registering your command to the game api
-command:register(function(player, repeat_count, smiley, _)
+ -- Registering your command to the base game api
+command:register(function(player, repeat_count, smiley, raw)
local msg = ') '..player.name
if smiley then msg = ':'..msg end
@@ -2024,181 +2055,6 @@ nb: this must be the last function ran on the command and must be done for the c
-
- #
- error([error_message=''][, play_sound=utility/wire_pickup])
-
-
- -
-
-
-
Sends an error message to the player and when returned will stop exicution of the command
-nb: this is for non fatal errors meaning there is no log of this event, use during register callback
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- error_message
-
- :
-
- (string)
-
- an optional error message that can be sent to the user
-
- (default: '')
-
-
-
-
-
-
- -
-
- play_sound
-
- :
-
- (string)
-
- the sound to play for the error
-
- (default: utility/wire_pickup)
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (Commands.defines.error)
- return this to command handler to exit execution
-
-
-
-
-
-
-
-
-
- Usage:
- -- Send an error message to the player, and stops further code running
-return Commands.error('The player you selected is offline')
-
-
-
- -
-
-
- #
- internal_error(success, command_name, error_message)
-
-
- -
-
-
-
Sends an error to the player and logs the error, used with pcall within command handler please avoid direct use
-nb: use error(error_message) within your callback to trigger do not trigger directly as code exictuion may still continue
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- success
-
- :
-
- (boolean)
-
- the success value returned from pcall, or just false to trigger error
-
-
-
-
-
-
-
- -
-
- command_name
-
- :
-
- (string)
-
- the name of the command this is used within the log
-
-
-
-
-
-
-
- -
-
- error_message
-
- :
-
- (string)
-
- the error returned by pcall or some other error, this is logged and not returned to player
-
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (boolean)
- the opposite of success so true means to cancel execution, used internally
-
-
-
-
-
-
-
-
-
- Usage:
- -- Used in the command system to log handler errors
-local success, err = pcall(command_data.callback, player, unpack(params))
-if Commands.internal_error(success, command_data.name, err) then
- return command_log(player, command_data, 'Internal Error: Command Callback Fail', raw_params, command_event.parameter, err)
-end
-
-
-
- -
-
-
#
success([value])
@@ -2206,8 +2062,7 @@ nb: use error(error_message) within your callback to trigger do not trigger dire
-
-
Sends a value to the player, followed by a command complete message
-nb: returning any value from your callback will trigger this function, return this function to prevent duplicate messages
+ Sends a value to the player, followed by a command complete message, returning a value will trigger this automatically
@@ -2227,7 +2082,7 @@ nb: returning any value from your callback will trigger this function, return th
(any)
- the value to return to the player, if nil then only success message returned
+ The value to return to the player, if nil then only the success message is returned
(optional)
@@ -2242,7 +2097,7 @@ nb: returning any value from your callback will trigger this function, return th
-
(Commands.defines.success)
- return this to the command handler to prevent two success messages
+ Return this to the command handler to prevent two success messages
@@ -2290,7 +2145,7 @@ nb: returning any value from your callback will trigger this function, return th
(any)
- the value that you want to return to the player
+ The value that you want to return to the player
@@ -2306,7 +2161,7 @@ nb: returning any value from your callback will trigger this function, return th
(table)
- the colour of the message that the player sees
+ The colour of the message that the player sees
@@ -2328,6 +2183,181 @@ nb: returning any value from your callback will trigger this function, return th
Commands.print('Your command is in progress')
+
+ -
+
+
+ #
+ error([error_message=''][, play_sound=utility/wire_pickup])
+
+
+ -
+
+
+
Sends an error message to the player and when returned will stop execution of the command
+nb: this is for non fatal errors meaning there is no log of this event, use during register callback
+
+
+
+ Parameters:
+
+
+
+
+
+
+
+ -
+
+ error_message
+
+ :
+
+ (string)
+
+ An optional error message that can be sent to the user
+
+ (default: '')
+
+
+
+
+
+
+ -
+
+ play_sound
+
+ :
+
+ (string)
+
+ The sound to play for the error
+
+ (default: utility/wire_pickup)
+
+
+
+
+
+
+
+
+ Returns:
+
+ -
+ (Commands.defines.error)
+ Return this to command handler to terminate execution
+
+
+
+
+
+
+
+
+
+ Usage:
+ -- Send an error message to the player, and stops further code running
+return Commands.error('The player you selected is offline')
+
+
+
+ -
+
+
+ #
+ internal_error(success, command_name, error_message)
+
+
+ -
+
+
+
Sends an error to the player and logs the error, used internally please avoid direct use
+nb: use error(error_message) within your callback to trigger do not trigger directly as code execution may still continue
+
+
+
+ Parameters:
+
+
+
+
+
+
+
+ -
+
+ success
+
+ :
+
+ (boolean)
+
+ The success value returned from pcall, or just false to trigger error
+
+
+
+
+
+
+
+ -
+
+ command_name
+
+ :
+
+ (string)
+
+ The name of the command this is used within the log
+
+
+
+
+
+
+
+ -
+
+ error_message
+
+ :
+
+ (string)
+
+ The error returned by pcall or some other error, this is logged and not returned to player
+
+
+
+
+
+
+
+
+
+ Returns:
+
+ -
+ (boolean)
+ The opposite of success so true means to cancel execution, used internally
+
+
+
+
+
+
+
+
+
+ Usage:
+ -- Used in the command system to log handler errors
+local success, err = pcall(command_data.callback, player, unpack(params))
+if Commands.internal_error(success, command_data.name, err) then
+ return command_log(player, command_data, 'Internal Error: Command Callback Fail', raw_params, command_event.parameter, err)
+end
+
+
-
@@ -2359,7 +2389,7 @@ nb: returning any value from your callback will trigger this function, return th
(table)
- passed directly from command event from the add_command function
+ Passed directly from the add_command function
@@ -2396,7 +2426,7 @@ nb: returning any value from your callback will trigger this function, return th
generated by LDoc
diff --git a/docs/core/Common.html b/docs/core/Common.html
index 21ac0209..13e05173 100644
--- a/docs/core/Common.html
+++ b/docs/core/Common.html
@@ -2765,7 +2765,7 @@ https://github.com/Refactorio/RedMew/blob/9184b2940f311d8c9c891e83429fc57ec7e0c4
generated by LDoc
diff --git a/docs/core/Datastore.html b/docs/core/Datastore.html
index d5d976f0..530fe6ab 100644
--- a/docs/core/Datastore.html
+++ b/docs/core/Datastore.html
@@ -2945,7 +2945,7 @@ ExampleData:on_update(function(key, value)
generated by LDoc
diff --git a/docs/core/Groups.html b/docs/core/Groups.html
index 1bf64be1..4bf5814d 100644
--- a/docs/core/Groups.html
+++ b/docs/core/Groups.html
@@ -1441,7 +1441,7 @@
generated by LDoc
diff --git a/docs/core/Gui.html b/docs/core/Gui.html
index daefcd1c..3665e58d 100644
--- a/docs/core/Gui.html
+++ b/docs/core/Gui.html
@@ -4419,7 +4419,7 @@ Gui.left_toolbar_button('entity/inserter', generated by LDoc
diff --git a/docs/core/PlayerData.html b/docs/core/PlayerData.html
index b7c3a0b6..68c80163 100644
--- a/docs/core/PlayerData.html
+++ b/docs/core/PlayerData.html
@@ -529,7 +529,7 @@
generated by LDoc
diff --git a/docs/core/Roles.html b/docs/core/Roles.html
index 2190c925..a94bcd3a 100644
--- a/docs/core/Roles.html
+++ b/docs/core/Roles.html
@@ -3348,7 +3348,7 @@ nb: this is one way, failing false after already gaining the role will not revok
generated by LDoc
diff --git a/docs/data/Alt-View.html b/docs/data/Alt-View.html
index d55aad15..b2e4a570 100644
--- a/docs/data/Alt-View.html
+++ b/docs/data/Alt-View.html
@@ -333,7 +333,7 @@
generated by LDoc
diff --git a/docs/data/Bonus.html b/docs/data/Bonus.html
index 37ca37de..c0ebd14f 100644
--- a/docs/data/Bonus.html
+++ b/docs/data/Bonus.html
@@ -485,7 +485,7 @@
generated by LDoc
diff --git a/docs/data/Greetings.html b/docs/data/Greetings.html
index bfdca1be..057b26d0 100644
--- a/docs/data/Greetings.html
+++ b/docs/data/Greetings.html
@@ -428,7 +428,7 @@
generated by LDoc
diff --git a/docs/data/Player-Colours.html b/docs/data/Player-Colours.html
index 77cf6ac2..aa18e92d 100644
--- a/docs/data/Player-Colours.html
+++ b/docs/data/Player-Colours.html
@@ -389,7 +389,7 @@
generated by LDoc
diff --git a/docs/data/Quickbar.html b/docs/data/Quickbar.html
index 3773168e..75269c96 100644
--- a/docs/data/Quickbar.html
+++ b/docs/data/Quickbar.html
@@ -406,7 +406,7 @@
generated by LDoc
diff --git a/docs/data/Tag.html b/docs/data/Tag.html
index 4ca8c3d6..0f53f092 100644
--- a/docs/data/Tag.html
+++ b/docs/data/Tag.html
@@ -484,7 +484,7 @@
generated by LDoc
diff --git a/docs/guis/Player-List.html b/docs/guis/Player-List.html
index b0f12a4f..005be88f 100644
--- a/docs/guis/Player-List.html
+++ b/docs/guis/Player-List.html
@@ -732,7 +732,7 @@
generated by LDoc
diff --git a/docs/guis/Readme.html b/docs/guis/Readme.html
index e79c9f55..d35b07c5 100644
--- a/docs/guis/Readme.html
+++ b/docs/guis/Readme.html
@@ -769,7 +769,7 @@
generated by LDoc
diff --git a/docs/guis/Rocket-Info.html b/docs/guis/Rocket-Info.html
index 81233cbf..7d119932 100644
--- a/docs/guis/Rocket-Info.html
+++ b/docs/guis/Rocket-Info.html
@@ -704,7 +704,7 @@
generated by LDoc
diff --git a/docs/guis/Science-Info.html b/docs/guis/Science-Info.html
index b024ec4d..35554414 100644
--- a/docs/guis/Science-Info.html
+++ b/docs/guis/Science-Info.html
@@ -583,7 +583,7 @@
generated by LDoc
diff --git a/docs/guis/Task-List.html b/docs/guis/Task-List.html
index 4020572d..234a52bf 100644
--- a/docs/guis/Task-List.html
+++ b/docs/guis/Task-List.html
@@ -769,7 +769,7 @@
generated by LDoc
diff --git a/docs/guis/Warps-List.html b/docs/guis/Warps-List.html
index bdd5376d..4d1a8a45 100644
--- a/docs/guis/Warps-List.html
+++ b/docs/guis/Warps-List.html
@@ -1040,7 +1040,7 @@
generated by LDoc
diff --git a/docs/guis/server-ups.html b/docs/guis/server-ups.html
index e41ea3c5..fd463d14 100644
--- a/docs/guis/server-ups.html
+++ b/docs/guis/server-ups.html
@@ -450,7 +450,7 @@
generated by LDoc
diff --git a/docs/index.html b/docs/index.html
index dc3b8ce7..118574fd 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -540,7 +540,7 @@ Events.set_event_filter(defines.events.on_built_entity, {{filter = "name", name
generated by LDoc
diff --git a/docs/modules/control.html b/docs/modules/control.html
index 7f3eb19a..ee9a3a9e 100644
--- a/docs/modules/control.html
+++ b/docs/modules/control.html
@@ -308,7 +308,7 @@
generated by LDoc
diff --git a/docs/modules/modules.addons.station-auto-name.html b/docs/modules/modules.addons.station-auto-name.html
index 83ac9ddb..61efcb6f 100644
--- a/docs/modules/modules.addons.station-auto-name.html
+++ b/docs/modules/modules.addons.station-auto-name.html
@@ -306,7 +306,7 @@ Events.set_event_filter(defines.events.on_built_entity, {{filter = "name", name
generated by LDoc
diff --git a/docs/modules/overrides.debug.html b/docs/modules/overrides.debug.html
index b175f514..f96e2246 100644
--- a/docs/modules/overrides.debug.html
+++ b/docs/modules/overrides.debug.html
@@ -667,7 +667,7 @@
generated by LDoc
diff --git a/docs/modules/overrides.math.html b/docs/modules/overrides.math.html
index 3bf9a513..01c6abf4 100644
--- a/docs/modules/overrides.math.html
+++ b/docs/modules/overrides.math.html
@@ -366,7 +366,7 @@
generated by LDoc
diff --git a/docs/modules/overrides.table.html b/docs/modules/overrides.table.html
index 72bc3296..2068f31c 100644
--- a/docs/modules/overrides.table.html
+++ b/docs/modules/overrides.table.html
@@ -2021,7 +2021,7 @@
generated by LDoc
diff --git a/docs/modules/utils.event.html b/docs/modules/utils.event.html
index 4efd1950..0d432869 100644
--- a/docs/modules/utils.event.html
+++ b/docs/modules/utils.event.html
@@ -1305,7 +1305,7 @@
generated by LDoc
diff --git a/docs/modules/utils.event_core.html b/docs/modules/utils.event_core.html
index 10b173aa..8a752b58 100644
--- a/docs/modules/utils.event_core.html
+++ b/docs/modules/utils.event_core.html
@@ -447,7 +447,7 @@
generated by LDoc
diff --git a/docs/modules/utils.task.html b/docs/modules/utils.task.html
index a8c63ed7..1936ce1c 100644
--- a/docs/modules/utils.task.html
+++ b/docs/modules/utils.task.html
@@ -664,7 +664,7 @@
generated by LDoc
diff --git a/docs/topics/LICENSE.html b/docs/topics/LICENSE.html
index 8d3a2cfa..b0ab1beb 100644
--- a/docs/topics/LICENSE.html
+++ b/docs/topics/LICENSE.html
@@ -802,7 +802,7 @@ Public License instead of this License. But first, please read
generated by LDoc
diff --git a/docs/topics/README.md.html b/docs/topics/README.md.html
index c825802b..1b4fd5f4 100644
--- a/docs/topics/README.md.html
+++ b/docs/topics/README.md.html
@@ -354,7 +354,7 @@ Please report these errors to [the issues page](issues).
generated by LDoc