BF2 Object Reference

# Object Reference

Python program interact with Battlefield 2 using "objects", as well as "methods" (functions) and "attributes" (data) that are part of those objects. This section is a reference to the objects, methods, and attributes in BF2 that can be accessed and manipulated by Python programs.

## host

The host object encapsulates the interfaces between the main BF2 engine (written in C++) and Python modules. Most host methods will generally not need to be used directly from within Python modules, as standard BF2 Python modules (like bf2.GameLogic, for example) provide object-oriented wrappers around most of the raw BF2 engine functions.

You must `import host` to access the methods and attributes shown here.

### Event Handler Methods

`host.registerHandler('EventName', eventHandler[, alwaysCall])`
Registers a function to handle an event. If `alwaysCall` is not specified the handler will only be called when the game is in the "Playing" state--not in the "Pregame" and "Postgame" states. If you would like it to run in Pregame and Postgame as well, `alwaysCall` must be specified and evaluate as true (e.g. "1").
`host.registerGameStatusHandler(gameStatusEventHandler)`
Registers a function to handle a game status event.
`host.unregisterGameStatusHandler(gameStatusEventHandler)`
Unregisters a game status event-handling function.
### Trigger Methods

`host.trig_create(object, callback, objName, radius, unknownBool, data)`
`host.trig_getObjects(trig_id)`
`host.trig_destroyAll()`
`host.trig_destroy(trig_id)`
### Global Stats Methods

`host.pers_gamespyStatsNewGame()`
`host.pers_gamespyStatsEndGame()`
`host.pers_gamespyStatsSendSnapshotFinal(snapShot)`
`host.pers_gamespyStatsSendSnapshotUpdate`
`host.pers_getStatsKeyVal(key)`
`host.pers_plrRequestAwards(playerIndex, unknown, unknown)`
`host.pers_plrRequestStats(playerIndex, unknown, urlToStatType)`
Presumably returns the specified stat of the specified player.
`host.pers_plrRequestUnlocks(playerIndex, unknown)`
Presumably returns the specified player's unlocks.
`host.pers_plrSetUnlocks(playerIndex, unknown, unknown)`
`host.pers_plrAwardMedal`
### "sh" Methods (SwiffHost?)

`host.sh_setEnableCommander(bool)`
Enables or disables the commander position.
### "gl" Methods (GameLogic?)

`host.gl_sendEndOfRoundData(dataString)`
Presumably sends stats-related information to clients when a round ends.
### "sgl" Methods (ServerGameLogic?)

`host.sgl_getSettingsBool`
`host.sgl_sendTextMessage(playerId, 10, 1, message)`
Send a server message to one player. Working Status Unknown
`host.sgl_sendRankEvent(playerIndex, rank, score)`
`host.sgl_sendMedalEvent(playerIndex, type, value)`
`host.sgl_sendPythonEvent`
`host.sgl_sendGameLogicEvent(playerID, event, data)`
`host.sgl_sendHudEvent(playerID, event, data)`
`host.sgl_getIsAIGame()`
Presumably returns whether or not the current game has AI.
`host.sgl_getControlPointsInGroup`
`host.sgl_endGame(winner, victoryType)`
Presumably ends a current game, awarding victory of victoryType to winner.
`host.sgl_getParam(name, unknown, unknown)`
`host.sgl_setParam(name, unknown, unknown, unknown)`
`host.sgl_getWorldSize()`
returns a tuple giving the north/south and east/west dimensions of the current map, more-or-less in meters.
`host.sgl_getMapName()`
Returns the current map name.
`host.sgl_getModDirectory()`
Returns the directory containing the currently active mod.
### "ss" Methods (Server Settings?)

`host.ss_getParam(parameter)`
Returns value of specified setting.
Settings include:
ticketRatio
teamRatioPct
maxPlayers
gameMode
mapName
timeLimit
scoreLimit
autoBalance
tkpEnabled
tkpNeeded
tkpDefault
globRank
globUnlocks
You cannot find out server name, port and other similar information this way. Instead, use f.e. host.rcon\_invoke('sv.serverName') to get the server name.
### Object Manager Methods

`host.omgr_getObjectsOfTemplate(template)`
`host.omgr_getObjectsOfType(type)`
### Timer Methods

`host.timer_created(timer)`
`host.timer_getTimers` - Do not use, unfinished DICE code
Creates a Tuple and only fills one slot. Trying to access the other slots will crash the server.
`host.timer_destroy(timer)`
`host.timer_getWallTime()`
Return the number of seconds since server started; see BF2 Time
### Player Manager Methods

`host.pmgr_enableScoreEvents`
`host.pmgr_getScore(playerIndex, name)`
Gets value of score name of specified player.
`host.pmgr_setScore(playerIndex, name, value)`
Sets value of score name of specified player.
`host.pmgr_p_get(name, playerIndex)`
`host.pmgr_p_set(name, playerIndex, value)`
`host.pmgr_isIndexValid(index)`
Checks the validity of specified player index.
`host.pmgr_getCommander()`
Presumably returns Player object for the current commander.
`host.pmgr_getPlayers()`
Returns current player objects.
`host.pmgr_getNumberOfPlayers()`
Returns number of players.
### RCon Methods

`host.rcon_invoke(command)`
Executes a server console command.
`host.rcon_feedback(playerid, message)`
Send a message to an in-game player RCon client.
List of available host.rcon\_invoke commands

### Logging Methods

`host.log(message)`
Send a message to the log.
## PhysicalObject

PhysicalObjects represent physical things in the BF2 game world; as such, they have the properties of real objects in the physical world: properties like position (X, Y, Z coordinates) and orientation (rotation), and can contain, and be contained by, other PhysicalObjects. PhysicalObjects appear to be implemented as C++ objects in the game engine which the embedded Python engine has access to, but since they are game engine objects, they are not defined anywhere in Python, and cannot be created directly in Python--but they can be accessed from Python. No special imports are necessary to manipulate these objects.

Please note that since these are not native Python objects, we don't know what they are actually named inside the game engine; "PhysicalObject", as well as the names of other types of objects that inherit from that class, are made up for convienience. We also can't see into the game engine code to see if the hierarchial structure of these classes is what is presented here--for example, VehicleObject and SoldierObject may, in fact, be a single class; the hierarchy of PhysicalObject's decendents given here should nevertheless be equivalent to whatever the real hierarchy is.

PhysicalObject is a base class whose methods and attributes are inherited by several sub-classes.

### Methods for instances of PhysicalObject

`physicalObject.isValid()`
`physicalObject.getTemplateProperty()`
`physicalObject.getPosition()`
`physicalObject.setPosition( (X, Y, Z) )`
`physicalObject.getRotation()`
`physicalObject.setRotation( (A, B, C) )`
`physicalObject.getParent()`
Returns PhysicalObject that contains this instance, if any
`physicalObject.getChildren()`
Returns a tuple of PhysicalObjects contained by this instance
For information about the coordinate system used by the Position and Rotation methods, see the page on BF2 Coordinates.

The known properties available via the getTemplateProperty method are:

`radius`
(For control points only.)
`ControlPointID`
(For control points only.)
### Attributes for instances of PhysicalObject

`physicalObject.templateName`
`physicalObject.isControlPoint`
`physicalObject.isPlayerControlObject`
`physicalObject.hasArmor`
`physicalObject.token`
### WeaponObject

A WeaponObject is used to represent a weapon in BF2. The WeaponObject class inherits the methods and attributes of PhysicalObject, with no additonal methods or attributes.

### KitObject

A KitObject is used to represent a "kit" in BF2. The KitObject class inherits the methods and attributes of PhysicalObject, with no additonal methods or attributes.

### ControlPointObject

A ControlPointObject is used to represent a control point in BF2. The ControlPointObject class inherits the methods and attributes of PhysicalObject, with the following additional methods and attributes:

#### Additional Methods

`ControlPointObject.cp_getParam('parameter')`
`ControlPointObject.cp_setParam('parameter', value)`
#### Additional Attributes

`ControlPointObject.flagPosition`
Returns 0=top, 1=middle, 2=bottom
`ControlPointObject.lastAttackingTeam`
`ControlPointObject.triggerId`
#### Internal Properties

ControlPointObjects also have a number of internal properties that are accessed through the `cp_getParam` and `cp_setParam` methods:

`isHemisphere`
0 or 1, indicating if the control point capture area is a hemisphere or not.
`team`
Team the capture point belongs to: 0 for neutral, 1 for team 1, and 2 for team 2. Updating this value also changes the minimap and flag tag indicator.
`flag`
The flag image used in the control point; 1 for team 1's flag, 2 for team 2's.
`areaValue`
The weighting value for this control point
`unableToChangeTeam`
Whether or not this control point is capturable (0) or not (1)
`timeToGetControl`
How many seconds it takes to get control of this control point
`timeToLoseControl`
How many seconds it takes to get control of this control point
`onlyTakeableByTeam`
Whether (1) or not (0) this control point is only capturable by one team
`takeOverChangePerSecond`
Capture speed; speed at which the flag at this control point raises or lowers.
`enemyTicketLossWhenCaptured`
Ticket loss caused to the enemy when this control point is captured *(needs to be verified)*
`playerId`
*Unknown; may set the playerID of the player that captured this control point first (the first player to arrive, not assisting players?)*
### VehicleObject

A VehicleObject represents a BF2 vehicle. The VehicleObject class inherits the methods and attributes of PhysicalObject, with several additional methods. SoldierObject, used to represent the physical body of player, is a sub-class of VehicleObject.

#### Additional Methods

`vehicleObject.getDamage()`
`vehicleObject.setDamage(intValue)`
`vehicleObject.getIsWreck()`
Returns boolean, 1 if the vehicle is destroyed
`vehicleObject.getOccupyingPlayers()`
Returns an array with index 0 being the driver
`vehicleObject.getIsRemoteControlled()`
The getDamage() and setDamage() methods actually read/set the health of the vehicle. Transport helicopters start with 1500, tanks with 1000 and light jeeps with 750. They all explode when the damage reaches 0.

### SoldierObject

A SoldierObject represents the physical body of a human or AI player in BF2. The SoldierObject class inherits the methods and attributes of VehicleObject, with no additonal methods or attributes. (Note: it appears that within the game engine, SoldierObject and VehicleObject may actually be the exact same thing; conceptually, though, it helps to think of SoldierObject as a subclass of VehicleObject).

It is important to pay attention to the destinction between a player's "physical" body in the game, which is represented by an instance of the SoldierObject class, having position, orientation, health, etc., and the in-game "spirit" of that player, which is represented by an instance of the bf2.PlayerManager.Player class, having properties like a name, squad, profile ID, etc. The bf2.PlayerManager.Player ("spirit") is created when a player connects to the server, and persists as long as the server continues running, even across game rounds (and disconnect/reconnects--if the player disconnects and then reconnects, the server tries to match them up with an existing bf2.PlayerManager.Player object). By contrast, a player remains associated with a SoldierObject only as long as they remain alive; as soon as they die, their association with the SoldierObject is broken; when they respawn, a new SoldierObject instance is created, and becomes associated with the player. That is to say, between dying and respawning, the player's "spirit" leaves their first "body" and is "reincarnated" in a new "body". Is that metaphysical enough for you?

## bf2.GameStatus

Just used as a container for the constant values returned by callbacks from the `GameStatusChanged` event:

`bf2.GameStatus.Playing`
`bf2.GameStatus.EndGame`
`bf2.GameStatus.PreGame`
`bf2.GameStatus.Paused`
`bf2.GameStatus.RestartServer`
`bf2.GameStatus.NotConnected`
You must `import bf2` to access these class attributes.

## bf2.GameLogic.GameLogic

A wrapper around lots of BF2 engine stuff accessible through host, apparently to make it more Pythonic. During its initialization the bf2 class instantiates this class as the singleton object `bf2.gameLogic`.

You must `import bf2` to access the methods and attributes of this object.

### Methods for the singleton object

`bf2.gameLogic.getModDir()`
`bf2.gameLogic.getMapName()`
`bf2.gameLogic.getWorldSize()`
returns a tuple giving the north/south and east/west dimensions of the current map, more-or-less in meters.
`bf2.gameLogic.getTeamName(team)`
`bf2.gameLogic.isAIGame()`
`bf2.gameLogic.sendClientCommand(playerId, command, args)`
Appears to tell game engine to prompt a player for input; the player's response returns control to Python by generating a ClientCommand event; command is typically a numeric value, args can be anything, but is typically a tuple or list.
`bf2.gameLogic.sendGameEvent(playerObject, event, data)`
Tells the BF2 game engine to cause a GameEvent to occur.
`bf2.gameLogic.sendMedalEvent(playerObject, type, value)`
`bf2.gameLogic.sendRankEvent(playerObject, rank, score)`
`bf2.gameLogic.sendHudEvent(playerObject, event, data)`
Tells the BF2 game engine to cause a HudEvent to occur.
`bf2.gameLogic.sendServerMessage(playerId, message)`
`bf2.gameLogic.getTicketState(team)`
`bf2.gameLogic.setTicketState(team, value)`
`bf2.gameLogic.getTickets(team)`
`bf2.gameLogic.setTickets(team, value)`
`bf2.gameLogic.getDefaultTickets(team)`
`bf2.gameLogic.getTicketChangePerSecond(team)`
`bf2.gameLogic.setTicketChangePerSecond(team, value)`
`bf2.gameLogic.getTicketLimit(team, id)`
`bf2.gameLogic.setTicketLimit(team, id, value)`
`bf2.gameLogic.getDefaultTicketLossPerMin(team)`
`bf2.gameLogic.getDefaultTicketLossAtEndPerMin()`
`bf2.gameLogic.getWinner()`
`bf2.gameLogic.getVictoryType()`
`bf2.gameLogic.setHealPointLimit(value)`
Percentage heal required to trigger a PlayerHealPoint event.
`bf2.gameLogic.setRepairPointLimit(value)`
Percentage heal required to trigger a PlayerRepairPoint event.
`bf2.gameLogic.setGiveAmmoPointLimit(value)`
Percentage heal required to trigger a PlayerGiveAmmoPoint event.
`bf2.gameLogic.setTeamDamagePointLimit(value)`
Percentage heal required to trigger a PlayerTeamDamagePoint event.
`bf2.gameLogic.setTeamVehicleDamagePointLimit(value)`
## bf2.GameLogic.ServerSettings

Another wrapper around more BF2 engine stuff that's accessible through host; this class makes it accessing these things cleaner and more Pythonic. During its initialization the bf2 class instantiates this class as the singleton object bf2.serverSettings.

You must `import bf2` to access the methods and attributes of this object.

### Methods for the singleton object

`bf2.serverSettings.getTicketRatio()`
`bf2.serverSettings.getTeamRatioPercent()`
`bf2.serverSettings.getMaxPlayers()`
`bf2.serverSettings.getGameMode()`
`bf2.serverSettings.getMapName()`
`bf2.serverSettings.getTimeLimit()`
`bf2.serverSettings.getScoreLimit()`
`bf2.serverSettings.getAutoBalanceTeam()`
`bf2.serverSettings.getTKPunishEnabled()`
`bf2.serverSettings.getTKNumPunishToKick()`
`bf2.serverSettings.getTKPunishByDefault()`
`bf2.serverSettings.getUseGlobalRank()`
`bf2.serverSettings.getUseGlobalUnlocks()`
You cannot find out server name, port and other similar information this way. Instead, use f.e. host.rcon\_invoke('sv.serverName') to get the server name.

## bf2.ObjectManager.ObjectManager

During its initialization the bf2 class instantiates this class as the singleton object bf2.objectManager. This object can be used by Python to get access to internal game engine C++ objects. A list of the available object types can be found here, and a list of available object templates can be found here.

You must `import bf2` to access the methods and attributes of this object.

### Methods for the singleton object

`bf2.objectManager.getObjectsOfType('object type')`
`bf2.objectManager.getObjectsOfTemplate('object template')`

## bf2.PlayerManager.PlayerScore

Objects of this class maintain a long list of player score attributes. They are used inside of objects of the Player class; for any Player object x, `x.score` is an object of class PlayerScore.

You will not normally create objects of this class; they are created automatically as part of the Player class when Player objects are created. No special imports are necessary to access methods and attributes of these objects.

There is also a separate `player.stats` object, which tracks different information. You can use the following code fragment to see all of the variables in the `player.stats` object.

`for s in vars(player.stats): print str(s)`

### Class methods

`reset()`
resets all score attributes stored within the object itself.
### Class attributes stored in the PlayerScore object

`index`
`heals`
`ammos`
`repairs`
`damageAssists`
`passengerAssists`
`driverAssists`
`targetAssists`
`driverSpecials`
`revives`
`teamDamages`
`teamVehicleDamages`
`cpCaptures`
`cpDefends`
`cpAssists`
`suicides`
`cpNeutralizes`
`cpNeutralizeAssists`
`rplScore`
This attribute may not be in all versions of BF2
`skillScore`
`cmdScore`
### Class attributes stored in the BF2 engine

`deaths`
`kills`
`TKs`
`score`
`skillScore`
`rplScore`
`cmdScore`
`fracScore`
`rank`
`firstPlace`
`secondPlace`
`thirdPlace`
`bulletsFired`
gives a tuple, each element of which is a 2-tuple consisting of the name of a weapon the player has fired, and the number of shots they fired from that weapon. As the player uses more weapons, more of the 2-tuples are added to the list. An example tuple returned:
`(("uspi-m16", 30), ("knife", 3))`
Before the first weapon is fired, this may be `None` or an empty tuple. The first weapon fired will not always be the first 2-tuple on the list returned.
`bulletsGivingDamage`
Same as above, but only with bullets giving damage
`bulletsFiredAndClear`
The "AndClear" resets the engine counter. polling this will only give new bullets. However having more than one module polling them is not a good idea.
`bulletsGivingDamageAndClear`
## bf2.PlayerManager.Player

An object of this class is created for each player in the game. When they are initialized, Player objects automatically instantiate a PlayerScore object and assign it to their score attribute.

You must `import bf2.PlayerManager` if you wish to create objects of this class; normally, however, you will just access methods and attributes of already existing Player objects that are returned to you by other calls, which requires no special import statement.

### Instances created with

```
 x = bf2.PlayerManager.Player(index)

```

### Class Attributes

`index`
playerID for this player
`score`
current score for this player
### Methods

`isValid()`
`isRemote()`
`isAIPlayer()`
`isAlive()`
`isManDown()`
`isConnected()`
`getProfileId()`
`isFlagHolder()`
`getTeam()`
`setTeam(t)`
`getPing()`
Returns the player's ping (network transit time from player to server and back) in milliseconds
`getSuicide()`
Returns 1 if the player suicided. Resets once the player spawns.
`setSuicide(t)`
`getTimeToSpawn()`
Returns 0 when a player is spawned in; when a player is waiting to spawn, it returns the number of seconds until they are allowed to spawn.
`setTimeToSpawn(t)`
Appears to generate an exception if used on a player that is already spawned in; if used on a player that that is waiting to spawn it changes the time until they are allowed to spawn.
`getSquadId()`
Returns the player's squad ID. Squads for each team are independently numbered beginning at "1" and increasing thereafter. Players not on a squad, including team commanders, are assigned to squad "0".
`isSquadLeader()`
Returns 1 if player is a squad leader.
`isCommander()`
Returns 1 if player is currently the commander.
`getName()`
Return's player's name
`setName(name)`
Sets a player's name (at least, it changes what getName() returns), but the change doesn't show up in-game--everything in the game still shows the player's old name. (it is working,but only sees that player who connected after the name change.)
`getSpawnGroup()`
`setSpawnGroup(t)`
`getKit()`
Returns the current player's kit object.
`getVehicle()`
Returns the current player's vehicle object. If the player is not in a vehicle at the time this returns the player's soldier object.
`getDefaultVehicle()`
Returns the player's soldier object, no matter what vehicle they are in.
`getPrimaryWeapon()`
Returns the weapon object for the player's currently selected weapon.
`getAddress()`
Returns player's IP address
`setIsInsideCP(val)`
`getIsInsideCP()`
## bf2.PlayerManager.PlayerManager

This class is a wraper around some player management functions in the BF2 engine, and also adds some simple calculations and logic to those functions. During its initialization the bf2 class instantiates this class as the singleton object bf2.playerManager.

You must `import bf2` to access the methods and attributes of this object.

### Methods for the singleton object

`bf2.playerManager.getNumberOfPlayers()`
`bf2.playerManager.getCommander(team)`
`bf2.playerManager.getPlayers()`
`bf2.playerManager.getPlayerByIndex(index)`
`bf2.playerManager.getNextPlayer(index)`
`bf2.playerManager.getNumberOfPlayersInTeam(team)`
`bf2.playerManager.getNumberOfAlivePlayersInTeam(team)`
`bf2.playerManager.enableScoreEvents()`
Enables PlayerScore events
`bf2.playerManager.disableScoreEvents()`
Disables PlayerScore events

## bf2.Timer

(Not available in PR, use the realitytimer below.)

Objects in this class are timers that can cause timer events to be generated when a fixed amount of time has elapsed. Instances are created with

```
 timer = bf2.Timer(timerEventHandler, delta, alwaysTrigger, data)

```

`timerEventHandler` is the handler to be called when `delta` seconds have elapsed since the creation of the timer; `alwaysTrigger` should be `1` *(not sure what the alternative is).* `data` is an optional item (typically a tuple) that will be passed to `timerEventHandler`. (Note that even though `data` is optional when establishing a timer, the timerEventHandler must specify it as a parameter, or the handler won't work).

A timer may fire only once per tick. Setting a very low interval time will assure the timer fires every tick. Setting 0 disables it.

You must `import bf2.Timer` to create timer objects.

### Class Methods

`destroy()`
Destroys the associated game engine timer (but not the Python instance.)
`getTime()`
Returns the wall time at which this timer will fire.
`setTime(time)`
Changes the wall time at which this timer will fire.
`setRecurring(interval)`
Specifies this this timer should fire repeatedly, every interval seconds.
`onTrigger()`
For internal use only; calls `timerEventHandler`.

### Project Reality Timer interface

Project Reality timer (realitytimer.py) expands the default interface and adds:

-Exception catching with a debug message when an exception is not caught in the handler, No need to worry about bad code crashing the server.

-Internal check to make sure timers don't fire after destroy() was called (Can happen when Destroy() is called on the same tick)

-realitytimer.fireOnce(targetFunc, delay, data=None) class that can fire an event once after delay and then destroy itself (No need to store reference)

-realitytimer.fireNextTick(targetFunc, data=None) class that will fire the event at the next game tick and then destroy itself (Also no need to store)

## bf2.TriggerManager.TriggerManager

This class is a wraper around some player management functions in the BF2 engine. During its initialization the bf2 class instantiates this class as the singleton object bf2.triggerManager. This object is used to manage "triggers", which are events that are fired when a PCO enters a defined spherical or hemispherical volume surrounding an object.

You must `import bf2` to access the methods and attributes of this object.

### Methods for the singleton object

`bf2.triggerManager.createRadiusTrigger(object, callback, objName, radius, data=None)`
Creates a trigger that causes `callback` to be called if a player enters a spherical region of radius `radius` centered on `object`, passing `data` as an argument.
`bf2.triggerManager.createHemiSphericalTrigger(object, callback, objName, radius, data=None)`
Same as `bf2.triggerManager.createRadiusTrigger`, except that instead of a spherical trigger region, the trigger region is a flat circle lying along the ground (yes, it's badly named).
`bf2.triggerManager.destroyAllTriggers()`
Destroys all registered triggers.
`bf2.triggerManager.destroy(trig_id)`
Destroys a specific trigger.
`getObjects(trig_id)`
Returns a tuple containing all objects currently within the specified trigger region.
## bf2.stats.constants

This module appears intended to be imported with something like

```
 from bf2.stats.constants import *

```

so that everything in it is loaded into the local namespace, rather than being a part of any object. The module includes a lot of constants and dictionaries, as well as some utility functions.

### Functions

`getVehicleType(templateName)`
`getWeaponType(templateName)`
`getKitType(templateName)`
`getArmy(templateName)`
`getMapId(mapName)`
`getGameModeId(gameMode)`
`getRootParent(physicalObject)`
Traverses the containment for physicalObject all the way to the top; returns the outermost (topmost?) containing object.
For example, `getWeaponType("usrif_m16a2")` looks up an M16 rifle in a dictionary called `weaponTypeMap` (also defined in bf2.stats.constants) and returns the constant `WEAPON_TYPE_ASSAULT`. . . which, too, is defined in bf2.stats.constants, as having a numeric value of "0". A list of template names used in some of these functions can be found in the Game Engine Object Templates page.

These constant values appear to be the same as those used in the statistics server, specifically the look up values.