1. General Functions

These functions allow general control of the Xpilot client

AI_xpilot_setargs(char *args) → void

Sets the arguments to use when launching xpilot. Use prior to calling AI_xpilot_launch() 

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

AI_xpilot_setargs("-name jim -join localhost -port 1338");
AI_xpilot_launch();

See also: [AI_xpilot_launch]

AI_xpilot_launch(void) → int success

Launches xpilot client 

/*loads up xpilot with the name "jim"*/

AI_xpilot_setargs("-name jim");
AI_xpilot_launch();

See also: [AI_xpilot_setargs]

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.

AIself_thrust(int thrust) → void

Controls the ship’s thrust. 1 to thrust, 0 to not thrust. AIself_thrust() will only thrust for one frame; you must call it every frame for continuous thrusting. 

/* a ship that thrusts every frame */

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

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

AIself_turn(int deg) → void

Turns the ship deg 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]

AIself_shoot(int shoot) → void

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) {
        AIself_shoot(AIself_reload() == 0);
}

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

AIself_shield_enable(int shield) → void

Turns the ship’s shield on or off. Use [AIself_shield] to see the status of the shield. Some maps do not allow ships to use shields. 

/* a ship whose shield is always on */
void AImain(void) {
        AIself_shield_enable(1);
}

See also: [AIself_shield] [AIself_turn] [AIself_thrust] [AIself_shoot]

AIself_destruct(void) → void

Start or stop the self-destruct sequence.

3. Self state

Functions that return values of variables concerning the self ship.

AIself_id(void) → int id

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

See also: [AIship_id]

AIself_alive(void) → int

Return 1 if alive, 0 if not.

AIself_x(void) → int

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

AIself_y(void) → int

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

See also: [AIself_x], [AIship_y], [AIradar_y], [AIshot_y], [AIself_vel]

AIself_vel(void) → int

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

See also: [AIself_track], [AIship_vel], [AIshot_vel], [AIself_heading]

AIself_heading(void) → int

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]

AIself_track(void) → int

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

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

AIself_mapx(void) → int

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

See also: [AIself_mapy], [AIself_x]

AIself_mapy(void) → int

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

See also: [AIself_mapx], [AIself_y]

AIself_team(void) → int

Self’s team number on the server.

See also: [AI_teamplay], [AIship_team]

AIself_life(void) → int

Number of remaining lives.

See also: [AIship_life]

AIself_shield(void) → int

1 if shield is on, 0 if off

See also: [AIship_shield]

AIself_name(void) → char *

Self’s name. This string is used internally by Xpilot-AI and should only be read.

See also: [AIship_name]

AIself_score(void) → float

Self’s total score on the server, as displayed in the rankings.

See also: [AIself_HUD_score]

AIself_reload(void) → int

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

See also: AIship_reload

4. Ship State

Functions returning information about other ships on screen. The ships are sorted from nearest to furthest and addressed with integers. Passing these functions an argument of 0 will always give information on the closest ship, if it exists.

AIship_x(int idx) → int

Ship’s x position, where bottom left of map is [0, 0]. -1 if the ship does not exist.

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

AIship_y(int idx) → int

Ship’s y position, where bottom left of map is [0, 0]. -1 if the ship does not exist.

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

AIship_heading(int idx) → int

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

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

AIship_track(int idx) → int

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

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

AIship_vel(int idx) → int

Ship’s velocity in pixels/frame.

See also:[AIself_vel], [AIshot_vel]

AIship_dist(int idx) → int

Ship’s distance from self, in pixels. See also:[AIradar_dist], [AIshot_dist]

AIship_id(int idx) → int

Server assigned id of ship See also:[AIself_id]

AIship_xdir(int idx) → 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]

AIship_shield(int idx) → int

1 if ship’s shield is on, 0 if not, or -1 if ship not on screen. See also:[AIself_shield]

AIship_life(int idx) → int

number of lives remaining for ship, or -1 if ship not on screen. See also:[AIself_life]

AIship_team(int idx) → int

Team of ship, or -1 if ship not on screen See also:[AIself_team]

AIship_reload(int idx) → 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]

AIship_name(int idx) → char *

Name of ship, or NULL if not on screen See also:[AIself_name]

AIship_aimdir(int idx) → 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]

4. Radar

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

AIradar_x(int idx) → 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]

AIradar_y(int idx) → 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]

AIradar_dist(int idx) → int

Radar ship’s distance from self, in pixels (approximate). See also:[AIship_dist], [AIshot_dist]

AIradar_xdir(int idx) → int

Direction of radar ship from self. 0 degrees is to the right and 90 upright. See also:[AIself_heading], [AIship_xdir], [anglediff], [angleadd]

AIradar_enemy(int idx) → int

See also: AIship_team

AIshot_x(int idx) → int

shot’s x position, where bottom left of map is [0, 0]. See also:[AIself_x], [AIshot_y]

AIshot_y(int idx) → int

shot’s y position, where bottom left of map is [0, 0]. See also:[AIself_y], [AIshot_x]

AIshot_track(int idx) → int

shot’s track (direction of velocity). 0 degrees is to the right, and 90 straight up. See also:[AIshot_vel], [anglediff], [angleadd]

AIshot_vel(int idx) → int

shot’s velocity in pixels/frame. See also:[AIship_vel], [AIshot_track]

AIshot_dist(int idx) → int

shot’s distance from self, in pixels. See also:[AIship_dist], [AIradar_dist]

AIshot_imaginary(int idx) → 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]

AIshot_xdir(int idx) → int

Direction of shot from self. 0 degrees is to the right and 90 upright. See also:[AIshot_idir], [AIself_heading], [anglediff], [angleadd]

AIshot_idir(int idx) → 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. See also:[AIshot_idist], [AIshot_itime], [AIself_heading], [anglediff], [angleadd]

AIshot_idist(int idx) → 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]

AIshot_itime(int idx) → 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]

AIshot_alert(int idx) → 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]

5. Walls and Map

Functions to check for walls and to look at map tiles

AI_wallbetween(int x1, int y1, int x2, int y2) → int

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]

AI_wallbetween_x(int x1, int y1, int x2, int y2) → int

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]

AI_wallbetween_y(int x1, int y1, int x2, int y2) → int

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]

AImap_get(int mapx, int mapy) → unsigned int

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
AImap_set(int mapx, int mapy, unsigned int value) → void

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]

tomap(int x) → int

Converts a gamplay pixel value to a map value. See also:[AImap_get], [AImap_set], [frmap]

frmap(mapn) → int

Takes a map value and returns the middle of that map tile, in pixels. See also:[AImap_get], [AImap_set], [tomap]

5. Messages

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

AI_talk(char *msg) → void

Say a message through the xpilot chat system. 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]

AImsg_to(int idx) → char *

Look at a private message’s "to" field from the player-to-player messaging system. Returns "" 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]

AImsg_from(int idx) → char *

Look at a message’s "from" field from the player-to-player messaging system. Returns empty string if there are no messages. See also:[AI_talk], [AImsg_to], [AImsg_body]

AImsg_body(int idx) → char *

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

/* cycles through all the messages recieved
   every frame and prints the body*/

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

See also:[AI_talk], [AImsg_to], [AImsg_from]

7. 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 and crashes).

AIself_HUD_name(int idx) → char *

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]

AIself_HUD_score(int idx) → float

Look at a HUD slot’s score field. Returns -99999.0 if slot does not exists. It is best to check for empty slots using AIself_HUD_time. See also:[AIself_HUD_time], [AIself_HUD_name]

AIself_HUD_time(int idx) → 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]

8. Math Functions

Useful math functions

anglediff(int a1, int a2) → int

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]

angleadd(int a1, int a2) → int

Adds two angles together. 

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

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

rad(int degree) → float

Converts a degree angle to radian, which is used in sin, cos, and tan. See also:[deg], [angleadd], [anglediff]

deg(float radian) → int

Converts a radian angle to degree, which is used in gameplay. See also:[rad], [angleadd], [anglediff]