====== Functions ======
===== Player Functions =====
==== Identification ====
^ Name and Parameters ^ Return Value ^ Description ^
| server.player_id(cn) | number | Get the unique ID for the player's name and ip address. |
| server.player_sessionid(cn) | number | Get the unique ID for the player's connection |
| server.player_name(cn) | string | Get the player's name. |
| server.player_displayname(cn) | string | Get the player's name for name display. If name is not unique then CN is appended. |
| server.player_team(cn) | string | Get the player's team name. |
| server.player_ip(cn) | string | Get the player's IP address. |
| server.player_iplong(cn) | number | Get the player's IP address in long number form. |
==== Game Stats ====
^ Name and Parameters ^ Return Value ^ Description ^
| server.player_frags(cn) | number | Note: affected by suicide and teamkilling |
| server.player_deaths(cn) | number | |
| server.player_teamkills(cn) | number | |
| server.player_suicides(cn) | number | |
| server.player_damage(cn) | number | |
| server.player_damagewasted(cn) | number | |
| server.player_hits(cn) | number | |
| server.player_misses(cn) | number | |
| server.player_shots(cn) | number | |
| server.player_accuracy(cn) | number | Calculated from shots and misses. Note: game client uses different calculation method which maybe noticeable in game modes such as ffa or efficiency. |
| server.player_accuracy2(cn) | number | Calculated from damage and damagewasted. Client calculation method, used in awards/best_stats and stats modules. |
| server.player_timeplayed(cn) | number | Number of seconds played in the current game. |
| server.player_win(cn) | number | Returns 1 or 0 for win or lose, respectively. In singles mode, a winner is a player with the most frags. In team mode, winners are players on the winning team. |
| server.player_rank(cn) | number | Player's rank calculated at the end of the game. For team games, rank is relative to team members. |
| server.player_armour(cn) | number | |
| server.player_armour_type(cn) | number | |
==== Connection Stats ====
^ Name and Parameters ^ Return Value ^ Description ^
| server.player_connection_time(cn) | number | Number of seconds connected to the server. |
| server.player_ping(cn) | number | Returns the last reported ping value. |
| server.player_lag(cn) | number | Get the player's lag value measured as the time delay between receiving position updates. |
==== Current Status ====
^ Name and Parameters ^ Return Value ^ Description ^
| server.player_status(cn) | string | Game status: dead, alive, editing etc. |
| server.player_status_code(cn) | number | Constants: ''server.ALIVE'', ''server.DEAD'', ''server.SPAWNING'', ''server.LAGGED'', ''server.SPECTATOR'', ''server.EDITING'' |
| server.player_pos(cn) | number, number, number | Last received position |
| server.player_gun(cn) | string | Current weapon held |
| server.player_health(cn) | number | |
| server.player_maxhealth(cn) | number | |
| server.player_priv(cn) | string | Master status: none, master or admin |
| server.player_priv_code(cn) | number | Constants: ''server.PRIV_NONE'', ''server.PRIV_MASTER'' and ''server.PRIV_ADMIN'' |
| server.player_mapcrc(cn) | string | The map crc value sent by the client. |
| server.player_isbot(cn) | boolean | Returns true if the player is a bot. |
==== Control ====
^ Name and Parameters ^ Return Value ^ Description ^
| server.player_msg(cn, text) | nil | Send a server message to a player.|
| server.player_slay(cn) | nil | Kill a player; their stats aren't affected.|
| server.player_suicide(cn) | nil | Force a player to suicide, which will affect their game stats. |
| server.changeteam(cn, team) | boolean | Move a player to another team.|
| server.kick(cn,[bantime],[admin],[reason]) | nil | Kick and ban a player from the server. Argument defaults: bantime=4 hours, admin="server", reason="".|
| server.permban(ip) | nil | Set IP address range as permanently banned from the server.|
| server.unsetban(ip) | boolean | Remove IP address from ban list.|
| server.spec(cn) | number | Force a player to join spectators.|
| server.unspec(cn) | nil | Force a player to join the game.|
| server.mute(cn) | nil | Block the player's chat messages as they're received.|
| server.unmute(cn) | nil | Set to not block the player's chat messages.|
| server.setmaster(cn) | nil | Give a player master privilege. Note: only 1 visible master/admin is supported.|
| server.setadmin(cn) | nil | Give a player admin privilege. Note: only 1 visible master/admin is supported.|
| server.unsetmaster() | nil | Take away master privilege from the current master.|
| server.set_invisible_admin(cn) | nil | Give player admin status, but is invisible to other players.|
| server.set_invisible_master(cn) | nil | Give player master status, but is invisible to other players.|
| server.unsetpriv(cn) | nil | Take away player's master or admin privilege. This function should work on all privilege configurations.|
==== Player Iteration ====
^ Name and Parameters ^ Return Value ^ Description ^
| server.players() | table | Returns an array of CNs for all the human players playing |
| server.gplayers(option) | | Iterator function, returns a player object for each iteration. Option argument can be either nil, "players", "spectators" or "all" |
| server.spectators() | table | Returns an array of CNs for all the spectators |
| server.bots | table | Returns an array of CNs for all the bot players |
==== Object Wrapper ====
The object wrapper turns the player functions into player object methods, you might find it's quicker or think it's nicer to use the object wrapper. The function names are the same except they don't have the player prefix, so for example the .player_frags(cn) is just :frags() for the player object. To construct a new player object call server.new_player_object(cn)
Example:
for player in server.gplayers() do
player:spec()
end
===== Team Functions =====
^ Name and Parameters ^ Return Value ^ Description ^
| server.teams() | table | Returns an array of team names. |
| server.team_players(team) | table | Returns an array of CNs for all players on the specified team. |
| server.team_score(team) | number | |
| server.team_win(team) | boolean | Has the highest score of all the teams |
| server.team_draw(team) | boolean | Score is equal to the scores of all the other teams. TODO: remove argument. |
===== Game Functions =====
^ Name and Parameters ^ Description ^
| pausegame(pause) | Pause or resume game. Argument value must be 1 or 0 |
| changetime(milliseconds) | Change time remaining |
| changemap(map,[mode],[time]) | Change map |
| delbot(cn) | Remove a bot from the game belonging to a player |
===== Server Functions =====
^ Name and Parameters ^ Description ^
| restart() | Restart server process at end of the game or immediately if the server is empty. |
| restart_now() | Restart server now |
| shutdown() | Shut down server process (which will also terminate the irc bot process) |
| reloadscripts() | Reload all the scripts without restarting the server |
| msg(text) | Broadcast message on server |
| clearbans() | Clear all temporary bans |
| loadbanlist(filename) | |
| writebanlist(filename) | |
| permban(ip) | |
| unsetban(ip) | |
| recorddemo(filename) | Immediately start recording the game (no server message is broadcast) |
| stopdemo() | Stop recording game |
===== Utility Functions =====
^ Name and Parameters ^ Description ^
| ip_to_country(ip) | Resolve IP address to country |
| ip_to_country_code(ip) | Resolve IP address to a two letter country code |
| load_geoip_database(filename) | Resolve ip address to a two letter country code |
| gethostbyname(name) | Resolve FQDN to IP address. |