Lua API version: 1.9.0.0

Game FunctionsAction
assign_weaponGives a weapon to a player, if possible.
camoGives active camouflage to a player.
cprintPrints a message to the console.
destroy_objectRemoves an object.
drop_weaponDrops the player's current weapon.
enter_vehicleForces a player to enter a vehicle.
execute_commandExecutes a command, optionally as a player.
execute_command_sequenceExecutes a sequence of commands, optionally as a player.
exit_vehicleRemoves a player from a vehicle.
get_dynamic_playerGets the player's object if the player is alive.
get_object_memoryGets the memory address of an object by its object ID.
get_playerRetrieves the memory address of the player table entry.
get_varRetrieves an event or custom variable.
intersectChecks for collision intersection between two vectors.
killKills a player.
lookup_tagLooks up the address of a tag using a tag ID.
lookup_tagLooks up the address of a tag using its class and name.
player_aliveChecks if the player is alive.
player_presentChecks if the player is online.
powerup_interactGives a powerup to a player.
randGenerates a random number between two numbers.
register_callbackRegisters an event callback.
rprintSends an rcon message to a player.
saySends a chat message to a player.
say_allSends a chat message to all players.
sig_scanSearches Halo's code for a signature.
spawn_objectSpawns an object.
sync_ammoSyncs the ammo and magazine of a weapon.
timerCreates a timer that is executed after a delay.
to_player_indexConverts a player's table index to an rcon index.
to_real_indexConverts a player's rcon index to a table index.
unregister_callbackUnegisters an event callback.
Event IDsAction
EVENT_ALIVECalled every second a player is alive.
EVENT_AREA_ENTERCalled when a player enters an area.
EVENT_AREA_EXITCalled when a player exits an area.
EVENT_BETRAYCalled when a player has team-killed.
EVENT_CAMPCalled when a player killed while camping and was caught by anticamp.
EVENT_CHATCalled when a chat message is sent.
EVENT_COMMANDCalled when a command is executed.
EVENT_DAMAGE_APPLICATIONCalled when damage is applied to a player.
EVENT_DIECalled when a player has died.
EVENT_ECHOCalled if a command executed by execute_command(_sequence) with Echo.
EVENT_GAME_ENDCalled at the end of the game.
EVENT_GAME_STARTCalled at the beginning of the game.
EVENT_JOINCalled when a player joined the server
EVENT_KILLCalled when a player has killed another player.
EVENT_LEAVECalled when a player left the server
EVENT_LOGINCalled when a player has logged into SAPP.
EVENT_MAP_RESETCalled at map reset.
EVENT_OBJECT_SPAWNCalled before an object is created.
EVENT_PREJOINCalled when a player machine joined the server
EVENT_PRESPAWNCalled when a player spawns before clients are notified.
EVENT_SCORECalled when a player scored in CTF.
EVENT_SNAPCalled when a player's camera has been reported to snap.
EVENT_SPAWNCalled when a player spawns and clients have been notified.
EVENT_SUICIDECalled when a player committed suicide.
EVENT_TEAM_SWITCHCalled when a player changed teams.
EVENT_TICKCalled every tick.
EVENT_VEHICLE_ENTERCalled when a player has entered a vehicle.
EVENT_VEHICLE_EXITCalled when a player has exited a vehicle.
EVENT_WARPCalled when a player warped.
EVENT_WEAPON_DROPCalled when a player dropped their weapon.
EVENT_WEAPON_PICKUPCalled when a player picked up a weapon.
Virtual Memory FunctionsAction
safe_readPrevents segmentation fault when reading invalid addresses.
safe_writePrevents segmentation fault when writing invalid addresses.
read_bitReads a bit from a byte.
read_byteReads an unsigned 8-bit byte.
read_charReads a signed 8-bit char.
read_wordReads an unsigned 16-bit word.
read_shortReads a signed 16-bit short.
read_dwordReads an unsigned 32-bit word.
read_intReads a signed 32-bit int.
read_floatReads a 32-bit float.
read_doubleReads a 64-bit double.
read_vector3dReads three 32-bit floats.
read_stringReads an 8-bit null-terminated string.
write_bitWrites a bit to a byte.
write_byteWrites an unsigned 8-bit byte.
write_charWrites a signed 8-bit char.
write_wordWrites an unsigned 16-bit word.
write_shortWrites an signed 16-bit short.
write_dwordWrites an unsigned 32-bit dword.
write_intWrites a signed 32-bit int.
write_floatWrites a 32-bit float.
write_doubleWrites a 64-bit double.
write_vector3dWrites three 32-bit floats.
write_stringWrites an 8-bit null-terminated string.

Game Functions

These functions are important for interacting with players and objects, as well as manipulating the game.

assign_weapon(number ObjectIDnumber 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 PlayerIndexnumber 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 ObjectIDnumber PlayerIndexnumber 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 Commandoptional number PlayerIndexoptional 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 Commandoptional number PlayerIndexoptional 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 PlayerIndexstring Variable)

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

Returns: string Value

intersect(number VectorX1number VectorY1number VectorZ1number VectorX2number VectorY2number VectorZ2optional 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 Successnumber CollisionXnumber CollisionYnumber CollisionZnumber 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 TagClassstring 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 ObjectIDnumber PlayerIndex)

This function assigns a powerup to a player.

Returns: boolean Success

rand(optional number Minimumoptional 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 CallbackIDstring 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 PlayerIndexstring Message)

This function sends an rcon message to a specific player.

say(number PlayerIndexstring 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 TagTypestring TagPathoptional number Xoptional number Yoptional number Zoptional number Rotationoptional 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 Millisecondsstring FunctionNameoptional 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)

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”].

Events

These events are called when certain conditions have been met. The actual function names are determined by the function name provided in the register_callback function, and these are the event IDs you use. Return values are the values that your function can return.

EVENT_ALIVE(number PlayerIndex)

This event is called every second that a player is alive.

EVENT_AREA_ENTER(number PlayerIndexstring Area)

This event is called when a player enters an area.

EVENT_AREA_EXIT(number PlayerIndexstring Area)

This event is called when a player exits an area.

EVENT_BETRAY(number PlayerIndex)

This event is called when a player has team-killed.

EVENT_CAMP(number PlayerIndexstring 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.

EVENT_CHAT(number PlayerIndexstring Message)

This event is called when a chat message is sent.

Returns: optional boolean Allow

EVENT_COMMAND(number PlayerIndexstring Commandnumber Environmentstring 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

EVENT_DAMAGE_APPLICATION(number PlayerIndexnumber Causernumber MetaIDnumber Damagestring HitStringnumber 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 Allowoptional number NewDamage

EVENT_DIE(number PlayerIndexstring 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.).

EVENT_ECHO(number PlayerIndexstring 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.

EVENT_GAME_END()

This event is called when the game has ended and the scores are being shown.

EVENT_GAME_START()

This event is called when the game has started.

EVENT_JOIN(number PlayerIndex)

This event is called when a player has joined the server.

EVENT_KILL(number PlayerIndexstring KilledIndex)

This event is called when a player kills another player.

EVENT_LEAVE(number PlayerIndex)

This event is called when a player has disconnected from the server.

EVENT_LOGIN(number PlayerIndex)

This event is called when a player has logged as a SAPP admin.

EVENT_MAP_RESET()

This event is called when the sv_map_reset command is executed.

EVENT_OBJECT_SPAWN(number PlayerIndexnumber MetaIDnumber ParentObjectIDnumber 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 Allowoptional number ReplacementMetaID

EVENT_PREJOIN(number PlayerIndex)

This event is called when a player machine has joined the server.

EVENT_PRESPAWN(number PlayerIndex)

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

EVENT_SCORE(number PlayerIndex)

This event is called when a player has scored in CTF.

EVENT_SNAP(number PlayerIndexstring AimbotScoreAdded)

This event is called when a player's camera has moved irregularly and snapped. The player may be suspected of aimbotting.

EVENT_SPAWN(number PlayerIndex)

This event is called when a player spawns and clients have been notified.

EVENT_SUICIDE(number PlayerIndex)

This event is called when a player has committed suicided.

EVENT_TEAM_SWITCH(number PlayerIndex)

This event is called when a player has switched teams.

EVENT_TICK()

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

EVENT_VEHICLE_ENTER(number PlayerIndexstring Seat)

This event is called when a player has entered a vehicle. Seat is the index of the seat, starting with 0.

EVENT_VEHICLE_EXIT(number PlayerIndex)

This event is called when a player has exited a vehicle.

EVENT_WARP(number PlayerIndex)

This event is called when a player has warped.

EVENT_WEAPON_DROP(number PlayerIndexstring WeaponSlot)

This event is called when a player dropped a weapon. WeaponSlot is weapon slots 1 thru 4.

EVENT_WEAPON_PICKUP(number PlayerIndexstring WeaponSlotstring 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.

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 ReadAddressnumber 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 ValueXnumber ValueYnumber 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 WriteAddressnumber Bitnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber 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 WriteAddressnumber ValueXnumber ValueYnumber 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 WriteAddressstring 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