<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="Lua.xsl"?>
<!DOCTYPE document [
          <!ELEMENT document (section*,triggers,tables,types,section*)>
          <!ATTLIST document title CDATA #REQUIRED>
	  
          <!ELEMENT triggers (description?,(function*))>
          <!ATTLIST triggers id ID #REQUIRED>
          <!ELEMENT tables (description*,(table|accessor|enum|enum-accessor)*)>
          <!ATTLIST tables id ID #REQUIRED>
          <!ELEMENT types (description*)>
          <!ATTLIST types id ID #REQUIRED>

          <!ELEMENT section (description?,(section*))>
          <!ATTLIST section name CDATA #REQUIRED>
          <!ATTLIST section id ID #REQUIRED>
          
          <!ELEMENT table ((description?),(function|function-variable|subtable|subtable-accessor|variable)*)>
          <!ATTLIST table name ID #REQUIRED>
          <!ATTLIST table singleton (true|false) 'false'>

          <!ELEMENT subtable ((alias*),(description?),(length?),(index?),(call?),(function|subtable|variable|note)*)>
          <!ATTLIST subtable name CDATA #REQUIRED>
          <!ATTLIST subtable classname ID #REQUIRED>

          <!ELEMENT subtable-accessor ((alias?),(description?),(function|subtable|variable)*)>
          <!ATTLIST subtable-accessor name CDATA #REQUIRED>
          <!ATTLIST subtable-accessor classname ID #REQUIRED>
          <!ATTLIST subtable-accessor index CDATA #REQUIRED>

          <!ELEMENT description ANY>
          <!ELEMENT br EMPTY>
          <!ELEMENT p ANY>
          <!ELEMENT pre ANY>

          <!ELEMENT function ((description?),(argument*),(return*),(note*))>
          <!ATTLIST function name CDATA #REQUIRED>
          <!ATTLIST function access (local-player|all) 'all'>
          <!ATTLIST function return (single|variant) 'single'>
	  <!ATTLIST function named_parameters (true|false) 'false'>

          <!ELEMENT function-variable ((description?),(argument),(type))>
          <!ATTLIST function-variable name CDATA #REQUIRED>
          <!ATTLIST function-variable classname CDATA #IMPLIED>

          <!ELEMENT argument (description?,type)>
          <!ATTLIST argument name CDATA #REQUIRED>
          <!ATTLIST argument required (true|false) 'true'>

          <!ELEMENT return (type)>

          <!ELEMENT variable ((alias*), (description?),(type),(note*))>
          <!ATTLIST variable name CDATA #REQUIRED>
          <!ATTLIST variable access (read-only|read-write|local-player|write-only) "read-write">
          <!ATTLIST variable version CDATA #IMPLIED>

          <!ELEMENT accessor ((description?),(length?),(index?),(call?),(function)*)>
          <!ATTLIST accessor name ID #REQUIRED>
          <!ATTLIST accessor contains IDREF #REQUIRED>

          <!ELEMENT enum-accessor ((description?),(length?),(index?),(call?))>
          <!ATTLIST enum-accessor name ID #REQUIRED>
          <!ATTLIST enum-accessor contains IDREF #REQUIRED>
          <!ATTLIST enum-accessor nice-name CDATA #IMPLIED>
          
          <!ELEMENT enum ((description?),(function|function-variable|subtable|variable)*,(mnemonics?))>
          <!ATTLIST enum name ID #REQUIRED>

          <!ELEMENT mnemonics (mnemonic*)>
          <!ELEMENT mnemonic EMPTY>

          <!ATTLIST mnemonic name CDATA #REQUIRED>

          <!ELEMENT length (description?)>
          <!ELEMENT index ((description?),(type?))>
          <!ELEMENT call (description?)>
          <!ELEMENT type (#PCDATA)>
          <!ELEMENT alias (#PCDATA)>
          <!ELEMENT note (#PCDATA)>
          <!ATTLIST note version CDATA #IMPLIED>
          ]>
<document title="Aleph One HUD Scripters' Guide">
  <section name="General" id="general">
    <section name="What is This?" id="what_is_this">
      <description>
        <p>This is a reference for writing Lua scripts to draw heads-up displays (HUDs) in Aleph One.</p>
        <p>This is not a reference for Lua itself - see lua.org for that.</p>
      </description>
    </section>
    <section name="Loading Collections" id="loading_collections">
      <description>
        <p>A Lua script can ask for the engine to load collections it might otherwise not load; for instance, in order to be able to draw defender and compiler shapes during a level that might not have them otherwise, add the indices for those collections to the global table CollectionsUsed:
        </p>
        <pre>CollectionsUsed = { 10, 16 }</pre>
      </description>
    </section>
  </section>
  <triggers id="triggers">
    <description>These are functions scripts can define which Aleph One will call at specific times or events. For the HUD, the draw() trigger is the most important. For example, to write "Hello world" in the upper left corner of the screen:
<span class="pre">Triggers = {}
function Triggers.init()
  myFont = Fonts.new{size = 14}
end
function Triggers.draw()
  myFont:draw_text("Hello world", 50, 50, {1, 1, 1, 1});
end
</span>
</description>
    <function name="init">
      <description>when a game session is started (after leaving the main menu)</description>
    </function>
    <function name="cleanup">
      <description>when a game session is completed (before returning to the main menu)</description>
    </function>
    <function name="resize">
      <description>when the window size changes in the middle of a game (with the F1/F2 keys)</description>
    </function>
    <function name="draw">
      <description>at each game frame</description>
      <note>all screen drawing must be called from this trigger</note>
      <note>the screen is cleared before each frame</note>
    </function>
  </triggers>
  <section id="using_tables" name="Using Tables">
    <description><p>There are numerous tables (technically, userdata) defined in Aleph One which scripts can use to access objects in the game. A complete list is below.</p></description>
    <section id="custom" name="Custom Fields">
      <description><p>In a real Lua table, you can set any field you want. In order to help troubleshooting, Aleph One's userdata tables will only accept the fields listed in the documentation below. However, by prepending an underscore, custom fields can be indexed. These custom fields will be associated with the object until it is destroyed.</p><pre>Players[0]._favorite_flavor = "chocolate"</pre></description>
    </section>
    <section id="table_is" name="is_ Functions">
      <description><p>Aleph One installs a set of boolean functions that can be used to recognize each of the userdata table types. For example, <code>is_font(Fonts[1])</code> returns true. Each of these functions begins with the "is_" prefix.</p></description>
    </section>
  </section>
  <tables id="tables">

    <table name="color">
      <description>Colors are standard Lua tables; you don't need to call a new() method to create them. Colors have four fields, accessed by name or number. If a field is missing, it is assumed to be 1, which allows you to write opaque colors as {r, g, b}.</description>
      <variable name="r">
        <alias>red</alias>
        <alias>[1]</alias>
        <description>red component, from 0 to 1</description>
        <type>number</type>
      </variable>
      <variable name="g">
        <alias>green</alias>
        <alias>[2]</alias>
        <description>green component, from 0 to 1</description>
        <type>number</type>
      </variable>
      <variable name="b">
        <alias>blue</alias>
        <alias>[3]</alias>
        <description>blue component, from 0 to 1</description>
        <type>number</type>
      </variable>
      <variable name="a">
        <alias>alpha</alias>
        <alias>[4]</alias>
        <description>alpha component (opacity), from 0 to 1</description>
        <type>number</type>
      </variable>
    </table>
    <accessor name="Colors" contains="color"/>

    <table name="screen" singleton="true">
      <variable name="width" access="read-only">
        <description>width of the available screen area</description>
        <type>number</type>
      </variable>
      <variable name="height" access="read-only">
        <description>height of the available screen area</description>
        <type>number</type>
      </variable>
      <subtable name="field_of_view" classname="lua_field_of_view">
        <variable name="horizontal">
          <type>number</type>
        </variable>
        <variable name="vertical">
          <type>number</type>
        </variable>
        <variable name="fix_h_not_v">
          <description>whether horizontal or vertical FOV is adjusted as aspect ratio changes</description>
          <type>boolean</type>
        </variable>
      </subtable>
      <subtable name="crosshairs" classname="lua_crosshairs">
        <variable name="active" access="read-only" version="20111201">
          <description>whether crosshairs are visible</description>
          <type>boolean</type>
        </variable>
        <variable name="lua_hud" version="20111201">
          <description>whether the Lua HUD script draws the crosshairs</description>
          <type>boolean</type>
        </variable>
      </subtable>
      <variable name="renderer" access="read-only">
        <description>which renderer is in use</description>
        <type>renderer_type</type>
      </variable>
      <variable name="map_active" access="read-only">
        <description>whether the overhead map is currently displayed</description>
        <type>boolean</type>
      </variable>
      <variable name="map_overlay_active" access="read-only" version="20111201">
        <description>whether the "Overlay Map" preference is enabled</description>
        <type>boolean</type>
      </variable>
      <variable name="term_active" access="read-only">
        <description>whether a terminal is currently displayed</description>
        <type>boolean</type>
      </variable>
      <variable name="hud_size_preference" access="read-only">
        <description>current preference setting for HUD size (normal, double, largest)</description>
        <type>size_preference</type>
      </variable>
      <variable name="term_size_preference" access="read-only">
        <description>current preference setting for terminal size (normal, double, largest)</description>
        <type>size_preference</type>
      </variable>
      <variable name="masking_mode">
        <description>image-based masking; set to drawing mode to create visible areas and enabled to use the mask</description>
        <note>masking only available in OpenGL renderer</note>
        <type>masking_mode</type>
      </variable>
      <subtable name="clip_rect" classname="lua_clip_rect">
        <description>constrain drawing to the specified area of the screen</description>
        <variable name="x"><type>number</type></variable>
        <variable name="y"><type>number</type></variable>
        <variable name="width"><type>number</type></variable>
        <variable name="height"><type>number</type></variable>
      </subtable>
      <subtable name="world_rect" classname="lua_world_rect">
        <description>specifies the area of the screen for the 3D game view</description>
        <variable name="x"><type>number</type></variable>
        <variable name="y"><type>number</type></variable>
        <variable name="width"><type>number</type></variable>
        <variable name="height"><type>number</type></variable>
      </subtable>
      <subtable name="map_rect" classname="lua_map_rect">
        <description>specifies the area of the screen for the overhead map</description>
        <variable name="x"><type>number</type></variable>
        <variable name="y"><type>number</type></variable>
        <variable name="width"><type>number</type></variable>
        <variable name="height"><type>number</type></variable>
      </subtable>
      <subtable name="term_rect" classname="lua_term_rect">
        <description>specifies the area of the screen for displaying terminals</description>
        <variable name="x"><type>number</type></variable>
        <variable name="y"><type>number</type></variable>
        <variable name="width"><type>number</type></variable>
        <variable name="height"><type>number</type></variable>
      </subtable>
	  <subtable name="text_margins" classname="lua_text_margins" version="20210408">
		<description>specifies margins from the edges of the world_rect for drawing text such as Lua overlays, messages, and the input console</description>
		<variable name="bottom"><type>number</type></variable>
		<variable name="left"><type>number</type></variable>
		<variable name="right"><type>number</type></variable>
		<variable name="top"><type>number</type></variable>
	  </subtable>
      <function name="clear_mask">
        <description>reset the image-based mask</description>
      </function>
      <function name="fill_rect">
        <description>draws a solid rectangle to the screen</description>
        <argument name="x"><type>number</type></argument>
        <argument name="y"><type>number</type></argument>
        <argument name="width"><type>number</type></argument>
        <argument name="height"><type>number</type></argument>
        <argument name="color"><type>color</type></argument>
      </function>
      <function name="frame_rect">
        <description>draws an outlined rectangle to the screen</description>
        <note>the outline is drawn entirely inside the given bounds</note>
        <argument name="x"><type>number</type></argument>
        <argument name="y"><type>number</type></argument>
        <argument name="width"><type>number</type></argument>
        <argument name="height"><type>number</type></argument>
        <argument name="color"><type>color</type></argument>
        <argument name="thickness"><description>outline size in pixels</description><type>number</type></argument>
      </function>
    </table>
    <accessor name="Screen" contains="screen"/>

    <table name="font">
      <variable name="id" access="read-only">
        <type>number</type>
        <note>can be nil</note>
      </variable>
      <variable name="file" access="read-only">
        <type>string</type>
        <note>can be nil</note>
      </variable>
      <variable name="size" access="read-only">
        <type>number</type>
      </variable>
      <variable name="style" access="read-only">
        <type>number</type>
      </variable>
      <variable name="line_height" access="read-only">
        <type>number</type>
      </variable>
      <variable name="scale" version="20140104">
        <description>scale factor, for resizing specific bitmap font sizes</description>
        <note>it's usually better to create a new font at the correct size instead</note>
        <type>number</type>
      </variable>
      <function name="measure_text">
        <description>returns the width and height of a string when drawn in this font</description>
        <argument name="string"><type>string</type></argument>
      </function>
      <function name="draw_text">
        <description>draws a string to the screen</description>
        <argument name="string"><type>string</type></argument>
        <argument name="x"><type>number</type></argument>
        <argument name="y"><type>number</type></argument>
        <argument name="color"><type>color</type></argument>
        <note>transparency only available in OpenGL renderer</note>
      </function>
    </table>
    <accessor name="Fonts" contains="font">
      <function name="new" named_parameters="true">
        <argument name="file" required="false">
          <description>the path to a TTF file, for the standard variant of the font (the special path "mono" indicates the default Mono Sans font) [default: "mono"]</description>
          <type>string</type>
        </argument>
        <argument name="size" required="false">
          <description>the font size to use [default: 12]</description>
          <type>number</type>
        </argument>
        <argument name="style" required="false">
          <description>a number indicating the sum of any font styles to use (1 - bold; 2 - italic; 4 - underline) [default: 0]</description>
          <type>number</type>
        </argument>
      </function>
      <function name="new" named_parameters="true">
        <argument name="id">
          <description>a resource ID from the Fonts file (for the default Fonts file, valid values are 4 for Monaco and 22 for Courier)</description>
          <type>number</type>
        </argument>
        <argument name="size" required="false">
          <description>the font size to use [default: 12]</description>
          <type>number</type>
        </argument>
        <argument name="style" required="false">
          <description>a number indicating the sum of any font styles to use (1 - bold; 2 - italic; 4 - underline) [default: 0]</description>
          <type>number</type>
        </argument>
      </function>
      <function name="new" named_parameters="true" version="20140104">
        <argument name="interface">
          <description>see InterfaceFonts for mnemonics</description>
          <type>interface_font</type>
        </argument>
      </function>
      <index/>
    </accessor>
    
    <table name="image">
      <variable name="width" access="read-only">
        <description>width of the image in pixels</description>
        <type>number</type>
      </variable>
      <variable name="height" access="read-only">
        <description>height of the image in pixels</description>
        <type>number</type>
      </variable>
      <variable name="unscaled_width" access="read-only">
        <description>width of the image before any calls to :rescale()</description>
        <type>number</type>
      </variable>
      <variable name="unscaled_height" access="read-only">
        <description>height of the image before any calls to :rescale()</description>
        <type>number</type>
      </variable>
      <subtable name="crop_rect" classname="lua_crop_rect">
        <description>specifies a portion of the image to be drawn</description>
        <variable name="x"><type>number</type></variable>
        <variable name="y"><type>number</type></variable>
        <variable name="width"><type>number</type></variable>
        <variable name="height"><type>number</type></variable>
      </subtable>
      <variable name="tint_color">
        <description>scale the color and opacity by this value when drawing</description>
        <type>Color</type>
        <note>default is (r=1, g=1, b=1, a=1)</note>
        <note>only available in OpenGL renderer</note>
      </variable>
      <variable name="rotation">
        <description>degrees to rotate the image when drawn</description>
        <type>number</type>
        <note>axis of rotation is about the center of the drawn area</note>
        <note>only available in OpenGL renderer</note>
      </variable>
      <function name="rescale">
        <description>resize image to specified width and height</description>
        <argument name="width"><type>number</type></argument>
        <argument name="height"><type>number</type></argument>
      </function>
      <function name="draw">
        <description>draw image (or cropped portion) to screen, with top left corner at specified position</description>
        <argument name="x"><type>number</type></argument>
        <argument name="y"><type>number</type></argument>
      </function>
    </table>
    <accessor name="Images" contains="image">
      <function name="new" named_parameters="true">
        <argument name="resource">
          <description>a resource ID from the Images file</description>
          <type>number</type>
        </argument>
      </function>
      <function name="new" named_parameters="true">
        <argument name="path">
          <description>the path to the image file to use</description>
          <type>string</type>
        </argument>
        <argument name="mask" required="false">
          <description>the path to an image file to use as an opacity mask</description>
          <type>string</type>
        </argument>
      </function>
      <index/>
    </accessor>

    <table name="shape">
      <variable name="width" access="read-only">
        <description>width of the shape in pixels</description>
        <type>number</type>
      </variable>
      <variable name="height" access="read-only">
        <description>height of the shape in pixels</description>
        <type>number</type>
      </variable>
      <variable name="unscaled_width" access="read-only">
        <description>width of the shape before any calls to :rescale()</description>
        <type>number</type>
      </variable>
      <variable name="unscaled_height" access="read-only">
        <description>height of the shape before any calls to :rescale()</description>
        <type>number</type>
      </variable>
      <subtable name="crop_rect" classname="lua_shape_crop_rect">
        <description>specifies a portion of the shape to be drawn</description>
        <variable name="x"><type>number</type></variable>
        <variable name="y"><type>number</type></variable>
        <variable name="width"><type>number</type></variable>
        <variable name="height"><type>number</type></variable>
      </subtable>
      <variable name="tint_color">
        <description>scale the color and opacity by this value when drawing</description>
        <type>Color</type>
        <note>default is (r=1, g=1, b=1, a=1)</note>
        <note>only available in OpenGL renderer</note>
      </variable>
      <variable name="rotation">
        <description>degrees to rotate the shape when drawn</description>
        <type>number</type>
        <note>axis of rotation is about the center of the drawn area</note>
        <note>only available in OpenGL renderer</note>
      </variable>
      <function name="rescale">
        <description>resize shape to specified width and height</description>
        <argument name="width"><type>number</type></argument>
        <argument name="height"><type>number</type></argument>
      </function>
      <function name="draw">
        <description>draw shape (or cropped portion) to screen, with top left corner at specified position</description>
        <argument name="x"><type>number</type></argument>
        <argument name="y"><type>number</type></argument>
      </function>
    </table>
    <accessor name="Shapes" contains="shape">
      <function name="new" named_parameters="true">
        <description>all arguments are passed by name; returns shape or nil</description>
        <argument name="collection">
          <description>the shape collection</description>
          <type>collection</type>
        </argument>
        <argument name="texture_index">
          <description>frame (not bitmap) index</description>
          <type>number</type>
        </argument>
        <argument name="type" required="false">
          <description>type such as wall or sprite; see "Texture Types"</description>
          <type>texture_type</type>
        </argument>
        <argument name="color_table" required="false">
          <description>color table index</description>
          <type>number</type>
        </argument>
      </function>
      <index/>
    </accessor>

    <table name="game" singleton="true">
      <note>all items in Game are read-only</note>
      <function name="deserialize" version="20200830">
        <description>deserializes s and returns the original Lua value</description>
        <argument name="s"><type>string</type></argument>
        <return><type>value</type></return>
        <note>see Game.serialize (from the non-HUD scripter's guide)</note>
      </function>
      <variable name="difficulty">
        <description>the difficulty level</description>
        <type>difficulty_type</type>
      </variable>
      <variable name="kill_limit">
        <description>the game kill limit, or nil if there is none</description>
        <type>number</type>
      </variable>
      <variable name="time_remaining">
        <description>the number of ticks until the game ends, or nil if there is no time limit</description>
        <type>number</type>
      </variable>
      <variable name="scoring_mode">
        <description>the current scoring mode (if the gametype is "custom")</description>
        <type>scoring_mode_type</type>
      </variable>
      <variable name="ticks">
        <description>ticks since game started</description>
        <type>time</type>
      </variable>
      <variable name="interpolated_ticks" version="20240822">
        <description>ticks since game started, including fractional ticks if running at greater than 30 fps</description>
        <type>number</type>
      </variable>
      <variable name="type">
        <description>whether the game is EMFH, KOTH, etc.</description>
        <type>game_type</type>
      </variable>
      <variable name="version">
        <description>the date version of the local player's engine</description>
        <note>for example, "20071103"</note>
      </variable>
      <subtable name="players[index]" classname="lua_players">
        <variable name="local_">
          <description>true if this player is the local player</description>
          <type>boolean</type>
        </variable>
        <variable name="active" version="20111201">
          <description>true if this player's viewpoint is currently displayed</description>
          <type>boolean</type>
        </variable>
        <variable name="name"><type>string</type></variable>
        <variable name="color">
          <description>color of player (shirt color, if teams are enabled)</description>
          <type>number</type>
        </variable>
        <variable name="team">
          <description>player's team (pants color)</description>
          <type>number</type>
        </variable>
        <variable name="kills">
          <description>player kills, not including suicides</description>
          <type>number</type>
        </variable>
        <variable name="ranking">
          <description>points or ticks, depending on game type</description>
          <type>number</type>
        </variable>
      </subtable>
    </table>
    <accessor name="Game" contains="game"/>

    <table name="level" singleton="true">
      <note>all items in Level are read-only</note>
      <variable name="name" version="20150619">
        <description>level name</description>
        <type>string</type>
      </variable>
      <variable name="index" version="20150619">
        <description>level index in the map file (starting from 0)</description>
        <type>number</type>
      </variable>
      <variable name="map_checksum" version="20150619">
        <description>checksum of map file</description>
        <type>number</type>
      </variable>
      <variable name="stash[key]" version="20200830">
        <description>reads values from a stash shared between all running Lua scripts</description>
        <note>keys/values must be strings</note>
        <type>string</type>
      </variable>
    </table>
    <accessor name="Level" contains="level"/>

    <table name="player" singleton="true">
      <note>All items in Player are read-only</note>
      <variable name="color">
        <description>color of player (shirt color, if teams are enabled)</description>
        <type>number</type>
      </variable>
      <variable name="dead">
        <description>whether player is dead</description>
        <type>boolean</type>
      </variable>
      <variable name="direction">
        <alias>yaw</alias>
        <description>direction player is facing, in degrees</description>
        <note>0 is east, 90 is south</note>
        <type>number</type>
      </variable>
      <variable name="elevation">
        <alias>pitch</alias>
        <description>angle player is looking up or down</description>
        <type>number</type>
      </variable>
      <subtable name="velocity">
        <variable name="forward" version="20111201">
          <description>player's forward/backward velocity, from internal and external forces</description>
          <note>in WU per tick; positive values mean forward movement</note>
          <type>number</type>
        </variable>
        <variable name="perpendicular" version="20111201">
          <description>player's left/right velocity</description>
          <note>in WU per tick; positive values mean rightward movement</note>
          <type>number</type>
        </variable>
        <variable name="vertical" version="20111201">
          <description>player's up/down velocity</description>
          <note>in WU per tick; positive values mean upward movement</note>
          <type>number</type>
        </variable>
      </subtable>
      <variable name="energy">
        <alias>life</alias>
        <description>amount of suit energy player has (150 is normal red health)</description>
        <type>number</type>
      </variable>
      <subtable name="inventory_sections">
        <variable name="current">
          <description>which section of the inventory to display</description>
          <type>player_section</type>
          <note>HUD themes can choose to display multiple sections simultaneously</note>
        </variable>
      </subtable>
      <subtable-accessor name="inventory_sections" classname="player_section" index="section_type">
        <variable name="type"><type>section_type</type></variable>
        <variable name="name"><type>string</type></variable>
      </subtable-accessor>

      <subtable-accessor name="items" classname="player_item" index="item_type">
        <variable name="count">
          <description>how many of item the player is carrying</description>
          <type>number</type>
        </variable>
        <variable name="inventory_section">
          <description>which section of the inventory should display this item</description>
          <type>inventory_section</type>
        </variable>
        <variable name="singular">
          <description>label to use for 1 of the item</description>
          <type>string</type>
          <note>from stringset 150</note>
        </variable>
        <variable name="plural">
          <description>label to use for more than 1 of the item</description>
          <type>string</type>
          <note>from stringset 150</note>
        </variable>
        <variable name="valid" version="20140104">
          <description>whether item is valid in the current environment (i.e. vacuum)</description>
          <type>boolean</type>
        </variable>
        <variable name="type"><type>item_type</type></variable>
      </subtable-accessor>
      <subtable name="compass" classname="lua_compass">
        <variable name="ne">
          <alias>northeast</alias>
          <description>whether north east compass quadrant is active</description>
          <type>boolean</type>
        </variable>
        <variable name="nw">
          <alias>northwest</alias>
          <description>whether north west compass quadrant is active</description>
          <type>boolean</type>
        </variable>
        <variable name="se">
          <alias>southeast</alias>
          <description>whether south east compass quadrant is active</description>
          <type>boolean</type>
        </variable>
        <variable name="sw">
          <alias>southwest</alias>
          <description>whether south west compass quadrant is active</description>
          <type>boolean</type>
        </variable>
      </subtable>
      <subtable name="motion_sensor" classname="lua_motion_sensor">
        <variable name="active">
          <description>whether player can view his motion sensor</description>
          <note>currently, this also indicates compass visibility</note>
          <type>boolean</type>
        </variable>
        <subtable name="blips[index]" classname="lua_blips">
          <variable name="intensity">
            <description>from 0 (strongest) to 5 (weakest)</description>
            <type>number</type>
          </variable>
          <variable name="type">
            <note>see "Sensor Blip Types" for mnemonics</note>
            <type>sensor_blip</type>
          </variable>
          <variable name="distance">
            <description>distance from player, in WU (maximum is 8)</description>
            <type>number</type>
          </variable>
          <variable name="direction">
          <alias>yaw</alias>
            <description>direction relative to player, in degrees</description>
            <note>0 is to player's right, 90 is directly behind player</note>
            <type>number</type>
          </variable>
        </subtable>
      </subtable>
      <variable name="name">
        <description>player's name</description>
        <type>string</type>
      </variable>
      <variable name="oxygen">
        <description>amount of oxygen player has (max is 10800)</description>
        <type>number</type>
      </variable>
      <variable name="respawn_duration" version="20140104">
        <description>ticks remaining before dead player can revive</description>
        <note>nil until player is completely dead</note>
        <type>number</type>
      </variable>
	  <variable name="run_key" version="20231125">
		<description>whether the run key is down</description>
	  </variable>
      <variable name="team">
        <description>player's team (pants color)</description>
        <type>number</type>
      </variable>
      <subtable name="texture_palette" classname="lua_texture_palette">
        <variable name="highlight">
          <description>number of slot to highlight</description>
          <note>can be nil</note>
          <type>number</type>
        </variable>
        <variable name="size">
          <description>how many slots the palette is using</description>
          <note>the texture palette is normally visible whenever the size is greater than 0</note>
          <type>number</type>
        </variable>
        <subtable name="slots[n]" classname="lua_slots">
          <variable name="collection">
            <description>collection of this slot</description>
            <type>number</type>
          </variable>
          <variable name="texture_index">
            <description>texture index of this slot</description>
            <type>number</type>
          </variable>
          <variable name="type">
            <description>texture type of this slot such as wall or sprite; see "Texture Types"</description>
            <type>texture_type</type>
          </variable>
        </subtable>
      </subtable>
      <subtable name="weapons">
        <variable name="current">
          <description>weapon the player is currently wielding</description>
          <type>player_weapon</type>
          <note>can be nil</note>
        </variable>
	<variable name="desired">
	  <description>weapon the player wants to switch to</description>
	  <type>player_weapon</type>
	  <note>can be nil</note>
	</variable>
      </subtable>
      <subtable-accessor name="weapons" classname="player_weapon" index="weapon_type">
        <variable name="type"><type>weapon_type</type></variable>
        <variable name="name" version="20111201">
          <description>label shown in classic HUD</description>
          <type>string</type>
          <note>from stringset 137; may differ from label in Player.items</note>
        </variable>
        <subtable name="name_rect" classname="player_weapon_name_rect" version="20140104">
          <description>position of label in classic HUD</description>
          <variable name="x"><type>number</type></variable>
          <variable name="y"><type>number</type></variable>
          <variable name="width"><type>number</type></variable>
          <variable name="height"><type>number</type></variable>
        </subtable>
        <subtable name="shape" classname="player_weapon_shape" version="20140104">
          <alias>multiple_shape</alias>
          <alias>multiple_unused_shape</alias>
          <note>can be nil</note>
          <variable name="texture_index">
            <description>frame in Interface collection</description>
            <type>number</type>
          </variable>
          <variable name="x"><type>number</type></variable>
          <variable name="y"><type>number</type></variable>
        </subtable>
        <subtable name="primary" classname="player_weapon_trigger">
          <alias>secondary</alias>
          <variable name="rounds">
            <description>how many rounds are currently loaded into the weapon</description>
            <type>number</type>
          </variable>
          <variable name="total_rounds">
            <description>how many rounds can be loaded into the weapon</description>
            <type>number</type>
          </variable>
          <variable name="ammo_type">
            <type>item_type</type>
          </variable>
          <variable name="weapon_drawn">
            <type>boolean</type>
          </variable>
          <subtable name="bullet_display" classname="player_weapon_trigger_bullet" version="20140104">
            <note>can be nil</note>
            <variable name="x">
              <type>number</type>
            </variable>
            <variable name="y">
              <type>number</type>
            </variable>
            <variable name="width">
              <description>width of a single bullet in classic HUD</description>
              <type>number</type>
            </variable>
            <variable name="height">
              <description>height of a single bullet in classic HUD</description>
              <type>number</type>
            </variable>
            <variable name="across">
              <description>number of bullets in a single row</description>
              <type>number</type>
            </variable>
            <variable name="down">
              <description>number of bullet rows</description>
              <type>number</type>
            </variable>
            <variable name="right_to_left">
              <type>boolean</type>
            </variable>
            <variable name="texture_index">
              <type>number</type>
            </variable>
            <variable name="empty_texture_index">
              <type>number</type>
            </variable>
          </subtable>
          <subtable name="energy_display" classname="player_weapon_trigger_energy" version="20140104">
            <note>can be nil</note>
            <variable name="x">
              <type>number</type>
            </variable>
            <variable name="y">
              <type>number</type>
            </variable>
            <variable name="width">
              <type>number</type>
            </variable>
            <variable name="height">
              <type>number</type>
            </variable>
            <variable name="maximum">
              <note>should usually match total_rounds</note>
              <type>number</type>
            </variable>
            <variable name="color">
              <description>the interface color for drawing the full region and border</description>
              <type>InterfaceColor</type>
            </variable>
            <variable name="empty_color">
              <description>the interface color for drawing the empty region</description>
              <type>InterfaceColor</type>
            </variable>
          </subtable>
        </subtable>
      </subtable-accessor>
      <variable name="zoom_active">
        <description>whether player's sniper zoom is active</description>
        <type>boolean</type>
      </variable>

    </table>
    <accessor name="Player" contains="player"/>

    <table name="lighting" singleton="true">
      <note>All items in Lighting are read-only</note>
      <variable name="ambient_light">
        <description>light level in current location, from 0 to 1</description>
        <type>number</type>
      </variable>
      <variable name="weapon_flash">
        <description>current brightness of weapons fire, from 0 to 1</description>
        <type>number</type>
      </variable>
      <subtable name="liquid_fader" classname="lighting_liquid_fader">
        <alias>damage_fader</alias>
        <note>faders only available in OpenGL, when "Color Effects" are enabled</note>
        <variable name="active">
          <description>true if fade effect is being drawn</description>
          <type>boolean</type>
        </variable>
        <variable name="type">
          <description>which fade effect type is used</description>
          <type>fade_effect_type</type>
        </variable>
        <variable name="color">
          <description>color used for this fade effect</description>
          <type>color</type>
        </variable>
      </subtable>
    </table>
    <accessor name="Lighting" contains="lighting"/>

    
    <enum name="interface_color">
      <variable name="r" access="read-only">
        <alias>red</alias>
        <type>number</type>
      </variable>
      <variable name="g" access="read-only">
        <alias>green</alias>
        <type>number</type>
      </variable>
      <variable name="b" access="read-only">
        <alias>blue</alias>
        <type>number</type>
      </variable>
      <variable name="a" access="read-only">
        <alias>alpha</alias>
        <type>number</type>
        <note>alpha is always 1</note>
      </variable>
      <mnemonics>
        <mnemonic name="ammo box full"/>
        <mnemonic name="ammo box empty"/>
        <mnemonic name="black"/>
        <mnemonic name="inventory text"/>
        <mnemonic name="inventory header background"/>
        <mnemonic name="inventory background"/>
        <mnemonic name="slate player"/>
        <mnemonic name="red player"/>
        <mnemonic name="violet player"/>
        <mnemonic name="yellow player"/>
        <mnemonic name="white player"/>
        <mnemonic name="orange player"/>
        <mnemonic name="blue player"/>
        <mnemonic name="green player"/>
        <mnemonic name="white"/>
        <mnemonic name="invalid weapon"/>
        <mnemonic name="computer border text background"/>
        <mnemonic name="computer border text"/>
        <mnemonic name="computer text"/>
        <mnemonic name="computer white text"/>
        <mnemonic name="computer red text"/>
        <mnemonic name="computer dark green text"/>
        <mnemonic name="computer cyan text"/>
        <mnemonic name="computer yellow text"/>
        <mnemonic name="computer dark red text"/>
        <mnemonic name="computer blue text"/>
      </mnemonics>
    </enum>
    <enum-accessor name="InterfaceColors" contains="interface_color" nice-name="Interface Colors" version="20140104"/>
    
    <enum name="interface_font">
      <mnemonics>
        <mnemonic name="interface"/>
        <mnemonic name="weapon name"/>
        <mnemonic name="player name"/>
        <mnemonic name="interface item count"/>
        <mnemonic name="terminal"/>
        <mnemonic name="terminal title"/>
        <mnemonic name="network statistics"/>
      </mnemonics>
    </enum>
    <enum-accessor name="InterfaceFonts" contains="interface_font" nice-name="Interface Fonts" version="20140104"/>

    <enum name="interface_rect">
      <variable name="x" access="read-only"><type>number</type></variable>
      <variable name="y" access="read-only"><type>number</type></variable>
      <variable name="width" access="read-only"><type>number</type></variable>
      <variable name="height" access="read-only"><type>number</type></variable>
      <mnemonics>
        <mnemonic name="player name"/>
        <mnemonic name="oxygen"/>
        <mnemonic name="shield"/>
        <mnemonic name="motion sensor"/>
        <mnemonic name="microphone"/>
        <mnemonic name="inventory"/>
        <mnemonic name="weapon display"/>
        <mnemonic name="new-game button"/>
        <mnemonic name="load-game button"/>
        <mnemonic name="gather button"/>
        <mnemonic name="join button"/>
        <mnemonic name="preferences button"/>
        <mnemonic name="replay button"/>
        <mnemonic name="save-last button"/>
        <mnemonic name="replace-saved button"/>
        <mnemonic name="credits button"/>
        <mnemonic name="quit button"/>
        <mnemonic name="center button"/>
        <mnemonic name="unused 18"/>
        <mnemonic name="unused 19"/>
        <mnemonic name="terminal screen"/>
        <mnemonic name="terminal header"/>
        <mnemonic name="terminal footer"/>
        <mnemonic name="terminal full text"/>
        <mnemonic name="terminal left"/>
        <mnemonic name="terminal right"/>
        <mnemonic name="terminal logon graphic"/>
        <mnemonic name="terminal logon title"/>
        <mnemonic name="terminal logon location"/>
        <mnemonic name="respawn indicator"/>
        <mnemonic name="blinker"/>
      </mnemonics>
    </enum>
    <enum-accessor name="InterfaceRects" contains="interface_rect" nice-name="Interface Rectangles" version="20140104"/>
    
    <enum name="item_type">
      <mnemonics>
        <mnemonic name="knife"/>
        <mnemonic name="pistol"/>
        <mnemonic name="pistol ammo"/>
        <mnemonic name="fusion pistol"/>
        <mnemonic name="fusion pistol ammo"/>
        <mnemonic name="assault rifle"/>
        <mnemonic name="assault rifle ammo"/>
        <mnemonic name="assault rifle grenades"/>
        <mnemonic name="missile launcher"/>
        <mnemonic name="missile launcher ammo"/>
        <mnemonic name="invisibility"/>
        <mnemonic name="invincibility"/>
        <mnemonic name="infravision"/>
        <mnemonic name="alien weapon"/>
        <mnemonic name="alien weapon ammo"/>
        <mnemonic name="flamethrower"/>
        <mnemonic name="flamethrower ammo"/>
        <mnemonic name="extravision"/>
        <mnemonic name="oxygen"/>
        <mnemonic name="single health"/>
        <mnemonic name="double health"/>
        <mnemonic name="triple health"/>
        <mnemonic name="shotgun"/>
        <mnemonic name="shotgun ammo"/>
        <mnemonic name="key"/>
        <mnemonic name="uplink chip"/>
        <mnemonic name="light blue ball"/>
        <mnemonic name="ball"/>
        <mnemonic name="violet ball"/>
        <mnemonic name="yellow ball"/>
        <mnemonic name="brown ball"/>
        <mnemonic name="orange ball"/>
        <mnemonic name="blue ball"/>
        <mnemonic name="green ball"/>
        <mnemonic name="smg"/>
        <mnemonic name="smg ammo"/>
      </mnemonics>
    </enum>
    <enum-accessor name="ItemTypes" contains="item_type" nice-name="Items"/>

    <enum name="section_type">
      <mnemonics>
        <mnemonic name="weapons"/>
        <mnemonic name="ammunition"/>
        <mnemonic name="powerups"/>
        <mnemonic name="items"/>
        <mnemonic name="weapon powerups"/>
        <mnemonic name="balls"/>
        <mnemonic name="network statistics"/>
      </mnemonics>
    </enum>
    <enum-accessor name="InventorySections" contains="section_type" nice-name="Inventory Sections"/>

    <enum name="size_preference">
      <mnemonics>
        <mnemonic name="normal"/>
        <mnemonic name="double"/>
        <mnemonic name="largest"/>
      </mnemonics>
    </enum>
    <enum-accessor name="SizePreferences" contains="size_preference" nice-name="Size Preferences"/>
    
        
    <enum name="sensor_blip">
      <mnemonics>
        <mnemonic name="friend"/>
        <mnemonic name="alien"/>
        <mnemonic name="hostile player"/>
      </mnemonics>
    </enum>
    <enum-accessor name="SensorBlipTypes" contains="sensor_blip" nice-name="Sensor Blip Types"/>
    
    <enum name="player_color">
      <mnemonics>
        <mnemonic name="slate"/>
        <mnemonic name="red"/>
        <mnemonic name="violet"/>
        <mnemonic name="yellow"/>
        <mnemonic name="white"/>
        <mnemonic name="orange"/>
        <mnemonic name="blue"/>
        <mnemonic name="green"/>
      </mnemonics>
    </enum>
    <enum-accessor name="PlayerColors" contains="player_color" nice-name="Player and Team Colors"/>

    <enum name="difficulty_type">
      <mnemonics>
        <mnemonic name="kindergarten"/>
        <mnemonic name="easy"/>
        <mnemonic name="normal"/>
        <mnemonic name="major damage"/>
        <mnemonic name="total carnage"/>
      </mnemonics>
    </enum>
    <enum-accessor name="DifficultyTypes" contains="difficulty_type" nice-name="Difficulty"/>

    <enum name="renderer_type">
      <mnemonics>
        <mnemonic name="software"/>
        <mnemonic name="opengl"/>
        <mnemonic name="shader"/>
      </mnemonics>
    </enum>
    <enum-accessor name="RendererTypes" contains="renderer_type" nice-name="Renderer Types"/>

    <enum name="masking_mode">
      <mnemonics>
        <mnemonic name="disabled"/>
        <mnemonic name="enabled"/>
        <mnemonic name="drawing"/>
        <mnemonic name="erasing"/>
      </mnemonics>
    </enum>
    <enum-accessor name="MaskingModes" contains="masking_mode" nice-name="Masking Modes"/>

    <enum name="game_type">
      <mnemonics>
        <mnemonic name="kill monsters"/>
        <mnemonic name="cooperative play"/>
        <mnemonic name="capture the flag"/>
        <mnemonic name="king of the hill"/>
        <mnemonic name="kill the man with the ball"/>
        <mnemonic name="defense"/>
        <mnemonic name="rugby"/>
        <mnemonic name="tag"/>
        <mnemonic name="netscript"/>
      </mnemonics>
    </enum>
    <enum-accessor name="GameTypes" contains="game_type" nice-name="Game Types"/>

    <enum name="scoring_mode">
      <mnemonics>
        <mnemonic name="most points"/>
        <mnemonic name="most time"/>
        <mnemonic name="least points"/>
        <mnemonic name="least time"/>
      </mnemonics>
    </enum>
    <enum-accessor name="ScoringModes" contains="scoring_mode" nice-name="Scoring Modes"/>

    <enum name="weapon_type">
      <mnemonics>
        <mnemonic name="fist"/>
        <mnemonic name="pistol"/>
        <mnemonic name="fusion pistol"/>
        <mnemonic name="assault rifle"/>
        <mnemonic name="missile launcher"/>
        <mnemonic name="flamethrower"/>
        <mnemonic name="alien weapon"/>
        <mnemonic name="shotgun"/>
        <mnemonic name="ball"/>
        <mnemonic name="smg"/>
      </mnemonics>
    </enum>
    <enum-accessor name="WeaponTypes" contains="weapon_type" nice-name="Weapons"/>
    
    <enum name="fade_effect_type">
      <mnemonics>
        <mnemonic name="tint"/>
        <mnemonic name="randomize"/>
        <mnemonic name="negate"/>
        <mnemonic name="dodge"/>
        <mnemonic name="burn"/>
        <mnemonic name="soft tint"/>
      </mnemonics>
    </enum>
    <enum-accessor name="FadeEffectTypes" contains="fade_effect_type" nice-name="Fade Effect Types"/>

    <enum name="collection">
      <variable name="bitmap_count">
        <description>number of bitmaps in collection</description>
      </variable>
      <mnemonics>
        <mnemonic name="interface"/>
        <mnemonic name="weapons in hand"/>
        <mnemonic name="juggernaut"/>
        <mnemonic name="tick"/>
        <mnemonic name="explosions"/>
        <mnemonic name="hunter"/>
        <mnemonic name="player"/>
        <mnemonic name="items"/>
        <mnemonic name="trooper"/>
        <mnemonic name="fighter"/>
        <mnemonic name="defender"/>
        <mnemonic name="yeti"/>
        <mnemonic name="bob"/>
        <mnemonic name="vacbob"/>
        <mnemonic name="enforcer"/>
        <mnemonic name="drone"/>
        <mnemonic name="compiler"/>
        <mnemonic name="water"/>
        <mnemonic name="lava"/>
        <mnemonic name="sewage"/>
        <mnemonic name="jjaro"/>
        <mnemonic name="pfhor"/>
        <mnemonic name="water scenery"/>
        <mnemonic name="lava scenery"/>
        <mnemonic name="sewage scenery"/>
        <mnemonic name="jjaro scenery"/>
        <mnemonic name="pfhor scenery"/>
        <mnemonic name="day"/>
        <mnemonic name="night"/>
        <mnemonic name="moon"/>
        <mnemonic name="space"/>
        <mnemonic name="cyborg"/>
      </mnemonics>
    </enum>
    <enum-accessor name="Collections" contains="collection" nice-name="Collections"/>
    
    <enum name="texture_type">
      <mnemonics>
        <mnemonic name="wall"/>
        <mnemonic name="landscape"/>
        <mnemonic name="sprite"/>
        <mnemonic name="weapon in hand"/>
        <mnemonic name="interface"/>
      </mnemonics>
    </enum>
    <enum-accessor name="TextureTypes" contains="texture_type" nice-name="Texture Types"/>

  </tables>
  <types id="types">
  </types>

</document>
