Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -57,10 +57,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -56,10 +56,12 @@Makes trees which are marked for decon "decay" quickly to allow faster building
+ + + + + + + + + + + + +| utils.event | +
| utils.game | +
| utils.global | +
| expcore.roles | +
Greets players on join
+ + + + + + + + + + + + +| utils.event | +
| utils.event | +
| config.join_messages | +
| utils.global | +
Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -76,13 +76,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -77,13 +77,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -42,7 +42,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -51,7 +51,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -51,7 +51,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -42,7 +42,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -42,7 +42,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -51,7 +51,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -50,7 +50,6 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -66,13 +66,13 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -42,9 +42,9 @@| get_color(clamp, active_value, passive_value) | +Returns a color value bassed on the value that was given | +
| format_number(value) | +Returns three parts used to format a number | +
| get_color(clamp, active_value, passive_value) | -Returns a color value bassed on the value that was given | -
| format_number(value) | -Returns three parts used to format a number | -
Returns a color value bassed on the value that was given
+ + + + Parameters: + +Returns three parts used to format a number
+ + + + Parameters: + +Returns a color value bassed on the value that was given
- - - - Parameters: - -Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -65,13 +65,13 @@ @@ -86,10 +86,12 @@ + + @@ -98,8 +100,10 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -65,13 +65,13 @@ @@ -86,10 +86,12 @@ + + @@ -98,8 +100,10 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -65,13 +65,13 @@ @@ -86,10 +86,12 @@ + + @@ -98,8 +100,10 @@Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
@@ -66,13 +66,13 @@ @@ -87,10 +87,12 @@ + + @@ -99,8 +101,10 @@| utils.task | +
| utils.token | +
| register(callback) | +Register a new async function, must called when the file is loaded | +
| run(token[, ...]) | +Runs an async function, you may supply any number of arguments as required by that function | +
| wait(ticks, token[, ...]) | +Runs an async function after the given number of ticks, you may supply any number of arguments as required by that function | +
Register a new async function, must called when the file is loaded
+ + + + Parameters: + +-- Registering a function to set the admin state of a player
+local set_admin =
+Async.register(function(player, state)
+ if player.valid then
+ player.admin = state
+ end
+end)-- Registering a function to print to a player
+local print_to_player =
+Async.register(function(player, message)
+ if player.valid then
+ player.print(message)
+ end
+end)Runs an async function, you may supply any number of arguments as required by that function
+ + + + Parameters: + +-- Make a player admin regardless of if you are admin
+Async.run(set_admin, player, true)Runs an async function after the given number of ticks, you may supply any number of arguments as required by that function
+ + + + Parameters: + +-- Print a message to a player after 5 seconds
+Async.wait(300, print_to_player, 'Hello, World!')Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
----- 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.')
+ --- Full code example, see below for explaination
+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)
- -- 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)
+ local msg = ') '..player.name
+ if smiley then
+ msg = ':'..msg
+ end
- -- 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
+ for 1 = 1,repeat_count do
+ 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.
- -- 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)
+-- 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.')
- -- 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
+-- 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)
- -- 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)
+-- 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)
+
+-- 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
+--- 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;
+-- 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);
+-- 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:
+-- 1) player - the player who used the command
+-- 2) command - the name of the command that is being used
+-- 3) flags - the flags which have been set for this command, flags are set with :set_flag(name, value)
+-- 4) reject - the reject function which is the preferred method to prevent execution of the command
+
+-- No return is required to allow the command to execute but 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 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:
+-- 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
+-- 5) return reject() -- using return on either case above is best practice as you should execute all your code before rejecting
+
+-- Example Code:
+Commands.add_authenticator(function(player, command, flags, reject)
+ -- Check if the command is admin only
+ if flags.admin_only then
+ -- Return true if player is admin, or reject and return error message
+ return player.admin or reject('This command is for admins only!')
+ else
+ -- Return true if command was not admin only
+ return true
+ end
+end)--- Example Parse:
+-- 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.
+
+-- 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
+
+-- 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
+-- nb: the input is a string but can be nil if the param is marked as optional
+-- 2) player - the player who is using the command, this is always present
+-- 3) reject - the reject function to throw an error to the user, this is always present
+-- 4) range_min - the range min, this is user defined and has the value given when the param is defined
+-- 5) range_max - the range max, this is user defined and has the value given when the param is defined
+
+-- When returning from the param parse you 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 is rejected, 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 to the user
+-- nb: if you do not return reject after you call it then you will still be returning nil so there will be a duplicate error message
+
+-- It should be noted that if you want to expand on an existing parse you can use Commands.parse(type, input, player, reject)
+-- this function will either return a new value for the input or nil, if it is nil you should return nil to prevent duplicate
+-- error 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)| defines | +Values returned by the signal functions to cause the command system to react | +
| commands | +Custom command data will be stored here | +
| authorization | +Custom function are stored here which control who can use what commands | +
| parse_functions | +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 | +
| authorization_fail_on_error | +Set true to have authorize fail if a callback fails to run, more secure | +
| get([player]) | -Gets all commands that a player is allowed to use, game commands not included | +Gets all commands that a player is allowed to use, game commands are not included | |
| search(keyword[, allowed_player]) | -Searches command names and help messages to find possible commands, game commands included | +search(keyword[, player]) | +Searches command names and help messages to find possible commands, game commands are included |
Values returned by the signal functions to cause the command system to react
+ + + + Fields: + +Custom command data will be stored here
+ + + + + + + + + + + + + + + + +Custom function are stored here which control who can use what commands
+ + + + + + + + + + + + + + + + +Used to store default functions which are common parse function such as player or number in range
+ + + + + + + + + + + + + + + + +Used to store functions which gets added to new custom commands
+ + + + + + + + + + + + + + + + + +Set true to have authorize fail if a callback fails to run, more secure
+ + + + + + + + + @@ -662,10 +921,6 @@ (function) the callback you want to register as an authenticator - callback param - player: LuaPlayer - the player who is trying to use the command - callback param - command: string - the name of the command which is being used - callback param - flags: table - any flags which have been set for the command - callback param - reject: function(error_message?: string) - call to fail authorize with optional error message @@ -689,6 +944,16 @@ + Usage: +-- Test if a command is admin only and if the player is 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!')
+ else
+ return true
+ end
+end)-- Removing the admin authenticator, can not be done dueing runtime
+Commands.remove_authenticator(admin_authenticator)-- Test if a player can use "repeat-name"
+local authorized, status = Commands.authorize(game.player, 'repeat-name')Gets all commands that a player is allowed to use, game commands not included
+Gets all commands that a player is allowed to use, game commands are not included
@@ -895,6 +1166,11 @@ + 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()Searches command names and help messages to find possible commands, game commands included
+Searches command names and help messages to find possible commands, game commands are included
@@ -928,7 +1204,7 @@ (string) - the word which you are trying to find + the word which you are trying to find in your search @@ -938,7 +1214,7 @@-- 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)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
+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
@@ -1023,10 +1304,6 @@ (function) the callback that is ran to parse the input - parse param - input: string - the input given by the user for this param - parse param - player: LuaPlayer - the player who is using the command - parse param - reject: function(error_message) - use this function to send a error to the user and fail running - parse return - the value that will be passed to the command callback, must not be nil and if reject then command is not run @@ -1050,6 +1327,18 @@ + Usage: +-- Adding a parse to validate ints 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
+ 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
+ return rtn
+ end
+end)-- Removing a parse
+Commands.remove_parse('number-range-int')-- 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
+Creates a new command object to added details to, note this does not register the command to the game
+Creates a new command object to added details to, note this does not register the command to the game api
@@ -1281,6 +1577,10 @@ + Usage: +-- Define a new command
+local command =
+Commands.new_command('repeat-name', 'Will repeat you name a number of times in chat.')-- 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
+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
+end)Adds default values to params only matters if the param is optional, if default value is a function it is called with param 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 acting player
@@ -1425,8 +1729,7 @@ (table) - table a keyed by the name of the param with the value as the default value {paramName=defaultValue} - callback param - player: LuaPlayer - the player using the command, default value does not need to be a function callback + table which is keyed by the name of the param and the value is the default value @@ -1450,6 +1753,15 @@ + Usage: +-- Adding default values
+command:set_defaults{
+ smiley = false,
+ -- not in example just used to show arguments given
+ player_name = function(player)
+ return player.name
+ end
+}-- Setting a custom flag
+command:set_flag('admin_only', true)-- When value is true it does not need to be given
+command:set_flag('admin_only')Adds an alias or multiple that will also be registered with the same callback, eg /teleport can be /tp with both working
+Adds an alias, or multiple, that will also be registered with the same callback, eg /teleport can be used as /tp
@@ -1582,7 +1899,8 @@ Usage: -command:add_alias('aliasOne','aliasTwo','etc')-- Added multiple aliases to a command
+command:add_alias('name', 'rname')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
+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 @@ -1619,6 +1937,9 @@ + Usage: +-- Enable auto concat for a command
+command:enable_auto_concat()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
+Adds the callback to the command and registers all aliases, params and help message with the game api +nb: this must be the last function ran on the command and must be done for the command to work
@@ -1654,9 +1975,6 @@ (function) the callback for the command, will receive the player running command, and params added with add_param - callback param - player: LuaPlayer - the player who used the command - callback param - ... - any params which were registered with add_param in the order they where registered - callback param - raw: string - the raw input from the user, comes after every param added with add_param @@ -1673,6 +1991,16 @@ + Usage: +-- Registering your command to the game api
+command:register(function(player, repeat_count, smiley, _)
+ local msg = ') '..player.name
+ if smiley then msg = ':'..msg end
+
+ for 1 = 1,repeat_count do
+ Command.print(1..msg)
+ end
+end)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
+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
@@ -1713,7 +2040,7 @@ an optional error message that can be sent to the user - (optional) + (default: '') @@ -1730,7 +2057,7 @@ the sound to play for the error - (optional) + (default: utility/wire_pickup) @@ -1754,7 +2081,8 @@ Usage: -return Commands.error()-- Send an error message to the player, and stops further code running
+return Commands.error('The player you selected is offline')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
+nb: use error(error_message) within your callback to trigger do not trigger directly as code exictuion may still continue @@ -1845,6 +2173,12 @@ + 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)
+endSends 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
+nb: returning any value from your callback will trigger this function, return this function to prevent duplicate messages @@ -1904,6 +2238,80 @@ + Usage: +-- Print a custom success message
+return Commands.success('Your message has been printed')-- Returning the value has the same result
+return 'Your message has been printed'Sends a value to the player, different to success as this does not signal the end of your command
+ + + + Parameters: + +-- Output a message to the player
+Commands.print('Your command is in progress')Commands.run_command(event)| type_check(value[, test_type=nil]) | -Compare types faster for faster validation of params | +Asserts the argument is of type test_type | |
| type_check_error(value, test_type, error_message, level) | +type_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) | +multi_type_check(value, test_types) | +Asserts the argument is one of type test_types | +|
| multi_type_error(value, test_types, error_message, level) | +Raises an error if the value is of the wrong type | +||
| validate_argument_type(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 | +validate_argument_multi_type(value, test_types, param_name, param_number) | +Raises an error when the value is the incorrect type, uses a consistent error message format | +
| error_if_runtime() | +Will raise an error if called during runtime | +||
| error_if_runetime_closure(func) | +Will raise an error if the function is a closure | +
| string_contains(s, contains) | +Tests if a string contains a given substring. | +||
| resolve_value(value) | +Used to resolve a value that could also be a function returning that value | +||
| get_actor() | +Returns a valid string with the name of the actor of a command. | +||
| cast_bool(var) | +Converts a varible into its boolean value, nil and false return false | +||
| ternary(c, t, f) | +Returns either the second or third argument based on the first argument | +||
| comma_value(n) | +Returns a string for a number with comma seperators | +||
| set_and_return(tbl, key, value) | +Sets a table element to value while also returning value. | ||
| write_json(path, tbl) | @@ -285,8 +342,40 @@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 | +get_file_path([offset=0]) | +Returns a desync safe file path for the current file | +
| 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 | +
| 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 | +
| 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 |
| format_time(ticks, options) | @@ -296,6 +385,14 @@ 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 | @@ -313,66 +410,6 @@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 | -||
| get_file_path([offset=0]) | -Returns a desync safe file path for the current file | -||
| array_insert(tbl[, start_index], values) | -Much faster method for inserting items into an array | -||
| table_insert(tbl[, start_index], tbl2) | -Much faster method for inserting keys into a table | -||
| resolve_value(value) | -Used to resolve a value that could also be a function returning that value | -
Compare types faster for faster validation of params
+Asserts the argument is of type test_type
@@ -540,8 +577,8 @@type_check_error('foo','number','Value must be a number') -- will raise error "Value must be a number"type_error('foo','number','Value must be a number') -- will raise error "Value must be a number"Asserts the argument is one of type test_types
+ + + + Parameters: + +Raises an error if the value is of the wrong type
+ + + + Parameters: + +multi_type_error('foo',{'string','table'},'Value must be a string or table') -- will raise error "Value must be a string or table"param_check('foo','number','repeat_count',2) -- will raise error "Invalid param #02 given to <anon>; repeat_count is not of type number"validate_argument_type('foo','number','repeat_count',2) -- will raise error "Bad argument #02 to "<anon>"; "repeat_count" is of type string expected number"Will return a value of any type to the player/server console, allows colour for in-game players
+Raises an error when the value is the incorrect type, uses a consistent error message format
@@ -779,8 +994,9 @@ : + (any) - any value of any type that will be returned to the player or console + the value that you want to test the type of @@ -790,15 +1006,14 @@validate_argument_type('foo',{'string','table'},'repeat_count',2) -- will raise error "Bad argument #02 to "<anon>"; "repeat_count" is of type string expected string or table"Will raise an error if called during runtime
+ + + + + + + + + + + + + + Usage: +error_if_runtime()Will raise an error if the function is a closure
+ + + + Parameters: + +player_return('Hello, World!') -- returns 'Hello, World!' to game.player or server consoleplayer_return('Hello, World!','green') -- returns 'Hello, World!' to game.player with colour green or server consoleplayer_return('Hello, World!',nil,player) -- returns 'Hello, World!' to the given playererror_if_runetime_closure(func)Tests if a string contains a given substring.
+ + + + Parameters: + +Used to resolve a value that could also be a function returning that value
+ + + + Parameters: + +-- Default value handling
+-- if default value is not a function then it is returned
+-- if it is a function then it is called with the first argument being self
+local value = Common.resolve_value(self.defaut_value,self)Returns a valid string with the name of the actor of a command.
+ + + + + + + Returns: +Converts a varible into its boolean value, nil and false return false
+ + + + Parameters: + +Returns either the second or third argument based on the first argument
+ + + + Parameters: + +Returns a string for a number with comma seperators
+ + + + Parameters: + +Sets a table element to value while also returning value.
+ + + + Parameters: + +Calls a require and returns only the keys given, file must return a table
+Returns a desync safe file path for the current file
@@ -986,29 +1738,71 @@Converts a table to an enum
+ + + + Parameters: + +Returns the closest match to the input
+ + + + Parameters: + +Returns a message with valid chat tags to change its colour
+ + + + Parameters: + +Returns a message with valid chat tags to change its colour, using localization
+ + + + Parameters: + +Returns the players name in the players color
+ + + + Parameters: + +Will return a value of any type to the player/server console, allows colour for in-game players
+ + + + Parameters: + +local extract, param_check = ext_require('expcore.common','extract','param_check') --- @dep expcore.commonplayer_return('Hello, World!') -- returns 'Hello, World!' to game.player or server consoleplayer_return('Hello, World!','green') -- returns 'Hello, World!' to game.player with colour green or server consoleplayer_return('Hello, World!',nil,player) -- returns 'Hello, World!' to the given playerTests if a string contains a given substring.
- - - - Parameters: - -Extracts certain keys from a table
- - - - Parameters: - -local key_three, key_one = extract({key_one='foo',key_two='bar',key_three=true},'key_three','key_one')Converts a table to an enum
- - - - Parameters: - -Returns the closest match to the input
- - - - Parameters: - -Returns a copy of all of the values in the table.
- - - - Parameters: - -Returns a copy of all of the keys in the table.
- - - - Parameters: - -Returns the list is a sorted way that would be expected by people (this is by key)
- - - - Parameters: - -Returns the list is a sorted way that would be expected by people (this is by key) (faster alternative than above)
- - - - Parameters: - -Returns a message with valid chat tags to change its colour
- - - - Parameters: - -Returns a message with valid chat tags to change its colour, using localization
- - - - Parameters: - -Returns the players name in the players color
- - - - Parameters: - -Returns a desync safe file path for the current file
- - - - Parameters: - -Much faster method for inserting items into an array
- - - - Parameters: - --- Adding 1000 values into the middle of the array
-local tbl = {}
-local values = {}
-for i = 1,1000 do tbl[i] = i values[i] = i end
-Common.array_insert(tbl,500,values) -- around 0.4msMuch faster method for inserting keys into a table
- - - - Parameters: - --- Merging two tables
-local tbl = {}
-local tbl2 = {}
-for i = 1,100 do tbl[i] = i tbl['_'..i] = i tbl2[i] = i tbl2['__'..i] = i end
-Common.table_insert(tbl,50,tbl2)Used to resolve a value that could also be a function returning that value
- - - - Parameters: - --- Default value handling
--- if default value is not a function then it is returned
--- if it is a function then it is called with the first argument being self
-local value = Common.resolve_value(self.defaut_value,self)Core Module - Common +- Adds some commonly used functions used in many modules
+ + + + + + + + + + + + +| utils.color_presets | +
| utils.game | +
| util | +
| type_check(value[, test_type=nil]) | +Asserts the argument is of type test_type | +
| type_error(value, test_type, error_message, level) | +Raises an error if the value is of the wrong type | +
| multi_type_check(value, test_types) | +Asserts the argument is one of type test_types | +
| multi_type_error(value, test_types, error_message, level) | +Raises an error if the value is of the wrong type | +
| validate_argument_type(value, test_type, param_number[, param_name]) | +Raises an error when the value is the incorrect type, uses a consistent error message format | +
| validate_argument_multi_type(value, test_types, param_number[, param_name]) | +Raises an error when the value is the incorrect type, uses a consistent error message format | +
| error_if_runtime() | +Will raise an error if called during runtime | +
| error_if_runetime_closure(func) | +Will raise an error if the function is a closure | +
| string_contains(s, contains) | +Tests if a string contains a given substring. | +
| resolve_value(value) | +Used to resolve a value that could also be a function returning that value | +
| cast_bool(var) | +Converts a varible into its boolean value, nil and false return false | +
| ternary(c, t, f) | +Returns either the second or third argument based on the first argument | +
| comma_value(n) | +Returns a string for a number with comma seperators | +
| set_and_return(tbl, key, value) | +Sets a table element to value while also returning value. | +
| 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 | +
| get_file_path([offset=0]) | +Returns a desync safe file path for the current file | +
| 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 | +
| get_actor(player_name) | +Returns a valid string with the name of the actor of a command. | +
| 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 | +
| 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 | +
| format_time(ticks, options) | +Formats tick into a clean format, denominations from highest to lowest +-- time will use : separates +-- 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=1][, offset=0][, immutable=false]) | +Prints a colored value on a location, color is based on the value. | +
| clear_flying_text(surface) | +Clears all flying text entities on a surface | +
Asserts the argument is of type test_type
+ + + + Parameters: + +-- Check for a string value
+local is_string = type_check(value, 'string')-- Check for a nil value
+local is_nil = type_check(value)Raises an error if the value is of the wrong type
+ + + + Parameters: + +-- Raise error if value is not a number
+type_error(value, 'number', 'Value must be a number')Asserts the argument is one of type test_types
+ + + + Parameters: + +-- Check for a string or table
+local is_string_or_table = multi_type_check(value, {'string','table'})Raises an error if the value is of the wrong type
+ + + + Parameters: + +-- Raise error if value is not a string or table
+multi_type_error('foo', {'string','table'}, 'Value must be a string or table')Raises an error when the value is the incorrect type, uses a consistent error message format
+ + + + Parameters: + +-- Output: "Bad argument #2 to "<anon>"; argument is of type string expected number"
+validate_argument_type(value, 'number', 2)-- Output: "Bad argument #2 to "<anon>"; "repeat_count" is of type string expected number"
+validate_argument_type(value, 'number', 2, 'repeat_count')Raises an error when the value is the incorrect type, uses a consistent error message format
+ + + + Parameters: + +-- Output: "Bad argument #2 to "<anon>"; argument is of type number expected string or table"
+validate_argument_type(value, {'string','table'}, 2)-- Output: "Bad argument #2 to "<anon>"; "player" is of type number expected string or table"
+validate_argument_type(value, {'string','table'}, 2, 'player')Will raise an error if called during runtime
+ + + + + + + + + + + + + + Usage: +error_if_runtime()Will raise an error if the function is a closure
+ + + + Parameters: + +error_if_runetime_closure(func)Tests if a string contains a given substring.
+ + + + Parameters: + +-- Test if a string contains a sub string
+local found = string_contains(str, 'foo')Used to resolve a value that could also be a function returning that value
+ + + + Parameters: + +-- Default value handling
+-- if default value is not a function then it is returned
+-- if default value is a function then it is called with the first argument being self
+local value = Common.resolve_value(self.defaut_value, self)Converts a varible into its boolean value, nil and false return false
+ + + + Parameters: + +local bool = cast_bool(var)Returns either the second or third argument based on the first argument
+ + + + Parameters: + +ternary(input_string == 'test', 'Input is test', 'Input is not test')Returns a string for a number with comma seperators
+ + + + Parameters: + +comma_value(input_number)Sets a table element to value while also returning value.
+ + + + Parameters: + +-- Set and return value
+local value = set_and_return(players, player.name, player.online_time)Writes a table object to a file in json format
+ + + + Parameters: + +-- Write a lua table as a json to script-outpt/dump
+write_json('dump', tbl)Calls a require that will not error if the file is not found
+ + + + Parameters: + +local file = opt_require('file.not.present') -- will not cause any error-- Require a file without causing errors, for when a file might not exist
+local Module = opt_require 'expcore.common'Returns a desync safe file path for the current file
+ + + + Parameters: + +-- Get the current file path
+local file_path = get_file_path()Converts a table to an enum
+ + + + Parameters: + +-- Make an enum
+local colors = enum{
+ 'red',
+ 'green',
+ 'blue'
+}Returns the closest match to the input
+ + + + Parameters: + +-- Get the element that includes "foo"
+local value = auto_complete(tbl, "foo")-- Get the element with a key that includes "foo"
+local value = auto_complete(tbl, "foo", true)-- Get the key with that includes "foo"
+local key = auto_complete(tbl, "foo", true, true)Returns a valid string with the name of the actor of a command.
+ + + + Parameters: + +-- Get the current actor
+local player_name = get_actor()Returns a message with valid chat tags to change its colour
+ + + + Parameters: + +-- Use factorio tags to color a chat message
+local message = format_chat_colour('Hello, World!', { r=355, g=100, b=100 })Returns a message with valid chat tags to change its colour, using localization
+ + + + Parameters: + +-- Use factorio tags and locale strings to color a chat message
+local message = format_chat_colour_localized('Hello, World!', { r=355, g=100, b=100 })Returns the players name in the players color
+ + + + Parameters: + +-- Format a players name using the players color as a string
+local message = format_chat_player_name(game.player, true)Will return a value of any type to the player/server console, allows colour for in-game players
+ + + + Parameters: + +-- Return a value to the current actor, rcon included
+player_return('Hello, World!')-- Return a value to the current actor, with color
+player_return('Hello, World!', 'green')-- Return to a player other than the current
+player_return('Hello, World!', nil, player)Formats tick into a clean format, denominations from highest to lowest +-- time will use : separates +-- when a denomination is false it will overflow into the next one
+ + + + Parameters: + +-- Output: "0h 5m"
+local time = format_time(18000, { hours=true, minutes=true, string=true })-- Output: "0 hours and 5 minutes"
+local time = format_time(18000, { hours=true, minutes=true, string=true, long=true })-- Output: "00:05:00"
+local time = format_time(18000, { hours=true, minutes=true, seconds=true, string=true })-- Output: "--:--:--"
+local time = format_time(18000, { hours=true, minutes=true, seconds=true, string=true, null=true })Moves items to the position and stores them in the closest entity of the type given
+ + + + Parameters: + +-- Copy all the items in a players inventory and place them in chests at {0,0}
+move_items(game.player.get_main_inventory().get_contents())Prints a colored value on a location, color is based on the value.
++nb: src is below but the gradent has been edited +https://github.com/Refactorio/RedMew/blob/9184b2940f311d8c9c891e83429fc57ec7e0c4a2/map_gen/maps/diggy/debug.lua#L31
+ + + Parameters: + +-- Place a 0 at {0,0}
+print_grid_value(0, game.player.surface, { x=0, y=0 })Clears all flying text entities on a surface
+ + + + Parameters: + +-- Remove all flying text on the surface
+clear_flying_text(game.player.surface)Core Module - Permission Groups +- Permission group making for factorio so you never have to make one by hand again
+ + + + + + + +--- Example Group (Allow All)
+-- here we will create an admin group however we do not want them to use the map editor or mess with the permission groups
+Permission_Groups.new_group('Admin') -- this defines a new group called "Admin"
+:allow_all() -- this makes the default to allow any input action unless set other wise
+:disallow{ -- here we disallow the input action we don't want them to use
+ 'add_permission_group',
+ 'delete_permission_group',
+ 'import_permissions_string',
+ 'map_editor_action',
+ 'toggle_map_editor'
+}--- Example Group (Disallow All)
+-- here we will create a group that cant do anything but talk in chat
+Permission_Groups.new_group('Restricted') -- this defines a new group called "Restricted"
+:disallow_all() -- this makes the default to disallow any input action unless set other wise
+:allow('write_to_console') -- here we allow them to chat, {} can be used here if we had more than one action
+| utils.game | +
| utils.event | +
| expcore.async | +
| new_group(name) | +Defines a new permission group that can have it actions set in the config | +
| get_group_by_name(name) | +Returns the group with the given name, case sensitive | +
| get_group_from_player(player) | +Returns the group that a player is in | +
| reload_permissions() | +Reloads/creates all permission groups and sets them to they configured state | +
| set_player_group(player, group) | +Sets a player's group to the one given, a player can only have one group at a time | +
| Permissions_Groups._prototype:set_action(action, state) | +Sets the allow state of an action for this group, used internally but is safe to use else where | +
| Permissions_Groups._prototype:allow(actions) | +Sets an action or actions to be allowed for this group even with disallow_all triggered, Do not use in runtime | +
| Permissions_Groups._prototype:disallow(actions) | +Sets an action or actions to be disallowed for this group even with allow_all triggered, Do not use in runtime | +
| Permissions_Groups._prototype:allow_all() | +Sets the default state for any actions not given to be allowed, useful with :disallow | +
| Permissions_Groups._prototype:disallow_all() | +Sets the default state for any action not given to be disallowed, useful with :allow | +
| Permissions_Groups._prototype:is_allowed(action) | +Returns if an input action is allowed for this group | +
| Permissions_Groups._prototype:create() | +Creates or updates the permission group with the configured actions, used internally | +
| Permissions_Groups._prototype:get_raw() | +Returns the LuaPermissionGroup that was created with this group object, used internally | +
| Permissions_Groups._prototype:add_player(player) | +Adds a player to this group | +
| Permissions_Groups._prototype:remove_player(player) | +Removes a player from this group | +
| Permissions_Groups._prototype:get_players([online]) | +Returns all player that are in this group with the option to filter to online/offline only | +
| Permissions_Groups._prototype:print(message) | +Prints a message to every player in this group | +
Defines a new permission group that can have it actions set in the config
+ + + + Parameters: + +-- Defining a new permission group
+Groups.new_group('Admin')Returns the group with the given name, case sensitive
+ + + + Parameters: + +-- Getting a permision group
+local admin_group = Groups.get_group_by_name('Admin')Returns the group that a player is in
+ + + + Parameters: + +-- Get your permission group
+local group = Groups.get_group_from_player(game.player)Reloads/creates all permission groups and sets them to they configured state
+ + + + + + + + + + + + + + Usage: +-- Reload the permission groups, used internally
+Groups.reload_permissions()Sets a player's group to the one given, a player can only have one group at a time
+ + + + Parameters: + +-- Set your permission group
+Groups.set_player_group(game.player, 'Admin')Sets the allow state of an action for this group, used internally but is safe to use else where
+ + + + Parameters: + +-- Set an action to be disalowed
+group:set_action('toggle_map_editor', false)Sets an action or actions to be allowed for this group even with disallow_all triggered, Do not use in runtime
+ + + + Parameters: + +-- Allow some actions
+group:allow{
+ 'write_to_console'
+}Sets an action or actions to be disallowed for this group even with allow_all triggered, Do not use in runtime
+ + + + Parameters: + +-- Disalow some actions
+group:disallow{
+ 'add_permission_group',
+ 'delete_permission_group',
+ 'import_permissions_string',
+ 'map_editor_action',
+ 'toggle_map_editor'
+}Sets the default state for any actions not given to be allowed, useful with :disallow
+ + + + + + + Returns: +-- Allow all actions unless given by disallow
+group:allow_all()Sets the default state for any action not given to be disallowed, useful with :allow
+ + + + + + + Returns: +-- Disallow all actions unless given by allow
+group:disallow_all()Returns if an input action is allowed for this group
+ + + + Parameters: + +-- Test if a group is allowed an action
+local allowed = group:is_allowed('write_to_console')Creates or updates the permission group with the configured actions, used internally
+ + + + + + + Returns: +-- Create the permission group so players can be added, used internally
+group:create()Returns the LuaPermissionGroup that was created with this group object, used internally
+ + + + + + + Returns: +-- Get the factorio api permision group, used internally
+local permission_group = group:get_raw()Adds a player to this group
+ + + + Parameters: + +-- Add a player to this permission group
+group:add_player(game.player)Removes a player from this group
+ + + + Parameters: + +-- Remove a player from this permission group
+group:remove_player(game.player)Returns all player that are in this group with the option to filter to online/offline only
+ + + + Parameters: + +-- Get all players in this group
+local online_players = group:get_players()-- Get all online players in this group
+local online_players = group:get_players(true)Prints a message to every player in this group
+ + + + Parameters: + +-- Print a message to all players in thie group
+group:print('Hello, World!')Explosive Gaming's server scenario for 0.17
+Explosive Gaming's server scenario for 0.18
Core Module - Gui -- Used to define new gui elements and gui event handlers
+- Used to simplify gui creation using factory functions called element defines @@ -245,65 +248,114 @@-- Defining a button that prints the player's name
+ -- To draw your element you only need to call the factory function
+-- You are able to pass any other arguments that are used in your custom functions but the first is always the parent element
+local example_button_element = example_button(parent_element)
+ -- Making a factory function for a button with the caption "Example Button"
+-- This method has all the same features as LuaGuiElement.add
local example_button =
Gui.element{
type = 'button',
caption = 'Example Button'
-}
-:on_click(function(player,element,event)
- player.print(player.name)
-end)
- -- Defining a button with a custom style
-local example_button =
-Gui.element{
- type = 'button',
- caption = 'Example Button'
-}
-:style{
- height = 25,
- width = 100
-}
-:on_click(function(player,element,event)
- player.print(player.name)
-end)
- -- Defining a button using a custom function
+}
+ -- Making a factory function for a button which is contained within a flow
+-- This method is for when you still want to register event handlers but cant use the table method
local example_flow_with_button =
-Gui.element(function(event_trigger,parent)
- -- Add the flow the button is in
+Gui.element(function(event_trigger,parent,...)
+ -- ... shows that all other arguments from the factory call are passed to this function
+ -- Here we are adding a flow which we will then later add a button to
local flow =
- parent.add{
- name = 'example_flow',
+ parent.add{ -- paraent is the element which is passed to the factory function
+ name = 'example_flow',
type = 'flow'
}
- -- Get the players name
- local player = game.players[parent.player_index]
- local player_name = player.name
-
- -- Add the button
+ -- Now we add the button to the flow that we created earlier
local element =
flow.add{
- name = event_trigger,
- type = 'button',
- caption = 'Example Button: '..player_name
+ name = event_trigger, -- event_trigger should be the name of any elements you want to trigger your event handlers
+ type = 'button',
+ caption = 'Example Button'
}
- -- Set the style of the button
- local style = element.style
- style.height = 25
- style.width = 100]
- style.font_color = player.color
-
- -- Return the element
+ -- You must return a new element, this is so styles can be applied and returned to the caller
+ -- You may return any of your elements that you added, consider the context in which it will be used for which should be returned
return element
-end)
-:on_click(function(player,element,event)
- player.print(player.name)
end)
- -- Drawing an element
-local exmple_button_element = example_button(parent)
-local example_flow_with_button = example_flow_with_button(parent)
+ -- Styles can be added to any element define, simplest way mimics LuaGuiElement.style[key] = value
+local example_button =
+Gui.element{
+ type = 'button',
+ caption = 'Example Button',
+ style = 'forward_button' -- factorio styles can be applied here
+}
+:style{
+ height = 25, -- same as element.style.height = 25
+ width = 100 -- same as element.style.width = 25
+}
+ -- Styles can also have a custom function when the style is dynamic and depends on other factors
+-- Use this method if your style is dynamic and depends on other factors
+local example_button =
+Gui.element{
+ type = 'button',
+ caption = 'Example Button',
+ style = 'forward_button' -- factorio styles can be applied here
+}
+:style(function(style,element,...)
+ -- style is the current style object for the elemenent
+ -- element is the element that is being changed
+ -- ... shows that all other arguments from the factory call are passed to this function
+ local player = game.players[element.player_index]
+ style.height = 25
+ style.width = 100
+ style.font_color = player.color
+end)
+ -- You are able to register event handlers to your elements, these can be factorio events or custom ones
+-- All events are checked to be valid before raising any handlers, this means element.valid = true and player.valid = true
+Gui.element{
+ type = 'button',
+ caption = 'Example Button'
+}
+:on_click(function(player,element,event)
+ -- player is the player who interacted with the element to cause the event
+ -- element is a refrence to the element which caused the event
+ -- event is a raw refrence to the event data if player and element are not enough
+ player.print('Clicked: '..element.name)
+end)
+ -- Example from core_defines, Gui.core_defines.hide_left_flow, called like: hide_left_flow(parent_element)
+--- Button which hides the elements in the left flow, shows inside the left flow when frames are visible
+-- @element hide_left_flow
+local hide_left_flow =
+Gui.element{
+ type = 'sprite-button',
+ sprite = 'utility/close_black',
+ style = 'tool_button',
+ tooltip = {'expcore-gui.left-button-tooltip'}
+}
+:style{
+ padding = -3,
+ width = 18,
+ height = 20
+}
+:on_click(function(player,_,_)
+ Gui.hide_left_flow(player)
+end)
+ -- Eample from defines, Gui.alignment, called like: Gui.alignment(parent, name, horizontal_align, vertical_align)
+-- Notice how _ are used to blank arguments that are not needed in that context and how they line up with above
+Gui.alignment =
+Gui.element(function(_,parent,name,_,_)
+ return parent.add{
+ name = name or 'alignment',
+ type = 'flow',
+ }
+end)
+:style(function(style,_,_,horizontal_align,vertical_align)
+ style.padding = {1,2}
+ style.vertical_align = vertical_align or 'center'
+ style.horizontal_align = horizontal_align or 'right'
+ style.vertically_stretchable = style.vertical_align ~= 'center'
+ style.horizontally_stretchable = style.horizontal_align ~= 'center'
+end)
@@ -330,24 +382,28 @@ Gui.element(function(event_trigger,parent)
- top_elements
- Contains the uids of the elements that will show on the top flow and the auth function
-
-
- left_elements
- Contains the uids of the elements that will show on the left flow and the open on join function
+ events
+ String indexed table used to avoid conflict with custom event names, similar to how defines.events works
defines
- Table of all the elements which have been registed with the draw function and event handlers
+ Uid indexed array that stores all the factory functions that were defined, no new values will be added during runtime
+
+
+ core_defines
+ An string indexed table of all the defines which are used by the core of the gui system, used for internal refrence
file_paths
- An index used for debuging to find the file where different elements where registered
+ Used to store the file names where elements were defined, this can be useful to find the uid of an element, mostly for debuging
+
+
+ debug_info
+ Used to store extra infomation about elements as they get defined such as the params used and event handlers registered to them
_prototype_element
- The element prototype which is returned from Gui.element
+ The prototype used to store the functions of an element define
_mt_element
@@ -363,7 +419,139 @@ Gui.element(function(event_trigger,parent)
uid
- The current highest uid that is being used, will not increase during runtime
+ The current highest uid that is being used by a define, will not increase during runtime
+
+
+
+
+
+ Core Defines
+
+
+
+
+ hide_top_flow
+ Button which toggles the top flow elements, version which shows inside the top flow when top flow is visible
+
+
+ show_top_flow
+ Button which toggles the top flow elements, version which shows inside the left flow when top flow is hidden
+
+
+ hide_left_flow
+ Button which hides the elements in the left flow, shows inside the left flow when frames are visible
+
+
+
+
+
+ Defines
+
+
+
+
+ alignment
+ Draw a flow used to align its child elements, default is right align
+
+
+ scroll_table
+ Draw a scroll pane that has a table inside of it
+
+
+ header
+ Used to add a frame with the header style, has the option for a right alignment flow for buttons
+
+
+ footer
+ Used to add a frame with the footer style, has the option for a right alignment flow for buttons
+
+
+ container
+ Used for left frames to give them a nice boarder
+
+
+ bar
+ Used to make a solid white bar in a gui
+
+
+ centered_label
+ Used to make a label which is centered and of a certian size
+
+
+ title_label
+ Used to make a title which has two bars on either side
+
+
+
+
+
+ Helper Functions
+
+
+
+
+ get_player_from_element(element)
+ Get the player that owns a gui element
+
+
+ toggle_enabled_state(element[, state])
+ Will toggle the enabled state of an element or set it to the one given
+
+
+ toggle_visible_state(element[, state])
+ Will toggle the visible state of an element or set it to the one given
+
+
+ destroy_if_valid(element)
+ Destory a gui element without causing any errors, often because the element was already removed
+
+
+ sprite_style(size[, padding=-2][, style])
+ Returns a table to be used as the style for a sprite buttons, produces a sqaure button
+
+
+
+
+
+ Left Flow
+
+
+
+
+ left_elements
+ Contains the uids of the elements that will shown on the left flow and their join functions
+
+
+ get_left_flow(player)
+ Gets the flow refered to as the left flow, each player has one left flow
+
+
+ Gui._prototype_element:add_to_left_flow([open_on_join])
+ Sets an element define to be drawn to the left flow when a player joins, includes optional check
+
+
+ left_toolbar_button(sprite, tooltip, element_define[, authenticator])
+ Creates a button on the top flow which will toggle the given element define, the define must exist in the left flow
+
+
+ draw_left_flow(player)
+ Draw all the left elements onto the left flow, internal use only with on join
+
+
+ update_left_flow(player)
+ Update the visible state of the hide button, can be used to check if any frames are visible
+
+
+ hide_left_flow(player)
+ Hides all left elements for a player
+
+
+ get_left_element(player, element_define)
+ Get the element define that is in the left flow, use in events without an element refrence
+
+
+ toggle_left_element(player, element_define[, state])
+ Toggles the visible state of a left element for a given player, can be used to set the visible state
@@ -375,19 +563,19 @@ Gui.element(function(event_trigger,parent)
element(element_define)
- Base function used to define new elements, can be used with a table or with a function
+ Used to define new elements for your gui, can be used like LuaGuiElement.add or a custom function
Gui._prototype_element:style(style_define)
- Extension of Gui.element when using the table method, values applied after the element is drawn
+ Used to extent your element define with a style factory, this style will be applied to your element when created, can also be a custom function
- Gui._prototype_element:add_to_top_flow([authenticator])
- Adds an element to be drawn to the top flow when a player joins
+ Gui._prototype_element:on_custom_event(event_name, handler)
+ Set the handler which will be called for a custom event, only one handler can be used per event per element
- Gui._prototype_element:add_to_left_flow([open_on_join])
- Adds an element to be drawn to the left flow when a player joins
+ Gui._prototype_element:raise_custom_event(event)
+ Raise the handler which is attached to an event; external use should be limited to custom events
@@ -398,11 +586,11 @@ Gui.element(function(event_trigger,parent)
- Gui._prototype_element.on_opened
+ Gui._prototype_element.on_open
Called when the player opens a GUI.
- Gui._prototype_element.on_closed
+ Gui._prototype_element.on_close
Called when the player closes the GUI they have open.
@@ -438,7 +626,7 @@ Gui.element(function(event_trigger,parent)
Called when LuaGuiElement switch state is changed (related to switches).
- Gui._prototype_element.on_text_change
+ Gui._prototype_element.on_text_changed
Called when LuaGuiElement text is changed by the player.
@@ -454,84 +642,44 @@ Gui.element(function(event_trigger,parent)
- toggle_top_flow
- Button which toggles the top flow elements
+ top_elements
+ Contains the uids of the elements that will shown on the top flow and their auth functions
top_flow_button_style
The style that should be used for buttons on the top flow
+ top_flow_button_visible_style
+ The style that should be used for buttons on the top flow when their flow is visible
+
+
get_top_flow(player)
- Gets the flow which contains the elements for the top flow
+ Gets the flow refered to as the top flow, each player has one top flow
+
+
+ Gui._prototype_element:add_to_top_flow([authenticator])
+ Sets an element define to be drawn to the top flow when a player joins, includes optional authenticator
update_top_flow(player)
- Updates the visible states of all the elements on a players top flow
+ Updates the visible state of all the elements on the players top flow, uses authenticator
toggle_top_flow(player[, state])
- Toggles the visible states of all the elements on a players top flow
-
-
-
-
-
- Left Flow
-
-
-
-
- hide_left_flow
- Button which hides the elements in the left flow
+ Toggles the visible state of all the elements on a players top flow, effects all elements
- get_left_flow(player)
- Gets the flow which contains the elements for the left flow
+ get_top_element(player, element_define)
+ Get the element define that is in the top flow, use in events without an element refrence
- hide_left_flow(player)
- Hides all left elements for a player
+ toolbar_button(sprite, tooltip[, authenticator])
+ Creates a button on the top flow with consistent styling
- toggle_left_element(player, element_define[, state])
- Toggles the visible state of all a left element for a player
-
-
-
-
-
- Helper Functions
-
-
-
-
- get_player_from_element(element)
- Get the player that owns a gui element
-
-
- toggle_enabled_state(element[, state])
- Will toggle the enabled state of an element or set it to the one given
-
-
- toggle_visible_state(element[, state])
- Will toggle the visible state of an element or set it to the one given
-
-
- destroy_if_valid(element)
- Destory a gui element without causing any errors, likly if the element may have already been removed
-
-
- alignment(parent[, horizontal_align='right'][, vertical_align='center'][, name='alignment'])
- Draw a flow that has custom element alignments, default is right align
-
-
- scroll_table(parent, height, column_count[, name='scroll'])
- Draw a scroll pane that has a table inside of it
-
-
- header(parent, caption[, tooltip][, add_alignment=false][, name='header'])
- Used to add a header to a frame, this has the option for a custom right alignment flow for buttons
+ toolbar_button_style(button, state)
+ Styles a top flow button depending on the state given
@@ -598,41 +746,14 @@ Gui.element(function(event_trigger,parent)
-
-
-
Contains the uids of the elements that will show on the top flow and the auth function
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -
-
-
- #
- left_elements
-
-
- -
-
-
-
Contains the uids of the elements that will show on the left flow and the open on join function
+ String indexed table used to avoid conflict with custom event names, similar to how defines.events works
@@ -659,7 +780,34 @@ Gui.element(function(event_trigger,parent)
-
-
Table of all the elements which have been registed with the draw function and event handlers
+ Uid indexed array that stores all the factory functions that were defined, no new values will be added during runtime
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
+ #
+ core_defines
+
+
+ -
+
+
+
An string indexed table of all the defines which are used by the core of the gui system, used for internal refrence
@@ -686,7 +834,34 @@ Gui.element(function(event_trigger,parent)
-
-
An index used for debuging to find the file where different elements where registered
+ Used to store the file names where elements were defined, this can be useful to find the uid of an element, mostly for debuging
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
+ #
+ debug_info
+
+
+ -
+
+
+
Used to store extra infomation about elements as they get defined such as the params used and event handlers registered to them
@@ -713,7 +888,7 @@ Gui.element(function(event_trigger,parent)
-
-
The element prototype which is returned from Gui.element
+ The prototype used to store the functions of an element define
@@ -791,30 +966,10 @@ Gui.element(function(event_trigger,parent)
-
-
The current highest uid that is being used, will not increase during runtime
+ The current highest uid that is being used by a define, will not increase during runtime
-
-
-
-
-
-
-
- -
-
- uid
-
-
-
-
-
-
-
-
-
-
@@ -829,908 +984,19 @@ Gui.element(function(event_trigger,parent)
- Element Define
+ Core Defines
-
-
-
Base function used to define new elements, can be used with a table or with a function
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- element_define
-
- :
-
- (table or function)
-
- used to define how the element is draw, using a table is the simplist way of doing this
-
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (table)
- the new element define that is used to register events to this element
-
-
-
-
-
-
-
-
-
- Usage:
- -- Defining an element with a table
-local example_button =
-Gui.element{
- type = 'button',
- caption = 'Example Button'
-}
- -- Defining an element with a function
-local example_flow_with_button =
-Gui.element(function(event_trigger,parent,...)
- -- Add the flow the button is in
- local flow =
- parent.add{
- name = 'example_flow',
- type = 'flow'
- }
-
- -- Add the button
- local element =
- flow.add{
- name = event_trigger,
- type = 'button',
- caption = 'Example Button'
- }
-
- -- Set the style of the button
- local style = element.style
- style.height = 25
- style.width = 100
-
- -- Return the element
- return element
-end)
-
-
-
- -
-
-
- #
- Gui._prototype_element:style(style_define)
-
-
- -
-
-
-
Extension of Gui.element when using the table method, values applied after the element is drawn
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- style_define
-
- :
-
- (table or function)
-
- used to define how the style is applied, using a table is the simplist way of doing this
-
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (table)
- the new element define that is used to register events to this element
-
-
-
-
-
-
-
-
-
- Usage:
- -- Setting the height and width of the example button
-local example_button =
-Gui.element{
- type = 'button',
- caption = 'Example Button'
-}
-:style{
- height = 25,
- width = 100
-}
- -- Using a function to set the style
-local example_button =
-Gui.element{
- type = 'button',
- caption = 'Example Button'
-}
-:style(function(style,element,...)
- local player = game.players[element.player_index]
- style.height = 25
- style.width = 100
- style.font_color = player.color
-end)
-
-
-
- -
-
-
- #
- Gui._prototype_element:add_to_top_flow([authenticator])
-
-
- -
-
-
-
Adds an element to be drawn to the top flow when a player joins
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- authenticator
-
- :
-
- (function)
-
- called during toggle or update to decide if the element should be visible
-
- (optional)
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (table)
- the new element define that is used to register events to this element
-
-
-
-
-
-
-
-
-
- Usage:
- -- Adding the example button
-example_button:add_to_top_flow(function(player)
- -- example button will only show when game time is less than 1 minute
- return player.online_time < 3600
-end)
-
-
-
- -
-
-
- #
- Gui._prototype_element:add_to_left_flow([open_on_join])
-
-
- -
-
-
-
Adds an element to be drawn to the left flow when a player joins
-
-
-
- Parameters:
-
-
-
-
-
-
-
- -
-
- open_on_join
-
- :
-
- (boolean or function)
-
- called during first darw to decide if the element is visible
-
- (optional)
-
-
-
-
-
-
-
-
- Returns:
-
- -
- (table)
- the new element define that is used to register events to this element
-
-
-
-
-
-
-
-
-
- Usage:
- -- Adding the example button
-example_flow_with_button:add_to_left_flow(true)
-
-
-
-
- Element Events
-
- -
-
-
- #
- Gui._prototype_element.on_opened
-
-
- -
-
-
-
Called when the player opens a GUI.
-
-
-
-
-
-
-
-
-
-
- -
-
- handler
-
- :
-
- (function)
-
- the event handler which will be called
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -
-
-
- #
- Gui._prototype_element.on_closed
-
-
- -
-
-
-
Called when the player closes the GUI they have open.
-
-
-
-
-
-
-
-
-
-
- -
-
- handler
-
- :
-
- (function)
-
- the event handler which will be called
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -
-
-
- #
- Gui._prototype_element.on_click
-
-
- -
-
-
-
Called when LuaGuiElement is clicked.
-
-
-
-
-
-
-
-
-
-
- -
-
-