View source for Event Reference

The interaction between the BF2 engine and Python programs is largely [[wikipedia:Event-driven programming|event-driven]]: when an "event" happens in a game, BF2 checks to see if any Python programs have registered to be notified of that particular event; if they have, they are called (a "callback"). One way to think about this: the events are "hooks" into the game engine to which you can attach your own Python code.

Multiple callbacks can be registered for any given event; all registered callbacks will be executed when the event occurs.  For example, if three different programs have registered for the "PlayerConnect" event, then when a new player connects, all three of those programs will be run.


== Types of Events ==

The BF2 engine supports five types of events:


=== Standard Events ===

These are events that occur during the normal course of game play.

To register to receive a callback for a particular standard event:
  host.registerHandler('EventName', pythonEventHandler[, parameter])
This registration will typically be done in the <tt>init()</tt> method of an object, but could be done anywhere in your code.


=== Game Status Events ===

The BF2 engine generates these events when the status of the game changes. You register to receive callbacks for these events with:
  host.registerGameStatusHandler(pythonEventHandler)

The possible states game status can be in (as enumerated in <code>bf2.GameStatus</code>) are:
* NotConnected
* PreGame
* Playing
* Paused
* EndGame
* RestartServer

Game status events are usually used to kick off pre-game initialization or post-game clean-up processing.


=== Trigger Events ===

"Trigger" events activate when a vehicle comes within a specified distance of an object. Triggers are created and registered for by:
  bf2.triggerManager.createHemiSphericalTrigger
       (object, triggerEventHandler, objectName, radius[, data])
or
  bf2.triggerManager.createRadiusTrigger
       (object, triggerEventHandler, objectName, radius[, data])

In standard Battlefield 2, trigger events are used to track scoring for flag captures (triggers activate whenever a player enters or leaves a fixed radius around each control point), as well as effects such as birds (birds are triggered to take flight whenever a player enter their trigger radius).


=== Timer Events ===

"Timer" events activate when a certain amount of time has elapsed. Timers are created and registered for by:
  bf2.Timer(timerEventHandler, delta, alwaysTrigger[, data])
(see the description of the [[Object Reference#bf2.Timer|<code>bf2.Timer</code>]] class for details).

In standard Battlefield 2, timer events are used to cause periodic status checks related to scoring, ranking, punishing TKs, etc.


== Descriptions of Events ==

EA/DICE have not published a list of events, but here is a list of events that have been discovered so far. The format of this information is
; EventName(handlerParameter1, handlerParameter2, ...) : Description of event
The "EventName" is the name of the event to register for with <code>host.registerHandler</code>; the parameters are the parameters your handler should receive when called.

Some notes about some of the arguments used in these descriptions: 
* [[Player Identity#Player Object|'''playerObject''']]: An instance of <code>[[Object Reference#bf2.PlayerManager.Player|bf2.PlayerManager.Player]]</code>	 
* [[Player Identity#Player ID|'''playerID''']]: As players connect to the server they are assigned playerID numbers from "1" up.	 
* '''squadID''': Squads for each side are independently numbered beginning at "1" and increasing thereafter. Players not on a squad, including team commanders, are assigned to squad "0".	 
* '''teamID''': "0" for US, "1" for China or MEC	 



=== Server Events ===

; ServerReady : TBD
; BeginRound : TBD
; EndRound : TBD


=== Player Events ===

; PlayerConnect(playerObject) : fires when a player connects to the game.
; PlayerSpawn(playerObject, soldierObject) : Occurs when a player spawns, and associates a playerObject "spirit" with a soldierObject "body".
; PlayerChangeTeams(playerObject, humanHasSpawned) : HumanHasSpawned is 1 if the player the event is firing for is a human (as opposed to an AI).
; PlayerChangeWeapon(playerObject, oldWeaponObject, newWeaponObject)  : Player has changed which weapon they are holding.
; PlayerChangedSquad(playerObject, oldSquadID, newSquadID) : SquadID is 0 for players who are not members of any squad (including the team commander).
; PlayerScore(playerObject, difference) : Difference is change to player's score (positive or negative)
; PlayerHealPoint(givingPlayerObject, receivingSoldierObject) : Occurs whenever a player heals another player; there is no indication of how much health was restored.
; PlayerRepairPoint(givingPlayerObject, receivingVehicleObject) : Occurs whenever a player repairs a vehicle; there is no indication of how much damage was repaired.
; PlayerGiveAmmoPoint(givingPlayerObject, receivingPhysicalObject) : Occurs whenever a player replenishes the ammo in another player or vehicle. There is no indication of how much ammo was replenished.
; PlayerTeamDamagePoint(playerObject, victimSoldierObject) : Occurs whenever a player damages another player on their own team. There is no indication of how much damage was done.
; PlayerKilled(victimPlayerObject, attackerPlayerObject, weaponObject, assists, victimSoldierObject) : This event occurs when a player is "critically injured", but still capable of being revived. If any players assisted in the kill, then "assists" will be a tuple of tuples: the top-level tuple will contain one lower-level tuple for each assisting player; the lower-level tuples will each have two elements: a playerObject for one of the assisting players, and a number indicating the type of assist (1=targeting assist, 2=kill damage assist, 3=driver assist)
; PlayerRevived(revivedPlayerObject, medicPlayerObject) : Player has been revived from a "critically injured" condition to full health by a medic using "shock paddles".  Players can only be revived in the interval between a PlayerKilled event and a subsequent PlayerDeath event.
; PlayerDeath(playerObject, soldierObject) : This event occurs when a player is decisively dead, and cannot be revived; they will only return to the game by respawning. SoldierObject is the soldier "body" (which is now discarded) for the playerObject "spirit" (which will persist through the next spawn).
; PlayerBanned(playerObject, time, type) : TBD
; PlayerKicked(playerObject): Player has been kicked off the server.
; PlayerDisconnect(playerObject): Player has disconnected from the server.



=== Vehicle and Kit Events ===

; EnterVehicle(playerObject, vehicleObject[, freeSoldier]) : Player represented by playerObject has entered the vehicle represented by vehicleObject.  "freeSoldier" is 1 if the player is a passenger of the vehicle and is able to use weapons/objects of his kit. i.e. seat 4(+) of a black hawk. --[[User:Kiff|Kiff]] 11:21, 25 January 2006 (MST)
; ExitVehicle(playerObject, vehicleObject) : Player has exited a vehicle.
; VehicleDestroyed(vehicleObject, attackerObject) : VehicleObject has been destroyed by attackerObject.
; PickupKit(playerObject, kitObject) : Player has picked up a kit. This occurs both when a player physically picks up a kit, as well as when a player spawns.
; DropKit(playerObject, kitObject) : Player has dropped a kit; can occur either because a player has died, or because a player has picked up a different kit.

=== Team Events ===

; Reset(data) : TBD
; ChangedCommander(teamID, oldCommanderPlayerObject, newCommanderPlayerObject) : Occurs when a team changes commanders; the old or new commander may be "None".
; ChangedSquadLeader(squadID, oldLeaderPlayerObject, newLeaderPlayerObject) : Occurs when a squad changes squad leaders; the old or new squad leader may be "None".



=== Game Events ===

; ControlPointChangedOwner(controlPointObject, attackingTeamID) : TBD
; TimeLimitReached(value) : Event fires when the fixed time limit for a round expires ''(not sure what "value" is)''
; TicketLimitReached(team, limitID) : TBD



=== Command Events ===

; ConsoleSendCommand(command, args) : This event is triggered by someone using the <code>pythonHost.sendCommand</code> console command. Unfortunately, this command/event mechanism appears to be disabled in non-ranked servers. (As a workaround, you can achieve a similar effect by [[Cookbook:Adding New RCon Commands|creating and registering your own custom RCon commands]]).
; RemoteCommand(playerId, cmd) : Event fires when a game client gives an RCon (remote console) command. Cmd is the command the player gave. This event is used by the admin module to receive and process RCon commands from players; RCon commands from TCP connections are received by the admin module directly, and do not fire this event.
; ClientCommand(command, issuerPlayerObject, args) : This event occurs when a game client issues certain in-game commands. The only such commands identified so far are: command=100 means player wants to punish teammate for teamkill; command=101 means player wants to forgive. In both cases, args=1. This response is generated by the player responding to an on-screen prompt caused by a call to the <code>bf2.gameLogic.sendClientCommand</code> method.

=== Misc Events ===

; PlayerUnlocksResponse(succeeded, player, unlocks) : Unlocks are requested and received asynchronously.  This event is triggered when the response for ''player'' (which is an object of type Player) are received.  If the ranking server did not successfully find the player in question, ''succeeded'' is set to false, else true.  ''unlocks'' is a list of kit ids, which are 11, 22, 33 .. 77.
; PlayerAwardsResponse : TBD
; ChatMessage(playerId, text, channel, flags) : Channel is "Squad", "Team", ,"Global", "ServerTeamMessage" or "ServerMessage". Text is the text of the message sent, prefixed by "HUD_TEXT_CHAT_TEAM" or "HUD_TEXT_CHAT_SQUAD" if the message is sent to the Team or Squad channel; there is no prefix if it is sent to the Global channel. PlayerId is -1 for all server messages. If the player sending the message is dead, their message is also prefixed by HUD_CHAT_DEADPREFIX. (Strings such as HUD_TEXT_CHAT_TEAM, HUD_CHAT_DEADPREFIX, and so on, are used as keys by the game engine to match and replace with localized text.)
; PlayerStatsResponse(succeeded, player, response) : TBD
; Update(data) : TBD

=== Non-Standard Events ===

; ''GameStatusChangedEvent''(status) : This type of event is registered for with <code>host.registerGameStatusHandler</code>. <code>status</code> is an integer status code enumerated by [[Object Reference#bf2.GameStatus|<code>bf2.GameStatus</code>]].
; ''TriggerEvent''(triggerID, object, vehicle, enter, userData) : This type of event is registered for with <code>bf2.triggerManager.createHemiSphericalTrigger</code> or <code>bf2.triggerManager.createRadiusTrigger</code>; trigger <code>triggerID</code> is activated when <code>vehicle</code> comes within the preset radius of <code>object</code>. 
; ''TimerEvent''(data) : This type of event fires when a timer established with [[Object Reference#bf2.Timer|<code>bf2.Timer</code>]] expires. "data" is an optional piece of information (of any type) that can be set when the timer is established.

== Mysterious Events ==

These strings were found in the server executable, and appear to be internal game engine events. They seem to not be accessible from Python, except in a few cases, where there is a correspondence between these "events" and Python events (e.g. "BeginRoundEvent" may be the same as "BeginRound").

* RemoveSpawnGroupEvent
* CreateSpawnGroupEvent
* ContentCheckEvent
* UAVEvent
* MissileInitEvent
* UnlockEvent
* MedalEvent
* ToggleFreeCameraEvent
* VoipSessionEvent
* RequestEvent
* PythonCommandEvent
* EndOfRoundEvent &rarr; EndRound
* BeginRoundEvent &rarr; BeginRound
* TargetDirectionEvent
* VoteEvent
* VoipPlayerMuteEvent
* SupplyDropEvent
* CommanderCamEvent
* VoipOnOffEvent
* AmbientEffectAreaEvent
* StickyProjectileEvent
* ArtilleryEvent
* SpottedEvent
* SetSquadLeaderEvent
* SetAcceptOrderEvent
* KickBanEvent
* RankEvent
* InviteEvent
* IssueSquadOrderEvent
* SetPrivateSquadEvent
* ChangeSquadNameEvent
* KilledByEvent
* RadioMessageEvent
* CommanderEvent
* LeaveSquadEvent
* JoinSquadEvent
* StringBlockEvent
* HandleDropEvent
* HandlePickupEvent
* ChangePlayerNameEvent
* PostRemoteEvent
* ExitVehicleEvent &rarr; ExitVehicle
* EnterVehicleEvent &rarr; EnterVehicle
* DestroyPlayerEvent
* DestroyObjectEvent
* CreateKitEvent
* CreateObjectEvent
* CreatePlayerEvent
* DataBlockEvent
* ConnectionTypeEvent
* ChallengeResponseEvent
* ChallengeEvent

== Event Patterns ==

While each event documented here corresponds to a discrete change of game state, there are certain actions that happen in the game that cause a fixed sequence of events to happen every time--a PlayerSpawn event, for example, is always followed by a PlayerChangeWeapon event and a PickupKit event. This section documents some of these recurring patterns.

=== Player Spawn Pattern ===
# PlayerConnect
# PlayerSpawn (player becomes associated with a SoldierObject)
# PlayerChangeWeapon (from "None" to a WeaponObject)
# PickupKit

=== Player Killed Pattern ===
# PlayerKilled
# PlayerScore
# DropKit (the victim drops their kit)
# PlayerDeath

=== Player Revived Pattern ===
# PlayerKilled
# PlayerScore (for attacker)
# DropKit (victim drops their kit)
# PlayerRevived
# PickupKit (revived player picks up the nearest kit [hopefully, but not necessarily, their old one]; if there is no kit nearby, they default to picking up an "assault" kit)
# PlayerScore (for medic who did the revive)

=== Flag Change Pattern ===
# ControlPointChangedOwner (when neutralized)
# PlayerScoreEvent (score for having neutralized flag, repeated for each attacker in CP radius)
# ControlPointChangedOwner (when capture complete)
# PlayerScoreEvent (score for having completed capture, repeated for each attacker in CP radius)

=== Player Kicked Pattern ===
# PlayerKicked
# DropKit
# PlayerDeath
# PlayerDisconnect

=== Player Banned Pattern ===
# PlayerBanned
# PlayerKicked
# DropKit
# PlayerDeath
# PlayerDisconnect

=== Overall Game State Change Pattern ===
# StatusChange (to "PreGame")
# Reset (this event doesn't happen in the first round after a server starts)
# StatusChange (to "Playing"; stay here until enough players connect)
# StatusChange (to "PreGame", once enough players have connected)
# Reset
# StatusChange (to "Playing"--the real game round now begins)
# (play game, beginning with players spawning in)
# StatusChange (to "EndGame")
# DropKit (for each player still in game at end)