Explosive Gaming's server scenario for 0.17
+ + +Core Module - Commands + - Factorio command making module that makes commands with better parse and more modularity
+ + + + + + + +
+---- Example Authenticator:
+ -- The command system is most useful when you can control who can use commands; to do this would would 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 some commands to require the user to be a game admin:
+
+ -- When the authenticator is called be the command handler it will be passed 4 vales:
+ -- 1) the player who used the command
+ -- 2) the name of the command that is being used
+ -- 3) any flags which have been set for this command, this is a table of values set using :set_flag(name,value)
+ -- 4) the reject function which is the preferred method to prevent execution of the command
+
+ -- For our admin only example we will set a flag to true when we want it do be admin only so when we define the
+ -- command will will use :set_flag('admin_only',true) and then inside the authenticator we will test if the flag
+ -- is present using: if flags.admin_only then
+
+ -- Although no return is required to allow the command to execute it is best practice to return true; we do this in
+ -- two cases in our authenticator:
+ -- 1) when the "admin_only" flag is not set, which we take to mean any one can use it
+ -- 2) when the "admin_only" flag is set, and the player is admin
+
+ -- Now when the user is not an admin and the command requires you to be an admin then we must reject the request:
+ -- 1) return false -- this is the most basic block and should only be used while testing
+ -- 2) return reject -- returning the reject function is only an option as a fail safe, same as returning false
+ -- 3) reject() -- this will block execution without returning to allow further code to be ran in the 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 code before rejecting
+
+ -- Example Code:
+ Commands.add_authenticator(function(player,command,flags,reject)
+ if flags.admin_only then -- our test for the "admin_only" flag
+ if player.admin then
+ return true -- true return 2
+ else
+ return reject('This command is for admins only!') -- reject return 5 with a custom error message
+ end
+ else
+ return true -- true return 1
+ end
+ end)
+---- Example Parse:
+ -- Before you go making commands 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 by an handler so before your
+ -- command is ever executed you can be sure that all the params are valid. 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
+ -- Example parse usage:
+ :add_param('repeat_count',false,'number-range-int',5,10) -- range 5 to 10 inclusive
+
+ -- The command parse will be passed 3 params and any other you define, in our case:
+ -- 1) the input that has been given by the user for this param, the role of this function is to transform this value
+ -- nb: the input is a string but can be nil if the param is marked as optional
+ -- 2) the player who is using the command, this is always present
+ -- 3) the reject function to throw an error to the user, this is always present
+ -- 4) the range min, this is user defined and has the value given when the param is defined
+ -- 5) the range max, this is user defined and has the value given when the param is defined
+
+ -- When returning from the param parse you again have a few options with how to do this:
+ -- 1) you return the new value for the param (any non nil value) this value is then passed to the command callback
+ -- 2) not returning will cause a generic invalid error and the command callback is blocked, not recommenced
+ -- 3) return reject -- this is just a failsafe in case the function is not called, same as no return
+ -- 4) return reject() -- will give a shorter error message as you pass a nil custom error
+ -- 5) return reject('Number entered is not in range: '..range_min..', '..range_max) -- returns a custom error the the user
+ -- nb: if you do not return reject after you call it then you are still returning nil so there will be a duplicate message
+
+ -- It should be noted that if you want to expand on an existing parse you can use Commands.parse(type,input,player,reject)
+ -- and this value will either return a new value for the input or nil, if it is nil you should return nil to prevent double
+ -- messages to the user:
+ input = Commands.parse('number-int',input,player,reject)
+ if not input then return end -- nil check
+
+ -- Example Code:
+ 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
+ return reject('Number entered is not in range: '..range_min..', '..range_max)
+ else
+ -- returns the input as a number value rather than a string, thus the param is now the correct type
+ return rtn
+ 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.
+
+ -- 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:
+ 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)
+
+ -- 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:
+ :add_param('smiley',true,function(input,player,reject)
+ -- 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
+ 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:
+ :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
+ }
+
+ -- 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
+
+ -- 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:
+ -- 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
+ 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
+ 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
+ end)
+
+ -- Some other useful functions that can be used are:
+ 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 Code:
+ 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('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
+ end)
+ :set_defaults{smiley=false}
+ :set_flag('admin_only',true) -- 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)
+ local msg = ') '..player.name
+ if smiley then
+ msg = ':'..msg
+ end
+ for 1 = 1,repeat_count do
+ Command.print(1..msg)
+ end
+ end)| utils.game | +
| expcore.common | +
| add_authenticator(callback) | +Adds an authorization callback, function used to check if a player if allowed to use a command | +
| remove_authenticator(callback) | +Removes an authorization callback | +
| authorize(player, command_name) | +Mostly used internally, calls all authorization callbacks, returns if the player is authorized | +
| get([player]) | +Gets all commands that a player is allowed to use, game commands not included | +
| search(keyword[, allowed_player]) | +Searches command names and help messages to find possible commands, game commands included | +
| add_parse(name, callback) | +Adds a parse function which can be called by name rather than callback (used in add_param) + nb: this is not needed 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 | +
| new_command(name, help) | +Creates a new command object to added details to, note this does not register the command to the game | +
| Commands._prototype:add_param(name[, optional=false][, parse=pass function through][, ...]) | +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) | +Adds default values to params only matters if the param is optional, if default value is a function it is called with param player | +
| Commands._prototype:set_flag(name, value) | +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 | +
| Commands._prototype:add_alias(any) | +Adds an alias or multiple that will also be registered with the same callback, eg /teleport can be /tp with both working | +
| 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 | +
| Commands._prototype:register(callback) | +Adds the callback to the command and registers all aliases, params and help message with the game + nb: this must be the last function ran on the command and must be done for the command to work | +
| error([error_message][, play_sound]) | +Sends an error message to the player and returns a constant to return to command handler to exit execution + nb: this is for non fatal errors meaning there is no log of this event + nb: if reject is giving as a param to the callback use that instead | +
| 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 the handler may still continue | +
| success([value]) | +Sends a value to the player, followed by a command complete message + nb: either return a value from your callback to trigger or return the return of this to prevent two messages | +
| run_command(command_event) | +Main event function that is ran for all commands, used internally please avoid direct use | +
Adds an authorization callback, function used to check if a player if allowed to use a command
+ + + + Parameters: + +Removes an authorization callback
+ + + + Parameters: + +Mostly used internally, calls all authorization callbacks, returns if the player is authorized
+ + + + Parameters: + +Gets all commands that a player is allowed to use, game commands not included
+ + + + Parameters: + +Searches command names and help messages to find possible commands, game commands included
+ + + + Parameters: + +Adds a parse function which can be called by name rather than callback (used in add_param) + nb: this is not needed as you can use the callback directly this just allows it to be called by name
+ + + + Parameters: + +Removes a parse function, see add_parse for adding them
+ + + + Parameters: + +Intended to be used within other parse functions, runs a parse and returns success and new value
+ + + + Parameters: + +Creates a new command object to added details to, note this does not register the command to the game
+ + + + Parameters: + +Adds a new param to the command this will be displayed in the help and used to parse the input
+ + + + Parameters: + +Adds default values to params only matters if the param is optional, if default value is a function it is called with param player
+ + + + Parameters: + +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
+ + + + Parameters: + +Adds an alias or multiple that will also be registered with the same callback, eg /teleport can be /tp with both working
+ + + + Parameters: + +command:add_alias('aliasOne','aliasTwo','etc')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
+ + + + + + + Returns: +Adds the callback to the command and registers all aliases, params and help message with the game + nb: this must be the last function ran on the command and must be done for the command to work
+ + + + Parameters: + +Sends an error message to the player and returns a constant to return to command handler to exit execution + nb: this is for non fatal errors meaning there is no log of this event + nb: if reject is giving as a param to the callback use that instead
+ + + + Parameters: + +return Commands.error()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 the handler may still continue
+ + + + Parameters: + +Sends a value to the player, followed by a command complete message + nb: either return a value from your callback to trigger or return the return of this to prevent two messages
+ + + + Parameters: + +Main event function that is ran for all commands, used internally please avoid direct use
+ + + + Parameters: + +Explosive Gaming's server scenario for 0.17
+ + +Core Module - Common Library + - Adds some commonly used functions used in many modules
+ + + + + + + + + + + + +| resources.color_presets | +
| utils.game | +
| util | +
| type_check(value[, test_type=nil]) | +Compare types faster for faster validation of params | +
| type_check_error(value, test_type, error_message, level) | +Raises an error if the value is of the wrong type | +
| param_check(value, test_type, param_name, param_number) | +Raises an error when the value is the incorrect type, uses a consistent error message format | +
| player_return(value[, colour=defines.colour.white][, player=game.player]) | +Will return a value of any type to the player/server console, allows colour for in-game players | +
| write_json(path, tbl) | +Writes a table object to a file in json format | +
| opt_require(path) | +Calls a require that will not error if the file is not found | +
| ext_require(path, ...) | +Calls a require and returns only the keys given, file must return a table | +
| format_time(ticks, options) | +Formats tick into a clean format, denominations from highest to lowest + long will use words rather than letters + time will use : separates + string will return a string not a locale string + when a denomination is false it will overflow into the next one | +
| move_items(items[, surface=navies][, position={0][, radius=32][, chest_type=iron-chest]) | +Moves items to the position and stores them in the closest entity of the type given | +
| print_grid_value(value, surface, position, scale, offset, immutable) | +https://github.com/Refactorio/RedMew/blob/9184b2940f311d8c9c891e83429fc57ec7e0c4a2/map_gen/maps/diggy/debug.lua#L31 + Prints a colored value on a location. | +
| print_colored_grid_value(value, surface, position, offset, immutable, color_value, base_color, delta_color, under_bound, over_bound) | +Prints a colored value on a location. | +
| clear_flying_text(surface) | +Clears all flying text entities on a surface | +
| string_contains(s, contains) | +Tests if a string contains a given substring. | +
| extract_keys(tbl, ...) | +Extracts certain keys from a table | +
| enum(tbl) | +Converts a table to an enum | +
| auto_complete(options, input[, use_key=false][, rtn_key=false]) | +Returns the closest match to the input | +
| table_values(tbl[, sorted][, as_string]) | +Returns a copy of all of the values in the table. | +
| table_keys(tbl[, sorted][, as_string]) | +Returns a copy of all of the keys in the table. | +
| table_alphanumsort(tbl) | +Returns the list is a sorted way that would be expected by people (this is by key) | +
| table_keysort(tbl) | +Returns the list is a sorted way that would be expected by people (this is by key) (faster alternative than above) | +
| format_chat_colour(message, color) | +Returns a message with valid chat tags to change its colour | +
| format_chat_colour_localized(message, color) | +Returns a message with valid chat tags to change its colour, using localization | +
| format_chat_player_name(player[, raw_string=false]) | +Returns the players name in the players color | +