1. General Functions

These functions allow general control of the Xpilot client

xpilot(String args) → void

Launches the xpilot client with the specified command line arguments. 

/*joins server on localhost:1338 with name "jim"*/

xpilot("-name jim -join localhost -port 1338");
AI_setmaxturn(int degrees) → void

Sets the maximum turn for self in degrees per frame.

AI_teamplay(void) → int

Returns 1 if teamplay is enabled.

AI_pressKey(int key) → void

Simulates a key press. AI_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  */

void AImain(void) {
        AI_pressKey(KEY_FIRE_LASER);
        AI_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: [AI_releaseKey]

AI_releaseKey(int key) → void

Simulates a key release. Call to release a key pressed by [AI_pressKey()] See [AI_pressKey()] for a complete list of keys. 

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

void AImain(void) {
        AI_pressKey(KEY_FIRE_LASER);
        AI_releaseKey(KEY_FIRE_LASER);
}

See also: [AI_pressKey]

2. Self Control

Functions to control the ship

void AIself_thrust(int 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 */

void AImain(void) {
        AIself_thrust(1);
}

See Also: [AIself_turn], [AIself_shoot], [AIself_shield_enable]

void AIself_turn(int turn)

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

/*a ship that turns 15 degrees clockwise every frame*/

void AImain(void) {
        AIself_turn(-15);
}

See Also: [AI_setmaxturn], [AIself_thrust], [AIself_shoot], [anglediff], [angleadd], [AIself_shield_enable]

void AIself_shoot(int)

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 */

void AImain(void) {
        if (AIself_reload() == 0)
                AIself_shoot(1);
}

See Also: [AIself_reload], [AIself_turn], [AIself_thrust], [AIself_shield_enable]

void AIself_shield_enable(int)

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 */
void AImain(void) {
        AIself_shield_enable(1);
}

See Also: [AIself_shield], [AIself_turn], [AIself_thrust], [AIself_shoot]

void AIself_destruct(int)

Start or stop the self-destruct sequence.

3. Self Variables

Functions that return values of variables concerning the self ship.

int AIself_id()

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

See Also: [AIship_id]

int AIself_alive()

1 if alive, 0 if not.

int AIself_x()

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

int AIself_y()

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

See Also: [AIself_x], [AIship_y], [AIradar_y], [AIshot_y]

int AIself_vel()

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

See Also: [AIself_track], [AIship_vel], [AIshot_vel]

int AIself_heading()

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

See Also: [AIself_track], [anglediff], [angleadd]

int AIself_track()

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

See Also: [AIself_heading], [anglediff], [angleadd]

int AIself_mapx()

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

See Also: [AIself_mapy], [AIself_x]

int AIself_mapy()

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

See Also: [AIself_mapx], [AIself_y]

int AIself_team()

See Also: [AI_teamplay], [AIship_team]

int AIself_life()

See Also: [AIship_life]

int AIself_shield()

See Also: [AIship_shield]

String AIself_name()

See Also: [AIship_name]

float AIself_score() See Also: [AIself_HUD_score]

int AIself_reload()

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

See Also: [AIship_reload]

4. Ships

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

int AIship_x(int)

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

See Also: [AIself_x], [AIship_y], [AIradar_x], [AIshot_x]

int AIship_y(int)

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

See Also: [AIself_y], [AIship_x], [AIradar_y], [AIshot_y]

int AIship_heading(int)

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

See Also: [AIship_track], [anglediff], [angleadd]

int AIship_track(int)

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

See Also: [AIship_heading], [anglediff], [angleadd]

int AIship_vel(int)

Ship’s velocity in pixels/frame.

See Also: [AIself_vel], [AIshot_vel]

int AIship_dist(int)

Ship’s distance from self, in pixels.

See Also: [AIradar_dist], [AIshot_dist]

int AIship_id(int)

server assigned id of ship

See Also: [AIself_id]

int AIship_xdir(int)

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

/* Self always points at nearest on screen ship */
void AImain(void) {
        if (AIship_x(0) != -1)
                AIself_turn(anglediff(AIself_heading(), AIship_xdir(0)));
}

See Also: [AIself_heading], [anglediff], [angleadd], [AIradar_xdir]

int AIship_shield(int)

See Also: [AIself_shield]

int AIship_life(int)

See Also: [AIself_life]

int AIship_team(int)

See Also: [AIself_team]

int AIship_reload(int)

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: [AIself_reload]

String AIship_name(int)

See Also: [AIself_name]

int AIship_aimdir(int)

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 */

void AImain(void) {
        if (AIship_x(0) != -1) {
                AIself_turn(anglediff(AIself_heading(), AIship_aimdir(0)));
                AIself_shoot(1);
        }
}

See Also: [AIship_xdir], [AIself_heading], [anglediff], [angleadd]

5. Radar

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

int AIradar_x(int)

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

See Also: [AIself_x], [AIship_x], [AIradar_y], [AIshot_x]

int AIradar_y(int)

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

See Also: [AIself_y], [AIship_y], [AIradar_x], [AIshot_y]

int AIradar_dist(int)

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

See Also: [AIship_dist], [AIshot_dist]

int AIradar_xdir(int)

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

/* self always points at second-nearest radar ship */
void AImain(void) {
        if (AIradar_x(1) != -1)
                AIself_turn(anglediff(AIself_heading(), AIradar_xdir(1)));
}

See Also: [AIself_heading], [AIship_xdir], [anglediff], [angleadd]

int AIradar_enemy(int)

See Also: [AIship_team]

6. Shots

Functions returning information about the shots on screen.

int AIshot_x(int)

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

See Also: [AIself_x], [AIshot_y]

int AIshot_y(int)

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

See Also: [AIself_y], [AIshot_x]

int AIshot_track(int)

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

See Also: [AIshot_vel], [anglediff], [angleadd]

int AIshot_vel(int)

shot’s velocity in pixels/frame.

See Also: [AIship_vel], [AIshot_track]

int AIshot_dist(int)

shot’s distance from self, in pixels.

See Also: [AIship_dist], [AIradar_dist]

int AIshot_imaginary(int)

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: [AIshot_x]

int AIshot_xdir(int)

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

See Also: [AIshot_idir], [AIself_heading], [anglediff], [angleadd]

int AIshot_idir(int)

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(void) {
        if (AIshot_x(0) != -1)
                AIself_turn(anglediff(AIself_heading(), angleadd(AIshot_idir(0), 180)));
}

See Also: [AIshot_idist], [AIshot_itime], [AIself_heading], [anglediff], [angleadd]

int AIshot_idist(int)

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: [AIshot_idir], [AIshot_itime], [AIself_heading], [anglediff], [angleadd]

int AIshot_itime(int)

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

See Also: [AIshot_idir], [AIshot_idist], [AIself_heading], [anglediff], [angleadd]

int AIshot_alert(int)

A value derived from [AIshot_idist] and [AIshot_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: [AIself_reload]

7. Walls and Map

Functions to check for walls and to look at map tiles

int AI_wallbetween(int x1, int y1, int x2, int 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 = AI_wallbetween (       /
        AIself_x(),     /
        AIself_y(),             /
        AIself_x() + 200 * cos(rad(AIself_track())),    /
        AIself_y() + 200 * sin(rad(AIself_track())));

See Also: [AI_wallbetween_x], [AI_wallbetween_y]

int AI_wallbetween_x(int x1, int y1, int x2, int 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: [AI_wallbetween], [AI_wallbetween_y]

int AI_wallbetween_y(int x1, int y1, int x2, int 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: [AI_wallbetween], [AI_wallbetween_x]

unsigned int AImap_get(int mapx, int mapy) 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 (AImap_get(tomap(AIself_x()) + 1, tomap(AIself_y()) + 1) & BLUE_BIT)
        printf("To the right is a wall tile!\n");

See Also: [AImap_set], [tomap], [frmap]

Note:

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
void AImap_set(int mapx, int mapy, int 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 */

unsigned int newtile = AImap_get(tomap(AIself_x()), tomap(AIself_y()));
newtile = newtile | 0x1000;
AImap_set(tomap(AIself_x()), tomap(AIself_y()), newtile);

See Also: [AImap_get], [tomap], [frmap]

int tomap(int)

Converts a gamplay pixel value to a map value.

See Also: [AImap_get], [AImap_set], [frmap]

int frmap(int)

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

See Also: [AImap_get], [AImap_set], [tomap]

8. Messages

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

void AI_talk(String msg)

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 AI_talk is called more than once per frame, it will automatically spread sending the messages over several frames.

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

See Also: [AImsg_to], [AImsg_from], [AImsg_body]

String AImsg_to(int)

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: [AI_talk], [AImsg_from], [AImsg_body]

String AImsg_from(int)

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

See Also: [AI_talk], [AImsg_to], [AImsg_body]

String AImsg_body(int)

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*/

int i = 0;
while (AImsg_body(i) != NULL) {
        printf("s\n", AImsg_body(i));
        i++;
}

See Also: [AI_talk], [AImsg_to], [AImsg_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).

String AIself_HUD_name(int)

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

See Also: [AIself_HUD_score], [AIself_HUD_name]

float AIself_HUD_score(int) Look at a HUD slot’s score field. It is best to check for empty slots using [AIself_HUD_time] .

See Also: [AIself_HUD_time], [AIself_HUD_name]

int AIself_HUD_time(int)

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. [AIself_HUD_time] . 

/* check for and print out any names with positive points in HUD */
int i = 0;
while (AIself_HUD_time(i) != -1) {
        if (AIself_HUD_time(i) == 0 && AIself_HUD_score(i) >= 0.0)
                printf("You killed: s\n", AIself_HUD_name(i));
        i++;
}

See Also: [AIself_HUD_score], [AIself_HUD_name]

10. Math Functions

Useful math functions

int anglediff(int a1, int a2)

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

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

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

int angleadd(int a1, int a2)

Adds two angles together. 

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

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

float rad(int degree)

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

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

int deg(float radian)

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

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