Robot Class Reference

Inheritance diagram for Robot:

Member Functions
	Robot(pos, teamIndex, scriptName, scriptArg)
	Constructor.
	canSeePoint(pt)
	Does this robot have line-of-sight to the given point.
	copyMoveFromObject(obj)
	Move identically to obj. [details]
	dropItem()
	Drop all carried items. [details]
	engineerDeployObject(which)
	Deploy the an engineered object of type which [details]
	findClosestEnemy(range)
	Finds the closest enemy ship or robot that is within the specified distance. [details]
	findVisibleObjects(types,...)
	Finds all items of the specified type within ship's area of vision. [details]
	fireModule(module)
	Activates/fires the given module if it is equipped. [details]
	fireWeapon(weapon)
	Shoots the given weapon if it is equipped. [details]
	getActiveWeapon()
	Checks if the given module is active. [details]
	getAngle()
	Get the angle of the Ship. [details]
	getAnglePt(p)
	Gets the angle from the Robot to point p [details]
	getCaptureZone()
	Returns capture zone holding the item. [details]
	getEnergy()
	Gets the enegy of this ship. [details]
	getFiringSolution(obj)
	Calculate the angle to fire at in order to hit obj with the current Weapon. [details]
	getFlagCount()
	Get the number of flags carried by this Ship. [details]
	getGeom()
	Returns an object's geometry. [details]
	getHealth()
	Returns the health of this ship. [details]
	getId()
	Gets an object's user assigned id. [details]
	getInterceptCourse(obj)
	Calculate the angle to fly at in order to collide with obj. [details]
	getLoadout()
	Get the current loadout. [details]
	getMountedItems()
	Get all Items carried by this Ship. [details]
	getObjType()
	Gets an object's ObjType. [details]
	getOwner()
	Gets an object's owner as a PlayerInfo. [details]
	getPlayerInfo()
	Get the PlayerInfo for this Ship. [details]
	getPos()
	Gets an object's position. [details]
	getRad()
	Returns the radius of an item. [details]
	getShip()
	Returns the ship where the item is mounted. [details]
	getTeamIndex()
	Gets the index of the object's team. [details]
	getVel()
	Get the items's velocity. [details]
	getWaypoint(p)
	Get next waypoint to head toward in order to move to p [details]
	globalMsg(message)
	Send a message to all players. [details]
	hasFlag()
	Check if this Ship is carrying a flag. [details]
	hasModule(module)
	Does the robot have the given Module. [details]
	hasWeapon(weapon)
	Does the robot have the given Weapon. [details]
	isAlive()
	Check if this Ship is alive. [details]
	isInCaptureZone()
	Is item in a capture zone? [details]
	isModActive(module)
	Checks if the given module is active. [details]
	isSelected()
	Determine if an object is selected in the editor. [details]
	privateMsg(message, playerName)
	Send a private message to a player. [details]
	removeFromGame()
	Removes the object from the current game or editor session. [details]
	setAngle(angle)
	Sets the Robot's angle to angle [details]
	setAngle(p)
	Sets the Robot's angle to point towards p [details]
	setEnergy(energy)
	Set the current energy of this ship. [details]
	setGeom(geometry)
	Sets an object's geometry. [details]
	setHealth(health)
	Set the current health of this ship. [details]
	setId(id)
	Sets an object's user assigned id. [details]
	setLoadout(loadout)
	Sets the requested loadout for the ship. [details]
	setLoadout(w1, w2, w3, m1, m2)
	Convenience alias for setLoadout(table) [details]
	setLoadoutModule(slot, module)
	Request a new loadout where the given module slot is changed to the given module. This still requires the bot to change to its new loadout. [details]
	setLoadoutNow(loadout)
	Immediately sets the loadout for the ship. [details]
	setLoadoutWeapon(slot, weapon)
	Request a new loadout where the given weapon slot is changed to the given weapon. This still requires the bot to change to its new loadout. [details]
	setOwner(playerName)
	Sets the owner of the object. [details]
	setPos(pos)
	Set the object's position. [details]
	setSelected(selected)
	Set whether an object is selected in the editor. [details]
	setTeam(teamIndex)
	Assigns the object to a team. [details]
	setThrust(speed, angle)
	Makes the Robot thrust at speed along angle. [details]
	setThrust(speed, p)
	Makes the Robot thrust at speed towards p. [details]
	setThrustToPt(p)
	Makes the Robot thrust to p, stopping when it reaches that point. [details]
	setVel(vel)
	Sets the item's velocity. [details]
	subscribe(event)
	Let the bot listen for and respond to the specified event. [details]
	teamMsg(message)
	Send a message to this Robot's team. [details]
	unsubscribe(event)
	Stop listening for the specified event. [details]

Constructor Documentation

Robot.new(pos, teamIndex, scriptName, scriptArg)

Arg types: pos: point, teamIndex: int, scriptName: string, scriptArg: string  |  returns Robot

Constructor.

Example:

robot = Robot.new(pos, teamIndex, scriptName, scriptArg)
...
levelgen:addItem(robot)

All parameters are optional.

Parameters

pos	Starting position of the Robot. Defaults to point.zero (i.e. (0,0)). Note that this position is pretty much ignored at this point; bot is created, then it is spawned using normal game processes, which means at a spawnPoint or at (0,0) if there are none. Once spawned, a levelgen script can relocate a ship as shown in one of the samples below.
teamIndex	Starting Team of the Robot. If unspecified, defaults to balancing teams.
scriptName	The bot script to use. Defaults to the server's default bot.
scriptArg	Zero or more string arguments to pass to the script. If there are multiple arguments, just list them sequentially.

Passed arguments are available in the arg table.

-- Display all the passed arguments
for i = 1, #arg do
  bot:globalMsg(arg[i])  -- These are strings; use Lua methods to convert to other types as needed
end

Alterntively, if a coordinate pair has been passed to the bot (as two strings, "xxxx", "yyyy"): x = tonumber(arg[1]) y = tonumber(arg[2]) dest = point.new(x, y)

-- ~~~ IN A LEVELGEN SCRIPT THAT HAS SUBSCRIBED TO ShipSpawned EVENTS ~~~
-- Monitor all spawning ships, and if they're a bot, relocate them to 200,200.
function onShipSpawned(ship)
    playerInfo = ship:getPlayerInfo()
    if playerInfo:isRobot() then
       ship.setPos(200, 200)
 end

Member Function Documentation

canSeePoint(pt)

Arg types: pt: point  |  returns bool

Does this robot have line-of-sight to the given point.

Line-of-sight is a straight path from the robot to the object without any stationary, collideable objects in the way

Parameters

pt	point to test

Returns

true if this bot can see the given point, false otherwise

copyMoveFromObject(obj)

Arg types: obj: BfObject  |  returns nothing

Move identically to obj.

Parameters

obj	The BfObject to mimic.

dropItem()

returns nothing

Drop all carried items.

engineerDeployObject(which)

Arg types: which: EngineerBuildObject  |  returns bool

Deploy the an engineered object of type which

Parameters

which

The EngineerBuildObject to build.

Returns

true if the item was successfully deployed, false otherwise.

findClosestEnemy(range)

Arg types: range: num  |  returns Ship

Finds the closest enemy ship or robot that is within the specified distance.

Finds closest enemy within specified distance of the bot. If dist is omitted, this will use standard scanner range, taking into account whether the bot has the Sensor module. To search the entire map, specify -1 for the range.

Parameters

range

(Optional) Radius in which to search. Use -1 to search entire map. If omitted, will use normal scanner range.

Returns

Ship object representing closest enemy, or nil if none were found.

findVisibleObjects(types, ...)

Arg types: types: ObjType, ...:   |  returns table

Finds all items of the specified type within ship's area of vision.

This search will exclude the bot itself as well as other cloaked ships in the area (unless this bot has sensor equipped)

Can specify multiple types.

Parameters

types

One or more ObjType specifying what types of objects to find.

Returns

A table with any found objects.

-- Pass one or more object types
function countObjects(objType, ...)
  items = bot:findVisibleObjects(objType, ...)
  print(#items) -- Print the number of items found
end

fireModule(module)

Arg types: module: Module  |  returns nothing

Activates/fires the given module if it is equipped.

Parameters

module

Module to fire

fireWeapon(weapon)

Arg types: weapon: Weapon  |  returns nothing

Shoots the given weapon if it is equipped.

Parameters

weapon

Weapon to fire.

getActiveWeapon()

returns Weapon

inherited from Ship

Checks if the given module is active.

This will return an item of the Weapon enum, e.g. Weapon.Phaser.

Returns

The Weapon that is currently active on this ship.

getAngle()

returns num

inherited from Ship

Get the angle of the Ship.

Returns

The Ship's angle in radians.

getAnglePt(p)

Arg types: p: point  |  returns num

Gets the angle from the Robot to point p

Returns

The angle in radians

getCaptureZone()

returns Zone

inherited from Item

Returns capture zone holding the item.

Many games do not feature capture zones. For those games, this function will always return nil. Currently only FlagItems can be captured.

Returns

Zone where the item has been captured. Returns nil if the item is not in a capture zone.

getEnergy()

returns num

inherited from Ship

Gets the enegy of this ship.

Energy is specified as a number between 0 and 1 where 0 means no energy and 1 means full energy.

Returns

Returns a value between 0 and 1 indicating the energy of the item.

getFiringSolution(obj)

Arg types: obj: BfObject  |  returns num

Calculate the angle to fire at in order to hit obj with the current Weapon.

Parameters

obj	The intended target.

Returns

The angle to fire at, or nil if no solution can be found.

Note

The bot WILL fire at teammates if you ask it to!

getFlagCount()

returns int

inherited from Ship

Get the number of flags carried by this Ship.

Returns

The number of flags carried by this Ship.

getGeom()

returns Geom

inherited from BfObject

Returns an object's geometry.

Returns

A geometry as described on the Geom page

getHealth()

returns num

inherited from Ship

Returns the health of this ship.

Health is specified as a number between 0 and 1 where 0 is completely dead and 1 is full health.

Returns

Returns a value between 0 and 1 indicating the health of the item.

getId()

returns int

inherited from BfObject

Gets an object's user assigned id.

Users can assign an id to elements in the editor with the ! or # keys. Use this function to obtain this id. If the user has not assigned an object an id, getId() will return a negative id that will remain consistent throught the game.

Returns

The object's id.

getInterceptCourse(obj)

Arg types: obj: BfObject  |  returns num

Calculate the angle to fly at in order to collide with obj.

Parameters

obj	The intended target.

Returns

The angle to fly at, or nil if no solution can be found.

getLoadout()

returns table

inherited from Ship

Get the current loadout.

This method will return a table with the loadout in the following order:

Module 1, Module 2, Weapon 1, Weapon 2, Weapon 3

Returns

A table with the current loadout, as described above.

getMountedItems()

returns table

inherited from Ship

Get all Items carried by this Ship.

Returns

A table of all Items mounted on ship (e.g. ResourceItems and Flags)

getObjType()

returns ObjType

inherited from BfObject

Gets an object's ObjType.

obj = TestItem.new()
print(obj:getObjType() == ObjType.TestItem)   -- prints 'true'

See ObjType for a list of possible return values.

Returns

The object's ObjType.

getOwner()

returns PlayerInfo

inherited from BfObject

Gets an object's owner as a PlayerInfo.

Some objects (like projectiles) have an owning player associated. This method returns a PlayerInfo object if there is an owner. Otherwise, returns nil.

This method is intended to be used with bullets and other projectiles, not with game objects like zones.

Returns

A PlayerInfo representing the object's owner, or nil.

getPlayerInfo()

returns PlayerInfo

inherited from Ship

Get the PlayerInfo for this Ship.

Returns

The PlayerInfo for this Ship.

getPos()

returns point

inherited from BfObject

Gets an object's position.

For objects that are not points (such as a LoadoutZone), will return the object's centroid.

Returns

A Point representing the object's position.

getRad()

returns num

inherited from Item

Returns the radius of an item.

Returns

The radius of the item. For a Teleporter, this is the radius of the entrance. For a ForceFieldProjector, this is the radius of the base.

getShip()

returns Ship

inherited from Item

Returns the ship where the item is mounted.

Most objects cannot be mounted. For those, this function will always return nil.

Returns

Ship where the item is mounted. Returns nil if the item is not mounted.

getTeamIndex()

returns int

inherited from BfObject

Gets the index of the object's team.

Many BfObjects (such as TestItems) are never part of any particular team. For these objects, this method will return Team.Neutral.

Note

Remember that in Lua, indices start with 1!

Returns

Team index of the object.

getVel()

returns point

inherited from MoveObject

Get the items's velocity.

Returns

The velocity as an axis-aligned vector.

getWaypoint(p)

Arg types: p: point  |  returns point

Get next waypoint to head toward in order to move to p

Finds a path from the current position to p using the built-in pathing utility. The algorithm will consider teleporters and tries to take the shortest route to p.

Parameters

p	The destination point

Returns

The next point to head towards, or nil if no path can be found

globalMsg(message)

Arg types: message: string  |  returns nothing

Send a message to all players.

Parameters

message

Message to send.

hasFlag()

returns bool

inherited from Ship

Check if this Ship is carrying a flag.

Returns

true if the Ship is carrying at least one flag, false otherwise.

hasModule(module)

Arg types: module: Module  |  returns bool

Does the robot have the given Module.

Parameters

module

The Module to check

Returns

true if the bot has the Module, false if not.

hasWeapon(weapon)

Arg types: weapon: Weapon  |  returns bool

Does the robot have the given Weapon.

Parameters

weapon

The Weapon to check.

Returns

true if the bot has the weapon, false if not.

isAlive()

returns bool

inherited from Ship

Check if this Ship is alive.

Returns

true if the Ship is present in the game world and still alive, false otherwise.

isInCaptureZone()

returns bool

inherited from Item

Is item in a capture zone?

Returns

true if item is held in a capture zone, false if it is not.

isModActive(module)

Arg types: module: Module  |  returns bool

inherited from Ship

Checks if the given module is active.

This method takes a Module item as a parameter, e.g. Module.Shield

Parameters

module

The Module to check.

Returns

true if the given Module is in active use, false otherwise.

isSelected()

returns bool

inherited from BfObject

Determine if an object is selected in the editor.

This is useful for editor plugins only.

Returns

Returns true if the object is selected, false if not.

privateMsg(message, playerName)

Arg types: message: string, playerName: string  |  returns nothing

Send a private message to a player.

Currently, no events are fired for private messages, so they cannot be received by bots.

Parameters

message	Message to send.
playerName	Name of player to which to send a message.

removeFromGame()

returns nothing

inherited from BfObject

Removes the object from the current game or editor session.

May not be implemented for all objects.

setAngle(angle)[1/2]

Arg types: angle: num  |  returns nothing

Sets the Robot's angle to angle

Parameters

angle

The desired angle in radians

setAngle(p)[2/2]

Arg types: p: point  |  returns nothing

Sets the Robot's angle to point towards p

Parameters

p	The point to point at

setEnergy(energy)

Arg types: energy: num  |  returns nothing

inherited from Ship

Set the current energy of this ship.

Energy is specified as a number between 0 and 1 where 0 means no energy and 1 means full energy. Values outside this range will be clamped to the valid range.

Parameters

energy

A value between 0 and 1.

setGeom(geometry)

Arg types: geometry: Geom  |  returns nothing

inherited from BfObject

Sets an object's geometry.

Parameters

geometry

The object's new geometry.

Note that not all objects support changing geometry if the object has already been added to a game.

setHealth(health)

Arg types: health: num  |  returns nothing

inherited from Ship

Set the current health of this ship.

Health is specified as a number between 0 and 1 where 0 is completely dead and 1 is full health. Values outside this range will be clamped to the valid range.

Parameters

health

A value between 0 and 1.

Note

A setting of 0 will kill the ship instantly.

setId(id)

Arg types: id: int  |  returns nothing

inherited from BfObject

Sets an object's user assigned id.

Users can assign an id to elements in the editor with the ! or # keys. Use this function to set this id from Lua. When called from an editor plugin, the value passed will be displayed in the editor when the player presses ! or #.

setLoadout(loadout)[1/2]

Arg types: loadout: table  |  returns nothing

inherited from Ship

Sets the requested loadout for the ship.

When setting the loadout, normal rules apply for updating the loadout, e.g. moving over a loadout zone.

This method will take a table with 5 entries in any order comprised of 3 weapons and 2 modules.

Note

This method will also take 5 parameters as a new loadout, instead of a table. See setLoadout(Weapon, Weapon, Weapon, Module, Module)

Parameters

loadout

The new loadout to request.

See also

setLoadoutNow()

setLoadout(w1, w2, w3, m1, m2)[2/2]

Arg types: w1: Weapon, w2: Weapon, w3: Weapon, m1: Module, m2: Module  |  returns nothing

inherited from Ship

Convenience alias for setLoadout(table)

Parameters

w1	The new Weapon for slot 1.
w2	The new Weapon for slot 2.
w3	The new Weapon for slot 3.
m1	The new Module for slot 1.
m2	The new Module for slot 2.

setLoadoutModule(slot, module)

Arg types: slot: int, module: Module  |  returns nothing

Request a new loadout where the given module slot is changed to the given module. This still requires the bot to change to its new loadout.

Parameters

slot	Module slot to set.
module	Module to set.

setLoadoutNow(loadout)

Arg types: loadout: table  |  returns nothing

inherited from Ship

Immediately sets the loadout for the ship.

This method does not require that you follow normal loadout-switching rules.

The parameters for this method follow the same rules as Ship::setLoadout().

Parameters

loadout

The new loadout to set.

See also

setLoadout(loadout)

setLoadoutWeapon(slot, weapon)

Arg types: slot: int, weapon: Weapon  |  returns nothing

Request a new loadout where the given weapon slot is changed to the given weapon. This still requires the bot to change to its new loadout.

Parameters

slot	Weapon slot to set.
weapon	Weapon to set.

setOwner(playerName)

Arg types: playerName: string  |  returns nothing

inherited from BfObject

Sets the owner of the object.

Parameters

playerName

Name of player as a string.

Note

This method only works if the item in question has already been added to the game via addItem(object). The owner cannot be set beforehand. Also, 'playerName' must exactly match a the name of a player already in the game (case-sensitive).

This method is intended to be used with bullets and other projectiles, not with game objects like zones.

setPos(pos)

Arg types: pos: point  |  returns nothing

inherited from BfObject

Set the object's position.

To set the full geometry of a more complex object, see the setGeom() method.

Parameters

pos	The new position of the object.

setSelected(selected)

Arg types: selected: bool  |  returns nothing

inherited from BfObject

Set whether an object is selected in the editor.

This is useful for editor plugins only.

Parameters

selected

true to select the object, false to deselect it.

setTeam(teamIndex)

Arg types: teamIndex: int  |  returns nothing

inherited from BfObject

Assigns the object to a team.

Parameters

teamIndex

Index of the team the object should be assigned to. (first team index is 1; there is no team 0)

Instead of a team index, you can use the special team enums Team.Neutral and Team.Hostile.

Limitations:

• Will have no effect on items that are inherently teamless (such as a NexusZone).
• Neither Ships nor Robots can be assigned to Team.Neutral or Team.Hostile.

setThrust(speed, angle)[1/2]

Arg types: speed: num, angle: num  |  returns nothing

Makes the Robot thrust at speed along angle.

Parameters

speed	The desired speed in units per second.
angle	The desired angle in radians.

setThrust(speed, p)[2/2]

Arg types: speed: num, p: point  |  returns nothing

Makes the Robot thrust at speed towards p.

Parameters

speed	The desired speed in units per second.
p	The point move towards.

setThrustToPt(p)

Arg types: p: point  |  returns nothing

Makes the Robot thrust to p, stopping when it reaches that point.

Note that you need to keep calling this function every tick; the ship will advance a bit towards its destination each game cycle, then stop when it arrives at its destination, even if you continue to call the function. It is not a "set and forget" type of thing.

Parameters

p	The point move towards.

setVel(vel)

Arg types: vel: point  |  returns nothing

inherited from MoveObject

Sets the item's velocity.

As with other functions that take a point as an input, you can also specify the x and y components as numeric arguments.

Parameters

vel	A point representing item's velocity.

subscribe(event)

Arg types: event: Event  |  returns nothing

Let the bot listen for and respond to the specified event.

When the specified event is fired, the robot can respond by implementing a specially named listener function. See Subscribing to Events for more information. See also the Event page for a list of events you can subscribe to and their corresponding listener funtcitons.

As a conveneinece, robots are automatically subscribed to the Tick event, and if they implement a function called onTick(), it will be called every game cycle. You can unubscribe from this event if you want.

Parameters

event

Event to subscribe to.

teamMsg(message)

Arg types: message: string  |  returns nothing

Send a message to this Robot's team.

Parameters

message

Message to send.

unsubscribe(event)

Arg types: event: Event  |  returns nothing

Stop listening for the specified event.

After unsubscribing from the event, the corresponding listener function will no longer be called when the event is fired.

Parameters

event

Event to unsubscribe from.