aperx/factorio-scenario-ExpCluster
1
0
Fork 0
mirror of https://github.com/PHIDIAS0303/ExpCluster.git synced 2025-12-27 11:35:22 +09:00
Code Issues Packages Projects Releases Wiki Activity

Updated Docs

Browse Source
This commit is contained in:
Cooldude2606
2020-04-01 00:01:40 +01:00
parent 95af6cfc34
commit c9534de868
115 changed files with 23355 additions and 6604 deletions
Download Patch File Download Diff File Expand all files Collapse all files

661
expcore/roles.lua
View File

@@ -1,115 +1,111 @@
--[[-- Core Module - Roles
- Factorio role system to manage custom permissions.
@core Roles
@alias Roles
- Factorio role system to manage custom permissions.
@core Roles
@alias Roles
@usage
---- Using Role System (Frontend):
When a map first starts you will want to define on mass all the players you expect to join and the roles to give them:
Roles.override_player_roles{
Cooldude2606 = {'Owner','Admin','Member'},
NotCooldude2606 = {'Member'}
}
@usage--- Using Role System (assignment):
--When a map first starts you will want to define on mass all the players you expect to join and the roles to give them:
Roles.override_player_roles{
Cooldude2606 = {'Owner','Admin','Member'},
NotCooldude2606 = {'Member'}
}
Once the game is running you still want to be able to give role and remove them which is when you would use:
Roles.assign_player(player,'Admin',by_player_name) -- this will give the "Admin" role to the player
Roles.unassign_player(player,{'Admin','Moderator'},by_player_name) -- this will remove "Admin" and "Moderator" role in one go
--Once the game is running you still want to be able to give role and remove them which is when you would use:
Roles.assign_player(player,'Admin',by_player_name) -- this will give the "Admin" role to the player
Roles.unassign_player(player,{'Admin','Moderator'},by_player_name) -- this will remove "Admin" and "Moderator" role in one go
@usage
---- Using Role System (Backend):
To comparer two players you can comparer the index of they highest roles, can be used when you want to allow a "write" down type system:
Roles.get_player_highest_role(playerOne).index < Roles.get_player_highest_role(playerTwo).index -- remember that less means a higher role
@usage--- Using Role System (role testing):
--To comparer two players you can comparer the index of they highest roles, can be used when you want to allow a "write" down type system:
Roles.get_player_highest_role(playerOne).index < Roles.get_player_highest_role(playerTwo).index -- remember that less means a higher role
Listing all of a players roles can also be useful which is when you would want to use:
Roles.get_player_roles(player) -- the return is an array that can be looped over however this is not in particular order
--Listing all of a players roles can also be useful which is when you would want to use:
Roles.get_player_roles(player) -- the return is an array that can be looped over however this is not in particular order
Finally you may want to test if a player has a certain role, flag or action allowed which is when you would use:
Roles.player_has_role(player,'Admin') -- you can provide a role name if you only want a name based system
Roles.player_has_flag(player,'is_donator') -- your roles can be grouped together with flags such as is_donator
Roles.player_allowed(player,'game modifiers') -- or you can have an action based system where each action is something the player can do
--Finally you may want to test if a player has a certain role, flag or action allowed which is when you would use:
Roles.player_has_role(player,'Admin') -- you can provide a role name if you only want a name based system
Roles.player_has_flag(player,'is_donator') -- your roles can be grouped together with flags such as is_donator
Roles.player_allowed(player,'game modifiers') -- or you can have an action based system where each action is something the player can do
@usage
---- Example Flag Define:
Flags can be used to group multiple roles and actions under one catch all, for example if you want a piece of code to only
be active for your donators then you would add a "is_donator" flag to all your donator roles and then in the code test if
a player has that tag present:
@usage--- Example Flag Define:
--Flags can be used to group multiple roles and actions under one catch all, for example if you want a piece of code to only
--be active for your donators then you would add a "is_donator" flag to all your donator roles and then in the code test if
--a player has that tag present:
-- give you donators a speed boost when they join; these functions aren't required but can be useful
Roles.define_flag_trigger('is_donator',function(player,state)
if state then
player.character_running_speed_modifier = 1.5
else
player.character_running_speed_modifier = 1
end
end)
-- then on all your donator roles you would add
Roles.new_role('Donator')
:set_flag('is_donator')
-- and in your code you would test for
if Roles.player_has_flag(player,'is_donator') then
-- some donator only code
-- give you donators a speed boost when they join; these functions aren't required but can be useful
Roles.define_flag_trigger('is_donator',function(player,state)
if state then
player.character_running_speed_modifier = 1.5
else
player.character_running_speed_modifier = 1
end
end)
@usage
---- Example Role Define:
You can't use a role system without any roles so first you must define your roles; each role has a minimum of a name with
the option for a shorthand:
Roles.new_role('Administrator','Admin')
-- then on all your donator roles you would add
Roles.new_role('Donator')
:set_flag('is_donator')
Next you will want to add any extras you want to have, such as a tag, colour, permission group or any custom flags:
Roles.new_role('Administrator','Admin')
:set_custom_tag('[Admin]')
:set_custom_color('red') -- this can be {r=0,g=0,b=0} or a predefined value
:set_permission_group('Staff') -- a second argument can be added if you have not used the custom permission group config
:set_flag('is_admin')
-- and in your code you would test for
if Roles.player_has_flag(player,'is_donator') then
-- some donator only code
end
You will then want to decide if you want to allow all actions, this should of course be used sparely:
Roles.new_role('Administrator','Admin')
...extras...
:set_allow_all()
@usage--- Example Role Define:
--You can't use a role system without any roles so first you must define your roles; each role has a minimum of a name with
--the option for a shorthand:
Roles.new_role('Administrator','Admin')
If you don't do this want this as i would advise you do then you will want to define what the role can do; this comes with
an optional inheritance system if you like those sort of things in which case disallow may also be of some use to you:
Roles.new_role('Administrator','Admin')
...extras...
:set_parent('Moderator') -- the admin can do anything that a moderator can do
:allow{ -- these actions can be anything just try to keep them without conflicts
'command/kill',
'gui/game settings'
}
--Next you will want to add any extras you want to have, such as a tag, colour, permission group or any custom flags:
Roles.new_role('Administrator','Admin')
:set_custom_tag('[Admin]')
:set_custom_color('red') -- this can be {r=0,g=0,b=0} or a predefined value
:set_permission_group('Staff') -- a second argument can be added if you have not used the custom permission group config
:set_flag('is_admin')
Here is what the finished admin role would look like:
Roles.new_role('Administrator','Admin')
:set_custom_tag('[Admin]')
:set_custom_color('red')
:set_permission_group('Staff')
:set_flag('is_admin')
:set_parent('Moderator')
:allow{
'command/kill',
'gui/game settings'
}
--You will then want to decide if you want to allow all actions, this should of course be used sparely:
Roles.new_role('Administrator','Admin')
...extras...
:set_allow_all()
@usage
---- Example System Define:
Once all roles are defined these steps must be done to ensure the system is ready to use, this includes setting a default
role, assigning a root (all permission) role that the server/system will use and the linear order that the roles fall into:
--If you don't do this want this as i would advise you do then you will want to define what the role can do; this comes with
--an optional inheritance system if you like those sort of things in which case disallow may also be of some use to you:
Roles.new_role('Administrator','Admin')
...extras...
:set_parent('Moderator') -- the admin can do anything that a moderator can do
:allow{ -- these actions can be anything just try to keep them without conflicts
'command/kill',
'gui/game settings'
}
Roles.set_default('Guest')
Roles.set_root('System')
--Here is what the finished admin role would look like:
Roles.new_role('Administrator','Admin')
:set_custom_tag('[Admin]')
:set_custom_color('red')
:set_permission_group('Staff')
:set_flag('is_admin')
:set_parent('Moderator')
:allow{
'command/kill',
'gui/game settings'
}
Roles.define_role_order{
'System',
'Administrator',
'Moderator',
'Donator',
'Guest'
}
@usage--- Example System Define:
--Once all roles are defined these steps must be done to ensure the system is ready to use, this includes setting a default
--role, assigning a root (all permission) role that the server/system will use and the linear order that the roles fall into:
Roles.set_default('Guest')
Roles.set_root('System')
Roles.define_role_order{
'System',
'Administrator',
'Moderator',
'Donator',
'Guest'
}
--Just remember that in this example all these roles have not been defined; so make sure all your roles that are used are defined
--before hand; a config file on load is useful for this to ensure that its loaded before the first player even joins.
Just remember that in this example all these roles have not been defined; so make sure all your roles that are used are defined
before hand; a config file on load is useful for this to ensure that its loaded before the first player even joins.
]]
local Game = require 'utils.game' --- @dep utils.game
@@ -196,8 +192,13 @@ local function emit_player_roles_updated(player,type,roles,by_player_name,skip_g
})
end
--- Returns a string which contains all roles in index order displaying all data for them
-- @treturn string the debug output string
--[[-- Returns a string which contains all roles in index order displaying all data for them
@treturn string the debug output string
@usage-- Print the debug string
game.player.print(Roles.debug())
]]
function Roles.debug()
local output = ''
for index,role_name in pairs(Roles.config.order) do
@@ -209,9 +210,14 @@ function Roles.debug()
return output
end
--- Prints a message to all players in the given roles, may send duplicate message however factorio blocks spam
-- @tparam table roles table a of roles which to send the message to
-- @tparam string message the message to send to the players
--[[-- Prints a message to all players in the given roles, may send duplicate message however factorio blocks spam
@tparam table roles table a of roles which to send the message to
@tparam string message the message to send to the players
@usage-- Print a message to the given roles
Roles.print_to_roles({'Administrator','Moderator'}, 'Hello, World!')
]]
function Roles.print_to_roles(roles,message)
for _,role in pairs(roles) do
role = Roles.get_role_from_any(role)
@@ -219,9 +225,14 @@ function Roles.print_to_roles(roles,message)
end
end
--- Prints a message to all players who have the given role or one which is higher (excluding default)
-- @tparam string role the name of the role to send the message to
-- @tparam string message the message to send to the players
--[[-- Prints a message to all players who have the given role or one which is higher (excluding default)
@tparam string role the name of the role to send the message to
@tparam string message the message to send to the players
@usage-- Print a message to the roles above this role, includes the given role
Roles.print_to_roles_higher('Moderator', 'Hello, World!')
]]
function Roles.print_to_roles_higher(role,message)
role = Roles.get_role_from_any(role)
if not role then return end
@@ -234,9 +245,14 @@ function Roles.print_to_roles_higher(role,message)
Roles.print_to_roles(roles,message)
end
--- Prints a message to all players who have the given role or one which is lower (excluding default)
-- @tparam string role the name of the role to send the message to
-- @tparam string message the message to send to the players
--[[-- Prints a message to all players who have the given role or one which is lower (excluding default)
@tparam string role the name of the role to send the message to
@tparam string message the message to send to the players
@usage-- Print a message to the roles below this role, includes the given role
Roles.print_to_roles_higher('Moderator', 'Hello, World!')
]]
function Roles.print_to_roles_lower(role,message)
role = Roles.get_role_from_any(role)
if not role then return end
@@ -249,25 +265,40 @@ function Roles.print_to_roles_lower(role,message)
Roles.print_to_roles(roles,message)
end
--- Get a role for the given name
-- @tparam string name the name of the role to get
-- @treturn Roles._prototype the role with that name or nil
--[[-- Get a role for the given name
@tparam string name the name of the role to get
@treturn Roles._prototype the role with that name or nil
@usage-- Get a role by its name
local role = Roles.get_role_by_name('Moderator')
]]
function Roles.get_role_by_name(name)
return Roles.config.roles[name]
end
--- Get a role with the given order index
-- @tparam number index the place in the order list of the role to get
-- @treturn Roles._prototype the role with that index in the order list or nil
--[[-- Get a role with the given order index
@tparam number index the place in the order list of the role to get
@treturn Roles._prototype the role with that index in the order list or nil
@usage-- Get a role by its index in the order list
local role = Roles.get_role_by_name(2)
]]
function Roles.get_role_by_order(index)
local name = Roles.config.order[index]
return Roles.config.roles[name]
end
--- Gets a role from a name,index or role object (where it is just returned)
-- nb: this function is used for the input for most outward facing functions
-- @tparam ?number|string|table any the value used to find the role
-- @treturn Roles._prototype the role that was found or nil see above
--[[-- Gets a role from a name,index or role object (where it is just returned)
nb: this function is used for the input for most outward facing functions
@tparam ?number|string|table any the value used to find the role
@treturn Roles._prototype the role that was found or nil see above
@usage-- Get a role by its name or order
local role = Roles.get_role_from_any('Moderator')
]]
function Roles.get_role_from_any(any)
local t_any = type(any)
if t_any == 'number' or tonumber(any) then
@@ -280,9 +311,14 @@ function Roles.get_role_from_any(any)
end
end
--- Gets all the roles of the given player, this will always contain the default role
-- @tparam LuaPlayer player the player to get the roles of
-- @treturn table a table where the values are the roles which the player has
--[[-- Gets all the roles of the given player, this will always contain the default role
@tparam LuaPlayer player the player to get the roles of
@treturn table a table where the values are the roles which the player has
@usage-- Get the roles that a player has
local roles = Roles.get_player_roles(game.player)
]]
function Roles.get_player_roles(player)
player = Game.get_player_from_any(player)
if not player then return {Roles.config.roles[Roles.config.internal.root]} end
@@ -295,9 +331,14 @@ function Roles.get_player_roles(player)
return rtn
end
--- Gets the highest role which the player has, can be used to compeer one player to another
-- @tparam LuaPlayer player the player to get the highest role of
-- @treturn the role with the highest order index which this player has
--[[-- Gets the highest role which the player has, can be used to compeer one player to another
@tparam LuaPlayer player the player to get the highest role of
@treturn the role with the highest order index which this player has
@usage-- Get the highest role that a player has
local role = Roles.get_player_highest_role(game.player)
]]
function Roles.get_player_highest_role(player)
local roles = Roles.get_player_roles(player)
if not roles then return end
@@ -314,12 +355,20 @@ end
-- Functions for changing player's roles
-- @section assinment
--- Gives a player the given role(s) with an option to pass a by player name used in the log
-- @tparam LuaPlayer player the player that will be assigned the roles
-- @tparam table roles table a of roles that the player will be given, can be one role and can be role names
-- @tparam[opt=<server>] string by_player_name the name of the player that will be shown in the log
-- @tparam[opt=false] boolean skip_checks when true there will be no checks are done for if the player is valid
-- @tparam[opt=false] boolean silent when true there will be no game message printed
--[[-- Gives a player the given role(s) with an option to pass a by player name used in the log
@tparam LuaPlayer player the player that will be assigned the roles
@tparam table roles table a of roles that the player will be given, can be one role and can be role names
@tparam[opt=<server>] string by_player_name the name of the player that will be shown in the log
@tparam[opt=false] boolean skip_checks when true there will be no checks are done for if the player is valid
@tparam[opt=false] boolean silent when true there will be no game message printed
@usage-- Assign a player to the Moderator role
Roles.assign_player(game.player, 'Moderator')
@usage-- Assign a player to the Moderator role, even if the player has never been on the map
Roles.assign_player('Cooldude2606', 'Moderator', nil, true)
]]
function Roles.assign_player(player,roles,by_player_name,skip_checks,silent)
local valid_player = Game.get_player_from_any(player)
if not skip_checks and not valid_player then return end
@@ -337,12 +386,20 @@ function Roles.assign_player(player,roles,by_player_name,skip_checks,silent)
end
end
--- Removes a player from the given role(s) with an option to pass a by player name used in the log
-- @tparam LuaPlayer player the player that will have the roles removed
-- @tparam table roles table a of roles to be removed from the player, can be one role and can be role names
-- @tparam[opt=<server>] string by_player_name the name of the player that will be shown in the logs
-- @tparam[opt=false] boolean skip_checks when true there will be no checks are done for if the player is valid
-- @tparam[opt=false] boolean silent when true there will be no game message printed
--[[-- Removes a player from the given role(s) with an option to pass a by player name used in the log
@tparam LuaPlayer player the player that will have the roles removed
@tparam table roles table a of roles to be removed from the player, can be one role and can be role names
@tparam[opt=<server>] string by_player_name the name of the player that will be shown in the logs
@tparam[opt=false] boolean skip_checks when true there will be no checks are done for if the player is valid
@tparam[opt=false] boolean silent when true there will be no game message printed
@usage-- Unassign a player from the Moderator role
Roles.unassign_player(game.player, 'Moderator')
@usage-- Unassign a player from the Moderator role, even if the player has never been on the map
Roles.unassign_player('Cooldude2606', 'Moderator', nil, true)
]]
function Roles.unassign_player(player,roles,by_player_name,skip_checks,silent)
local valid_player = Game.get_player_from_any(player)
if not skip_checks and not valid_player then return end
@@ -361,20 +418,41 @@ function Roles.unassign_player(player,roles,by_player_name,skip_checks,silent)
end
end
--- Overrides all player roles with the given table of roles, useful to mass set roles on game start
-- @tparam table roles table a which is indexed by case sensitive player names and has the value of a table of role names
function Roles.override_player_roles(roles)
Roles.config.players = roles
--[[-- Overrides all player roles with the given table of roles, useful to mass set roles on game start
@tparam[opt] string player_name the player to set the roles for, if not given all roles are overriden
@tparam table roles table a which is indexed by case sensitive player names and has the value of a table of role names
@usage-- Override the roles of a single player, other users are not effected
Roles.override_player_roles('Cooldude2606', {'Moderator'})
@usage-- Override all existing roles, effects all users not just ones listed
Roles.override_player_roles{
['Cooldude2606'] = {'Administrator','Moderator'},
['arty714'] = {'Administrator','Moderator'},
}
]]
function Roles.override_player_roles(player_name,roles)
if not roles then
Roles.config.players = player_name
else
Roles.config.players[player_name] = roles
end
end
--- Checks.
-- Functions for checking player's roles
-- @section checks
--- A test for weather a player has the given role
-- @tparam LuaPlayer player the player to test the roles of
-- @tparam ?string|number|table search_role a pointer to the role that is being searched for
-- @treturn boolean true if the player has the role, false otherwise, nil for errors
--[[-- A test for weather a player has the given role
@tparam LuaPlayer player the player to test the roles of
@tparam ?string|number|table search_role a pointer to the role that is being searched for
@treturn boolean true if the player has the role, false otherwise, nil for errors
@usage-- Test if a player has a role
local has_role = Roles.player_has_role(game.player, 'Moderator')
]]
function Roles.player_has_role(player,search_role)
local roles = Roles.get_player_roles(player)
if not roles then return end
@@ -386,10 +464,15 @@ function Roles.player_has_role(player,search_role)
return false
end
--- A test for weather a player has the given flag true for at least one of they roles
-- @tparam LuaPlayer player the player to test the roles of
-- @tparam string flag_name the name of the flag that is being looked for
-- @treturn boolean true if the player has at least one role which has the flag set to true, false otherwise, nil for errors
--[[-- A test for weather a player has the given flag true for at least one of they roles
@tparam LuaPlayer player the player to test the roles of
@tparam string flag_name the name of the flag that is being looked for
@treturn boolean true if the player has at least one role which has the flag set to true, false otherwise, nil for errors
@usage-- Test if a player has a role
local has_flag = Roles.player_has_flag(game.player, 'is_donator')
]]
function Roles.player_has_flag(player,flag_name)
local roles = Roles.get_player_roles(player)
if not roles then return end
@@ -401,10 +484,15 @@ function Roles.player_has_flag(player,flag_name)
return false
end
--- A test for weather a player has at least one role which is allowed the given action
-- @tparam LuaPlayer player the player to test the roles of
-- @tparam string action the name of the action that is being tested for
-- @treturn boolean true if the player has at least one role which is allowed this action, false otherwise, nil for errors
--[[-- A test for weather a player has at least one role which is allowed the given action
@tparam LuaPlayer player the player to test the roles of
@tparam string action the name of the action that is being tested for
@treturn boolean true if the player has at least one role which is allowed this action, false otherwise, nil for errors
@usage-- Test if a player has a role
local has_flag = Roles.player_has_flag(game.player, 'is_donator')
]]
function Roles.player_allowed(player,action)
local roles = Roles.get_player_roles(player)
if not roles then return end
@@ -420,9 +508,20 @@ end
-- Functions which are used to define roles
-- @section checks
--- Used to set the role order, higher in the list is better, must be called at least once in config
--[[-- Used to set the role order, higher in the list is better, must be called at least once in config
-- nb: function also re links parents due to expected position in the config file
-- @tparam table order table a which is keyed only by numbers (start 1) and values are roles in order with highest first
@tparam table order table a which is keyed only by numbers (start 1) and values are roles in order with highest first
@usage-- Define which roles are higher than others
Roles.define_role_order{
'System',
'Administrator',
'Moderator',
'Donator',
'Guest'
}
]]
function Roles.define_role_order(order)
-- Clears and then rebuilds the order table
_C.error_if_runtime()
@@ -457,26 +556,41 @@ function Roles.define_role_order(order)
end
end
--- Defines a new trigger for when a tag is added or removed from a player
-- @tparam string name the name of the flag which the roles will have
-- @tparam function callback the function that is called when roles are assigned
-- flag param - player - the player that has had they roles changed
-- flag param - state - the state of the flag, aka if the flag is present
--[[-- Defines a new trigger for when a tag is added or removed from a player
@tparam string name the name of the flag which the roles will have
@tparam function callback the function that is called when roles are assigned
@usage-- Defineing a flag trigger
Roles.define_flag_trigger('is_donator', function(player, state)
player.character_running_speed_modifier = state and 1.5 or 1
end)
]]
function Roles.define_flag_trigger(name,callback)
_C.error_if_runtime()
Roles.config.flags[name] = Async.register(callback)
end
--- Sets the default role which every player will have, this needs to be called at least once
-- @tparam string name the name of the default role
--[[-- Sets the default role which every player will have, this needs to be called at least once
@tparam string name the name of the default role
@usage-- Setting the default role
Roles.set_default('Guest')
]]
function Roles.set_default(name)
local role = Roles.config.roles[name]
if not role then return end
Roles.config.internal.default = name
end
--- Sets the root role which will always have all permissions, any server actions act from this role
-- @tparam string name the name of the root role
--[[-- Sets the root role which will always have all permissions, any server actions act from this role
@tparam string name the name of the root role
@usage-- Setting the root role
Roles.set_root('System')
]]
function Roles.set_root(name)
local role = Roles.config.roles[name]
if not role then return end
@@ -484,10 +598,15 @@ function Roles.set_root(name)
Roles.config.internal.root = name
end
--- Defines a new role and returns the prototype to allow configuration
-- @tparam string name the name of the new role, must be unique
-- @tparam[opt=name] string short_hand the shortened version of the name
-- @treturn Roles._prototype the start of the config chain for this role
--[[-- Defines a new role and returns the prototype to allow configuration
@tparam string name the name of the new role, must be unique
@tparam[opt=name] string short_hand the shortened version of the name
@treturn Roles._prototype the start of the config chain for this role
@usage-- Defineing a new role
local role = Roles.new_role('Moderator', 'Mod')
]]
function Roles.new_role(name,short_hand)
_C.error_if_runtime()
if Roles.config.roles[name] then return error('Role name is non unique') end
@@ -506,18 +625,31 @@ end
-- Functions for using the role action system
-- @section actions
--- Sets the default allow state of the role, true will allow all actions
-- @tparam[opt=true] boolean state true will allow all actions
-- @treturn Roles._prototype allows chaining
--[[-- Sets the default allow state of the role, true will allow all actions
@tparam[opt=true] boolean state true will allow all actions
@treturn Roles._prototype allows chaining
@usage-- Allow all actions for this role, useful for root like roles
role:set_allow_all()
]]
function Roles._prototype:set_allow_all(state)
if state == nil then state = true end
self.allow_all_actions = not not state -- not not forces a boolean value
return self
end
--- Sets the allow actions for this role, actions in this list will be allowed for this role
-- @tparam table actions indexed with numbers and is an array of action names, order has no effect
-- @treturn Roles._prototype allows chaining
--[[-- Sets the allow actions for this role, actions in this list will be allowed for this role
@tparam table actions indexed with numbers and is an array of action names, order has no effect
@treturn Roles._prototype allows chaining
@usage-- Allow some actions for a role
role:allow{
'command/kill',
'gui/game settings'
}
]]
function Roles._prototype:allow(actions)
if type(actions) ~= 'table' then
actions = {actions}
@@ -528,9 +660,17 @@ function Roles._prototype:allow(actions)
return self
end
--- Sets the disallow actions for this role, will prevent actions from being allowed regardless of inheritance
-- @tparam table actions indexed with numbers and is an array of action names, order has no effect
-- @treturn Roles._prototype allows chaining
--[[-- Sets the disallow actions for this role, will prevent actions from being allowed regardless of inheritance
@tparam table actions indexed with numbers and is an array of action names, order has no effect
@treturn Roles._prototype allows chaining
@usage-- Disalow an action for a role, useful if inherit an action from a parent
role:disallow{
'command/kill',
'gui/game settings'
}
]]
function Roles._prototype:disallow(actions)
if type(actions) ~= 'table' then
actions = {actions}
@@ -541,9 +681,14 @@ function Roles._prototype:disallow(actions)
return self
end
--- Test for if a role is allowed the given action, mostly internal see Roles.player_allowed
-- @tparam string action the name of the action to test if it is allowed
-- @treturn boolean true if action is allowed, false otherwise
--[[-- Test for if a role is allowed the given action, mostly internal see Roles.player_allowed
@tparam string action the name of the action to test if it is allowed
@treturn boolean true if action is allowed, false otherwise
@usage-- Test if a role is allowed an action
local allowed = role:is_allowed('command/kill')
]]
function Roles._prototype:is_allowed(action)
local is_root = Roles.config.internal.root.name == self.name
return self.allowed_actions[action] or self.allow_all_actions or is_root
@@ -553,26 +698,41 @@ end
-- Functions for using the role flag system
-- @section flags
--- Sets the state of a flag for a role, flags can be used to apply effects to players
-- @tparam string name the name of the flag to set the value of
-- @tparam[opt=true] boolean value the state to set the flag to
-- @treturn Roles._prototype allows chaining
--[[-- Sets the state of a flag for a role, flags can be used to apply effects to players
@tparam string name the name of the flag to set the value of
@tparam[opt=true] boolean value the state to set the flag to
@treturn Roles._prototype allows chaining
@usage-- Set a flag for a role
role:set_flag('is_admin')
]]
function Roles._prototype:set_flag(name,value)
if value == nil then value = true end
self.flags[name] = not not value -- not not forces a boolean value
return self
end
--- Clears all flags from this role, individual flags can be removed with set_flag(name,false)
-- @treturn Roles._prototype allows chaining
--[[-- Clears all flags from this role, individual flags can be removed with set_flag(name,false)
@treturn Roles._prototype allows chaining
@usage-- Remove all flags from a role
role:clear_flags()
]]
function Roles._prototype:clear_flags()
self.flags = {}
return self
end
--- A test for if the role has a flag set
-- @tparam string name the name of the flag to test for
-- @treturn boolean true if the flag is set, false otherwise
--[[-- A test for if the role has a flag set
@tparam string name the name of the flag to test for
@treturn boolean true if the flag is set, false otherwise
@usage-- Test if a role has a flag
local has_flag = role:has_flag('is_admin')
]]
function Roles._prototype:has_flag(name)
return self.flags[name] or false
end
@@ -581,17 +741,27 @@ end
-- Functions for chaning other proerties
-- @section properties
--- Sets a custom player tag for the role, can be accessed by other code
-- @tparam string tag the value that the tag will be
-- @treturn Roles._prototype allows chaining
--[[-- Sets a custom player tag for the role, can be accessed by other code
@tparam string tag the value that the tag will be
@treturn Roles._prototype allows chaining
@usage-- Set a custom tag for this role, other code is required to set the tag
role:set_custom_tag('Mod')
]]
function Roles._prototype:set_custom_tag(tag)
self.custom_tag = tag
return self
end
--- Sets a custom colour for the role, can be accessed by other code
-- @tparam table color ?string|table can either be and rgb colour or the name of a colour defined in the presets
-- @treturn Roles._prototype allows chaining
--[[-- Sets a custom colour for the role, can be accessed by other code
@tparam table color ?string|table can either be and rgb colour or the name of a colour defined in the presets
@treturn Roles._prototype allows chaining
@usage-- Set a custom colour for this role, other code is required to use this value
role:set_custom_color{ r=255, g=100, b=100}
]]
function Roles._prototype:set_custom_color(color)
if type(color) ~= 'table' then
color = Colours[color]
@@ -600,10 +770,15 @@ function Roles._prototype:set_custom_color(color)
return self
end
--- Sets the permission group for this role, players will be moved to the group of they highest role
-- @tparam string name the name of the permission group to have players moved to
-- @tparam[opt=false] boolean use_factorio_api when true the custom permission group module is ignored
-- @treturn Roles._prototype allows chaining
--[[-- Sets the permission group for this role, players will be moved to the group of they highest role
@tparam string name the name of the permission group to have players moved to
@tparam[opt=false] boolean use_factorio_api when true the custom permission group module is ignored
@treturn Roles._prototype allows chaining
@usage-- Set the permission group for this role, see permission_groups.lua
role:set_permission_group('Admin')
]]
function Roles._prototype:set_permission_group(name,use_factorio_api)
_C.error_if_runtime()
if use_factorio_api then
@@ -616,10 +791,15 @@ function Roles._prototype:set_permission_group(name,use_factorio_api)
return self
end
--- Sets the parent for a role, any action not in allow or disallow will be looked for in its parents
-- nb: this is a recursive action, and changing the allows and disallows will effect all children roles
-- @tparam string role the name of the role that will be the parent; has imminent effect if role is already defined
-- @treturn Roles._prototype allows chaining
--[[-- Sets the parent for a role, any action not in allow or disallow will be looked for in its parents
nb: this is a recursive action, and changing the allows and disallows will effect all children roles
@tparam string role the name of the role that will be the parent; has imminent effect if role is already defined
@treturn Roles._prototype allows chaining
@usage-- Set the parent for this role to inherit all actions allowed
role:set_parent('Guest')
]]
function Roles._prototype:set_parent(role)
_C.error_if_runtime()
self.parent = role
@@ -629,19 +809,31 @@ function Roles._prototype:set_parent(role)
return self
end
--- Sets an auto promote condition that is checked every 5 seconds, if true is returned then the player will receive the role
-- nb: this is one way, failing false after already gaining the role will not revoke the role
-- @tparam function callback receives only one param which is player to promote, return true to promote the player
-- @treturn Roles._prototype allows chaining
function Roles._prototype:set_auto_promote_condition(callback)
--[[-- Sets an auto assign condition that is checked every 60 seconds, if true is returned then the player will receive the role
nb: this is one way, failing false after already gaining the role will not revoke the role
@tparam function callback receives only one param which is player to promote, return true to promote the player
@treturn Roles._prototype allows chaining
@usage-- Give this role to a user if there are admin, ran every 60 seconds
role:set_auto_assign_condition(function(player)
return player.admin
end)
]]
function Roles._prototype:set_auto_assign_condition(callback)
_C.error_if_runetime_closure(callback)
self.auto_promote_condition = callback
return self
end
--- Sets the role to not allow players to have auto promote effect them, useful to keep people locked to a punishment
-- @tparam[opt=true] boolean state when true the players with this role will not be auto promoted
-- @treturn Roles._prototype allows chaining
--[[-- Sets the role to not allow players to have auto assign effect them, useful to keep people locked to a role
@tparam[opt=true] boolean state when true the players with this role will not be auto assigned to other roles
@treturn Roles._prototype allows chaining
@usage-- Make a role stop players from being auto assigned to other roles
role:set_block_auto_promote()
]]
function Roles._prototype:set_block_auto_promote(state)
if state == nil then state = true end
self.block_auto_promote = not not state -- forces a boolean value
@@ -652,11 +844,16 @@ end
-- Functions that control players in a role
-- @section players
--- Adds a player to this role, players can have more than one role at a time, used internally see Roles.assign
-- @tparam LuaPlayer player the player that will be given this role
-- @tparam boolean skip_check when true player will be taken as the player name (use when player has not yet joined)
-- @tparam boolean skip_event when true the event emit will be skipped, this is used internally with Roles.assign
-- @treturn boolean true if the player was added successfully
--[[-- Adds a player to this role, players can have more than one role at a time, used internally see Roles.assign
@tparam LuaPlayer player the player that will be given this role
@tparam boolean skip_check when true player will be taken as the player name (use when player has not yet joined)
@tparam boolean skip_event when true the event emit will be skipped, this is used internally with Roles.assign
@treturn boolean true if the player was added successfully
@usage-- Assign a player to this role
role:add_player(game.player)
]]
function Roles._prototype:add_player(player,skip_check,skip_event)
player = Game.get_player_from_any(player)
-- Default role cant have players added or removed
@@ -686,11 +883,16 @@ function Roles._prototype:add_player(player,skip_check,skip_event)
return true
end
--- Removes a player from this role, players can have more than one role at a time, used internally see Roles.unassign
-- @tparam LuaPlayer player the player that will lose this role
-- @tparam boolean skip_check when true player will be taken as the player name (use when player has not yet joined)
-- @tparam boolean skip_event when true the event emit will be skipped, this is used internally with Roles.unassign
-- @treturn boolean true if the player was removed successfully
--[[-- Removes a player from this role, players can have more than one role at a time, used internally see Roles.unassign
@tparam LuaPlayer player the player that will lose this role
@tparam boolean skip_check when true player will be taken as the player name (use when player has not yet joined)
@tparam boolean skip_event when true the event emit will be skipped, this is used internally with Roles.unassign
@treturn boolean true if the player was removed successfully
@usage-- Unassign a player from this role
role:remove_player(game.player)
]]
function Roles._prototype:remove_player(player,skip_check,skip_event)
player = Game.get_player_from_any(player)
-- Default role cant have players added or removed
@@ -725,9 +927,17 @@ function Roles._prototype:remove_player(player,skip_check,skip_event)
return rtn
end
--- Returns an array of all the players who have this role, can be filtered by online status
-- @tparam[opt=nil] boolean online when given will filter by this online state, nil will return all players
-- @treturn table all the players who have this role, indexed order is meaningless
--[[-- Returns an array of all the players who have this role, can be filtered by online status
@tparam[opt=nil] boolean online when given will filter by this online state, nil will return all players
@treturn table all the players who have this role, indexed order is meaningless
@usage-- Get all the players with this role
local players = role:get_players()
@usage-- Get all online players with this role
local players = role:get_players(true)
]]
function Roles._prototype:get_players(online)
local players = {}
-- Gets all players that have this role
@@ -756,9 +966,14 @@ function Roles._prototype:get_players(online)
end
end
--- Will print a message to all players with this role
-- @tparam string message the message that will be printed to the players
-- @treturn number the number of players who received the message
--[[-- Will print a message to all players with this role
@tparam string message the message that will be printed to the players
@treturn number the number of players who received the message
@usage-- Print a message to all players with this role
role:print('Hello, World!')
]]
function Roles._prototype:print(message)
local players = self:get_players(true)
for _,player in pairs(players) do