Xpilot-AI Java Reference

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.

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);
}

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);
}

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);
}

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);
}

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.

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

int AIship_y(int): Ship’s y position, where bottom left of map is [0, 0].

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

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

int AIship_vel(int): Ship’s velocity in pixels/frame.

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

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

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

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

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())));

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.

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.

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");

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");

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.

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.

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

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++;
}

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