Module expcore.roles
Factorio role system to manage custom permissions
[[
Info:
- Author: Cooldude2606
Functions
Roles.debug () | Returns a string which contains all roles in index order displaying all data for them |
Roles.print_to_roles (roles, message) | Prints a message to all players in the given roles, may send duplicate message however factorio blocks spam |
Roles.print_to_roles_higher (role, message) | Prints a message to all players who have the given role or one which is higher (excluding default) |
Roles.print_to_roles_lower (role, message) | Prints a message to all players who have the given role or one which is lower (excluding default) |
Roles.get_role_by_name (name) | Get a role for the given name |
Roles.get_role_by_order (index) | Get a role with the given order index |
Roles.get_role_from_any (any) | 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 |
Roles.get_player_roles (player) | Gets all the roles of the given player, this will always contain the default role |
Roles.get_player_highest_role (player) | Gets the highest role which the player has, can be used to compeer one player to another |
Roles.assign_player (player, roles[, by_player_name= |
Gives a player the given role(s) with an option to pass a by player name used in the log |
Roles.unassign_player (player, roles[, by_player_name= |
Removes a player from the given role(s) with an option to pass a by player name used in the log |
Roles.override_player_roles (roles) | Overrides all player roles with the given table of roles, useful to mass set roles on game start |
Roles.player_has_role (player, search_role) | A test for weather a player has the given role |
Roles.player_has_flag (player, flag_name) | A test for weather a player has the given flag true for at least one of they roles |
Roles.player_allowed (player, action) | A test for weather a player has at least one role which is allowed the given action |
Roles.define_role_order (order) | 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 |
Roles.define_flag_trigger (name, callback) | Defines a new trigger for when a tag is added or removed from a player |
Roles.set_default (name) | Sets the default role which every player will have, this needs to be called at least once |
Roles.set_root (name) | Sets the root role which will always have all permissions, any server actions act from this role |
Roles.new_role (name[, short_hand=name]) | Defines a new role and returns the prototype to allow configuration |
Roles._prototype:set_allow_all ([state=true]) | Sets the default allow state of the role, true will allow all actions |
Roles._prototype:allow (actions) | Sets the allow actions for this role, actions in this list will be allowed for this role |
Roles._prototype:disallow (actions) | Sets the disallow actions for this role, will prevent actions from being allowed regardless of inheritance |
Roles._prototype:is_allowed (action) | Test for if a role is allowed the given action, mostly internal see Roles.player_allowed |
Roles._prototype:set_flag (name[, value=true]) | Sets the state of a flag for a role, flags can be used to apply effects to players |
Roles._prototype:clear_flags () | Clears all flags from this role, individual flags can be removed with set_flag(name,false) |
Roles._prototype:has_flag (name) | A test for if the role has a flag set |
Roles._prototype:set_custom_tag (tag) | Sets a custom player tag for the role, can be accessed by other code |
Roles._prototype:set_custom_color (color) | Sets a custom colour for the role, can be accessed by other code |
Roles._prototype:set_permission_group (name[, use_factorio_api=false]) | Sets the permission group for this role, players will be moved to the group of they highest role |
Roles._prototype:set_parent (role) | 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 |
Roles._prototype:set_auto_promote_condition (callback) | Sets an auto promote condition that is checked every 5 seconds, if true is returned then the player will recive the role nb: this is one way, failing false after already gaining the role will not revoke the role |
Roles._prototype:set_block_auto_promote ([state=true]) | Sets the role to not allow players to have auto promote effect them, useful to keep people locked to a punishment |
Roles._prototype:add_player (player, skip_check, skip_event) | Adds a player to this role, players can have more than one role at a time, used internally see Roles.assign |
Roles._prototype:remove_player (player, skip_check, skip_event) | Removes a player from this role, players can have more than one role at a time, used internally see Roles.unassign |
Roles._prototype:get_players ([online=nil]) | Returns an array of all the players who have this role, can be filtered by online status |
Roles._prototype:print (message) | Will print a message to all players with this role |
Functions
- Roles.debug ()
-
Returns a string which contains all roles in index order displaying all data for them
Returns:
-
string
the debug output string
- Roles.print_to_roles (roles, message)
-
Prints a message to all players in the given roles, may send duplicate message however factorio blocks spam
Parameters:
- Roles.print_to_roles_higher (role, message)
-
Prints a message to all players who have the given role or one which is higher (excluding default)
Parameters:
- Roles.print_to_roles_lower (role, message)
-
Prints a message to all players who have the given role or one which is lower (excluding default)
Parameters:
- Roles.get_role_by_name (name)
-
Get a role for the given name
Parameters:
- name string the name of the role to get
Returns:
-
Roles._prototype
the role with that name or nil
- Roles.get_role_by_order (index)
-
Get a role with the given order index
Parameters:
- index number the place in the oder list of the role to get
Returns:
-
Roles._prototype
the role with that index in the order list or nil
- Roles.get_role_from_any (any)
-
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
Parameters:
Returns:
-
Roles._prototype
the role that was found or nil see above
- Roles.get_player_roles (player)
-
Gets all the roles of the given player, this will always contain the default role
Parameters:
- player LuaPlayer the player to get the roles of
Returns:
-
table
a table where the values are the roles which the player has
- Roles.get_player_highest_role (player)
-
Gets the highest role which the player has, can be used to compeer one player to another
Parameters:
- player LuaPlayer the player to get the highest role of
Returns:
-
the
role with the highest order index which this player has
-
Roles.assign_player (player, roles[, by_player_name=
[, silent=false]]) -
Gives a player the given role(s) with an option to pass a by player name used in the log
Parameters:
- player LuaPlayer the player that will be assigned the roles
- roles table table a of roles that the player will be given, can be one role and can be role names
- by_player_name
string
the name of the player that will be shown in the log
(default
) - silent boolean when true there will be no game message printed (default false)
-
Roles.unassign_player (player, roles[, by_player_name=
[, silent=false]]) -
Removes a player from the given role(s) with an option to pass a by player name used in the log
Parameters:
- player LuaPlayer the player that will have the roles removed
- roles table table a of roles to be removed from the player, can be one role and can be role names
- by_player_name
string
the name of the player that will be shown in the logs
(default
) - silent boolean when true there will be no game message printed (default false)
- Roles.override_player_roles (roles)
-
Overrides all player roles with the given table of roles, useful to mass set roles on game start
Parameters:
- roles table table a which is indexed by case sensitive player names and has the value of a table of role names
- Roles.player_has_role (player, search_role)
-
A test for weather a player has the given role
Parameters:
- player LuaPlayer the player to test the roles of
- search_role string, number or table a pointer to the role that is being searched for
Returns:
-
boolean
true if the player has the role, false otherwise, nil for errors
- Roles.player_has_flag (player, flag_name)
-
A test for weather a player has the given flag true for at least one of they roles
Parameters:
- player LuaPlayer the player to test the roles of
- flag_name string the name of the flag that is being looked for
Returns:
-
boolean
true if the player has at least one role which has the flag set to true, false otherwise, nil for errors
- Roles.player_allowed (player, action)
-
A test for weather a player has at least one role which is allowed the given action
Parameters:
- player LuaPlayer the player to test the roles of
- action string the name of the action that is being tested for
Returns:
-
boolean
true if the player has at least one role which is allowed this action, false otherwise, nil for errors
- Roles.define_role_order (order)
-
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
Parameters:
- order table table a which is keyed only by numbers (start 1) and values are roles in order with highest first
- Roles.define_flag_trigger (name, callback)
-
Defines a new trigger for when a tag is added or removed from a player
Parameters:
- name string the name of the flag which the roles will have
- callback function 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
- Roles.set_default (name)
-
Sets the default role which every player will have, this needs to be called at least once
Parameters:
- name string the name of the default role
- Roles.set_root (name)
-
Sets the root role which will always have all permissions, any server actions act from this role
Parameters:
- name string the name of the root role
- Roles.new_role (name[, short_hand=name])
-
Defines a new role and returns the prototype to allow configuration
Parameters:
- name string the name of the new role, must be unique
- short_hand string the shortened version of the name (default name)
Returns:
-
Roles._prototype
the start of the config chain for this role
- Roles._prototype:set_allow_all ([state=true])
-
Sets the default allow state of the role, true will allow all actions
Parameters:
- state boolean true will allow all actions (default true)
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:allow (actions)
-
Sets the allow actions for this role, actions in this list will be allowed for this role
Parameters:
- actions table indexed with numbers and is an array of action names, order has no effect
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:disallow (actions)
-
Sets the disallow actions for this role, will prevent actions from being allowed regardless of inheritance
Parameters:
- actions table indexed with numbers and is an array of action names, order has no effect
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:is_allowed (action)
-
Test for if a role is allowed the given action, mostly internal see Roles.player_allowed
Parameters:
- action string the name of the action to test if it is allowed
Returns:
-
boolean
true if action is allowed, false otherwise
- Roles._prototype:set_flag (name[, value=true])
-
Sets the state of a flag for a role, flags can be used to apply effects to players
Parameters:
- name string the name of the flag to set the value of
- value boolean the state to set the flag to (default true)
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:clear_flags ()
-
Clears all flags from this role, individual flags can be removed with set_flag(name,false)
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:has_flag (name)
-
A test for if the role has a flag set
Parameters:
- name string the name of the flag to test for
Returns:
-
boolean
true if the flag is set, false otherwise
- Roles._prototype:set_custom_tag (tag)
-
Sets a custom player tag for the role, can be accessed by other code
Parameters:
- tag string the value that the tag will be
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:set_custom_color (color)
-
Sets a custom colour for the role, can be accessed by other code
Parameters:
- color table ?string|table can either be and rgb colour or the name of a colour defined in the presets
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:set_permission_group (name[, use_factorio_api=false])
-
Sets the permission group for this role, players will be moved to the group of they highest role
Parameters:
- name string the name of the permission group to have players moved to
- use_factorio_api boolean when true the custom permission group module is ignored (default false)
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:set_parent (role)
-
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
Parameters:
- role string the name of the role that will be the parent; has imminent effect if role is already defined
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:set_auto_promote_condition (callback)
-
Sets an auto promote condition that is checked every 5 seconds, if true is returned then the player will recive the role
nb: this is one way, failing false after already gaining the role will not revoke the role
Parameters:
- callback function receives only one param which is player to promote, return true to promote the player
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:set_block_auto_promote ([state=true])
-
Sets the role to not allow players to have auto promote effect them, useful to keep people locked to a punishment
Parameters:
- state boolean when true the players with this role will not be auto promoted (default true)
Returns:
-
Roles._prototype
allows chaining
- Roles._prototype:add_player (player, skip_check, skip_event)
-
Adds a player to this role, players can have more than one role at a time, used internally see Roles.assign
Parameters:
- player LuaPlayer the player that will be given this role
- skip_check boolean when true player will be taken as the player name (use when player has not yet joined)
- skip_event boolean when true the event emit will be skipped, this is used internally with Roles.assign
Returns:
-
boolean
true if the player was added successfully
- Roles._prototype:remove_player (player, skip_check, skip_event)
-
Removes a player from this role, players can have more than one role at a time, used internally see Roles.unassign
Parameters:
- player LuaPlayer the player that will lose this role
- skip_check boolean when true player will be taken as the player name (use when player has not yet joined)
- skip_event boolean when true the event emit will be skipped, this is used internally with Roles.unassign
Returns:
-
boolean
true if the player was removed successfully
- Roles._prototype:get_players ([online=nil])
-
Returns an array of all the players who have this role, can be filtered by online status
Parameters:
- online boolean when given will filter by this online state, nil will return all players (default nil)
Returns:
-
table
all the players who have this role, indexed order is meaningless
- Roles._prototype:print (message)
-
Will print a message to all players with this role
Parameters:
- message string the message that will be printed to the players
Returns:
-
number
the number of players who received the message