# Module `ExpGamingCore.Role`

A full ranking system for factorio.

### Info:

- License: https://github.com/explosivegaming/scenario/blob/master/LICENSE
- Author: Cooldude2606

## Functions

output_ranks ([player=server]) | Outputs as a string all the ranks and the loaded order
_base_preset (ranks) | Used to set the prset ranks that will be given to players
get_rank (mixed) | Returns a rank object given a player or rank name
get_group (mixed) | Returns the group object used to sort ranks given group name or rank
print (rank_base, rtn[, colour=defines.color.white[, below=false]]) | Prints to all rank of greater/lower power of the rank given
give_rank (player[, rank=default[, by_player='server'[, tick=game.tick]]]) | Gives a user a rank
revert (player[, by_player=nil]) | Revert the last change to a players rank
find_preset (player[, tick=nil]) | Given that the player has a rank in the preset table it is given; also will attempt to promote players if a time requirement is met

## Tables

global | Global Table
ranks | Contains the location of all the ranks, readonly during runtime
ranks | Contains the location of all the rank groups, readonly during runtime
meta | Contains some meta data about the ranks

## Events

on_rank_change | Called when there is a rank change for a user

## Class Rank

Ranking._rank:allowed (action) | Is this rank allowed to open this gui or use this command etc.
Ranking._rank:get_players ([online=false]) | Get all the players in this rank
Ranking._rank:print (rtn[, colour=defines.color.white[, show_default=false]]) | Print a message to all players of this rank
Ranking._rank:edit (key, value) | Allows for a clean way to edit rank objects

## Class Group

Ranking._group:create (obj) | Creates a new group
Ranking._group:add_rank (obj) | Creats a new rank with this group as its group
Ranking._group:edit (key, value) | Allows for a clean way to edit rank group objects

## modules.expgamingcore.ranking.src.server Functions

_comment () | This file will be loaded when ExpGamingCore.Server is present
Ranking._rank:print (rtn[, colour=defines.color.white[, show_default=false]]) | Print a message to all players of this rank

## Functions

output_ranks ([player=server])
  Outputs as a string all the ranks and the loaded order

  ### Parameters:

  - player player_name, player_index or LuaPlayer the player that the info will be printed to, nil will print to server (default server)

  ### Usage:

      Ranking.output_ranks(player) -- prints to player

_base_preset (ranks)
  Used to set the prset ranks that will be given to players

  ### Parameters:

  - ranks table table of player names with the player name as the key and rank name as the value

  ### Usage:

      Ranking._base_preset{name=rank_name,nameTwo=rank_name_two} -- sets player name to have rank rank_name on join

get_rank (mixed)
  Returns a rank object given a player or rank name

  ### Parameters:

  - mixed player, player_index, player_name, rank_name, Ranking._rank, 'server' or 'root' what rank to get

  ### Returns:

  table the rank that is linked to mixed

  ### Or

  nil there was no rank found

  ### Usage:

  -     Ranking.get_rank(game.player) -- returns player's rank

  -     Ranking.get_rank('admin') -- returns rank by the name of admin

get_group (mixed)
  Returns the group object used to sort ranks given group name or rank

  ### Parameters:

  - mixed player, player_index, player_name, rank_name, rank, 'server', 'root', group_name or group what group to get

  ### Returns:

  table the group that is linked to mixed

  ### Or

  nil there was no rank group found

  ### See also:

  Ranking.get_rank

  ### Usage:

  -     Ranking.get_group(game.player) -- returns player's rank group

  -     Ranking.get_group('root') -- returns group by name of root

print (rank_base, rtn[, colour=defines.color.white[, below=false]])
  Prints to all rank of greater/lower power of the rank given

  ### Parameters:

  - rank_base Ranking._rank or pointerToRank the rank that acts as the cut off point (rank is always included)
  - rtn what do you want to return to the players
  - colour defines.color the colour that will be used to print (default defines.color.white)
  - below boolean if true print to children rather than parents (default false)

  ### Usage:

      Ranking.print('admin','We got a grifer')

give_rank (player[, rank=default[, by_player='server'[, tick=game.tick]]])
  Gives a user a rank

  ### Parameters:

  - player LuaPlayer or pointerToPlayer the player to give the rank to
  - rank Ranking._rank or pointerToRank the rank to give to the player (default default)
  - by_player LuaPlayer or pointerToPlayer the player who is giving the rank (default 'server')
  - tick number the tick that the rank is being given on, used as pass though (default game.tick)

  ### Usage:

      Ranking.give_rank(1,'admin')

revert (player[, by_player=nil])
  Revert the last change to a players rank

  ### Parameters:

  - player LuaPlayer or pointerToPlayer the player to revert the rank of
  - by_player the player who is doing the revert (default nil)

  ### Usage:

      Ranking.revert(1) -- reverts the rank of player with index 1

find_preset (player[, tick=nil])
  Given that the player has a rank in the preset table it is given; also will attempt to promote players if a time requirement is met

  ### Parameters:

  - player LuaPlayer or pointerToPlayer the player to test for an auto rank
  - tick number the tick it happens on (default nil)

  ### Usage:

      Ranking.find_preset(1) -- attemps to find the preset for player with index 1

## Tables

global
  Global Table

  ### Fields:

  - old contains the previous rank a use had before a rank change
  - preset contains the preset ranks that users will recive apon joining
  - last_change contains the name of the player who last had there rank chagned
ranks
  Contains the location of all the ranks, readonly during runtime
ranks
  Contains the location of all the rank groups, readonly during runtime
meta
  Contains some meta data about the ranks

  ### Fields:

  - default this is the name of the default rank
  - root this is the name of the root rank
  - time_ranks a list of all ranks which have a time requirement
  - time_highest the power of the highest rank that has a time requirement
  - time_lowest the lowest amount of time required for a time rank

## Events

on_rank_change
  Called when there is a rank change for a user

  ### field:

  - name the rank id
  - tick the tick which the event was raised on
  - player_index the player whos rank was changed
  - by_player_index the player who changed the rank, 0 means server
  - new_rank the name of the rank that was given
  - old_rank the name of the rank the player had

## Class Rank

The class for the ranks

Ranking._rank:allowed (action)
  Is this rank allowed to open this gui or use this command etc.

  ### Parameters:

  - action teh to test for

  ### Returns:

  boolean is it allowed

  ### Usage:

      rank:allowed('interface') -- does the rank have permision for 'interface'

Ranking._rank:get_players ([online=false])
  Get all the players in this rank

  ### Parameters:

  - online boolean get only online players (default false)

  ### Returns:

  table a table of all players in this rank

  ### Usage:

      rank:get_players()

Ranking._rank:print (rtn[, colour=defines.color.white[, show_default=false]])
  Print a message to all players of this rank

  ### Parameters:

  - rtn any value you want to return
  - colour define.color the colour that will be used to print (default defines.color.white)
  - show_default boolean weather to use the default rank name for the print, used as a pass though (default false)

  ### Usage:

      rank:print('foo') -- prints to all members of this rank

Ranking._rank:edit (key, value)
  Allows for a clean way to edit rank objects

  ### Parameters:

  - key string the key to edit, often allow or disallow
  - value the new value to be set

  ### Usage:

      rank:edit('allow',{'interface'}) -- allows this rank to use 'interface'

## Class Group

The class for the rank groups, the way to allow modules to idex a group that is always present, ranks will always look to there group as a parent

Ranking._group:create (obj)
  Creates a new group

  ### Parameters:

  - obj table the fields for this object

  ### Returns:

  Ranking._group returns the object to allow chaining

  ### Usage:

      Ranking._group:create{name='root'} -- returns group with name root

Ranking._group:add_rank (obj)
  Creats a new rank with this group as its group

  ### Parameters:

  - obj table the fields for this object

  ### Returns:

  Ranking._group returns the object to allow chaining

  ### Usage:

      group:add_rank{name='root'} -- returns self

Ranking._group:edit (key, value)
  Allows for a clean way to edit rank group objects

  ### Parameters:

  - key string the key to edit, often allow or disallow
  - value the new value to be set

  ### Usage:

      group:edit('allow',{'interface'}) -- allows this rank to use 'interface'

## modules.expgamingcore.ranking.src.server Functions

_comment ()
  This file will be loaded when ExpGamingCore.Server is present
Ranking._rank:print (rtn[, colour=defines.color.white[, show_default=false]])
  Print a message to all players of this rank

  ### Parameters:

  - rtn any value you want to return
  - colour define.color the colour that will be used to print (default defines.color.white)
  - show_default boolean weather to use the default rank name for the print, used as a pass though (default false)

  ### Usage:

      rank:print('foo') -- prints to all members of this rank

generated by LDoc 1.4.6 Last updated 2018-06-07 12:58:23