Xpilot-AI Scheme Reference for Chicken Scheme 4

The newest version of the Xpilot-AI bindings for Chicken Scheme has marked differences from the previous version. Code using the old API will have to be changed to fit the new version. This API change was done to make Xpilot-AI more comfortable to work with in a scheme environment.

1. General Functions

These functions allow general control of the Xpilot client application.

function (xpilot . args) → #<void>: Launches the xpilot client with the specified command line arguments. Takes any number and type of arguments and concatenates the result to form a single argument string. Arguments are separated by a space.

; Parses the command line arguments to join the desired server
(xpilot "-join" (car   (command-line-arguments))
        "-port" (cadr  (command-line-arguments))
        "-name" (caddr (command-line-arguments)))

function (xpilot-bg . args) → #<thread>: Analogous to xpilot, with the exception that the xpilot-process in launched in a background thread, allowing the user to enter commands at the repl.

#;1> (xpilot-bg "-join localhost -name Bill")
#<thread>
#;2> (x-pos)
82

2. Self Control

Functions to control the ship and perform various actions.

function (thrust #!optional bool) → #<void>: Controls the ship’s thrust. When bool has a value of #f, the thrust is inhibited. If bool is true, or the function is called with no arguments, the ship thrusts.

;; a ship that thrusts every frame
(define (AI-main)
  (thrust))
;; Or, more tersely,
(define AI-main thrust)

3. Game state access

Functions that retrieve the values of variables concerning all ships. In general, these functions take any number of arguments. If no arguments are supplied, they return the value corresponding to self’s ship. If n index values are supplied, n values are returned, each corresponding to the respective value of the ship at each index. Note that some values do not apply to both self’s ship and other ships: the argument lists change accordingly.

Other ships are indexed by their position on the screen. The closest ship will always be denoted by index 0, the second closest will be denoted by index 1, and so on.

3.1 Functions for accessing self or ship state

function (id . ships) → id1 id2 …: Retreive the unique id of a ship, according to the server. This id will not change even if a ship changes its nickname. If no arguments are supplied, self’s id is returned. For each index given as an argument, id will return the server identification number of the ship at the index, or #f if the ship is not on screen.

;; Get self's id
#;1> (id)
3
;; Get closest ship's id
#;2> (id 0)
7

function (alive?) → #t or #f: Returns #t if self is alive. Otherwise returns #f.
function (x-pos . ships) → x1 x2 …: Ships' x positions, where bottom left of map is (0, 0). If no arguments are supplied, self’s x position is returned. If the ship is not on screen, the return value is #f.

3.2 Functions for accessing self state only

function (score) → score …: Return self’s score as shown on the ranking list.

3.3 Functions for accessing other ships' state

function (on-screen? ship1 . ships) → bool1 bool2 …: Returns #t if ship is on-screen, #f otherwise.

4. Radar

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

function (radar-x ship1 . ships) → x1 x2 …: Return ships' approximate x positions on radar, or #f if ship is not on radar. Ships are sorted from nearest to farthest.

5. Shots

Functions returning information about the shots on the screen.

function (shot-x shot1 . shots) → x1 x2 …: Shots' x positions, or #f if shot is not on screen.

6. Walls and Map

Functions to check for walls and to look at map tiles

function (wall-between x1 y1 #!optional x2 y2) → bool, x, y: This function checks for walls in a straight line starting from point (x1, y1) and ending at point (x2, y2). If it finds a wall, it returns the distance in pixels from (x1, y1) to that point, and the x and y position of the point as secondary values. Otherwise, it returns #f. If x2 and y2 are not supplied, then wall-between looks for a wall between self’s position and x1, y1.

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

(define (wall-ahead)
  (wall-between
   (+ (x-pos)
      (* 200 (cos (deg->rad (track)))))
   (+ (y-pos)
      (* 200 (sin (deg->rad (track)))))))

;; Display position of wall ahead of track
(use srfi-11) ; for let-values

(let-values ((wall x y) (wall-ahead))
  (when wall
        (printf "Wall ~A px ahead at (~A,~A)"
                 x y)))

function (tile #!optional x y) → 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. This function returns the value stored in the tile containing the point (x, y). If x and y are not supplied, self’s position is used.

;; checks to see if the map tile to the right of the player
;; contains a wall of some sort
(when (positive?
       (bitwise-and (tile (+ (pos-x) 20) (pos-y))
                    BLUE_BIT))
      (print "To the right is a wall tile!"))

Here is a list of tile types.

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

7. Messages

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

function (talk . messages) → #<void> Say a message through the player-to-player talk system in Xpilot. Arguments may be of any type, and are concatenated together to form a string.

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

;; Writes a message to everyone
(talk "Hello everyone!")

;; Writes a private message to "Jimmy"
(talk "Jimmy: hello I'm at" (pos))

;; Change to team of closest ship
(when (on-screen? 0)
      (talk "/team" (team 0)))

function (msg-to index1 . idx) → m1 m2…: Look at a private message’s "to" field from the player-to-player messaging system. Returns #f if there is no "to" field either because there is no message or it is a public message.

8. 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).

function (HUD-name index1 . idx) → n1 n2…: Look at a HUD slot’s name field. Returns #f if there is no name in that slot.
function (HUD-score index1 . idx) → s1 s2…: Look at a HUD slot’s score field. It is best to check for empty slots using [AIself.HUD.time?] . Returns #f if slot does not exist.
function (HUD-time index1 . idx) → t1 t2…: 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.

(use srfi-1)

;; Return a list of all HUD messages
(define (HUD-list field)
  (unfold HUD-time field add1 0))

;; Return a list of HUD messages with positive scores
(define (HUD-gains)
  (filter positive?
          (HUD-list HUD-score)))

9. Arithmetic functions

Useful math functions

function (anglediff a1 a2) → a: Returns the smallest angle which angle1 could add to itself to be equal to angle2. This is useful for turning particular directions.

#;1> (anglediff 90 70)
-20
#;2> (anglediff 350 10)
20