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.