Difference between revisions of "Programming robots"

Revision as of 09:00, 30 April 2009

Starting with release 011, server admins will be able to program their own robots in addition to designing their own levels. Robots will be coded in Lua, and will will have a number of special functions available to them.

Robot coding is still fluid, and everything is subject to change, but here is a list of commands being implemented for the next alpha release (see forums for the URL):

Navigation, configuration, and combat

getZoneCenterXY( x, y ) - Return point representing center of zone containing point x,y
getGatewayFromZoneToZone( a, b ) - Return point representing fastest way from zone a to zone b. If zones a & b are not neighbors, returns nil
getZoneCount() - Return number of zones
getCurrentZone() - Return current zone that robot is in

getAngle() - Return angle robot is currently facing
getPosXY() - Return x, y of robot

setAngle(ang) - Set robot's angle
setAngleXY(x, y) - Point robot at point x,y
getAngleXY(x, y) - Return angle to point x, y
hasLosXY(x, y) - Return whether or not robot can see point x, y

hasFlag() - Return whether or not robot currently has the flag


getWeapon() - Return currently selected weapon (returns WeaponType)
Example:

weap = bot:getWeapon()            -- Get info about our currently active weapon
weapInfo = WeaponInfo( weap )     -- Get information about it	
bot:logprint( weapInfo:getName().." has a range of "..weapInfo:getRange() )

activateModule(module enum) - Activate module, specified by ModuleType. If specified module is not included in the current loadout, this command will have no effect. (returns nothing) Example:

-- Note that this line will do nothing if we don't have shields
bot:activateModule( ModuleShield )    -- Shields up!

activateModuleIndex(indx) - Activate module, specified by its index (1 or 2) (returns nothing)
Example:

-- Must specify an index, currently either 1 or 2
bot:activateModuleIndex( 1 )          -- Activate first module, whatever it is

setReqLoadout(Loadout) - Set the requested loadout to Loadout (returns nothing)
getCurrLoadout() - Returns current loadout (returns Loadout)
Example:

loadout = bot:getCurrLoadout()       -- Retrieve current bot configuration

weapType1 = loadout:getWeapon(1)     -- Get the first weapon
weapType2 = loadout:getWeapon(2)     -- Get the second weapon
weapType3 = loadout:getWeapon(3)     -- Get the third weapon

-- Check to see if the first weapon is a phaser
if ( weapType1 == WeaponPhaser ) then
	bot:logprint("First weapon is a phaser!")
end

-- Print a list of our three current weapons
bot:logprint( "My three weapons are: "..WeaponInfo(weapType1):getName()..", "
                                      ..WeaponInfo(weapType2):getName()..", and "
                                      ..WeaponInfo(weapType3):getName() )

getReqLoadout() - Returns requested loadout (returns Loadout)

Navigation

findObjects(ObjectType)
getWaypoint(x, y)


Ship control
setThrustAng(angle)
setThrustXY(x, y)

fire()
setWeapon(weapon number)
globalMsg(msg) - Send a message to all players
teamMsg(msg) - Send a message to players on the same team

logprint(msg) - Print msg to game logfile

GameItems

The Lua object structure follows that used by Bitfighter. The GameItems group conisists of RepairItems, Asteroids, ResourceItems, and TestItems. These all share similar properties, and have similar methods. All of these implement the getLoc, getVel, and getRad methods for querying location, velocity, and radius respectively. Some items have additional methods that apply only to them. See below for details on these additional methods.

TestItems

Category: GameItem

getLoc() - Center of testItem (returns point)
getRad() - Radius of testItem (returns number)
getVel() - Speed of testItem (returns point)

Example:

ti = bot:findTestItem()	-- Function likely to change
vel = it:getVel()

Asteroids

Category: GameItem

getSize() - Index of current asteroid size (0 = initial size, 1 = next smaller, 2 = ...) (returns int)
getSizeCount() - Number of indexes of size we can have (returns int)
getLoc() - Center of asteroid (returns point)
getRad() - Radius of asteroid (returns number)
getVel() - Speed of asteroid (returns point)

Example:

asteroid = bot:findAsteroid()	-- Function likely to change
target = asteroid:getLoc()

ResourceItems

Category: GameItem

getLoc() - Center of ResourceItem (returns point)
getRad() - Radius of ResourceItem (returns number)
getVel() - Speed of ResourceItem (returns point)

Example:

ri = bot:ResourceItem()	-- Function likely to change
vel = ri:getVel()

RepairItems

Category: GameItem

getLoc() - Center of RepairItem (returns point)
getRad() - Radius of RepairItem (returns number)
getVel() - Speed of RepairItem (returns point, usually 0,0)
isVis() - Is repair item currently visible? (returns boolean)

Example:

ri = bot:findRepairItem()	-- Function likely to change
vel = ri:getVel()

Weapon Information

All the WeaponInfo data will remain constant throughout the game. Therefore, if you need some information about a weapon, it might make sense to retrieve it in the bot's header and store it in a local variable rather than instantiating a new WeaponInfo object during every loop of the robot's getMove() method.

Example:

weap = bot:getWeapon()             -- Get bot's currently active weapon
bot:logprint( weap:getName().." has a range of "..weap:getRange() )

weap = WeaponInfo( WeaponTurret )  -- Get info about those infernal turrets
bot:logprint( weap:getName().." shoots with a speed of "..weap:getProjVel() )

getName() - Name of weapon ("Phaser", "Triple", etc.) (returns string)
getID() - ID of module (WeaponPhaser, WeaponTriple, etc.) (returns WeaponType)
getRange() - Get range of weapon (units) (returns integer)
getFireDelay() - Delay between shots in ms (returns integer)
getMinEnergy() - Minimum energy needed to use (returns integer)
getEnergyDrain() - Amount of energy weapon consumes (returns integer)
getProjVel() - Speed of projectile (units/sec) (returns integer)
getProjLife() - Time projectile will live (ms) (returns integer, -1 == live forever)
getDamage() - Damage projectile does (0-1, where 1 = total destruction) (returns float)
getCanDamageSelf() - Will weapon damage self? (returns boolean)
getCanDamageTeammate() - Will weapon damage teammates? (returns boolean)

WeaponType constants

WeaponPhaser
WeaponBounce
WeaponTriple
WeaponBurst
WeaponMine
WeaponSpyBug
WeaponTurret

Module Information

Example:

mod = ModuleInfo( ModuleBoost )
bot:logprint( "This is a lame example!" )

getName() - Name of module ("Shield", "Turbo", etc.) (returns string)
getID() - ID of module (ModuleShield, ModuleBoost, etc.) (returns ModuleType)

ModuleType constants

ModuleShield
ModuleBoost
ModuleSensor
ModuleRepair
ModuleEngineer (maybe someday)
ModuleCloak

Loadouts

setWeapon(i, mod) - Set weapon at index i (returns nothing)
setModule(i, mod) - Set module at index i (returns nothing)
isValid() - Is loadout config valid? (returns boolean)
equals(Loadout) - is loadout the same as Loadout? (returns boolean)
getWeapon(i) - return weapon at index i (returns Weapon enumeration)
getModule(i) - return module at index i (returns Module enumeration)

Game Information

You can get information about the current game with the GameInfo object. You only need get this object once, then you can use it as often as you like. It will always reflect the latest data.
Example:

game = GameInfo()	        -- Create the GameInfo object 
levelname = game:getLevelName()

Methods available:

getGameType()
getFlagCount()
getWinningScore()
getGameTimeTotal()
getGameTimeRemaining()
getLeadingScore()
getLeadingTeam()

getLevelName()
getGridSize()
getIsTeamGame()

getEventScore(ScoringEvent)

Valid GameType constants are:
BitmatchGame
CTFGame
HTFGame
NexusGame
RabbitGame
RetrieveGame
SoccerGame
ZoneControlGame

Valid ScoringEvent constants are:
KillEnemy
KillSelf
KillTeammate
KillEnemyTurret
KillOwnTurret
CaptureFlag
CaptureZone
UncaptureZone
HoldFlagInZone
RemoveFlagFromEnemyZone
RabbitHoldsFlag
RabbitKilled
RabbitKills
ReturnFlagsToNexus
ReturnFlagToZone
LostFlag
ReturnTeamFlag
ScoreGoalEnemyTeam
ScoreGoalHostileTeam
ScoreGoalOwnTeam

Misc

Some constants available in game:

Game Objects
ShipType
BarrierType
MoveableType
BulletType
ItemType
ResourceItemType
EngineeredType
ForceFieldType
LoadoutZoneType
MineType
TestItemType
FlagType
TurretTargetType
SlipZoneType
HeatSeekerType
SpyBugType
NexusType
BotNavMeshZoneType
RobotType
TeleportType
GoalZoneType
AsteroidType