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.
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 }
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
when a game session is started (after leaving the main menu)
when a game session is completed (before returning to the main menu)
when the window size changes in the middle of a game (with the F1/F2 keys)
at each game frame
all screen drawing must be called from this trigger
the screen is cleared before each frame
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.
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"
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}.
red component, from 0 to 1
green component, from 0 to 1
blue component, from 0 to 1
alpha component (opacity), from 0 to 1
can be nil
can be nil
scale factor, for resizing specific bitmap font sizes
it's usually better to create a new font at the correct size instead
returns the width and height of a string when drawn in this font
draws a string to the screen
transparency only available in OpenGL renderer
all items in Game are read-only
the difficulty level
the game kill limit, or nil if there is none
the number of ticks until the game ends, or nil if there is no time limit
the current scoring mode (if the gametype is "custom")
ticks since game started
whether the game is EMFH, KOTH, etc.
the date version of the local player's engine
for example, "20071103"
true if this player's viewpoint is currently displayed
color of player (shirt color, if teams are enabled)
player kills, not including suicides
true if this player is the local player
points or ticks, depending on game type
player's team (pants color)
width of the image in pixels
height of the image in pixels
width of the image before any calls to :rescale()
height of the image before any calls to :rescale()
specifies a portion of the image to be drawn
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
degrees to rotate the image when drawn
axis of rotation is about the center of the drawn area
only available in OpenGL renderer
resize image to specified width and height
draw image (or cropped portion) to screen, with top left corner at specified position
All items in Lighting are read-only
light level in current location, from 0 to 1
current brightness of weapons fire, from 0 to 1
faders only available in OpenGL, when "Color Effects" are enabled
true if fade effect is being drawn
color used for this fade effect
which fade effect type is used
All items in Player are read-only
color of player (shirt color, if teams are enabled)
whether player is dead
direction player is facing, in degrees
0 is east, 90 is south
angle player is looking up or down
player's forward/backward velocity, from internal and external forces
in WU per tick; positive values mean forward movement
player's left/right velocity
in WU per tick; positive values mean rightward movement
player's up/down velocity
in WU per tick; positive values mean upward movement
amount of suit energy player has (150 is normal red health)
true if netmic is on
which section of the inventory to display
HUD themes can choose to display multiple sections simultaneously
how many of item the player is carrying
which section of the inventory should display this item
label to use for more than 1 of the item
from stringset 150
label to use for 1 of the item
from stringset 150
whether item is valid in the current environment (i.e. vacuum)
whether north east compass quadrant is active
whether north west compass quadrant is active
whether south east compass quadrant is active
whether south west compass quadrant is active
whether player can view his motion sensor
currently, this also indicates compass visibility
direction relative to player, in degrees
0 is to player's right, 90 is directly behind player
distance from player, in WU (maximum is 8)
from 0 (strongest) to 5 (weakest)
see "Sensor Blip Types" for mnemonics
player's name
amount of oxygen player has (max is 10800)
ticks remaining before dead player can revive
nil until player is completely dead
player's team (pants color)
number of slot to highlight
can be nil
how many slots the palette is using
the texture palette is normally visible whenever the size is greater than 0
collection of this slot
texture index of this slot
texture type of this slot such as wall or sprite; see "Texture Types"
weapon the player is currently wielding
can be nil
weapon the player wants to switch to
can be nil
label shown in classic HUD
from stringset 137; may differ from label in Player.items
position of label in classic HUD
can be nil
number of bullets in a single row
number of bullet rows
height of a single bullet in classic HUD
width of a single bullet in classic HUD
can be nil
the interface color for drawing the full region and border
the interface color for drawing the empty region
should usually match total_rounds
how many rounds are currently loaded into the weapon
how many rounds can be loaded into the weapon
can be nil
frame in Interface collection
whether player's sniper zoom is active
width of the available screen area
height of the available screen area
whether horizontal or vertical FOV is adjusted as aspect ratio changes
whether crosshairs are visible
whether the Lua HUD script draws the crosshairs
which renderer is in use
whether the overhead map is currently displayed
whether the "Overlay Map" preference is enabled
whether a terminal is currently displayed
current preference setting for HUD size (normal, double, largest)
current preference setting for terminal size (normal, double, largest)
image-based masking; set to drawing mode to create visible areas and enabled to use the mask
masking only available in OpenGL renderer
constrain drawing to the specified area of the screen
specifies the area of the screen for the 3D game view
specifies the area of the screen for the overhead map
specifies the area of the screen for displaying terminals
reset the image-based mask
draws a solid rectangle to the screen
draws an outlined rectangle to the screen
the outline is drawn entirely inside the given bounds
all arguments are passed by name; returns shape or nil
width of the shape in pixels
height of the shape in pixels
width of the shape before any calls to :rescale()
height of the shape before any calls to :rescale()
specifies a portion of the shape to be drawn
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
degrees to rotate the shape when drawn
axis of rotation is about the center of the drawn area
only available in OpenGL renderer
resize shape to specified width and height
draw shape (or cropped portion) to screen, with top left corner at specified position
number of bitmaps in collection
alpha is always 1