<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="reference_xpai.xsl"?>

<header>
<category>
<name>General</name>
<desc>These functions allow general control of the Xpilot client</desc>
<function>
	<name>xpilot</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>char*</type>
			<name>args</name>
			<desc>a string of xpilot command-line arguments</desc>
		</var>
	</input_vars>
	<desc>Sets the arguments to use when launching xpilot.  Use prior to calling <flink>AI.xpilot.launch</flink>.</desc>
	<example>
; joins server on localhost:1338 with name "jim"

(xpilot "-name jim -join localhost -port 1338")
	</example>
	<see_also>
		<flink>AI.xpilot.launch</flink>
		<flink>AI.xpilot.setargs</flink>
	</see_also>
</function>

<function>
	<name>AI.xpilot.setargs</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>char*</type>
			<name>args</name>
			<desc>a string of xpilot command-line arguments</desc>
		</var>
	</input_vars>
	<desc>Sets the arguments to use when launching xpilot.  Use prior to calling <flink>AI.xpilot.launch</flink>.</desc>
	<example>
; joins server on localhost:1338 with name "jim"

(AI.xpilot.setargs "-name jim -join localhost -port 1338")
(AI.xpilot.launch)
	</example>
	<see_also><flink>AI.xpilot.launch</flink></see_also>
</function>

<function>
	<name>AI.xpilot.launch</name>
	<return_var>
		<type>int</type>
		<desc>1 if successful, program crashes if not</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Launches xpilot client</desc>
	<example>
; loads up xpilot with the name "jim"

(AI.xpilot.setargs "-name jim")
(AI.xpilot.launch)
	</example>
	<see_also><flink>AI.xpilot.setargs</flink></see_also>
</function>

<function>
	<name>AI.setmaxturn</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>maxturn</name>
			<desc>maximum turn degrees per frame</desc>
		</var>
	</input_vars>
	<desc>Sets the maximum turn for self in degrees per frame.</desc>
</function>


<function>
	<name>AI.teamplay?</name>
	<return_var>
		<type>int</type>
		<desc>1 if teamplay enabled, 0 if not</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Sees if teamplay is enabled.</desc>
	<see_also>
		<flink>AIself.team?</flink>
		<flink>AIship.team?</flink>	
	</see_also>
</function>

<function>
	<name>AI.pressKey</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>key</name>
			<desc>key number to press</desc>
		</var>
	</input_vars>
	<desc>Simulates a key press.  Usually <flink>AI.releaseKey</flink> must be called after to complete the key-stroke.
Below is a complete list of all the possible keys to press.
	</desc>
	<example>
;  A ship that tries to fire a laser every 
;  frame (if lasers are enabled by server  
   
(define AImain
	(lambda ()
		(AI.pressKey KEY_FIRE_LASER)
		(AI.releaseKey KEY_FIRE_LASER)))
	</example>
	<see_also>
		<flink>AI.releaseKey</flink>
	</see_also>
	<subnote>
    KEY_DUMMY,							;  0 
    KEY_LOCK_NEXT,
    KEY_LOCK_PREV,
    KEY_LOCK_CLOSE,
    KEY_CHANGE_HOME,
    KEY_SHIELD,							;  5 
    KEY_FIRE_SHOT,
    KEY_FIRE_MISSILE,
    KEY_FIRE_TORPEDO,
    KEY_TOGGLE_NUCLEAR,		
    KEY_FIRE_HEAT,						;  10 
    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,						;  20 
    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,							;  30 
    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,						;  40 
    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,					;  50 
    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,						;  60 
    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,						;  70 
    KEY_UNUSED_71,
    NUM_KEYS,
    KEY_MSG_1, ;  talk macros 
    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,
	</subnote>
</function>

<function>
	<name>AI.releaseKey</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>key</name>
			<desc>key number to release</desc>
		</var>
	</input_vars>
	<desc>Simulates a key release.  Call to release a key pressed by <flink>AI.pressKey</flink>.
See <flink>AI.pressKey</flink> for a complete list of keys.
	</desc>
	<example>
;  A ship that tries to fire a laser every
;  frame (if lasers are enabled by server  
	
(define AImain
	(lambda ()
		(AI.pressKey KEY_FIRE_LASER)
		(AI.releaseKey KEY_FIRE_LASER)))
	</example>
	<see_also>
		<flink>AI.pressKey</flink>
	</see_also>
</function>
</category>


<category>
<name>Self Control</name>
<desc>Functions to control the ship</desc>
<function>
	<name>AIself.thrust</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>thrust</name>
			<desc>1 to thrust, 0 to not thrust.</desc>
		</var>
	</input_vars>
	<desc>Controls the ship's thrust.  1 to thrust, 0 to not thrust.  Resets to not-thrust after every frame.</desc>
	<example>
;  a ship that thrusts every frame 

(define AImain
	(lambda ()
		(AIself.thrust 1)))
	</example>
	<see_also>
		<flink>AIself.turn</flink>
		<flink>AIself.shoot</flink>
		<flink>AIself.shield</flink>
	</see_also>
</function>

<function>
	<name>AIself.turn</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>turn</name>
			<desc>degrees to turn</desc>
		</var>
	</input_vars>
	<desc>Turns the ship <i>turn</i> degrees (out of 360).  Negative degrees are counter-clockwise, positive clockwise.</desc>
	<example>
; a ship that turns 15 degrees clockwise every frame

(define AImain
	(lambda ()
		(AIself.turn 15)))
	</example>
	<see_also>
		<flink>AI.setmaxturn</flink>
		<flink>AIself.thrust</flink>
		<flink>AIself.shoot</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>
		<flink>AIself.shield</flink>
	</see_also>
</function>

<function>
	<name>AIself.shoot</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>shoot</name>
			<desc>1 to shoot, 0 to not shoot.</desc>
		</var>
	</input_vars>
	<desc>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 <flink>AIself.reload?</flink> to check the number of frames remaining before it is possible to shoot again.</desc>
	<example>
;  a ship that waits until "reload" 
;  says it can shoot and then shoots 
   
(define AImain
	(lambda ()
		(if (= (AIself.reload?) 0)
			(AIself.shoot 1))))
	</example>
	<see_also>
		<flink>AIself.reload?</flink>
		<flink>AIself.turn</flink>
		<flink>AIself.thrust</flink>
		<flink>AIself.shield</flink>
	</see_also>
</function>

<function>
	<name>AIself.shield</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>shield</name>
			<desc>1 to enable, 0 to disable.</desc>
		</var>
	</input_vars>
	<desc>Turns on or off the ship's shield.  Use <flink>AIself.shield?</flink> to see the status of the shield.</desc>
	<example>
;  a ship whose shield is always on 

(define AImain
	(lambda ()
		(AIself.shield 1)))
	</example>
	<see_also>
		<flink>AIself.shield?</flink>
		<flink>AIself.turn</flink>
		<flink>AIself.thrust</flink>
		<flink>AIself.shoot</flink>
	</see_also>
</function>

<function>
	<name>AIself.destruct</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Start or stop the self-destruct sequence.</desc>
</function>
</category>


<category>
<name>Self Variables</name>
<desc>Functions that return values of variables concerning the self ship.</desc>

<function>
	<name>AIself.id?</name>
	<return_var>
		<type>int</type>
		<desc>self's id</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>The id of self's ship, according to the server.</desc>
	<see_also>
		<flink>AIship.id?</flink>
	</see_also>
</function>

<function>
	<name>AIself.alive?</name>
	<return_var>
		<type>int</type>
		<desc>1 if self is alive, else 0</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
</function>

<function>
	<name>AIself.x?</name>
	<return_var>
		<type>int</type>
		<desc>self's x position</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's x position, where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.y?</flink>
		<flink>AIship.x?</flink>
		<flink>AIradar.x?</flink>
		<flink>AIshot.x?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.y?</name>
	<return_var>
		<type>int</type>
		<desc>self's y position</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's y position, where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.x?</flink>
		<flink>AIship.y?</flink>
		<flink>AIradar.y?</flink>
		<flink>AIshot.y?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.vel?</name>
	<return_var>
		<type>int</type>
		<desc>self's velocity</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's velocity (number of pixels moved per frame).</desc>
	<see_also>
		<flink>AIself.track?</flink>
		<flink>AIship.vel?</flink>
		<flink>AIshot.vel?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.heading?</name>
	<return_var>
		<type>int</type>
		<desc>self's heading</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's heading (direction ship's nose is pointing).  0 degrees is to the right and 90 degrees is straight up.</desc>
	<see_also>
		<flink>AIself.track?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>
	</see_also>
</function>

<function>
	<name>AIself.track?</name>
	<return_var>
		<type>int</type>
		<desc>self's track</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's track (direction of movement).  0 degrees is to the right and 90 degrees is straight up.</desc>
	<see_also>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>
	</see_also>
</function>

<function>
	<name>AIself.mapx?</name>
	<return_var>
		<type>int</type>
		<desc>self's x position</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's x position on radar map, using radar map units.</desc>
	<see_also>
		<flink>AIself.mapy?</flink>
		<flink>AIself.x?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.mapy?</name>
	<return_var>
		<type>int</type>
		<desc>self's y position</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Self's y position on radar map, using radar map units.</desc>
	<see_also>
		<flink>AIself.mapx?</flink>
		<flink>AIself.y?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.team?</name>
	<return_var>
		<type>int</type>
		<desc>self's team</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<see_also>
		<flink>AI.teamplay?</flink>
		<flink>AIship.team?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.life?</name>
	<return_var>
		<type>int</type>
		<desc>number of self's remaining lives</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<see_also>
		<flink>AIship.life?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.shield?</name>
	<return_var>
		<type>int</type>
		<desc>1 if shield is on, 0 if off</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<see_also>
		<flink>AIship.shield?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.name?</name>
	<return_var>
		<type>char*</type>
		<desc>self's name</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<see_also>
		<flink>AIship.name?</flink>		
	</see_also>
</function>

<function>
	<name>AIself.score?</name>
	<return_var>
		<type>float</type>
		<desc>self's total point score</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<see_also>
		<flink>AIself.HUD.score</flink>		
	</see_also>
</function>

<function>
	<name>AIself.reload?</name>
	<return_var>
		<type>int</type>
		<desc>remaining reload time</desc>
	</return_var>
	<input_vars>
		<var>
			<type>void</type>
		</var>
	</input_vars>
	<desc>Number of frames remaining before self is able to shoot.  When 0, self is able to shoot.</desc>
	<see_also>
		<flink>AIship.reload?</flink>		
	</see_also>
</function>

</category>



<category>
<name>Ships</name>
<desc>Functions returning information about other ships on screen.  The ships are sorted from nearest to furthest.</desc>

<function>
	<name>AIship.x?</name>
	<return_var>
		<type>int</type>
		<desc>ship's x position, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Ship's x position, where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.x?</flink>
		<flink>AIship.y?</flink>
		<flink>AIradar.x?</flink>
		<flink>AIshot.x?</flink>		
	</see_also>
</function>

<function>
	<name>AIship.y?</name>
	<return_var>
		<type>int</type>
		<desc>ship's y position, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Ship's y position, where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.y?</flink>
		<flink>AIship.x?</flink>
		<flink>AIradar.y?</flink>
		<flink>AIshot.y?</flink>		
	</see_also>
</function>

<function>
	<name>AIship.heading?</name>
	<return_var>
		<type>int</type>
		<desc>ship's heading, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Ship's heading (angle nose is pointing).  0 degrees is to the right, and 90 straight up.</desc>
	<see_also>
		<flink>AIship.track?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIship.track?</name>
	<return_var>
		<type>int</type>
		<desc>ship's track, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Ship's track (direction of velocity).  0 degrees is to the right, and 90 straight up.</desc>
	<see_also>
		<flink>AIship.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIship.vel?</name>
	<return_var>
		<type>int</type>
		<desc>ship's velocity, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Ship's velocity in pixels/frame.</desc>
	<see_also>
		<flink>AIself.vel?</flink>
		<flink>AIshot.vel?</flink>
	</see_also>
</function>

<function>
	<name>AIship.dist?</name>
	<return_var>
		<type>int</type>
		<desc>ship's distance from self, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Ship's distance from self, in pixels.</desc>
	<see_also>
		<flink>AIradar.dist?</flink>
		<flink>AIshot.dist?</flink>
	</see_also>
</function>

<function>
	<name>AIship.id?</name>
	<return_var>
		<type>int</type>
		<desc>id of ship, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>server assigned id of ship</desc>
	<see_also>
		<flink>AIself.id?</flink>
	</see_also>
</function>

<function>
	<name>AIship.xdir?</name>
	<return_var>
		<type>int</type>
		<desc>ship's xdir, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Direction of ship from self.  0 degrees is to the right and 90 upright.</desc>
	<example>
;  Self always points at nearest on screen ship 
(define AImain
	(lambda ()
		(if (not (= (AIship.x? 0) -1))
			(AIself.turn (anglediff (AIself.heading?) (AIship.xdir? 0))))))
	</example>
	<see_also>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
		<flink>AIradar.xdir?</flink>
	</see_also>
</function>

<function>
	<name>AIship.shield?</name>
	<return_var>
		<type>int</type>
		<desc>1 if ship's shield is on, 0 if not, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<see_also>
		<flink>AIself.shield</flink>
	</see_also>
</function>

<function>
	<name>AIship.life?</name>
	<return_var>
		<type>int</type>
		<desc>number of lives remaining for ship, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<see_also>
		<flink>AIself.life?</flink>
	</see_also>
</function>

<function>
	<name>AIship.team?</name>
	<return_var>
		<type>int</type>
		<desc>team of ship, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<see_also>
		<flink>AIself.team?</flink>
	</see_also>
</function>

<function>
	<name>AIship.reload?</name>
	<return_var>
		<type>int</type>
		<desc>reload time of ship, or -1 if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<see_also>
		<flink>AIself.reload?</flink>
	</see_also>
</function>

<function>
	<name>AIship.name?</name>
	<return_var>
		<type>char*</type>
		<desc>name of ship, or NULL if ship not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<see_also>
		<flink>AIself.name?</flink>
	</see_also>
</function>

<function>
	<name>AIship.aimdir?</name>
	<return_var>
		<type>int</type>
		<desc>aimdir</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<example>
;  bot that aims and shoots at nearest ship 

(define AImain
	(lambda ()
		(if (not (= (AIship.x? 0) -1))
			(AIself.turn (anglediff (AIself.heading?) (AIship.aimdir? 0)))
			(AIself.shoot 1))))
	</example>
	<see_also>
		<flink>AIship.xdir?</flink>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>	
	</see_also>
</function>

</category>



<category>
<name>Radar</name>
<desc>Functions returning information about other ships on the radar.  The ships are sorted from nearest to furthest.</desc>

<function>
	<name>AIradar.x?</name>
	<return_var>
		<type>int</type>
		<desc>ship's x position, or -1 if no more ships on radar.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on radar, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Radar ship's x position (approximate), where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.x?</flink>
		<flink>AIship.x?</flink>
		<flink>AIradar.y?</flink>
		<flink>AIshot.x?</flink>		
	</see_also>
</function>

<function>
	<name>AIradar.y?</name>
	<return_var>
		<type>int</type>
		<desc>ship's y position, or -1 if no more ships on radar.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on radar, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Radar ship's y position (approximate), where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.y?</flink>
		<flink>AIship.y?</flink>
		<flink>AIradar.x?</flink>
		<flink>AIshot.y?</flink>		
	</see_also>
</function>

<function>
	<name>AIradar.dist?</name>
	<return_var>
		<type>int</type>
		<desc>ship's distance from self, or -1 if no more ships on radar.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on radar, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Radar ship's distance from self, in pixels (approximate).</desc>
	<see_also>
		<flink>AIship.dist?</flink>
		<flink>AIshot.dist?</flink>
	</see_also>
</function>


<function>
	<name>AIradar.xdir?</name>
	<return_var>
		<type>int</type>
		<desc>ship's xdir, or -1 if no more ships on radar.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on radar, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Direction of radar ship from self.  0 degrees is to the right and 90 upright.</desc>
	<example>
;  self always points at second-nearest radar ship 
(define AImain
	(lambda ()
		(if (not (= (AIradar.x? 1) -1))
			(AIself.turn (anglediff (AIself.heading?) (AIradar.xdir? 1))))))
	</example>
	<see_also>
		<flink>AIself.heading?</flink>
		<flink>AIship.xdir?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIradar.enemy?</name>
	<return_var>
		<type>int</type>
		<desc>1 if enemy, 0 if friend, or -1 if no more ships on radar.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which ship on radar, sorted near to far</desc>
		</var>
	</input_vars>
	<see_also>
		<flink>AIship.team?</flink>
	</see_also>
</function>

</category>




<category>
<name>Shots</name>
<desc>Functions returning information about the shots on screen.</desc>

<function>
	<name>AIshot.x?</name>
	<return_var>
		<type>int</type>
		<desc>shot's x position, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>shot's x position, where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.x?</flink>
		<flink>AIshot.y?</flink>
	</see_also>
</function>

<function>
	<name>AIshot.y?</name>
	<return_var>
		<type>int</type>
		<desc>shot's y position, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>shot's y position, where bottom left of map is [0, 0].</desc>
	<see_also>
		<flink>AIself.y?</flink>
		<flink>AIshot.x?</flink>
	</see_also>
</function>

<function>
	<name>AIshot.track?</name>
	<return_var>
		<type>int</type>
		<desc>shot's track, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>shot's track (direction of velocity).  0 degrees is to the right, and 90 straight up.</desc>
	<see_also>
		<flink>AIshot.vel?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIshot.vel?</name>
	<return_var>
		<type>int</type>
		<desc>shot's velocity, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>shot's velocity in pixels/frame.</desc>
	<see_also>
		<flink>AIship.vel?</flink>
		<flink>AIshot.track?</flink>
	</see_also>
</function>

<function>
	<name>AIshot.dist?</name>
	<return_var>
		<type>int</type>
		<desc>shot's distance from self, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>shot's distance from self, in pixels.</desc>
	<see_also>
		<flink>AIship.dist?</flink>
		<flink>AIradar.dist?</flink>
	</see_also>
</function>

<function>
	<name>AIshot.imaginary?</name>
	<return_var>
		<type>int</type>
		<desc>1 if shot imaginary, 0 if not, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Imaginary shots are calculated for every ship on screen.  If a ship were to shoot this frame, imaginary bullets tell that shots attributes.</desc>
	<see_also>
		<flink>AIshot.x?</flink>
	</see_also>
</function>

<function>
	<name>AIshot.xdir?</name>
	<return_var>
		<type>int</type>
		<desc>shot's xdir, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Direction of shot from self.  0 degrees is to the right and 90 upright.</desc>
	<see_also>
		<flink>AIshot.idir?</flink>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIshot.idir?</name>
	<return_var>
		<type>int</type>
		<desc>shot's intercept dir, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<example>
; self turns away from intercept dir and thrusts

(define AImain
	(lambda ()
		(if (not (= (AIshot.x? 0) -1))
			(AIself.turn (anglediff (AIself.heading?) (angleadd (AIshot.idir? 0) 180))))))
	</example>
	<see_also>
		<flink>AIshot.idist?</flink>
		<flink>AIshot.itime?</flink>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIshot.idist?</name>
	<return_var>
		<type>int</type>
		<desc>shot's intercept distance, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Distance to the location where the shot will be nearest to self, if both self velocity and bullet velocity remain constant, in pixels.</desc>
	<see_also>
		<flink>AIshot.idir?</flink>
		<flink>AIshot.itime?</flink>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIshot.itime?</name>
	<return_var>
		<type>int</type>
		<desc>shot's time to intercept, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>Number of frames until the nearest intercept will occur, if both self velocity and bullet velocity remain constant.</desc>
	<see_also>
		<flink>AIshot.idir?</flink>
		<flink>AIshot.idist?</flink>
		<flink>AIself.heading?</flink>
		<flink>anglediff</flink>
		<flink>angleadd</flink>		
	</see_also>
</function>

<function>
	<name>AIshot.alert?</name>
	<return_var>
		<type>int</type>
		<desc>alert value of shot, or -1 if shot not on screen.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which shot on screen, sorted near to far</desc>
		</var>
	</input_vars>
	<desc>A value derived from <flink>AIshot.idist?</flink> and <flink>AIshot.itime?</flink>.  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.</desc>
	<see_also>
		<flink>AIself.reload?</flink>
	</see_also>
</function>
</category>


<category>
<name>Walls and Map</name>
<desc>Functions to check for walls and to look at map tiles</desc>

<function>
	<name>AI.wallbetween</name>
	<return_var>
		<type>int</type>
		<desc>distance to nearest wall between [x1, y1] and [x2, y2].  Or -1 if no wall.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>x1</name>
			<desc>x coordinate of first point</desc>
		</var>
		<var>
			<type>int</type>
			<name>y1</name>
			<desc>y coordinate of first point</desc>
		</var>
		<var>
			<type>int</type>
			<name>x2</name>
			<desc>x coordinate of second point</desc>
		</var>			
		<var>
			<type>int</type>
			<name>y2</name>
			<desc>y coordinate of second point</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<example>
;  this checks for a wall 200 pixels
;   in front of the ships track 

(define wall_N 
	(lambda ()
		(AI.wallbetween
			(AIself.x?)
			(AIself.y?)
			(+ 	(AIself.x?)
				(* 200 (cos (rad (AIself.track?)))))
			(+	(AIself.y?)
				(* 200 (sin (rad (AIself.track?))))))))
	</example>	
	<see_also>
		<flink>AI.wallbetween.x</flink>
		<flink>AI.wallbetween.y</flink>
	</see_also>
</function>

<function>
	<name>AI.wallbetween.x</name>
	<return_var>
		<type>int</type>
		<desc>x coordinate of nearest wall between [x1, y1] and [x2, y2].  Or -1 if no wall.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>x1</name>
			<desc>x coordinate of first point</desc>
		</var>
		<var>
			<type>int</type>
			<name>y1</name>
			<desc>y coordinate of first point</desc>
		</var>
		<var>
			<type>int</type>
			<name>x2</name>
			<desc>x coordinate of second point</desc>
		</var>			
		<var>
			<type>int</type>
			<name>y2</name>
			<desc>y coordinate of second point</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<see_also>
		<flink>AI.wallbetween</flink>
		<flink>AI.wallbetween.y</flink>
	</see_also>
</function>

<function>
	<name>AI.wallbetween.y</name>
	<return_var>
		<type>int</type>
		<desc>y coordinate of nearest wall between [x1, y1] and [x2, y2].  Or -1 if no wall.</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>x1</name>
			<desc>x coordinate of first point</desc>
		</var>
		<var>
			<type>int</type>
			<name>y1</name>
			<desc>y coordinate of first point</desc>
		</var>
		<var>
			<type>int</type>
			<name>x2</name>
			<desc>x coordinate of second point</desc>
		</var>			
		<var>
			<type>int</type>
			<name>y2</name>
			<desc>y coordinate of second point</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<see_also>
		<flink>AI.wallbetween</flink>
		<flink>AI.wallbetween.x</flink>
	</see_also>
</function>


<function>
	<name>AImap?</name>
	<return_var>
		<type>unsigned int</type>
		<desc>bit flags for tile at (mapx, mapy)</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>mapx</name>
			<desc>mapx coordinate</desc>
		</var>
		<var>
			<type>int</type>
			<name>mapy</name>
			<desc>mapy coordinate</desc>
		</var>
	</input_vars>
	<desc>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 <flink>tomap</flink> and <flink>frmap</flink>.</desc>
	<example>
;  checks to see if the map tile to the immediate
;  right of the player contains a wall of some sort 

(if (bitwise-and (AImap? (+ (tomap (AIself.x?)) 1) (+ (tomap (AIself.y?)) + 1)) BLUE_BIT)
	printf("To the right is a wall tile!\n"); 
	</example>
	<see_also>
		<flink>AImap.set</flink>
		<flink>tomap</flink>
		<flink>frmap</flink>
	</see_also>
	<subnote>
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
	</subnote>
</function>

<function>
	<name>AImap.set</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>mapx</name>
			<desc>mapx coordinate</desc>
		</var>
		<var>
			<type>int</type>
			<name>mapy</name>
			<desc>mapy coordinate</desc>
		</var>
		<var>
			<type>unsigned int</type>
			<name>value</name>
			<desc>new map tile value</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<example>
;  Sets a bit flag on the map tile underneath self 

(let ((newtile (AImap? (tomap (AIself.x?)) (tomap (AIself.y?)))))
	(set! newtile (bitwise-ior newtile 0x1000))
	(AImap.set (tomap (AIself.x?)) (tomap (AIself.y?)) newtile))
	</example>
	<see_also>
		<flink>AImap?</flink>
		<flink>tomap</flink>
		<flink>frmap</flink>
	</see_also>
</function>

<function>
	<name>tomap</name>
	<return_var>
		<type>int</type>
		<desc>map tile</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>n</name>
			<desc>game pixel value</desc>
		</var>
	</input_vars>
	<desc>Converts a gamplay pixel value to a map value.</desc>
	<see_also>
		<flink>AImap?</flink>
		<flink>AImap.set</flink>
		<flink>frmap</flink>
	</see_also>
</function>

<function>
	<name>frmap</name>
	<return_var>
		<type>int</type>
		<desc>game pixel</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>mapn</name>
			<desc>map value</desc>
		</var>
	</input_vars>
	<desc>Takes a map value and returns the middle of that map tile, in pixels.</desc>
	<see_also>
		<flink>AImap?</flink>
		<flink>AImap.set</flink>
		<flink>tomap</flink>
	</see_also>
</function>
</category>

<category>
<name>Messages</name>
<desc>Write and recieve messages using the player-to-player messaging system in Xpilot</desc>

<function>
	<name>AI.talk</name>
	<return_var>
		<type>void</type>
	</return_var>
	<input_vars>
		<var>
			<type>char*</type>
			<name>message</name>
		</var>
	</input_vars>
	<desc>Say a message through the player-to-player talk system in Xpilot.</desc>
	<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.</note>
	<example>
;  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")
	</example>
	<see_also>
		<flink>AI.msg.to?</flink>
		<flink>AI.msg.from?</flink>
		<flink>AImsg.body</flink>
	</see_also>
</function>

<function>
	<name>AI.msg.to?</name>
	<return_var>
		<type>char*</type>
		<desc>player's name, or NULL if a public message or no more messages</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which message out of all recieved in frame</desc>
		</var>
	</input_vars>
	<desc>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.</desc>
	<see_also>
		<flink>AI.talk</flink>
		<flink>AI.msg.from?</flink>
		<flink>AImsg.body</flink>
	</see_also>
</function>

<function>
	<name>AI.msg.from?</name>
	<return_var>
		<type>char*</type>
		<desc>player's name, or NULL if no more messages</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which message out of all recieved in frame</desc>
		</var>
	</input_vars>
	<desc>Look at a message's "from" field from the player-to-player messaging system.  Returns NULL if there are no messages.</desc>
	<see_also>
		<flink>AI.talk</flink>
		<flink>AI.msg.to?</flink>
		<flink>AImsg.body</flink>
	</see_also>
</function>


<function>
	<name>AImsg.body</name>
	<return_var>
		<type>char*</type>
		<desc>body of message, or NULL if no messages</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>which message out of all recieved in frame</desc>
		</var>
	</input_vars>
	<desc>Look at a message's "body" field from the player-to-player messaging system.  Returns NULL if there are no messages.</desc>
	<example>
;  cycles through all the messages recieved
;  every frame and prints the body
(define print-bodies
	(lambda (n)
		(if (not (= 0 (AImsg.body n)))
			(begin 
				(print (AImsg.body n))
				(print-bodies (add1 n))))))

; then call (print-bodies 0) in AImain
	</example>
	<see_also>
		<flink>AI.talk</flink>
		<flink>AI.msg.to?</flink>
		<flink>AI.msg.from?</flink>
	</see_also>
</function>

</category>



<category>
<name>HUD</name>
<desc>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).</desc>

<function>
	<name>AIself.HUD.name</name>
	<return_var>
		<type>char*</type>
		<desc>name on HUD slot, or NULL if no more messages</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>HUD slot</desc>
		</var>
	</input_vars>
	<desc>Look at a HUD slot's name field.  Returns "" if there is no name in that slot.</desc>
	<see_also>
		<flink>AIself.HUD.score</flink>
		<flink>AIself.HUD.name</flink>
	</see_also>
</function>

<function>
	<name>AIself.HUD.score</name>
	<return_var>
		<type>float</type>
		<desc>score on HUD slot, or -99999.0 if empty</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>HUD slot</desc>
		</var>
	</input_vars>
	<desc>Look at a HUD slot's score field.  It is best to check for empty slots using <flink>AIself.HUD.time</flink>.</desc>
	<see_also>
		<flink>AIself.HUD.time</flink>
		<flink>AIself.HUD.name</flink>
	</see_also>
</function>

<function>
	<name>AIself.HUD.time</name>
	<return_var>
		<type>int</type>
		<desc>time of HUD slot, or -1 if slot is empty</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>which</name>
			<desc>HUD slot</desc>
		</var>
	</input_vars>
	<desc>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.<flink>AIself.HUD.time</flink>.</desc>
	<example>
;  check for and print out any names with positive points in HUD 
(define HUD-positive
	(lambda (n)
		(if (not (= (AIself.HUD.time n) -1))
			(begin
				(if (and (= (AIself.HUD.time n) 0) (>= (AIself.HUD.score n) 0.0))
					(print "You killed: " (AIself.HUD.name n)))
				(HUD-positive (add1 n))))))

; then call (HUD-positive 0) in AImain
	</example>
	<see_also>
		<flink>AIself.HUD.score</flink>
		<flink>AIself.HUD.name</flink>
	</see_also>
</function>
</category>




<category>
<name>Math Functions</name>
<desc>Useful math functions</desc>

<function>
	<name>anglediff</name>
	<return_var>
		<type>int</type>
		<desc>difference between angles</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>angle1</name>
			<desc>first angle</desc>
		</var>
		<var>
			<type>int</type>
			<name>angle2</name>
			<desc>second angle</desc>
		</var>	
	</input_vars>
	<desc>Returns the smallest angle which angle1 could add to itself to be equal to angle2.  This is useful for turning particular directions.</desc>
	<example>
	(anglediff 90 70) = -20
	(anglediff 350 10) = 20
	</example>
	<see_also>
		<flink>angleadd</flink>
		<flink>rad</flink>
		<flink>deg</flink>
	</see_also>
</function>

<function>
	<name>angleadd</name>
	<return_var>
		<type>int</type>
		<desc>addition of two angles</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>angle1</name>
			<desc>first angle</desc>
		</var>
		<var>
			<type>int</type>
			<name>angle2</name>
			<desc>second angle</desc>
		</var>	
	</input_vars>
	<desc>Adds two angles together.</desc>
	<example>
	(angleadd 90 70) = 160
	(angleadd 350 40) = 30
	</example>
	<see_also>
		<flink>angleadd</flink>
		<flink>rad</flink>
		<flink>deg</flink>
	</see_also>
</function>

<function>
	<name>rad</name>
	<return_var>
		<type>float</type>
		<desc>radians</desc>
	</return_var>
	<input_vars>
		<var>
			<type>int</type>
			<name>deg</name>
			<desc>angle in degrees</desc>
		</var>
	</input_vars>
	<desc>Converts a degree angle to radian, which is used in sin, cos, and tan.</desc>
	<see_also>
		<flink>deg</flink>
		<flink>angleadd</flink>
		<flink>anglediff</flink>
	</see_also>
</function>

<function>
	<name>deg</name>
	<return_var>
		<type>float</type>
		<desc>degrees</desc>
	</return_var>
	<input_vars>
		<var>
			<type>float</type>
			<name>rad</name>
			<desc>angle in radians</desc>
		</var>
	</input_vars>
	<desc>Converts a radian angle to degree, which is used in gameplay.</desc>
	<see_also>
		<flink>rad</flink>
		<flink>angleadd</flink>
		<flink>anglediff</flink>
	</see_also>
</function>
</category>
</header>


