scripting::events Namespace Reference

All script events are raised through functions here. More...

Enumerations
enum	e_ident_or_bool { kIdent = 0, kBool }

Functions
const std::string *	GetEventTable ()
size_t	GetEventTableElementCount ()
bool	OnTeamChange (const halo::s_player &player, bool relevant, DWORD old_team, DWORD new_team)
	Called when a player has changed team.
bool	OnServerCommand (const halo::s_player *player, const std::string &command)
	Called when a server command is being executed.
bool	OnServerCommandAttempt (const halo::s_player &player, const std::string &command, const std::string &password)
	Called when a player without the correct password is trying to execute a server command.
void	OnNewGame (const std::string &map)
	Called when a new game is starting.
void	OnGameEnd (DWORD stage)
	Called when a game is ending.
bool	OnBanCheck (const std::string &hash, const std::string &ip)
	Called when a player is attempting to join.
void	OnClientUpdate (const halo::s_player &player)
	Called when a client sends its update packet.
void	OnPlayerJoin (const halo::s_player &player)
	Called when a player successfully joins the game.
void	OnPlayerLeave (const halo::s_player &player)
	Called when a player quits.
bool	OnTeamDecision (DWORD in_team, DWORD &out_team)
	Called when a player needs to be assigned a team.
void	OnPlayerSpawn (const halo::s_player &player, halo::ident m_objectId)
	Called when a player has spawned.
void	OnPlayerSpawnEnd (const halo::s_player &player, halo::ident m_objectId)
	Called when the server has been notified on the player's spawn.
void	OnObjectCreation (halo::ident m_objectId)
	Called when an object has just been created. You can modify most object settings and have it sync.
e_ident_or_bool	OnObjectCreationAttempt (const halo::objects::s_object_creation_disposition *info, halo::ident &change_id, bool &allow)
	Called when an object wants to be created. You can block it.
bool	OnWeaponAssignment (halo::s_player *player, halo::ident owner, DWORD order, halo::ident weap_id, halo::ident &out)
	Called when an object is being assigned their spawn weapons.
bool	OnObjectInteraction (halo::s_player &player, halo::ident objid, halo::ident mapid)
	Called when a player interacts with an object (ie stands on it)
bool	OnDamageLookup (halo::s_damage_info *dmg, void *metaData, halo::ident receiver, halo::damage_script_options &out)
	Called when the server needs to apply damage to an object.
bool	OnDamageApplication (const halo::s_damage_info *dmg, halo::ident receiver, const halo::s_hit_info *hit, bool backtap)
	Called when the server is about to apply damage to an object.
bool	OnServerChat (const halo::s_player *sender, const std::string &msg, halo::server::chat::e_chat_types &type, std::string &change_msg)
	Called when a player chats in the server.
bool	OnVehicleEntry (const halo::s_player &player, halo::ident veh_id, DWORD seat, bool relevant)
	Called when a player is wanting to enter a vehicle.
bool	OnVehicleEject (const halo::s_player &player, bool forceEjected)
	Called when a player is leaving a vehicle.
void	OnPlayerKill (const halo::s_player &victim, const halo::s_player *killer, DWORD mode)
	Called when a player is killed.
void	OnKillMultiplier (const halo::s_player &player, DWORD multiplier)
	Called when a player gets a kill streak.
bool	OnWeaponReload (const halo::s_player *player, halo::ident weap)
	Called when a weapon is being reloaded.
bool	OnNameRequest (const std::string &hash, const std::string &name, std::string &new_name)
	Called when a player is requesting a certain name (during connection).

Detailed Description

All script events are raised through functions here.

All scripting events receive at least one parameter, this parameter determines whether or not your return value will be considered. It is the last parameter on all functions and you don't need to explicitly add it to your parameter list unless you want to use it.

CHANGES

• If you don't want your return value to be considered you must either return nil or return nothing at all.
• If you return a value and relevant == false it will be ignored.
• The value indicating the server is executing the command is nil not -1
• OnClientUpdate only receives the player's memory id, not their object id.
• OnPlayerJoin only receives the player's memory id, not their team too.
• OnWeaponAssignment should return the id on the desired weapon, it shouldn't returned the result of lookuptag, instead use gettagid. Also, for performance reasons scripts should save the result of gettagid instead of calling it each time.
• OnDamageLookup has completely changed, you shouldn't write to its tagdata anymore. Instead, use the odl_ functions to modify its behaviour.

Enumeration Type Documentation

enum scripting::events::e_ident_or_bool

Enumerator
kIdent
kBool

Function Documentation

const std::string * scripting::events::GetEventTable

(

)

size_t scripting::events::GetEventTableElementCount

(

)

bool scripting::events::OnBanCheck	(	const std::string &	hash,
		const std::string &	ip
	)

Called when a player is attempting to join.

Todo:

make function so scripts can check if hash-checking is on

Parameters

hash	The joining player's hash
ip	The joining player's ip

Returns

Boolean indicating whether or not the player is allowed to join.

Definition:

function OnBanCheck(hash, ip)

void scripting::events::OnClientUpdate

(

const halo::s_player &

player

)

Called when a client sends its update packet.

Parameters

player

The player's memory id.

Remarks

This function is called 30 times a second for every player in the server. Do not process this event unless you absolutely have to, and when processing it make your code as efficient as possible.

Definition:

function OnClientUpdate(player)

bool scripting::events::OnDamageApplication	(	const halo::s_damage_info *	dmg,
		halo::ident	receiver,
		const halo::s_hit_info *	hit,
		bool	backtap
	)

Called when the server is about to apply damage to an object.

Parameters

receiving	object id of the object that is to receive the damage.
causing	object id of the object that is causing the damage.
tagid	tag id of damage tag which is being used.
hit	string describing the hit location (eg head, legs)
backtap	true if damage is a melee from behind, false otherwise.

Returns

boolean indicating whether or not to allow the damage.

Remarks

You cannot modify the amount of damage done because it's already been calculated. The only action you can take is to block the damage.

There are many possible hit strings, including but not limited to: head, legs, body, metal, rubber, trunk, stock, ...

Definition:

function OnDamageApplication(receiving, causing, tagid, hit, backtap)

bool scripting::events::OnDamageLookup	(	halo::s_damage_info *	dmg,
		void *	metaData,
		halo::ident	receiver,
		halo::damage_script_options &	out
	)

Called when the server needs to apply damage to an object.

Parameters

receiving	object id of the object that is to receive the damage.
causing	object id of the object that is causing the damage.
tagid	tag id of damage tag which is being used.
tagdata	Memory address of the tag's meta data.

Returns

boolean indicating whether or not to allow the damage.

Definition:

function OnDamageLookup(receiving, causing, tagid)

void scripting::events::OnGameEnd

(

DWORD

stage

)

Called when a game is ending.

Parameters

stage

The stage of the game that has ended.

Remarks

stage can be either:

• 1 The game has just ended, and the ingame score card is shown.
• 2 The postgame scorecard is shown.
• 3 Players can now leave.

Definition:

function OnGameEnd(stage)

void scripting::events::OnKillMultiplier	(	const halo::s_player &	player,
		DWORD	multiplier
	)

Called when a player gets a kill streak.

Parameters

player	The player's memory id
multiplier	The multiplier the player got.

Remarks

Valid multipliers are:

• 7 Double kill
• 9 Triple kill
• 10 Killtacular
• 11 Killing spree
• 12 Running riot
• 16 Double kill w/ score
• 15 Triple kill w/ score
• 14 Killtacular w/ score
• 18 Killing spree w/ score
• 17 Running riot w/ score

I think the w/ score ones happen in Slayer.

Definition:

function OnKillMultiplier(player, multiplier)

bool scripting::events::OnNameRequest	(	const std::string &	hash,
		const std::string &	name,
		std::string &	new_name
	)

Called when a player is requesting a certain name (during connection).

Parameters

hash	The hash of the requesting machine.
name	The requested name.

Returns

allow, new_name

Remarks

If allow is false then the player is assigned a random name. If new_name is specified, then allow is ignored and the player's name is changed to new_name

Definition:

function OnNameRequest(hash, name)

void scripting::events::OnNewGame

(

const std::string &

map

)

Called when a new game is starting.

Parameters

map	The map the game is running.

Definition:

function OnNewGame(map)

void scripting::events::OnObjectCreation

(

halo::ident

m_objectId

)

Called when an object has just been created. You can modify most object settings and have it sync.

Parameters

objid

The object id of the newly created object.

Definition:

function OnObjectCreation(m_objid)

e_ident_or_bool scripting::events::OnObjectCreationAttempt	(	const halo::objects::s_object_creation_disposition *	info,
		halo::ident &	change_id,
		bool &	allow
	)

Called when an object wants to be created. You can block it.

Parameters

mapid	The id of the object being created.
parentid	The object id of the to be created object's parent.
player	The memory id of the owning player.

Returns

boolean indicating whether or not the object should be created OR map id of object to create instead.

Remarks

Both parent and player can be nil if the object doesn't have a parent or isn't owned by a player.

If you return a map id, it must be of the same class as the input (ie weap) or it is ignored, and the object is created.

Definition:

function OnObjectCreationAttempt(mapid, parentid, player)

bool scripting::events::OnObjectInteraction	(	halo::s_player &	player,
		halo::ident	objid,
		halo::ident	mapid
	)

Called when a player interacts with an object (ie stands on it)

Parameters

player	The player interacting with the object
objid	The object being interacted with.
mapid	The map id of the object being interacted with.

Returns

Boolean indicating whether or not to allow the interaction.

Definition:

function OnObjectInteraction(player, objid, mapid)

void scripting::events::OnPlayerJoin

(

const halo::s_player &

player

)

Called when a player successfully joins the game.

Parameters

player

The joining player's memory id.

Definition:

function OnPlayerJoin(player)

void scripting::events::OnPlayerKill	(	const halo::s_player &	victim,
		const halo::s_player *	killer,
		DWORD	mode
	)

Called when a player is killed.

Parameters

killer	The killer's memory id.
victim	The victim's memory id.
mode	Describes how they died.

Remarks

• killer can be nil.
• victim is never nil.
• Modes:
  • 0 Killed by the server.
  • 1 Killed by fall damage.
  • 2 Killed by the guardians.
  • 3 Killed by a vehicle.
  • 4 Killed by killer
  • 5 Betrayed by killer
  • 6 Suicide

Definition:

function OnPlayerKill(killer, victim, mode)

void scripting::events::OnPlayerLeave

(

const halo::s_player &

player

)

Called when a player quits.

Parameters

player

The player who left.

Definition:

function OnPlayerLeave(player)

void scripting::events::OnPlayerSpawn	(	const halo::s_player &	player,
		halo::ident	m_objectId
	)

Called when a player has spawned.

Parameters

player	The player who is spawning.
objid	The player's new object id.

Definition:

function OnPlayerSpawn(player, m_objectId)

void scripting::events::OnPlayerSpawnEnd	(	const halo::s_player &	player,
		halo::ident	m_objectId
	)

Called when the server has been notified on the player's spawn.

Parameters

player	The player who is spawning.
objid	The player's new object id.

Definition:

function OnPlayerSpawnEnd(player, m_objectId)

bool scripting::events::OnServerChat	(	const halo::s_player *	sender,
		const std::string &	msg,
		halo::server::chat::e_chat_types &	type,
		std::string &	change_msg
	)

Called when a player chats in the server.

Parameters

player	The chatting player's memory id
type	The type of chat
msg	The message being sent.

Returns

allow, msg, type

Remarks

player is nil if it's a server message. If it's a private server message then player is the player who will receive the message.

Valid type values:

• 0 All chat
• 1 Team chat
• 2 Vehicle chat
• 3 Server message
• 4 Private server message

return value: you can include (or not) any of the three return values. Note: you cannot change a server message into a player message. Below are some examples:

return false -- block the message

return true, "Hello" -- change the message to Hello

function OnServerChat(player, type, msg)
    if (type == 4) then return end
    return true, msg, 1 -- don't change the message, but make it team-only
end

Definition:

function OnServerChat(player, type, msg)

bool scripting::events::OnServerCommand	(	const halo::s_player *	player,
		const std::string &	command
	)

Called when a server command is being executed.

This function is only called when the player enters the correct rcon password and when they are allowed to execute the desired command.

Parameters

player	The player executing the command
command	The command being executed.

Returns

boolean indicating whether or not Phasor should process the command.

Definition:

function OnServerCommand(player, command)

bool scripting::events::OnServerCommandAttempt	(	const halo::s_player &	player,
		const std::string &	command,
		const std::string &	password
	)

Called when a player without the correct password is trying to execute a server command.

Parameters

player	The player wanting to execute the command
command	The command they want to execute.

Returns

boolean indicating whether or not the command can be processed.

Remarks

Only called when the incorrect password is supplied.

Definition:

function OnServerCommandAttempt(player, command, password)

bool scripting::events::OnTeamChange	(	const halo::s_player &	player,
		bool	relevant,
		DWORD	old_team,
		DWORD	new_team
	)

Called when a player has changed team.

Parameters

player	The player who is changing team.
old_team	The player's old team
new_team	The player's new team
relevant	Determines whether or not your return value matters.

Returns

boolean indicating whether or not the player should change team.

Remarks

It is important that if you process this function, you process relevant correctly.

Definition:

function OnTeamChange(player, old_team, new_team, relevant)

bool scripting::events::OnTeamDecision	(	DWORD	in_team,
		DWORD &	out_team
	)

Called when a player needs to be assigned a team.

Parameters

team	The team the player is about to be put on.

Returns

The team you want the player on, or nil if you don't care.

Definition:

function OnTeamDecsion(team)

bool scripting::events::OnVehicleEject	(	const halo::s_player &	player,
		bool	forceEjected
	)

Called when a player is leaving a vehicle.

Parameters

player	The player's memory id
relevant	Boolean indicating whether or not you can stop them leaving.

Returns

Boolean indicating whether or not they can leave.

Definition:

function OnVehicleEject(player, relevant)

bool scripting::events::OnVehicleEntry	(	const halo::s_player &	player,
		halo::ident	veh_id,
		DWORD	seat,
		bool	relevant
	)

Called when a player is wanting to enter a vehicle.

Parameters

player	The player's memory id.
veh_id	The object id of the vehicle they're trying to enter.
seat	The seat they're trying to enter.
mapid	The map id of the vehicle they're trying to enter.
relevant	Whether or not you can stop them entering.

Returns

Boolean indicating whether or not they should be allowed to enter.

Definition:

function OnVehicleEntry(player, veh_id, seat, mapid, relevant)

bool scripting::events::OnWeaponAssignment	(	halo::s_player *	player,
		halo::ident	owner,
		DWORD	order,
		halo::ident	weap_id,
		halo::ident &	out
	)

Called when an object is being assigned their spawn weapons.

Parameters

player	The memory id of the player, if the weapons belong to a player.
owner	The object id of the object which owns the assigned weapon.
order	Which weapon is being assigned (first, second, third etc)
weap_id	The map id of the weapon which will be assigned.

Returns

The map id of the weapon you wish to assign.

Remarks

• player is nil when assigning weapons to vehicles.
• The value returned should be either:
  • nil if you don't want to change the assigned weapon.
  • or The map id of the weapon you wish to assign
  • or -1 if you don't want the weapon to be assigned.

I recommend you do all of your tag lookups in OnNewGame and store the results globally.

For this to have any effect the gametype must have starting equipment set to generic.

Definition:

function OnWeaponAssignment(player, owner_id, order, weap_id)

bool scripting::events::OnWeaponReload	(	const halo::s_player *	player,
		halo::ident	weap
	)

Called when a weapon is being reloaded.

Parameters

player	The player who is reloading.
objid	The object id of the weapon being reloaded.

Returns

Boolean indicating whether or not they can reload.

Remarks

player can be nil if a vehicle's weapon is being reloaded.

Definition:

function OnWeaponReload(player, objid)