1. General Functions

These functions allow general control of the Xpilot client

xpai.setargs(String args) → void

Launches the xpilot client with the specified command line arguments. 

# joins server on localhost:1338 with name "jim"

xpai.setargs("-name jim -join localhost -port 1338")
xpai.launch()

xpai.launch(void) → int success

Launches xpilot client

xpai.setmaxturn(int degrees) → void

Sets the maximum turn for self in degrees per frame.

xpai.teamplay(void) → int

Returns 1 if teamplay is enabled.

See also: [xpai.self_team], [xpai.ship_team]

xpai.presskey(int key) → void

Simulates a key press. [xpai.releasekey] must be called after to complete the key-stroke. 

# A ship that tries to fire a laser every
# frame (if lasers are enabled by server

def AImain():
        xpai.presskey(KEY_FIRE_LASER)
        xpai.releasekey(KEY_FIRE_LASER)

Here is a complete list of all the possible keys to press.

  • KEY_DUMMY

  • KEY_LOCK_NEXT

  • KEY_LOCK_PREV

  • KEY_LOCK_CLOSE

  • KEY_CHANGE_HOME

  • KEY_SHIELD

  • KEY_FIRE_SHOT

  • KEY_FIRE_MISSILE

  • KEY_FIRE_TORPEDO

  • KEY_TOGGLE_NUCLEAR

  • KEY_FIRE_HEAT

  • KEY_DROP_MINE

  • KEY_DETACH_MINE

  • KEY_TURN_LEFT

  • KEY_TURN_RIGHT

  • KEY_SELF_DESTRUCT

  • KEY_LOSE_ITEM

  • KEY_PAUSE

  • KEY_TANK_DETACH

  • KEY_TANK_NEXT

  • KEY_TANK_PREV

  • KEY_TOGGLE_VELOCITY

  • KEY_TOGGLE_CLUSTER

  • KEY_SWAP_SETTINGS

  • KEY_REFUEL

  • KEY_CONNECTOR

  • KEY_INCREASE_POWER

  • KEY_DECREASE_POWER

  • KEY_INCREASE_TURNSPEED

  • KEY_DECREASE_TURNSPEED

  • KEY_THRUST

  • KEY_CLOAK

  • KEY_ECM

  • KEY_DROP_BALL

  • KEY_TRANSPORTER

  • KEY_TALK

  • KEY_FIRE_LASER

  • KEY_LOCK_NEXT_CLOSE

  • KEY_TOGGLE_COMPASS

  • KEY_TOGGLE_MINI

  • KEY_TOGGLE_SPREAD

  • KEY_TOGGLE_POWER

  • KEY_TOGGLE_AUTOPILOT

  • KEY_TOGGLE_LASER

  • KEY_EMERGENCY_THRUST

  • KEY_TRACTOR_BEAM

  • KEY_PRESSOR_BEAM

  • KEY_CLEAR_MODIFIERS

  • KEY_LOAD_MODIFIERS_1

  • KEY_LOAD_MODIFIERS_2

  • KEY_LOAD_MODIFIERS_3

  • KEY_LOAD_MODIFIERS_4

  • KEY_SELECT_ITEM

  • KEY_PHASING

  • KEY_REPAIR

  • KEY_TOGGLE_IMPLOSION

  • KEY_REPROGRAM

  • KEY_LOAD_LOCK_1

  • KEY_LOAD_LOCK_2

  • KEY_LOAD_LOCK_3

  • KEY_LOAD_LOCK_4

  • KEY_EMERGENCY_SHIELD

  • KEY_HYPERJUMP

  • KEY_DETONATE_MINES

  • KEY_DEFLECTOR

  • KEY_UNUSED_65

  • KEY_UNUSED_66

  • KEY_UNUSED_67

  • KEY_UNUSED_68

  • KEY_UNUSED_69

  • KEY_UNUSED_70

  • KEY_UNUSED_71

  • NUM_KEYS

  • KEY_MSG_1

  • KEY_MSG_2

  • KEY_MSG_3

  • KEY_MSG_4

  • KEY_MSG_5

  • KEY_MSG_6

  • KEY_MSG_7

  • KEY_MSG_8

  • KEY_MSG_9

  • KEY_MSG_10

  • KEY_MSG_11

  • KEY_MSG_12

  • KEY_MSG_13

  • KEY_MSG_14

  • KEY_MSG_15

  • KEY_MSG_16

  • KEY_MSG_17

  • KEY_MSG_18

  • KEY_MSG_19

  • KEY_MSG_20

  • KEY_ID_MODE

  • KEY_TOGGLE_OWNED_ITEMS

  • KEY_TOGGLE_MESSAGES

  • KEY_POINTER_CONTROL

  • KEY_TOGGLE_RECORD

  • KEY_PRINT_MSGS_STDOUT

  • KEY_TALK_CURSOR_LEFT

  • KEY_TALK_CURSOR_RIGHT

  • KEY_TALK_CURSOR_UP

  • KEY_TALK_CURSOR_DOWN

  • KEY_SWAP_SCALEFACTOR

See also: [xpai.releaseKey]

xpai.releasekey(int key) → void

Simulates a key release. Call to release a key pressed by [xpai.pressKey] See [xpai.presskey] for a complete list of keys. 

# A ship that tries to fire a laser every
# frame (if lasers are enabled by server

def AImain():
        xpai.presskey(KEY_FIRE_LASER);
        xpai.releasekey(KEY_FIRE_LASER);

See also: [xpai.pressKey]

2. Self Control

Functions to control the ship

xpai.self_thrust(thrust)

Controls the ship’s thrust. 1 to thrust, 0 to not thrust. Resets to not-thrust after every frame. 

# a ship that thrusts every frame

def AImain():
        xpai.self_thrust(1)

See Also: [xpai.self_turn], [xpai.self_shoot], [xpai.self_shield_enable]

xpai.self_turn(degrees)

Turns the ship turn degrees (out of 360). Negative degrees are clockwise, positive counter-clockwise. 

#a ship that turns 15 degrees counter-clockwise every frame

def AImain():
        xpai.self_turn(15);

See Also: [xpai.setmaxturn], [xpai.self_thrust], [xpai.self_shoot], [xpai.anglediff], [xpai.angleadd], [xpai.self_shield_enable]

xpai.self_shoot(shoot)

Makes the ship shoot. 1 to shoot, 0 to not shoot. Servers limit the shot rate and the number of shots, so AIself_shoot(1) will not always cause a shot to be fired. Use [AIself_reload] to check the number of frames remaining before it is possible to shoot again. 

# a ship that waits until "reload"
   says it can shoot and then shoots

def AImain():
        if (xpai.self_reload() == 0):
                xpai.self_shoot(1)

See Also: [xpai.self_reload], [xpai.self_turn], [xpai.self_thrust], [xpai.self_shield_enable]

xpai.self_shield_enable(shield)

Turns on or off the ship’s shield. Use [AIself_shield] to see the status of the shield. 

# a ship whose shield is always on
def: AImain():
        xpai.self_shield_enable(1)

See Also: [xpai.self_shield], [xpai.self_turn], [xpai.self_thrust], [xpai.self_shoot]

xpai.self_destruct()

Start or stop the self-destruct sequence.

3. Self Variables

Functions that return values of variables concerning the self ship.

xpai.self_id()

The id of self’s ship, according to the server.

See Also: [xpai.ship_id]

xpai.self_alive()

xpai.self_x()

Self’s x position, where bottom left of map is [0, 0].

See Also: [xpai.self_y], [xpai.ship_x], [xpai.radar_x], [xpai.shot_x]

xpai.self_y()

Self’s y position, where bottom left of map is [0, 0].

See Also: [xpai.self_x], [xpai.ship_y], [xpai.radar_y], [xpai.shot_y]

xpai.self_vel()

Self’s velocity (number of pixels moved per frame).

See Also: [xpai.self_track], [xpai.ship_vel], [xpai.shot_vel]

xpai.self_heading()

Self’s heading (direction ship’s nose is pointing). 0 degrees is to the right and 90 degrees is straight up.

See Also: [xpai.self_track], [xpai.anglediff], [xpai.angleadd]

xpai.self_track()

Self’s track (direction of movement). 0 degrees is to the right and 90 degrees is straight up.

See Also: [xpai.self_heading], [xpai.anglediff], [xpai.angleadd]

xpai.self_mapx()

Self’s x position on radar map, using radar map units.

See Also: [xpai.self_mapy], [xpai.self_x]

xpai.self_mapy()

Self’s y position on radar map, using radar map units.

See Also: [xpai.self_mapx], [xpai.self_y]

xpai.self_team()

See Also: [xpai._teamplay], [xpai.ship_team]

xpai.self_life()

See Also: [xpai.ship_life]

xpai.self_shield()

See Also: [xpai.ship_shield]

xpai.self_name()

See Also: [xpai.ship_name]

float xpai.self_score() See Also: [xpai.self_HUD_score]

xpai.self_reload()

Number of frames remaining before self is able to shoot. When 0, self is able to shoot.

See Also: [xpai.ship_reload]

4. Ships

Functions returning information about other ships on screen. The ships are sorted from nearest to furthest.

xpai.ship_x(idx)

Ship’s x position, where bottom left of map is [0, 0].

See Also: [xpai.self_x], [xpai.ship_y], [xpai.radar_x], [xpai.shot_x]

xpai.ship_y(idx)

Ship’s y position, where bottom left of map is [0, 0].

See Also: [xpai.self_y], [xpai.ship_x], [xpai.radar_y], [xpai.shot_y]

xpai.ship_heading(idx)

Ship’s heading (angle nose is pointing). 0 degrees is to the right, and 90 straight up.

See Also: [xpai.ship_track], [xpai.anglediff], [xpai.angleadd]

xpai.ship_track(idx)

Ship’s track (direction of velocity). 0 degrees is to the right, and 90 straight up.

See Also: [xpai.ship_heading], [xpai.anglediff], [xpai.angleadd]

xpai.ship_vel(idx)

Ship’s velocity in pixels/frame.

See Also: [xpai.self_vel], [xpai.shot_vel]

xpai.ship_dist(idx)

Ship’s distance from self, in pixels.

See Also: [xpai.radar_dist], [xpai.shot_dist]

xpai.ship_id(idx)

server assigned id of ship

See Also: [xpai.self_id]

xpai.ship_xdir(idx)

Direction of ship from self. 0 degrees is to the right and 90 upright. 

# Self always points at nearest on screen ship
def AImain():
        if (xpai.ship_x(0) != -1):
                xpai.self_turn(xpai.anglediff(xpai.self_heading(), xpai.ship_xdir(0)))

See Also: [xpai.self_heading], [xpai.anglediff], [xpai.angleadd], [xpai.radar_xdir]

xpai.ship_shield(idx)

See Also: [xpai.self_shield]

xpai.ship_life(idx)

See Also: [xpai.self_life]

xpai.ship_team(idx)

See Also: [xpai.self_team]

xpai.ship_reload(idx)

This is the number of frames remaining before the ship can fire again. This number is just an estimate, and may not always be correct.

See Also: [xpai.self_reload]

xpai.ship_name(idx)

See Also: [xpai.self_name]

xpai.ship_aimdir(idx)

Calculates the direction that self would need to point to hit the ship, according to self’s track and velocity, the enemy ship’s track and velocity, and the default bullet’s shotspeed. This is a pretty deadly function. Sometimes it can’t calculate correctly and returns some negative number. 

#bot that aims and shoots at nearest ship

def AImain():
        if (xpai.ship_x(0) != -1):
                xpai.self_turn(xpai.anglediff(xpai.self_heading(), xpai.ship_aimdir(0)))
                xpai.self_shoot(1)

See Also: [xpai.ship_xdir], [xpai.self_heading], [xpai.anglediff], [xpai.angleadd]

5. Radar

Functions returning information about other ships on the radar. The ships are sorted from nearest to furthest.

xpai.radar_x(idx)

Radar ship’s x position (approximate), where bottom left of map is [0, 0].

See Also: [xpai.self_x], [xpai.ship_x], [xpai.radar_y], [xpai.shot_x]

xpai.radar_y(idx)

Radar ship’s y position (approximate), where bottom left of map is [0, 0].

See Also: [xpai.self_y], [xpai.ship_y], [xpai.radar_x], [xpai.shot_y]

xpai.radar_dist(idx)

Radar ship’s distance from self, in pixels (approximate).

See Also: [xpai.ship_dist], [xpai.shot_dist]

xpai.radar_xdir(idx)

Direction of radar ship from self. 0 degrees is to the right and 90 upright. 

#self always points at second-nearest radar ship
def AImain():
        if (xpai.radar_x(1) != -1)
                xpai.self_turn(anglediff(xpai.self_heading(), xpai.radar_xdir(1)))

See Also: [xpai.self_heading], [xpai.ship_xdir], [xpai.anglediff], [xpai.angleadd]

xpai.radar_enemy(idx)

See Also: [xpai.ship_team]

6. Shots

Functions returning information about the shots on screen.

xpai.shot_x(idx)

shot’s x position, where bottom left of map is [0, 0].

See Also: [xpai.self_x], [xpai.shot_y]

xpai.shot_y(idx)

shot’s y position, where bottom left of map is [0, 0].

See Also: [xpai.self_y], [xpai.shot_x]

xpai.shot_track(idx)

shot’s track (direction of velocity). 0 degrees is to the right, and 90 straight up.

See Also: [xpai.shot_vel], [xpai.anglediff], [xpai.angleadd]

xpai.shot_vel(idx)

shot’s velocity in pixels/frame.

See Also: [xpai.ship_vel], [xpai.shot_track]

xpai.shot_dist(idx)

shot’s distance from self, in pixels.

See Also: [xpai.ship_dist], [xpai.radar_dist]

xpai.shot_imaginary(idx)

Imaginary shots are calculated for every ship on screen. If a ship were to shoot this frame, imaginary bullets tell that shots attributes.

See Also: [xpai.shot_x]

xpai.shot_xdir(idx)

Direction of shot from self. 0 degrees is to the right and 90 upright.

See Also: [xpai.shot_idir], [xpai.self_heading], [xpai.anglediff], [xpai.angleadd]

xpai.shot_idir(idx)

Direction of the location where the shot will be nearest to self, if both self velocity and bullet velocity remain constant. 0 degrees is to the right and 90 upright. 

/*self turns away from intercept dir and thrusts*/

void AImain():
        if (xpai.shot_x(0) != -1):
                xpai.self_turn(anglediff(xpai.self_heading(), angleadd(xpai.shot_idir(0), 180)))

See Also: [xpai.shot_idist], [xpai.shot_itime], [xpai.self_heading], [xpai.anglediff], [xpai.angleadd]

xpai.shot_idist(idx)

Distance to the location where the shot will be nearest to self, if both self velocity and bullet velocity remain constant, in pixels.

See Also: [xpai.shot_idir], [xpai.shot_itime], [xpai.self_heading], [xpai.anglediff], [xpai.angleadd]

xpai.shot_itime(idx)

Number of frames until the nearest intercept will occur, if both self velocity and bullet velocity remain constant.

See Also: [xpai.shot_idir], [xpai.shot_idist], [xpai.self_heading], [xpai.anglediff], [xpai.angleadd]

xpai.shot_alert(idx)

A value derived from [xpai.shot_idist] and [xpai.shot_itime] . An alert between 0 and 30 means that self will probably be killed by the shot, 30 to 120, that it is a dangerous shot and should be avoided, and above 120, it’s not very dangerous. This variable is just for convience, and should probably not be used in more advanced controllers.

See Also: [xpai.self_reload]

7. Walls and Map

Functions to check for walls and to look at map tiles

xpai.wallbetween(x1 y1 x2 y2)

This function checks for walls in a straight line starting from point [x1, y1] to point [x2, y2]. If it finds a wall, it returns the distance (in pixels) from [x1, y1] to that point. If gets to [x2, y2] without finding a wall, it returns -1. 

# this checks for a wall 200 pixels
   in front of the ships track

wall_N = xpai.wallbetween (     /
        xpai.self_x(),  /
        xpai.self_y(),          /
        xpai.self_x() + 200 * cos(xpai.rad(xpai.self_track())),
        xpai.self_y() + 200 * sin(xpai.rad(xpai.self_track())))

See Also: [xpai.wallbetween_x], [xpai.wallbetween_y]

xpai.wallbetween_x(x1 y1 x2 y2)

This function checks for walls in a straight line starting from point [x1, y1] to point [x2, y2]. If it finds a wall, it returns the x coordinate of that wall. If gets to [x2, y2] without finding a wall, it returns -1.

See Also: [xpai.wallbetween], [xpai.wallbetween_y]

xpai.wallbetween_y(x1 y1 x2 y2)

This function checks for walls in a straight line starting from point [x1, y1] to point [x2, y2]. If it finds a wall, it returns the y coordinate of that wall. If gets to [x2, y2] without finding a wall, it returns -1.

See Also: [xpai.wallbetween], [xpai.wallbetween_x]

xpai.map_get(x, y) The map consists of tiles which are 35x35 pixels each. Each tile contains information about that spot on the map, and can have multiple values. For instance, a square block tile may have 5 bit flags set; one for each side, and one to indicate it is a wall tile. The possible flags are listed below. Use the bitwise "and" operator to check the tiles for the flags. To convert a regular game coordinate to a map coordinate, use [tomap] and [frmap] .

# checks to see if the map tile to the immediate
# right of the player contains a wall of some sort

if (xpai.map_get(xpai.tomap(xpai.self_x()) + 1, xpai.tomap(xpai.self_y()) + 1) & BLUE_BIT):
        print "To the right is a wall tile!\n"

See Also: [xpai.map_set], [xpai.tomap], [xpai.frmap]

The following are possible tile values

SETUP_SPACE             0
SETUP_FILLED            1
SETUP_FILLED_NO_DRAW    2
SETUP_FUEL              3
SETUP_REC_RU            4
SETUP_REC_RD            5
SETUP_REC_LU            6
SETUP_REC_LD            7
SETUP_ACWISE_GRAV       8
SETUP_CWISE_GRAV        9
SETUP_POS_GRAV          10
SETUP_NEG_GRAV          11
SETUP_WORM_NORMAL       12
SETUP_WORM_IN           13
SETUP_WORM_OUT          14
SETUP_CANNON_UP         15
SETUP_CANNON_RIGHT      16
SETUP_CANNON_DOWN       17
SETUP_CANNON_LEFT       18
SETUP_SPACE_DOT         19
SETUP_TREASURE          20      /* + team number (10) */
SETUP_BASE_LOWEST       30      /* lowest base number */
SETUP_BASE_UP           30      /* + team number (10) */
SETUP_BASE_RIGHT        40      /* + team number (10) */
SETUP_BASE_DOWN         50      /* + team number (10) */
SETUP_BASE_LEFT         60      /* + team number (10) */
SETUP_BASE_HIGHEST      69      /* highest base number */
SETUP_TARGET            70      /* + team number (10) */
SETUP_CHECK             80      /* + check point number (26) */
SETUP_ITEM_CONCENTRATOR 110
SETUP_DECOR_FILLED      111
SETUP_DECOR_RU          112
SETUP_DECOR_RD          113
SETUP_DECOR_LU          114
SETUP_DECOR_LD          115
SETUP_DECOR_DOT_FILLED  116
SETUP_DECOR_DOT_RU      117
SETUP_DECOR_DOT_RD      118
SETUP_DECOR_DOT_LU      119
SETUP_DECOR_DOT_LD      120
SETUP_UP_GRAV           121
SETUP_DOWN_GRAV         122
SETUP_RIGHT_GRAV        123
SETUP_LEFT_GRAV         124
SETUP_ASTEROID_CONCENTRATOR     125

BLUE_UP                 0x01
BLUE_RIGHT              0x02
BLUE_DOWN               0x04
BLUE_LEFT               0x08
BLUE_OPEN               0x10    /* diagonal botleft -> rightup */
BLUE_CLOSED             0x20    /* diagonal topleft -> rightdown */
BLUE_FUEL               0x30    /* when filled block is fuelstation */
BLUE_BELOW              0x40    /* when triangle is below diagonal */
BLUE_BIT                0x80    /* set when drawn with blue lines */

DECOR_LEFT              0x01
DECOR_RIGHT             0x02
DECOR_DOWN              0x04
DECOR_UP                0x08
DECOR_OPEN              0x10
DECOR_CLOSED    0x20
DECOR_BELOW             0x40

xpai.map_set(x, y, value)

The map tiles in Xpilot-AI are 32 bits. Only the lowest order bits are used for Xpilot, so the other bits can be set as desired. 

# Sets a bit flag on the map tile underneath self

newtile = xpai.map_get(xpai.tomap(xpai.self_x()), xpai.tomap(xpai.self_y()))
newtile = newtile | 0x1000
xpai.map_set(xpai.tomap(xpai.self_x()), xpai.tomap(xpai.self_y()), newtile)

See Also: [xpai.map_get], [xpai.tomap], [xpai.frmap]

xpai.tomap(x)

Converts a gamplay pixel value to a map value.

See Also: [xpai.map_get], [xpai.map_set], [xpai.frmap]

xpai.frmap(x)

Takes a map value and returns the middle of that map tile, in pixels.

See Also: [xpai.map_get], [xpai.map_set], [xpai.tomap]

8. Messages

Write and recieve messages using the player-to-player messaging system in Xpilot

xpai.talk(message)

Say a message through the player-to-player talk system in Xpilot.

Note: Sometimes xpilot servers kick out players that type too much, or send two messages in on frame. Because of this, if xpai.talk is called more than once per frame, it will automatically spread sending the messages over several frames.

# Writes a message to everyone
        xpai.talk("Hello everyone")
# Writes a private message to a player named "Jimmy"
        xpai.talk("Jimmy: hello I'm at (22, 1004)")
# Change to team 5 */
        xpai.talk("/team 5")

See Also: [xpai.msg_to], [xpai.msg_from], [xpai.msg_body]

xpai.msg_to(idx)

Look at a private message’s "to" field from the player-to-player messaging system. Returns NULL if there is no "to" field either because there is no message or it is a public message.

See Also: [xpai.talk], [xpai.msg_from], [xpai.msg_body]

xpai.msg_from(idx)

Look at a message’s "from" field from the player-to-player messaging system. Returns NULL if there are no messages.

See Also: [xpai.talk], [xpai.msg_to], [xpai.msg_body]

xpai.msg_body(idx)

Look at a message’s "body" field from the player-to-player messaging system. Returns NULL if there are no messages. 

# cycles through all the messages recieved
   every frame and prints the body

i = 0
while (xpai.msg_body(i) != null):
        print "s\n", xpai.msg_body(i)
        i++

See Also: [xpai.talk], [xpai.msg_to], [xpai.msg_from]

9. HUD

The HUD is the informative box around the self’s ship. These functions access various information from the HUD, like the info about who killed who (Useful for determing kills).

xpai.self_HUD_name(idx)

Look at a HUD slot’s name field. Returns "" if there is no name in that slot.

See Also: [xpai.self_HUD_score], [xpai.self_HUD_name]

float xpai.self_HUD_score(idx) Look at a HUD slot’s score field. It is best to check for empty slots using [xpai.self_HUD_time] .

See Also: [xpai.self_HUD_time], [xpai.self_HUD_name]

xpai.self_HUD_time(idx)

Number of frames that the HUD message has been on the HUD slot. When a score first appears it will have a value of 0, then increase each frame thereafter until it gets to about 99. [xpai.self_HUD_time] . 

# check for and print out any names with positive points in HUD
i = 0
while (xpai.self_HUD_time(i) != -1):
        if (xpai.self_HUD_time(i) == 0 and xpai.self_HUD_score(i) >= 0.0):
                print "You killed: s\n", xpai.self_HUD_name(i)
                i++

See Also: [xpai.self_HUD_score], [xpai.self_HUD_name]

10. Math Functions

Useful math functions

xpai.anglediff(a1, a2)

Returns the smallest angle which angle1 could add to itself to be equal to angle2. This is useful for turning particular directions. 

xpai.anglediff(90, 70) = -20
xpai.anglediff(350, 10) = 20

See Also: [xpai.angleadd], [xpai.rad], [xpai.deg]

xpai.angleadd(a1, a2)

Adds two angles together. 

xpai.angleadd(90, 70) = 160
xpai.angleadd(350, 40) = 30

See Also: [xpai.angleadd], [xpai.rad], [xpai.deg]

xpai.rad(degree)

Converts a degree angle to radian, which is used in sin, cos, and tan.

See Also: [xpai.deg], [xpai.angleadd], [xpai.anglediff]

xpai.deg(radian)

Converts a radian angle to degree, which is used in gameplay.

See Also: [xpai.rad], [xpai.angleadd], [xpai.anglediff]