SAPP Lua Template

-- SAPP_LUA_SCRIPTING_TEMPLATE
-- by Sparky (noman@example.com)
-- March 29, 2016

-- Best viewed with Notepad++ so that the comment sections can collapse and the text indentation is kept.

--[=[   Quick Reference

---
GENERAL
---[[

lua_call <script name> <function name> [arguments]

    Call a function in this file from elsewhere within SAPP.

--]]

---
GAME FUNCTIONS
---[[

assign_weapon(number ObjectID, number PlayerIndex)

    This function assigns a weapon to a player. The player may have at most four weapons. This function will return false if the player was not given the weapon.

    Returns: boolean Success

camo(number PlayerIndex, number DurationTicks)

    This function applies active camouflage for a specified amount of time. There are 30 ticks in a second. Active camouflage cannot be removed from the player once given.

cprint(string Message)

    This function prints a message to the console.

destroy_object(number ObjectID)

    This function removes the object. Removing gametype-specific objects like oddballs or flags, and removing vehicles that were not spawned using SAPP may result in crashing Halo. Destroying a living player's object will cause that player to respawn.

drop_weapon(number PlayerIndex)

    This function drops the player's current weapon.

enter_vehicle(number ObjectID, number PlayerIndex, number Seat)

    This function forces the player to enter the specified object's seat. It returns true if the entry was successful.

    Returns: boolean Success

execute_command(string Command, optional number PlayerIndex, optional boolean Echo)

    This function executes a command on the console or as PlayerIndex if specified. It can be a SAPP command, a custom command, a Halo command, or a cheat command. If Echo is true, then the function raises EVENT_ECHO as well. This function will return a boolean of true if the command was successful, or false if it was not.

    Returns: boolean Success

execute_command_sequence(string Command, optional number PlayerIndex, optional boolean Echo)

    This function executes a sequence of commands separated by semicolons. These commands will be executed on the console or as PlayerIndex if specified. Each command can be a SAPP command, a custom command, a Halo command, or a cheat command. If Echo is true, then the function raises EVENT_ECHO as well. Unlike execute_command, this function does not return anything.

exit_vehicle(number PlayerIndex)

    This function forces the player to exit their vehicle.

get_dynamic_player(number PlayerIndex)

    This function retrieves the address of the player object, or 0 if the player is not alive. This value will change if the player dies or leaves the game.

    Returns: number PlayerObjectAddress

get_object_memory(number ObjectID)

    This function retrieves the address of the object, or 0 if the object does not exist.

    Returns: number PlayerObjectAddress

get_player(number PlayerIndex)

    This function retrieves the memory address of the player table entry.

    Returns: number PlayerTableAddress

get_var(number PlayerIndex, string Variable)

    This function retrieves an event variable, or a custom variable set by var_add.

    Returns: string Value

intersect(number VectorX1, number VectorY1, number VectorZ1, number VectorX2, number VectorY2, number VectorZ2, optional number ObjectID)

    This function checks for a collision intersection between two vectors, with the second vector being relative to the first one. ObjectID is the object to ignore. If Success is false, then all of the other return values are nil. If no object was hit, but there was still a collision, then the returned ObjectID will be 0xFFFFFFFF.

    Returns: boolean Success, number CollisionX, number CollisionY, number CollisionZ, number CollisionObjectID

kill(number PlayerIndex)

    This function will kill the player as well as increase their death count by 1.

lookup_tag(number MetaID)

    This function returns the address of a tag using the tag's ID.

    Returns: number TagAddress

lookup_tag(string TagClass, string TagName)

    This function returns the address of a tag using the tag's class and name.

    Returns: number TagAddress

player_alive(number PlayerIndex)

    This function returns true if the player is alive; false if not.

    Returns: boolean PlayerIsAlive

player_present(number PlayerIndex)

    This function returns true if the player is on the server; false if not.

    Returns: boolean PlayerIsPresent

powerup_interact(number ObjectID, number PlayerIndex)

    This function assigns a powerup to a player.

    Returns: boolean Success

rand(optional number Minimum, optional number Maximum)

    This function generates a random number between Minimum (including) and Maximum (excluding). If unspecified, the values of Minimum and Maximum are 0 and 231, respectively.

    Returns: number RandomNumber

register_callback(number CallbackID, string CallbackFunctionName)

    This function registers a function that will be called every time the event is called. You may only have one function registered per event. Callback IDs are in the cb global variable and are retrieved using cb[“EVENT_ID”].

rprint(number PlayerIndex, string Message)

    This function sends an rcon message to a specific player.

say(number PlayerIndex, string Message)

    This function sends a chat message to a specific player.

say_all(string Message)

    This function sends a chat message to all players.

sig_scan(string Signature)

    This function scans Halo's code for the given masked signature (e.g. "83EC??568BF0A0????????84C00F84"). Spaces are not allowed and ?? are masked bytes which can match anything. Signatures cannot start with masked bytes. If the signature was not found, then 0 is returned instead.

    Returns: number Address

spawn_object(string TagType, string TagPath, optional number X, optional number Y, optional number Z, optional number Rotation, optional number TagID)

    This function spawns an object at the specified coordiantes. If TagID is specified, then TagType and TagPath are not read and effectively become optional arguments. It will return the Object ID of the spawned object.

    Returns: number ObjectID

sync_ammo(number ObjectID)

    This function syncs the ammo for the object in the case that either the magazine or the remaining ammo was changed. It will not sync the battery age or heat of the weapon.

timer(number Milliseconds, string FunctionName, optional string Arguments, ...)

    This function creates a timer that executes a function after a delay. If the timer function returns true, then the timer repeats.

to_player_index(number RealPlayerIndex)

    This function converts a player's table index (used by player tables [0-15]) to the player's rcon index (used by SAPP and commands [1-16]).

    Returns: number PlayerIndex

to_real_index(number PlayerIndex)

    This function converts a player's rcon index (used by SAPP and commands [1-16]) to the player's table index (used by player tables [0-15]).

    Returns: number RealPlayerIndex

unregister_callback(number CallbackID)
unregister_callback(cb[<EVENT_ID>])
    This function unregisters an event that was registered with the register_callback function. Callback IDs are in the cb global variable and are retrieved using cb[“EVENT_ID”].

--]]

---
VIRTUAL MEMORY FUNCTIONS

    These functions are for more advanced scripts that require directly editing the game's memory. If used improperly, these functions can easily crash the server. safe_read and safe_write are provided to prevent a segmentation fault when reading/writing data, but they will not protect the server from crashing if invalid values or instructions are written, and they can increase the time for reading and writing substantially.

---[[

safe_read(boolean Enabled)

    Enabling safe reading will prevent invalid reading from crashing the server, at a significant cost of performance.

safe_write(boolean Enabled)

    Enabling safe reading will prevent invalid writing from crashing the server, as well as allow writing in read-only memory such as program instructions, at a significant cost of performance.

read_bit(number ReadAddress, number Bit)

    This function retrieves a bit from an unsigned 8-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_byte(number ReadAddress)

    This function retrieves an unsigned 8-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_char(number ReadAddress)

    This function retrieves a signed 8-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_word(number ReadAddress)

    This function retrieves an unsigned 16-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_short(number ReadAddress)

    This function retrieves a signed 16-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_dword(number ReadAddress)

    This function retrieves an unsigned 32-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_int(number ReadAddress)

    This function retrieves a signed 32-bit integer, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_float(number ReadAddress)

    This function retrieves a single-precision (32-bit) floating point number, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_double(number ReadAddress)

    This function retrieves a double-precision (64-bit) floating point number, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number Value

read_vector3d(number ReadAddress)

    This function retrieves three single-precision floating point numbers, or nil if failed. May crash server on failure if safe_read is off.

    Returns: number ValueX, number ValueY, number ValueZ

read_string(number ReadAddress)

    This function retrieves an 8-bit null-terminated character string at an address, or nil if failed. May crash server on failure if safe_read is off.

    Returns: string Value

write_bit(number WriteAddress, number Bit, number Value)

    This function writes a bit to an unsigned 8-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_byte(number WriteAddress, number Value)

    This function writes an unsigned 8-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_char(number WriteAddress, number Value)

    This function writes a signed 8-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_word(number WriteAddress, number Value)

    This function writes an unsigned 16-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_short(number WriteAddress, number Value)

    This function writes a signed 16-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_dword(number WriteAddress, number Value)

    This function writes an unsigned 32-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_int(number WriteAddress, number Value)

    This function writes a signed 32-bit integer. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_float(number WriteAddress, number Value)

    This function writes a single-precision (32-bit) floating point number. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_double(number WriteAddress, number Value)

    This function writes a double-precision (64-bit) floating point number. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_vector3d(number WriteAddress, number ValueX, number ValueY, number ValueZ)

    This function writes three single-precision floating point numbers. May crash server on failure if safe_write is off.

    Returns: boolean Success

write_string(number WriteAddress, string Value)

    This function writes an 8-bit null-terminated character string at an address. May crash server on failure if safe_write is off.

    Returns: boolean Success
--]]

---
EVENT VARIABLES
---[[

$n - PlayerIndex from sv_players / pl
$name - Player's name
$hash - Player's cd-key hash
$ip - Player's ip
$tk - Player's TK (betray) count
$kills - Player's kill count
$assists - Player's assist count
$deaths - Player's death count
$suicides - Player's suicide count
$streak - Killstreak count of the player (number of kills without die)
$combo - Combo count, like 2: double kill, 3: triple kill etc.
$score - Player's CTF/Slayer score count
$botscore - The player's current aimbot score
$afk - Player's afk timer
$ping - Player's ping
$x - Player's x coordinate
$y - Player's y coordinate
$z - Player's z coordinate
$hp - Player's health
$sh - Player's shield
$invis - 0: Player is visible, 1: Player is invisible
$team - Player's team
$oteam - Opposite team of the player
$lvl - Admin level of the player, not admin: -1, admin : 0 to 4
$map - The name of the current map
$mode - The name of the current gamemode
$gt - The type of the current game (ex: ctf, slayer, etc.)
$ffa -  0: Team game, 1: FreeForAll
$svname - The name of the server
$redscore - The score of the read team
$bluescore - The score of the blue team
$pn - The number of the players in the server
$reds - The number of the players in the red team
$blues - The number of the players in the blue team
$rand - Gives a random number from 1 to 16

--]]

---
CUSTOM VARIABLES

    You can use custom variables to store text/numbers and use them for more flexible modding. Their value can be used in the event system with adding a "$" before their name, using them like the generic event variables. They can be also used in custom commands in the same way.

---[[

var_add <name> <type>

    Adds a new variable, where:

        type =

            0 - global string
            1 - global int
            2 - global float
            3 - player string
            4 - player int
            5 - player float

    Global ones are containing only 1 variable, while player ones have a different variable for each player, tied to their player ID.

var_del <name>

    Deletes the given variable.

var_set <name> <value_expression> [player_number]

    Sets a given value, player_number is only required for player variables.

var_conv <name>

    Converts int variable to float and vice-versa, not available for string.

var_list

    Lists all variable names and their types. For extremely long lists of 2048 or more variables, will lag and potentially crash the game server. (A more optimal approach to manage lots of player information is to store it in a text file and load into memory only values relevant to the currently connected 16 players.)

--]]

---
COMMAND PLAYER-MATCHING EXPRESSIONS
---[[

'number' - Matches player with given number (from pl command).
* - Matches all players.
*Alan* - Matches all players with Alan in name. (Case-sensitive)
me - Matches the player who is executing the command.
rt - Matches all players on red team.
bt - Matches all players on blue team.
pl - Matches all regular players (non-admins).
admin - Matches all admins.
rand - Will pick a random player.
randred - Will pick a random player from the red team.
randblue - Will pick a random player from the blue team.

--]]

---
PLAYER COMMANDS
---[[

info

    Shows server name, amount of players, map, gametype and if scim mode is enabled or not.

stats

    Shows your kills, assists, deaths, your kill/death ratio and the time since you are playing in the server.

sv_stats

    Displays some cool stats about the server.

about

    Tells you the sapp version, and who made sapp.

whatsnext

    Tells you the next map and gametype if there is sapp mapcycle set.

login

    "V2" Admins can log in with this command so they can use chat too to execute admin commands. Also if Sapp-rcon is disabled (not recommended) players can log-in with the default rcon password.

afk

    Only if enabled by the server admin (set its level to -1): You won't respawn after you died until you type this command again (So you can't be afk-killed).

lead [enabled]

    Tells you if no-lead mode is enabled, if yes you can turn it off and on again for yourself.

clead [ping]

    If no-lead mode is enabled, you can set custom lead for yourself, but only lower or equal to your ping.

    For example if you have 200 ms ping, but you only want to lead 66 ms, then use /clead 66 command in the chat.

stfu

    Blocks every server and rcon message to you which is generated by events or scripts.

unstfu

    Unblocks every server and rcon message to you which is generated by events or scripts.
--]]

---
SERVER CONFIGURATION COMMANDS
---[[

setcmd <command> <name/level>

    Set the name/level of the given command.

    Example: setcmd k kick this will change 'k' command to 'kick'

    setcmd k 3 this will change 'k' (kick) command's level to level 3

anticheat [enabled]

    Enables anticheat mode, when only clients with anticheat can play in the server. Only possible to use it from sapp's init.txt, once it enabled, can't be disabled until you restart the server.

say_prefix [enabled]

    Enable / Disable "** SERVER **" prefix on server messages

msg_prefix <string>

    You can set a custom prefix instead of ** SERVER **. Ex: msg_prefix "** SAPP ** " (default), msg_prefix "" = no prefix

admin_prefix <string>

    Prefix used for messages by the admins with the say command etc. Default is "** ADMIN ** "

cmdstart1 [character]

    This will set the character that used to run admin commands from the chat (if you have admin rights ofc), default is '\'

    For ex in the chat: \pl, \sv_kick 4, or \k 4 noob

cmdstart2 [character]

    Secondary cmdstart, default is '/'

sapp_rcon [enabled]

    If enabled, only sapp admins can use the rcon, v1 admins with the default rcon password, v2 admins with their own password. Bruteforce protection is always active even if this function is disabled.

sapp_mapcycle [enabled]

    If enabled, sapp will use the mapcycle you specified in the mapcycle.txt, read more on the "Sapp Mapcycle" page.

map_skip [value]

    Players can type 'skip' to the chat to skip to the next map. The value is the % of the required votes to skip.

    Value can be between 40 and 100 or 0 to disable map skipping.

mapvote [enabled]

    Enables/disables map voting. See "Map Vote" page for more information.

max_votes [number]

    Specify the amount of displayed mapvotes / round, default value is 5.

    Sapp now cycles the mapvotes, instead of showing all the 8-12+ in the same time. For ex. if the "max_votes" is 5, then the players only can vote for the first 5 options, and after the voted game ended, they can choose from the next 5 option in the end of the next round, etc.

ping_kick [ping]

    If player's ping is higher than [ping] for about 20 seconds, he's kicked. However, player who just joined the game and his ping is high for a while is not punished by this feature. Admins are not kicked, if [ping] is 0 then ping kicking is disabled.

afk_kick [time]

    AFK players (unless they are admins) are kicked after a given period of inactivity (in seconds), if [time] is 0 then afk kicking is disabled.

disable_sj [enabled]

    Disables the usage of SightJacker for HAC users like in ScrimMode.

sj_admin_level [level]

    Enables the usage of HAC2's SightJacker for players with at least the given admin level, value can be between 0 and 5, default value is 5, which means no one can use SJ.

zombies [team]

    This will give some information for a future HAC2 with new medals about which team is the Zombies team. 0 - none, 1 - red, 2 - blue

scrim_mode [enabled]

    If enabled, no one can execute any naughty commands.

    Server sends a message to every player if this status is changed.

    You can also check it's status with the info command.

no_lead [enabled]

    Enables/disables the no_lead mode for everyone. You can check and change the state of leading with the lead command.

    If the admins didn't enable no-lead mode, you can't turn it on for yourself, but if they enabled it, everyone can disable this mod for themselves by typing lead 1 to the chat. Also, you can re-enable it with the lead 0 command.

collect_aliases [enabled] [valid_only]

    If this function is enabled Sapp will track what other names a player used in your server. If valid_only is true, then it will only collect aliases for valid CD-Keys.

alias <player_expr>

    Displays all the names that the player used in your server. Note that you have to enable collecting aliases first with the collect_aliases 1 command (put it to the sapp's init.txt) otherwise this function won't work.

adminban [type]

    Type:0 Admin can kick/ban another admin. (default)

    Type:1 Admin can't kick/ban another admin with higher level.

    Type:2 Admin can't kick/ban another admin with higher or equal level.

adminadd_samelevel [value]

    The value is 0 by default, if set to 1, admins can add other players as admin with the adminadd command with lower level than them, if value is set to 2, admins can add others as admin with lower or equal level.

admindel_samelevel [value]

    The value is 0 by default, if set to 1, admins can delete other players as admin with the admindel command with lower level than them, if value is set to 2, admins can delete others as admin with lower or equal level.

anticaps [enabled]

    OVERUSING CAPS LOCK IS PUNISHED WITH lowercase text

antispam [type]

    Players, who spam the chat usually with spam-bot, will get type: 1 - textban (cd-key based), type: 2 - mute (ip-based)

antihalofp [enabled]

    IP trying to connect to the server more than 8 times in a short time period will be added to IP banlist for 5 minutes. (recommended)

anticamp [time(s)] [distance(u)]

    Raises event_camp <killnumber> 'command' event. For ex. anticamp 30 5 : if the distance between the player's coordinates is less than 5 world units (1 world unit ~ 10 feet or 3.05 meters) in the last 30 sec, it will raise event_camp event with the number of the kills he did while he was in this "camping stage".

    Note: You walk about 3 world unit per second when moving forward at default speed.

    Example events:

        event_camp 3 'say $n "$name Please change your position!"'

        event_camp 4 'say $n "$name stop camping or you will be kicked!"'

        event_camp 5 'say * "Warning! $name will be kicked for camping!"'

        event_camp 6 'k $n Camping'

antiwarp [warp_num]

    Raises an event_warp after the player warped "warp_num" times. Recommended value: 5, 0 means this function is disabled.

    Example:

        sapp's init.txt:

            antiwarp 5

        events.txt:

            event_warp 'kill $n;say $n "You were killed because you are warping."'

spawn_protection [time]

    Spawn Protection. For Example with spawn_protection 5 players will be invincible in the first 5 seconds (or till the first shot) after spawning.

    Value can be between 1 and 10 (and 0 to disable spawn protection)

aimbot_ban [value] [type]

    Players will get scores for "suspect" movements. If a players score is higher than the aimbot_ban value, he/she will be banned =)

    Type -> 0 - Normal Ban, 1 - IP Ban (default), 2 - both, 3 - kick only

    Note that you WON'T get banned if you are shaking your camera like a retarded or killing 15 ppl in half second, etc.

    Value can be between 5000 and 20000. (The less the value, the faster the ban is but more risk for false positives.)

antiglitch [enabled]

    Kills the player if he is out of the BSP, useful in maps such as Danger Canyon or Coldsnap. Thx for 002 for this great find.

save_scores [enabled]

    If enabled, SAPP will save the player's score of the current game, in case if he/she is lag out etc., the player wont lose his/her score/kills/assists/deaths

block_tc [enabled]

    If enabled players are always blocked from changing their team.

log [enabled]

    Enable / Disable SAPP logging.

log rotation [kb]

    Sets the size of the log file after it gets archived. Default value is 4096 (kb).

log_name [name]

    You can specify custom log name. Note that name is without the ".log" file extension.

packet_limit [amount]

    Gives basic DoS protection to the server. If the server receives more packets in 1 second than specified with "amount" Sapp automatically bans the IP. Minimum value is 256, default is 1024, 0 = disabled.

full_ipban [enabled]

    If enabled, all packets from the banned IPs will be blocked, otherwise only join requests and server queries. This function is disabled by default, enabling it with a huge ipban list can cause the server lag and the pings increase.

subtract_afks [enabled]

    If enabled, the number AFK players will be subtracted in the player number on the server list, except if the server is full).

sapp_console [enabled]

    Disables the sv_status spam and instead displays when a player joins/leaves or a new game starts.

console_input [enabled]

    If disabled, the console won't accept any input, this slightly improves reg, mostly useful in servers at hosting companies, where you don't have access to the console anyways. Default value: 1

unlock_console_log <enabled>

    If enabled, unlock some stuff in the memory and console will be more "chatty" :P It will inform you from everything like player join, kill, betray, flag capture etc. (CE version only)

chat_console_echo [enabled]

    If enabled, chat messages will shown in the console window.

set_ccolor [value]

    Set the color of the console text (0-255), 0-15 with black background. Default is 7 (gray text on black background)

max_idle [time]

    If the server is idle for more than "time" seconds Sapp automatically restarts the mapcycle. Default is 60, 0 = disabled.

custom_sleep [value]

    Set the amount that the Halo thread Sleeps every cycle, to use the default speed set it to 0 (with the "33 pings"), default value is 8. Changing this value can improve reg, but very low values like 1 can cause low ping players desync. Note that this has no effect on physics processing or network traffic rate.

v [version]

    Displays/sets the current version of the server.

dns [url]

    Displays/sets the current master server DNS.

--]]

---
NORMAL SERVER COMMANDS

    All the Halo devmode commands are also available.

---[[

load

    Loads server plugin (sapp.dll), commands listed below are available only if 'load' had been issued before.

unload

    Unloads server app, useful when new version of sapp.dll is released :-) and you want to perform update without restarting server.

reload

    Reload all sapp files.

pl

    = sv_players + players/max slot

bans

    = sv_banlist

map <map> <gametype>

    = sv_map with an extra feature that it will cancels mapvote for that round

maplist

    = sv_maplist just with 3 columns

say <player_expr> <message>

    Sends server messages to players matching player_expr.

    sv_say "message" = say * "message"

    Special sequences:

        \n will be replaced with name of player that receives message.

        \t will be replaced with name of his team.

        \o will be replaced with name of opposite team.

k <player_expr> [reason]

    Player will be kicked with a reason noticing the other players.

    Ex: k 4 moron

        ** server ** New 001 was kicked by the admin. Reason: moron

b <player_expr> [time] [reason]

    Player will be banned with a reason noticing the other players.

    Ex: b 4 h4x0r

        ** server ** New 001 was banned by the admin. Reason: h4x0r


afks

    Displays inactivity periods (in seconds) of the players.

skips

    Displays a list about players who voted for skip the current map.

aimbot_scores

    Displays aimbot scores of all players in the server.

balance_teams

    This command will try to make the most equal teams based on kills, assists, deaths and TKs, with a two pass scoring system. ;-)

    Players who got team-switched won't get +1 death.

teamup

    Will set up the two teams based on the tags in the player names.

    This only works if at least one team has proper tags and all are the same, otherwise it won't be always 100% accurate.

refresh_ipbans

    Refresh IP-banlist and ipbans.txt.

change_password <old> <new>

    With this, v2 admins can change their own password.

inf <player_expr>

    Displays PlayerIndex, Name, IP and CD-Key Hash of the given players.

ip <player_number>

    Displays player's IP, Rev DNS and CD-Key hash.

d <player_number>

    Displays some shitty info about the player.

log_note <string>

    Writes a note into the SAPP log.

query_add <key> <value>

    Adds a new entry to the remote query string.

    For example:

        query_add xfire lgbalazs or query_add ventrilo 12.34.56.78:91011

    If a query already exists with the given name, it will be overwritten.

query_del <id/name>

    Deletes a custom remote query entry.

query_list

    Lists all the custom remote query entries.

files

    Lists the Sapp file locations and their encoding.

cpu

    Displays Processor brand string, and operating system version info.

uptime

    Displays uptime of sapp.dll and the operating system.

beep

    Beeepp!!! (beep <hz> <ms> ;)

about

    :*

--]]

---
SPECIAL SERVER COMMANDS

    Not available when scrim_mode is on.

---[[

timelimit [amount]

    Changes the timelimit on the fly, value smaller than 1 means infinitive.

scorelimit [amount]

    Changes the scorelimit on the fly. Works with all gametypes, both FFA and Team games. Note that in special gametypes like KingOfTheHill or OddBall, amount is in minutes.

s <player_expr> [amount]

    Changes speed of given player, default speed is 1.

    Example:

        s 4 6 will changes speed of player 4 to 6.

st <player_expr> [red|blue]

    Changes team of player, if no team is given then team is switched to opposite. Player won't get +1 death. :)

kill <player_expr>

    Kills the player.

kills <player_expr> [amount]

    Sets the kills of the player.

assist <player_expr> [amount]

    Sets the assists of the player.

deaths <player_expr> [amount]

    Sets the deaths of the player.

ctf_score <player_expr> [amount]

    Sets the ctf score of the player.

slayer_score <player_expr>[amount]

    Sets the slayer / team slayer score of the player.

ctf_score_team <team_expr>[amount]

    Sets the ctf scores of the team.

    Ex:

        ctf_scores_team red 20, ctf_scores_team * 4

slayer_score_team <team_expr> [amount]

    Sets the team slayer scores of the team.

god <player_expr>

    Player will be invincible. =)

ungod <player_expr>

    Player can be killed.

lag <player_expr>

    Lag given player.

unlag <player_expr>

    Unlag given player.

camo <player_expr> [time]

    Makes the player invisible for the given time, if no time was specified, the player will be invisible until death.

coord <player_expr>

    Displays the coordinates of the given players.

loc add <location_name> <x> <y> <z>

    Adds new location to list.

    Example:

        loc add red_base 546.4 3.3 24.3

loc add <location_name>

    Adds current player position to location list.

    Example:

        loc add red_base

loc del <location_name>

    Remove location from list.

    Example:

        loc del red_base

loc list

    Lists locations from current map.

loc listall

    Lists locations from all maps. Locations are stored in the halo ce\sapp\locations.txt

area add_sphere <name> <x> <y> <z> <r>

    Adds a new sphere to the current map. x,y,z are the coordinates of the center of the sphere, r is the radius in world units.

area add_cuboid <name> <a_x> <a_y> <a_z> <b_x> <b_y> <b_z>

    Adds a new cuboid to the current map. The cuboid will between the given 'a'-'b' coordinates.

area del <name>

    Deletes an area from the current map.

area list

    Lists all the areas for the current map.

area listall

    Lists all the areas. Areas are stored in the halo ce\sapp\areas.txt

t <player_expr> <x> <y> <z>

    Teleports the player to position (x, y, z).

    Example:

        t 3 100.4 -74.2 36

t <player_expr> <location_name>

    Teleports the player to a previously added location.

    Example:

        t 3 red_base

m <player_expr> <x> <y> <z>

    Same usage as t, this command teleports player to location relative to his current position.

    For example

        m me 0 0 100 moves admin 100 units up.

tp <player_expr> <player_number>

    Teleports given player(s) to another player.

    For example

        tp me 5
            teleports me to player 5

        tp * 1
            teleports all players to player 1

        tp 8 2
            teleports player 8 to player 2

boost <player_expr>

    Teleports the given player to the location where he/she looks.

hp <player_expr> [amount]

    Displays / sets the given player(s) health.

sh <player_expr> [amount]

    Displays / sets the given player(s) shield.

nades <player_expr> [amount] [type]

    Displays / sets the amount of nades of the given players.

    Type:
        0/ungiven: both
        1: frag nades
        2: plasma nades

ammo <player_expr> [amount] [type]

    Displays / sets the amount of the ammo of the given players.

    Type:
        0/ungiven: current weapon
        1: primary
        2: secondary
        3 tertiary
        4: quaternary
        5: all

battery <player_expr> [amount] [type]

    Works the same way as ammo, you can set the battery of the covenant weapons (in %), sync after you switch weapon and switch back. Type is same as above.

mag <player_expr> [amount] [type]

    Set the loaded bullets in the given weapon(s), set it to 32000 for "infinitive" bullets. Type is same as above too.

spawn <type> <name>

    Ex:

        spawn weap "weapons\sniper rifle\sniper rifle"

            will spawn a sniper to you. Scroll down to the bottom of the page for the names of all classic objects.

spawn <type> <name> [player_number]

    Will spawn the object to the given player.

spawn <type> <name> <x> <y> <z> [rot]

    Will spawn the object to the given coords and rotation (in radians).

spawn <type> <name> <location_name>

    Will spawn the object to a previously added location.

wadd <player_expr>

    Assign the last spawned weapon to the given player. You can assign up to 4 weapons. Note that if the player has 4 weapons, he/she can't pick up the flag/oddball.

wdel <player_expr> <weapon_number>

    Removes the weapon from the player's hand, weapon_number: 0 - all, 1-4 the selected one.

wdrop <player_expr>

    Forces the player to drop the current weapon from his/her hands.

venter <player_expr> [seat]

    Enters the player to the last spawned vehicle. Note that you can enter a player to more vehicles and/or more seats in one vehicle. =)

vexit <player_expr>

    Ejects player from the vehicle(s).

vdel <player_expr>

    Deletes the vehicles assigned (with the spawn command) to the given player.

vdel_all

    Deletes every vehicle spawned with Sapp.

disable_object <object_name> [team]

    It will deny the usage of the given objects. You can get the object names from the bottom of this page.

    team:
        0/unset - both
        1 - only players of the red team
        2 - only players of the blue team

    Example: disable shotgun for the blue team

        disable_object "weapons\shotgun\shotgun" 2

disabled_objects

    Displays the disabled objects and their IDs.

enable_object <ID or object_name>

    Allows the usage of the given object. You can get the ID from disabled_objects, or just use the same name of the object that's used for disable it.

disable_all_objects <team> <disable>

    team:
        0 - both
        1 - red
        2 - blue

    disable:
        0 - the team can interact with any object (default)
        1 - the given team(s) can't interact with any object (weapons, powerups, etc.)

disable_all_vehicles <team> <disable>

    team:
        0 - both
        1 - red
        2 - blue

    disable:
        0 - the team can interact with any object (default)
        1 - the given team(s) can't interact with any vehicle

color <player_expr> [index]

    Changes the color of the given players (after respawn, and not in team games).

    Index is a number from 0 to 17, where:
        0 - white
        1 - black
        2 - red
        3 - blue
        4 - gray
        5 - yellow
        6 - green
        7 - pink
        8 - purple
        9 - cyan
        10 - cobalt
        11 - orange
        12 - teal
        13 - sage
        14 - brown
        15 - tan
        16 - maroon
        17 or above - salmon.

gamespeed [speed]

    Sets the game speed, which will be synchronized with HAC2 and Anticheat users. Default value is 30.

--]]

---
DEFAULT OBJECT NAMES

    Escape the backslash and use single-quotation-mark symbols when using these in a Lua script. For example:

        execute_command('spawn vehi "vehicles\\banshee\\banshee_mp"')

---[[

    Vehicles:

Banshee                 vehi "vehicles\banshee\banshee_mp"

Covenant Gun turret     vehi "vehicles\c gun turret\c gun turret_mp"

Ghost                   vehi "vehicles\ghost\ghost_mp"

Rocket Warthog          vehi "vehicles\rwarthog\rwarthog"

Scorpion                vehi "vehicles\scorpion\scorpion_mp"

Warthog                 vehi "vehicles\warthog\mp_warthog"

    Weapons:

Assault Rifle           weap "weapons\assault rifle\assault rifle"

Oddball                 weap "weapons\ball\ball"

Flag                    weap "weapons\flag\flag"

Flamethrower            weap "weapons\flamethrower\flamethrower"

Fuel rod gun            weap "weapons\plasma_cannon\plasma_cannon"

Needler                 weap "weapons\needler\mp_needler"

Pistol                  weap "weapons\pistol\pistol"

Plasma Pistol           weap "weapons\plasma pistol\plasma pistol"

Plasma Rifle            weap "weapons\plasma rifle\plasma rifle"

Rocket Laucher          weap "weapons\rocket launcher\rocket launcher"

Shotgun                 weap "weapons\shotgun\shotgun"

Sniper Rifle            weap "weapons\sniper rifle\sniper rifle"

    Equipment:

Frag Grenade            eqip "weapons\frag grenade\frag grenade"

Plasma Grenade          eqip "weapons\plasma grenade\plasma grenade"

Healt Pack              eqip "powerups\health pack"

Over Shield             eqip "powerups\over shield"

Camouflage              eqip "powerups\active camouflage"

    Bipeds:

Spartan                 bipd "characters\cyborg_mp\cyborg_mp"


--]]

---
CUSTOM COMMANDS
---[[

    You can combine existing commands into custom commands to do more complex operations with one command.

    Custom commands are stored in the gametypes folder, for example "..\savegames\sapp\commands.txt" in the following format:

<command name> [arguments] <command sequence> [level]

    The arguments start with a "#" and they will be replaced in the sequence with the values the command is being called.

    The commands in the sequence are separated by a ";".

    If you don't specify required admin level, it will be 4 (highest) by default.

    Some examples:

        reset 'sv_map_reset' 3

        lo3 'sv_map_reset;w8 1;sv_map_reset;w8 1;sv_map_reset' 3

        max #n 'sv_maxplayers #n' 4

        spam 'w8 600;say * "Have Fun, \n! Server Powered by SAPP, xhalo.tk";spam'

        give #weap 'spawn weap "weapons\#weap\#weap" $n;wadd $n'

        shee 'spawn vehi vehicles\banshee\banshee_mp $n'

        toshee 'shee;venter $n'

        shee_army 'toshee;toshee;toshee;toshee;toshee;toshee;toshee;toshee;toshee;toshee'

cmd_add <command name> [arguments] <command sequence> [level]

    Creates a new custom command and adds it to the end of the commands.txt

cmd_del <command name>

    Deletes the given command, but doesn't modify the commands.txt

list custom

    Lists all custom commands.

--]]

--]=]


-- START OF USER CONFIGURATIONS



-- END OF USER CONFIGURATIONS

api_version = "1.9.0.0"
function OnScriptLoad()
    -- Called when you use the "lua_load" command.

    --register_callback(cb['EVENT_GAME_START'],"OnStart")
    --register_callback(cb['EVENT_DAMAGE_APPLICATION'],"OnDamage")
    --register_callback(cb['EVENT_KILL'],"OnKill")
    --register_callback(cb['EVENT_BETRAY'],"OnBetray")
    --register_callback(cb['EVENT_DIE'],"OnDie")
    --register_callback(cb['EVENT_SUICIDE'],"OnSuicide")
    --register_callback(cb['EVENT_SCORE'],"OnScore")
    --register_callback(cb['EVENT_PRESPAWN'],"OnPreSpawn")
    --register_callback(cb['EVENT_SPAWN'],"OnSpawn")
    --register_callback(cb['EVENT_ALIVE'],"OnLiving")
    --register_callback(cb['EVENT_CHAT'],"OnChat")
    --register_callback(cb['EVENT_PREJOIN'],"OnPreJoin")
    --register_callback(cb['EVENT_JOIN'],"OnJoin")
    --register_callback(cb['EVENT_LEAVE'],"OnLeave")
    --register_callback(cb['EVENT_TEAM_SWITCH'],"OnTeamSwitch")
    --register_callback(cb['EVENT_VEHICLE_ENTER'],"OnVehicleEnter")
    --register_callback(cb['EVENT_VEHICLE_EXIT'],"OnVehicleExit")
    --register_callback(cb['EVENT_AREA_ENTER'],"OnAreaEnter")
    --register_callback(cb['EVENT_AREA_EXIT'],"OnAreaExit")
    --register_callback(cb['EVENT_CAMP'],"OnCamp")
    --register_callback(cb['EVENT_GAME_END'],"OnEnd")
    --register_callback(cb['EVENT_LOGIN'],"OnLogin")
    --register_callback(cb['EVENT_COMMAND'],"OnCommand")
    --register_callback(cb['EVENT_ECHO'],"OnEcho")
    --register_callback(cb['EVENT_TICK'],"OnTick")
    --register_callback(cb['EVENT_MAP_RESET'],"OnMapReset")
    --register_callback(cb['EVENT_OBJECT_SPAWN'],"OnObjectSpawn")
    --register_callback(cb['EVENT_SNAP'],"OnCameraSnap")
    --register_callback(cb['EVENT_WARP'],"OnWarp")
    --register_callback(cb['EVENT_WEAPON_PICKUP'],"OnWeaponPickup")
    --register_callback(cb['EVENT_WEAPON_DROP'],"OnWeaponDrop")
end

function OnScriptUnload()
    -- Called when you use the "lua_unload" command.

end

function OnError(Message)
    -- Called if a declared error occurs in this Lua script
    print(debug.traceback())
end

function OnLiving(PlayerIndex)
    -- This event is called every second that a player is alive.

end

function OnAreaEnter(PlayerIndex, Area)
    -- This event is called when a player enters an area.

end

function OnAreaExit(PlayerIndex, Area)
    -- This event is called when a player exits an area.

end

function OnBetray(PlayerIndex)
    -- This event is called when a player has team-killed.

end

function OnCamp(PlayerIndex, CampKills)
    -- This event is called when a player has killed while camping and anticamp is enabled, with CampKills being the number of kills the player has made while camping.

end

function OnChat(PlayerIndex, Message)
    -- This event is called when a chat message is sent.

    -- Returns: optional boolean Allow

end

function OnCommand(PlayerIndex, Command, Environment, RconPassword)
    -- This event is called when a command has been attempted to be executed, regardless of if the command is valid or not. Environment is 0 if it was the console, 1 if it was executed using rcon (RconPassword will be the rcon password used), 2 if it was executed as a chat command.

    -- Returns: optional boolean Allow

end

function OnDamage(PlayerIndex, Causer, MetaID, Damage, HitString, Backtap)
    -- This event is called when damage is being applied to a player. PlayerIndex is the index of the player who suffers the damage, Causer is the index of the player who caused the damage, MetaID is the Tag-Index of the damage object, Damage is the amount of damage made, HitString can be "head", "body" or "legs", Backtap is true if the damage was a backtap.

    -- Returns: optional boolean Allow, optional number NewDamage

end

function OnDie(PlayerIndex, KilledIndex)
    -- This event is called when a player kills another player. KilledIndex is 0 if the player was killed by an object that was not owned by a player (e.g. a vehicle, an AI, etc.). KilledIndex is -1 if the player died, but not to an object (e.g. was killed by the server, changed teams, fell to their death, etc.).

end

function OnEcho(PlayerIndex, Message)
    -- This event is called if execute_command and execute_command_sequence was used when having their Echo parameter set to true, and if any commands resulted in a text response. This is called for every line.

end

function OnEnd()
    -- This event is called when the game has ended and the scores are being shown.

end

function OnStart()
    -- This event is called when the game has started.

end

function OnJoin(PlayerIndex)
    -- This event is called when a player has joined the server.

end

function OnKill(PlayerIndex, KilledIndex)
    -- This event is called when a player kills another player.

end

function OnLeave(PlayerIndex)
    -- This event is called when a player has disconnected from the server.

end

function OnLogin(PlayerIndex)
    -- This event is called when a player has logged as a SAPP admin.

end

function OnMapReset()
    -- This event is called when the sv_map_reset command is executed.

end

function OnObjectSpawn(PlayerIndex, MetaID, ParentObjectID, ObjectID)
    -- This event is called before an object is created. ParentObjectID is 0xFFFFFFFF if the object has no parents :(. The object's meta ID will be overridden with ReplacementMetaID if it is set.

    -- Returns: optional boolean Allow, optional number ReplacementMetaID

end

function OnPreJoin(PlayerIndex)
    -- This event is called when a player machine has joined the server.

end

function OnPreSpawn(PlayerIndex)
    -- This event is called the moment a player spawns, but before clients are notified, allowing modifications that aren't possible in EVENT_SPAWN.

end

function OnScore(PlayerIndex)
    -- This event is called when a player has scored in CTF.

end

function OnCameraSnap(PlayerIndex, AimbotScoreAdded)
    -- This event is called when a player's camera has moved irregularly and snapped. The player may be suspected of aimbotting.

end

function OnSpawn(PlayerIndex)
    -- This event is called when a player spawns and clients have been notified.

end

function OnSuicide(PlayerIndex)
    -- This event is called when a player has committed suicided.

end

function OnTeamSwitch(PlayerIndex)
    -- This event is called when a player has switched teams.

end

function OnTick()
    -- This event is called every tick (1 tick = 1/30th of a second).

end

function OnVehicleEnter(PlayerIndex, Seat)
    -- This event is called when a player has entered a vehicle. Seat is the index of the seat, starting with 0.

end

function OnVehicleExit(PlayerIndex)
    -- This event is called when a player has exited a vehicle.

end

function OnWarp(PlayerIndex)
    -- This event is called when a player has warped.

end

function OnWeaponDrop(PlayerIndex, WeaponSlot)
    -- This event is called when a player dropped a weapon. WeaponSlot is weapon slots 1 thru 4.

end

function OnWeaponPickup(PlayerIndex, WeaponSlot, WeaponType)
    -- This event is called when a player has picked up a weapon. WeaponType is 1 if it's a standard weapon, or 2 if it's a grenade. If it was a grenade that was picked up, then WeaponSlot is 1 if it was a fragmentation grenade, or 2 if it was a plasma grenade. Otherwise, it's weapon slots 1 thru 4.

end