# Table of Contents

1. General
   1. What is This?
   2. Loading Collections
2. Triggers
   1. cleanup
   2. draw
   3. init
   4. resize
3. Using Tables
   1. Custom Fields
   2. is_ Functions
4. Tables
   1. Colors
   2. Fonts
   3. Game
   4. Images
   5. Level
   6. Lighting
   7. Player
   8. Screen
   9. Shapes
5. Types and Mnemonics
   1. Collections
   2. Difficulty
   3. Fade Effect Types
   4. Game Types
   5. Interface Colors
   6. Interface Fonts
   7. Interface Rectangles
   8. Inventory Sections
   9. Items
   10. Masking Modes
   11. Player and Team Colors
   12. Renderer Types
   13. Scoring Modes
   14. Sensor Blip Types
   15. Size Preferences
   16. Texture Types
   17. 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 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:

    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
  .cleanup()

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

  .draw()

    at each game frame

    all screen drawing must be called from this trigger

    the screen is cleared before each frame

  .init()

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

  .resize()

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

# 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"

## is_ Functions

Aleph One installs a set of boolean functions that can be used to recognize each of the userdata table types. For example, `is_font(Fonts[1])` returns true. Each of these functions begins with the "is_" prefix.

# 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{ [file=] [, size=] [, style=]}

  - 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.new{id= [, size=] [, style=]}

  - id: a resource ID from the Fonts file (for the default Fonts file, valid values are 4 for Monaco and 22 for Courier)
  - 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.new{interface=} 20140104

  - interface: see InterfaceFonts for mnemonics
Fonts[index]
  .id (read-only)

    can be nil

  .file (read-only)

    can be nil

  .size (read-only)

  .style (read-only)

  .line_height (read-only)

  .scale 20140104

    scale factor, for resizing specific bitmap font sizes

    it's usually better to create a new font at the correct size instead

  :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

  .deserialize(s) 20200830

    deserializes s and returns the original Lua value

    see Game.serialize (from the non-HUD scripter's guide)

  .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

  .interpolated_ticks 20240822

    ticks since game started, including fractional ticks if running at greater than 30 fps

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

  - resource: a resource ID from the Images file
Images.new{path= [, mask=]}

  - path: the path to the image file to use
  - 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

### Level

Level

  all items in Level are read-only

  .name 20150619

    level name

  .index 20150619

    level index in the map file (starting from 0)

  .map_checksum 20150619

    checksum of map file

  .stash[key] 20200830

    reads values from a stash shared between all running Lua scripts

    keys/values must be strings

### 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)

  .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

    .valid 20140104

      whether item is valid in the current environment (i.e. vacuum)

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

  .respawn_duration 20140104

    ticks remaining before dead player can revive

    nil until player is completely dead

  .run_key 20231125

    whether the run key is down

  .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

    .name_rect 20140104

      position of label in classic HUD

      .height

      .width

      .x

      .y

    .primary
    .secondary
      .ammo_type

      .bullet_display 20140104

        can be nil

        .across

          number of bullets in a single row

        .down

          number of bullet rows

        .empty_texture_index

        .height

          height of a single bullet in classic HUD

        .right_to_left

        .texture_index

        .width

          width of a single bullet in classic HUD

        .x

        .y

      .energy_display 20140104

        can be nil

        .color

          the interface color for drawing the full region and border

        .empty_color

          the interface color for drawing the empty region

        .height

        .maximum

          should usually match total_rounds

        .width

        .x

        .y

      .rounds

        how many rounds are currently loaded into the weapon

      .total_rounds

        how many rounds can be loaded into the weapon

      .weapon_drawn

    .shape 20140104
    .multiple_shape
    .multiple_unused_shape

      can be nil

      .texture_index

        frame in Interface collection

      .x

      .y

    .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

  .text_margins 20210408

    specifies margins from the edges of the world_rect for drawing text such as Lua overlays, messages, and the input console

    .bottom

    .left

    .right

    .top

  .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: frame (not 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"

### Interface Colors 20140104

# InterfaceColors
InterfaceColors()
InterfaceColors[interface_color]
  .r (read-only)
  .red (read-only)

  .g (read-only)
  .green (read-only)

  .b (read-only)
  .blue (read-only)

  .a (read-only)
  .alpha (read-only)

    alpha is always 1

#### Mnemonics

- "ammo box full"
- "ammo box empty"
- "black"
- "inventory text"
- "inventory header background"
- "inventory background"
- "slate player"
- "red player"
- "violet player"

- "yellow player"
- "white player"
- "orange player"
- "blue player"
- "green player"
- "white"
- "invalid weapon"
- "computer border text background"
- "computer border text"

- "computer text"
- "computer white text"
- "computer red text"
- "computer dark green text"
- "computer cyan text"
- "computer yellow text"
- "computer dark red text"
- "computer blue text"

### Interface Fonts 20140104

# InterfaceFonts
InterfaceFonts()

#### Mnemonics

- "interface"
- "weapon name"
- "player name"
- "interface item count"
- "terminal"
- "terminal title"
- "network statistics"

### Interface Rectangles 20140104

# InterfaceRects
InterfaceRects()
InterfaceRects[interface_rect]
  .x (read-only)

  .y (read-only)

  .width (read-only)

  .height (read-only)

#### Mnemonics

- "player name"
- "oxygen"
- "shield"
- "motion sensor"
- "microphone"
- "inventory"
- "weapon display"
- "new-game button"
- "load-game button"
- "gather button"
- "join button"

- "preferences button"
- "replay button"
- "save-last button"
- "replace-saved button"
- "credits button"
- "quit button"
- "center button"
- "unused 18"
- "unused 19"
- "terminal screen"
- "terminal header"

- "terminal footer"
- "terminal full text"
- "terminal left"
- "terminal right"
- "terminal logon graphic"
- "terminal logon title"
- "terminal logon location"
- "respawn indicator"
- "blinker"

### 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"