Bullet¶

class BWAPI.Bullet¶

An object representing a bullet or missile spawned from an attack.

Bullet allows you to detect bullets, missiles, and other types of non-melee attacks or special abilities that would normally be visible through human eyes (A lurker spike or a Queen’s flying parasite), allowing quicker reaction to unavoidable consequences.

For example, ordering medics to restore units that are about to receive a lockdown to compensate for latency and minimize its effects. You can’t know entirely which unit will be receiving a lockdown unless you can detect the lockdown missile using the Bullet class.

Bullet objects are re-used after they are destroyed, however their ID is updated when it represents a new Bullet.

If BWAPI.Flag.CompleteMapInformation is disabled, then a Bullet is accessible if and only if it is visible. Otherwise if BWAPI.Flag.CompleteMapInformation is enabled, then all Bullets in the game are accessible.

See also

Game.getBullets(), Bullet.exists()

Constructors

This class is not constructable through Lua.

Member Variables

clientInfo¶

A Lua table that can be used to store arbitrary data associated with the current object.

Example usage¶

obj.clientInfo["test"] = 5
print(obj.clientInfo["test"]) -- prints "5"

Member Functions

exists() → boolean¶

Checks if the Bullet exists in the view of the BWAPI player.

If BWAPI.Flag.CompleteMapInformation is disabled, and a Bullet is not visible, then the return value will be false regardless of the Bullet’s true existence. This is because absolutely no state information on invisible enemy bullets is made available to the AI.

Returns:	Returns `true` if the bullet exists or is visible, or `false` if the bullet was destroyed or has gone out of scope
Return type:	boolean

See also

isVisible, Unit.exists()

getAngle() → double¶

Retrieve’s the direction the Bullet is facing.

If the angle is 0, then the Bullet is facing right.

Returns:	A double representing the direction the Bullet is facing. Returns `0.0` if the bullet is inaccessible.
Return type:	double

getID() → int¶

Retrieves a unique identifier for the current Bullet.

Returns:	An integer value containing the identifier.
Return type:	int

getPlayer() → Player¶

Retrieves the Player interface that owns the Bullet.

Returns:	The owning Player interface object. Returns `nil` if the Player object for this Bullet is inaccessible.
Return type:	`BWAPI.Player`

getPosition() → Position¶

Retrieves the Bullet’s current position.

Returns:	A Position containing the Bullet’s current coordinates. Returns `Positions.Unknown` if the Bullet is inaccessible.
Return type:	`BWAPI.Position`

See also

getTargetPosition()

getRemoveTimer() → int¶

Retrieves the timer that indicates the Bullet’s life span.

Bullets are not permanent objects, so they will often have a limited life span. This life span is measured in frames. Normally a Bullet will reach its target before being removed.

Returns:	An integer representing the remaining number of frames until the Bullet self-destructs. Returns `0` if the Bullet is inaccessible.
Return type:	int

getSource() → Unit¶

Retrieves the Unit interface that the Bullet spawned from.

Returns:	The owning Unit interface object. Returns `nil` if the source can not be identified or is inaccessible.
Return type:	`BWAPI.Unit`

See also

getTarget()

getTarget() → Unit¶

Retrieves the Unit interface that the Bullet is heading to.

Returns:	The target Unit interface object, if one exists. Returns `nil` if the Bullet’s target Unit is inaccessible, the Bullet is targetting the ground, or if the Bullet itself is inaccessible.
Return type:	`BWAPI.Unit`

See also

getTargetPosition(), getSource()

getTargetPosition() → Position¶

Retrieves the target position that the Bullet is heading to.

Returns:	A Position indicating where the Bullet is headed. Returns `Positions.Unknown` if the bullet is inaccessible.
Return type:	`BWAPI.Position`

See also

getTarget(), getPosition()

getType() → BulletType¶

Retrieves the type of this Bullet.

Returns:	A `BulletType` representing the Bullet’s type. Returns `BulletTypes.Unknown` if the Bullet is inaccessible.
Return type:	`BWAPI.BulletType`

getVelocityX() → double¶

Retrieves the X component of the Bullet’s velocity, measured in pixels per frame.

Returns:	A double representing the number of pixels moved on the X axis per frame. Returns `0.0` if the Bullet is inaccessible.
Return type:	double

See also

getVelocityY(), getAngle()

getVelocityY() → double¶

Retrieves the Y component of the Bullet’s velocity, measured in pixels per frame.

Returns:	A double representing the number of pixels moved on the Y axis per frame. Returns `0.0` if the Bullet is inaccessible.
Return type:	double

See also

getVelocityX(), getAngle()

isVisible([player = nil]) → boolean¶

Retrieves the visibility state of the Bullet.

Parameters:	player (BWAPI.Player) – (optional) If this parameter is specified, then the Bullet’s visibility to the given player is checked. If this parameter is omitted, then a default value of nil is used, which will check if the `BWAPI` player has vision of the Bullet.
Returns:	Returns `true` if the Bullet is visible to the specified player, or `false` if the Bullet is not visible to the specified player
Return type:	boolean

Note

If player is nil and Broodwar->self() is also nil, then the visibility of the Bullet is determined by checking if at least one other player has vision of the Bullet.

registerEvent(action[, condition = nil][, timesToRun = -1][, framesToCheck = 0])¶

Registers an event and associates it with the current object.

Events can be used to automate tasks (like train X Marines until Y of them have been created by the given Barracks) or to create user-defined callbacks.

Parameters:

action (function) – The callback to be executed when the event conditions are true.
condition (function) – (optional) The condition callback which will return true if the action is intended to be executed. The condition will always be true if omitted.
timesToRun (int) – (optional) The number of times to execute the action before the event is removed. If the value is negative, then the event will never be removed. The value will be -1 if omitted, causing the event to execute until the game ends.
framesToCheck (int) – (optional) The number of frames to skip between checks. If this value is 0, then a condition check is made once per frame. If this value is 1, then the condition for this event is only checked every other frame. This value is 0 by default, meaning the event’s condition is checked every frame.