# Table of Contents

1. General
   1. What is This?
   2. Loading Collections
2. Triggers
3. Using Tables
   1. Custom Fields
4. Tables
   1. Colors
   2. Fonts
   3. Game
   4. Images
   5. Lighting
   6. Player
   7. Screen
   8. Shapes
5. Types and Mnemonics
   1. Collections
   2. Difficulty
   3. Fade Effect Types
   4. Game Types
   5. Inventory Sections
   6. Items
   7. Masking Modes
   8. Player and Team Colors
   9. Renderer Types
   10. Scoring Modes
   11. Sensor Blip Types
   12. Size Preferences
   13. Texture Types
   14. Weapons

# General

## What is This?

This is a reference for writing Lua scripts to draw heads-up displays (HUDs) in Aleph One.

This is not a reference for Lua itself - see lua.org for that.

## Loading Collections

A Lua script can ask for the engine to load collections it might otherwise not load; for instance, in order to be able to spawn defenders and compilers on a map that might not have them otherwise, add the indices for those collections to the global table CollectionsUsed:

    CollectionsUsed = { 10, 16 }

# Triggers

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: 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

Triggers
  .init()

    when a game session is started (after leaving the main menu)

  .cleanup()

    when a game session is completed (before returning to the main menu)

  .resize()

    when the window size changes in the middle of a game (with the F1/F2 keys)

  .draw()

    at each game frame

    all screen drawing must be called from this trigger

    the screen is cleared before each frame

# Using Tables

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.

## Custom Fields

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.

    Players[0]._favorite_flavor = "chocolate"

# Tables

### Colors

Colors

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

  .r
  .red
  [1]

    red component, from 0 to 1

  .g
  .green
  [2]

    green component, from 0 to 1

  .b
  .blue
  [3]

    blue component, from 0 to 1

  .a
  .alpha
  [4]

    alpha component (opacity), from 0 to 1

### Fonts

Fonts.new{id=, file=, size=, style=}

  all arguments are optional and passed by name; "id" and "file" are mutually exclusive; returns font or nil

  - id: a resource ID from the Fonts file (for the default Fonts file, valid values are 4 for Monaco and 22 for Courier) [default: nil]
  - file: 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"]
  - size: the font size to use [default: 12]
  - style: a number indicating the sum of any font styles to use (1 - bold; 2 - italic; 4 - underline) [default: 0]
Fonts[index]
  .id (read-only)

    can be nil

  .file (read-only)

    can be nil

  .size (read-only)

  .style (read-only)

  :measure_text(string)

    returns the width and height of a string when drawn in this font

  :draw_text(string, x, y, color)

    draws a string to the screen

    transparency only available in OpenGL renderer

### Game

Game

  all items in Game are read-only

  .difficulty

    the difficulty level

  .kill_limit

    the game kill limit, or nil if there is none

  .time_remaining

    the number of ticks until the game ends, or nil if there is no time limit

  .scoring_mode

    the current scoring mode (if the gametype is "custom")

  .ticks

    ticks since game started

  .type

    whether the game is EMFH, KOTH, etc.

  .version

    the date version of the local player's engine

    for example, "20071103"

  .players[index]
    .active 20111201

      true if this player's viewpoint is currently displayed

    .color

      color of player (shirt color, if teams are enabled)

    .kills

      player kills, not including suicides

    .local_

      true if this player is the local player

    .name

    .ranking

      points or ticks, depending on game type

    .team

      player's team (pants color)

### Images

Images.new{ [resource=] [, path=] [, mask=]}

  all arguments are passed by name; returns image or nil

  - resource: a resource ID from the Images file (if given, other arguments are ignored)
  - path: the path to the image file to use (required if resource is not given)
  - mask: the path to an image file to use as an opacity mask
Images[index]
  .width (read-only)

    width of the image in pixels

  .height (read-only)

    height of the image in pixels

  .unscaled_width (read-only)

    width of the image before any calls to :rescale()

  .unscaled_height (read-only)

    height of the image before any calls to :rescale()

  .crop_rect

    specifies a portion of the image to be drawn

    .height

    .width

    .x

    .y

  .tint_color

    scale the color and opacity by this value when drawing

    default is (r=1, g=1, b=1, a=1)

    only available in OpenGL renderer

  .rotation

    degrees to rotate the image when drawn

    axis of rotation is about the center of the drawn area

    only available in OpenGL renderer

  :rescale(width, height)

    resize image to specified width and height

  :draw(x, y)

    draw image (or cropped portion) to screen, with top left corner at specified position

### Lighting

Lighting

  All items in Lighting are read-only

  .ambient_light

    light level in current location, from 0 to 1

  .weapon_flash

    current brightness of weapons fire, from 0 to 1

  .liquid_fader
  .damage_fader

    faders only available in OpenGL, when "Color Effects" are enabled

    .active

      true if fade effect is being drawn

    .color

      color used for this fade effect

    .type

      which fade effect type is used

### Player

Player

  All items in Player are read-only

  .color

    color of player (shirt color, if teams are enabled)

  .dead

    whether player is dead

  .direction
  .yaw

    direction player is facing, in degrees

    0 is east, 90 is south

  .elevation
  .pitch

    angle player is looking up or down

  .velocity
    .forward 20111201

      player's forward/backward velocity, from internal and external forces

      in WU per tick; positive values mean forward movement

    .perpendicular 20111201

      player's left/right velocity

      in WU per tick; positive values mean rightward movement

    .vertical 20111201

      player's up/down velocity

      in WU per tick; positive values mean upward movement

  .energy
  .life

    amount of suit energy player has (150 is normal red health)

  .microphone_active

    true if netmic is on

  .inventory_sections
    .current

      which section of the inventory to display

      HUD themes can choose to display multiple sections simultaneously

  .inventory_sections[section_type]
    .name

    .type

  .items[item_type]
    .count

      how many of item the player is carrying

    .inventory_section

      which section of the inventory should display this item

    .plural

      label to use for more than 1 of the item

      from stringset 150

    .singular

      label to use for 1 of the item

      from stringset 150

    .type

  .compass
    .ne
    .northeast

      whether north east compass quadrant is active

    .nw
    .northwest

      whether north west compass quadrant is active

    .se
    .southeast

      whether south east compass quadrant is active

    .sw
    .southwest

      whether south west compass quadrant is active

  .motion_sensor
    .active

      whether player can view his motion sensor

      currently, this also indicates compass visibility

    .blips[index]
      .direction
      .yaw

        direction relative to player, in degrees

        0 is to player's right, 90 is directly behind player

      .distance

        distance from player, in WU (maximum is 8)

      .intensity

        from 0 (strongest) to 5 (weakest)

      .type

        see "Sensor Blip Types" for mnemonics

  .name

    player's name

  .oxygen

    amount of oxygen player has (max is 10800)

  .team

    player's team (pants color)

  .texture_palette
    .highlight

      number of slot to highlight

      can be nil

    .size

      how many slots the palette is using

      the texture palette is normally visible whenever the size is greater than 0

    .slots[n]
      .collection

        collection of this slot

      .texture_index

        texture index of this slot

      .type

        texture type of this slot such as wall or sprite; see "Texture Types"

  .weapons
    .current

      weapon the player is currently wielding

      can be nil

    .desired

      weapon the player wants to switch to

      can be nil

  .weapons[weapon_type]
    .name 20111201

      label shown in classic HUD

      from stringset 137; may differ from label in Player.items

    .primary
    .secondary
      .ammo_type

      .rounds

        how many rounds are currently loaded into the weapon

      .total_rounds

        how many rounds can be loaded into the weapon

      .weapon_drawn

    .type

  .zoom_active

    whether player's sniper zoom is active

### Screen

Screen
  .width (read-only)

    width of the available screen area

  .height (read-only)

    height of the available screen area

  .field_of_view
    .fix_h_not_v

      whether horizontal or vertical FOV is adjusted as aspect ratio changes

    .horizontal

    .vertical

  .crosshairs
    .active (read-only) 20111201

      whether crosshairs are visible

    .lua_hud 20111201

      whether the Lua HUD script draws the crosshairs

  .renderer (read-only)

    which renderer is in use

  .map_active (read-only)

    whether the overhead map is currently displayed

  .map_overlay_active (read-only) 20111201

    whether the "Overlay Map" preference is enabled

  .term_active (read-only)

    whether a terminal is currently displayed

  .hud_size_preference (read-only)

    current preference setting for HUD size (normal, double, largest)

  .term_size_preference (read-only)

    current preference setting for terminal size (normal, double, largest)

  .masking_mode

    image-based masking; set to drawing mode to create visible areas and enabled to use the mask

    masking only available in OpenGL renderer

  .clip_rect

    constrain drawing to the specified area of the screen

    .height

    .width

    .x

    .y

  .world_rect

    specifies the area of the screen for the 3D game view

    .height

    .width

    .x

    .y

  .map_rect

    specifies the area of the screen for the overhead map

    .height

    .width

    .x

    .y

  .term_rect

    specifies the area of the screen for displaying terminals

    .height

    .width

    .x

    .y

  .clear_mask()

    reset the image-based mask

  .fill_rect(x, y, width, height, color)

    draws a solid rectangle to the screen

  .frame_rect(x, y, width, height, color, thickness)

    draws an outlined rectangle to the screen

    - thickness: outline size in pixels

    the outline is drawn entirely inside the given bounds

### Shapes

Shapes.new{collection=, texture_index= [, type=] [, color table=]}

  all arguments are passed by name; returns shape or nil

  - collection: the shape collection
  - texture_index: texture bitmap index
  - type: type such as wall or sprite; see "Texture Types"
  - color table: color table index
Shapes[index]
  .width (read-only)

    width of the shape in pixels

  .height (read-only)

    height of the shape in pixels

  .unscaled_width (read-only)

    width of the shape before any calls to :rescale()

  .unscaled_height (read-only)

    height of the shape before any calls to :rescale()

  .crop_rect

    specifies a portion of the shape to be drawn

    .height

    .width

    .x

    .y

  .tint_color

    scale the color and opacity by this value when drawing

    default is (r=1, g=1, b=1, a=1)

    only available in OpenGL renderer

  .rotation

    degrees to rotate the shape when drawn

    axis of rotation is about the center of the drawn area

    only available in OpenGL renderer

  :rescale(width, height)

    resize shape to specified width and height

  :draw(x, y)

    draw shape (or cropped portion) to screen, with top left corner at specified position

# Types and Mnemonics

### Collections

Collections()
Collections[collection]
  .bitmap_count

    number of bitmaps in collection

#### Mnemonics

- "interface"
- "weapons in hand"
- "juggernaut"
- "tick"
- "explosions"
- "hunter"
- "player"
- "items"
- "trooper"
- "fighter"
- "defender"

- "yeti"
- "bob"
- "vacbob"
- "enforcer"
- "drone"
- "compiler"
- "water"
- "lava"
- "sewage"
- "jjaro"
- "pfhor"

- "water scenery"
- "lava scenery"
- "sewage scenery"
- "jjaro scenery"
- "pfhor scenery"
- "day"
- "night"
- "moon"
- "space"
- "cyborg"

### Difficulty

# DifficultyTypes
DifficultyTypes()

#### Mnemonics

- "kindergarten"
- "easy"
- "normal"
- "major damage"
- "total carnage"

### Fade Effect Types

# FadeEffectTypes
FadeEffectTypes()

#### Mnemonics

- "tint"
- "randomize"
- "negate"
- "dodge"
- "burn"
- "soft tint"

### Game Types

# GameTypes
GameTypes()

#### Mnemonics

- "kill monsters"
- "cooperative play"
- "capture the flag"

- "king of the hill"
- "kill the man with the ball"
- "defense"

- "rugby"
- "tag"
- "netscript"

### Inventory Sections

# InventorySections
InventorySections()

#### Mnemonics

- "weapons"
- "ammunition"
- "powerups"
- "items"
- "weapon powerups"
- "balls"
- "network statistics"

### Items

# ItemTypes
ItemTypes()

#### Mnemonics

- "knife"
- "pistol"
- "pistol ammo"
- "fusion pistol"
- "fusion pistol ammo"
- "assault rifle"
- "assault rifle ammo"
- "assault rifle grenades"
- "missile launcher"
- "missile launcher ammo"
- "invisibility"
- "invincibility"

- "infravision"
- "alien weapon"
- "alien weapon ammo"
- "flamethrower"
- "flamethrower ammo"
- "extravision"
- "oxygen"
- "single health"
- "double health"
- "triple health"
- "shotgun"
- "shotgun ammo"

- "key"
- "uplink chip"
- "light blue ball"
- "ball"
- "violet ball"
- "yellow ball"
- "brown ball"
- "orange ball"
- "blue ball"
- "green ball"
- "smg"
- "smg ammo"

### Masking Modes

# MaskingModes
MaskingModes()

#### Mnemonics

- "disabled"
- "enabled"
- "drawing"
- "erasing"

### Player and Team Colors

# PlayerColors
PlayerColors()

#### Mnemonics

- "slate"
- "red"
- "violet"
- "yellow"
- "white"
- "orange"
- "blue"
- "green"

### Renderer Types

# RendererTypes
RendererTypes()

#### Mnemonics

- "software"
- "opengl"
- "shader"

### Scoring Modes

# ScoringModes
ScoringModes()

#### Mnemonics

- "most points"
- "most time"
- "least points"
- "least time"

### Sensor Blip Types

# SensorBlipTypes
SensorBlipTypes()

#### Mnemonics

- "friend"
- "alien"
- "hostile player"

### Size Preferences

# SizePreferences
SizePreferences()

#### Mnemonics

- "normal"
- "double"
- "largest"

### Texture Types

# TextureTypes
TextureTypes()

#### Mnemonics

- "wall"
- "landscape"
- "sprite"
- "weapon in hand"
- "interface"

### Weapons

# WeaponTypes
WeaponTypes()

#### Mnemonics

- "fist"
- "pistol"
- "fusion pistol"
- "assault rifle"

- "missile launcher"
- "flamethrower"
- "alien weapon"
- "shotgun"

- "ball"
- "smg"