This is a reference for writing Lua scripts to work in Aleph One. It lists every trigger and table available to Lua scripts. It is expected that Lua functionality will grow in Aleph One, and as it does, so will this document. Not everything here is completely documented, and any help fixing that would be appreciated.
This is not a reference for Lua itself - see lua.org for that.
There are three ways to get a script to run - by embedding it in a level, by selecting a solo script in the Environment Preferences, or by selecting a script at the gather network game dialog.
To embed a script in a level, use a tool such as Atque. Use embedded Lua scripts only for map specific features, not for modifying game types. For instance, it may be tempting to embed the latest version of the Lua CTF script in a map designed only for playing CTF; however, this would prevent the user from using a later version of CTF if it were to come out, or from using another net script that works on CTF maps. Some older scenarios use Lua scripts in TEXT resources, but this is no longer recommended since they are not transmitted in net games.
To use a solo script, check the "Use Solo Script" box in Environment Preferences, and choose the script file to use.
To use a script via the network game dialog, put then script in a text file with the extension .lua. Then, at the gather network game dialog, select "use script", then select your script file.
The unit for distance we use is World Units (WU) These are the same values you'd see in Forge or with F10 location display, and 1/1024 of what A1 uses internally and what you'd see in Pfhorte.
Units for speed are . . . well let's say they're messy. :) Lua speeds are expressed in World Units per tick (a tick is 1/30 of a second). Forge claims to use WU per sec, but it actually uses 0.87890625 WU per sec (which equals 30 internal units per tick). The following example illustrates the various conversions:
A few variables are marked "local player." These variables will always do the right thing when written to, but when reading, will only return a useful result if the player they belong to is "local." In net games, there is a separate copy of each Lua script running on each player's computer, and the player is "local" only to his copy of the script.
So, the only local player variables the script running on player 4's machine will be able to read from are the ones in Players[4]. For his script, the value of Players[1].zoom_active, for example, will return nil. If this confuses you, it might be better to avoid reading from any variable marked "local player."
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 }
Lua scripts are only active during a single level. If the user jumps to a new level, or restores from a saved game, the script is restarted in a clean state.
It is now possible to pass data across level jumps, by using the Game.restore_passed() function. This function will restore any custom fields (see the "Custom Fields" section of "Using Tables" below) in the Players or Game tables that were set immediately prior to the last level jump. Note that in order for data to survive multiple level jumps, Game.restore_passed() must be called after each level jump. Game.restore_passed() will not restore data from saved games.
It is also possible to restore data from saved games. The Game.restore_saved() function will restore all custom fields in use at the time the game was saved.
Only numbers, strings, booleans, and tables (including Aleph One's built-in userdata tables) can be restored.
These are functions scripts can define which Aleph One will call at specific times or events. For example, to regenerate health: Triggers = {} function Triggers.idle() for p in Players() do if p.life < 150 and not p.dead then p.life = p.life + 1 end end end Calling Triggers = {} at the beginning of the script removes the compatibility triggers installed for old Lua scripts, speeding up execution of new scripts.
at beginning of level
at end of the level
primarily this is intended as a last chance for changing netgame scores before the postgame carnage report.
at each tick, before physics and such
at each tick, after physics and such, but before rendering
whenever a player starts to use a refuel panel
whenever a player stops using a refuel panel
whenever a player uses a tag switch
not called when a projectile (e.g., fists) toggles a tag switch
side is only valid in version 20111201 and newer
whenever a player uses a light switch
not called when a projectile (e.g., fists) toggles a light switch
side is only valid in version 20111201 and newer
whenever a player uses a platform switch
not called when a projectile (e.g., fists) toggles a platform switch
side is only valid in version 20111201 and newer
whenever a projectile toggles a switch
whenever a player starts using a terminal
whenever a player stops using a terminal
whenever a player uses a pattern buffer
whenever a player picks up an item
also whenever a player gets an item when a script calls .items.add()
whenever a light is activated or deactivated
whenever a platform is activated or deactivated
whenever a player revives (presumably only happens in a netgame)
whenever a player dies
whenever a player has taken damage, but before he dies if applicable. The player's suit energy or oxygen may be negative when this trigger is called; if it still is when the trigger returns, it will be set to 0. The player's suit energy is tested again after this trigger returns, so a script may prevent a player's death
whenever a monster is damaged, but before it dies if applicable. The monster's vitality may be negative when this trigger is called. Ther monster's vitality will be tested again after this trigger returns, so a script may prevent a monster's death
whenever a monster dies
called after a monster has taken lethal damage, but before it's removed from the monster list
you can use this to find out when a monster created with new_monster dies, but a monster discovered by Polygons.monsters() may have already taken lethal damage, so you may need to check for that case when using Polygons.monsters()
whenever an item is created and placed on the ground (or floating) somewhere
does not trigger on initial item placement because the initial item placement is done before Lua becomes initialised.
whenever a projectile is created
whenever a projectile detonates, after it has done any area of effect damage
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.
Unless otherwise specified, these tables are only valid inside the trigger calls listed above. Attempting to use them in the main body of a script may cause an error in this version or a future version of Aleph One.
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"
Each table has a read-only .index variable, that corresponds to the engine's internal index.
=Players[0].index
0
Aleph One installs a set of boolean functions that can be used to recognize each of the userdata table types. For example, is_monster(Monsters[1]) returns true. Each of these functions begins with the "is_" prefix.
number of map annotations
iterates through all annotations
returns a new annotation
polygon this annotation is associated with
can be nil
an annotation is only shown when its polygon is visible on the overhead map
annotation text (64 characters max)
number of cameras
iterates through all cameras
returns a new uninitialized camera
make sure to add path points and angles before activating the camera
activate camera for player
deletes all path points and angles
deactivates camera
adds a path angle
adds a path point
maximum number of effects
iterates through all valid effects
returns a new effect
removes effect from map
direction effect is facing
play sound coming from this effect
polygon the effect is in
sets position of effect
type of effect
number of endpoints in level
iterates through all endpoints in the level
whether dead players drop items
the difficulty level
returns a random number between 0 and n-1 from Aleph One's original random number generator
the game kill limit, or 0 if there is none
whether monsters spawn or not; in a net game, this corresponds to the "Aliens" checkbox
this can suppress initial monster placement, if set to false directly when the script is loaded
When true, the current item counts on the map are updated properly when Lua deletes map items and changes player inventories. This defaults to false to preserve film playback with older scripts. New scripts that manipulate items should always set this to true.
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")
Use this variable to override the game's default scoring behavior. If set to false, the game will not end due to a score limit. If set to true, the game ends immediately. If left unset or if set to nil, the game will end if a score limit is reached. (Note that you cannot prevent the game from ending due to a time limit.)
returns a random number between 0 and n-1 from Aleph One's original random number generator
this is a good way to put net games out of sync
returns a random number between 0 and n-1 using a good random number generator
tries to restore any Player or Game custom fields from before the last level jump; returns true if custom fields were successfully restored
if successful, overwrites all existing Player or Game custom fields
tries to restore any custom fields from the saved game; returns true if custom fields were successfully restored
if successful, overwrites all existing custom fields
saves the game (as if the user had activated a pattern buffer)
solo only
ticks since game started
whether the game is EMFH, KOTH, etc.
the date version of the local player's engine
for example, "20071103"
number of saved map objects (of all types)
iterates through all goals
direction goal is facing
polygon the goal is in
ID number of goal
number of map objects in the level
iterates through all item starting locations in the level
direction item is initially facing
whether item location z is from ceiling
whether item will teleport in
item starting location polygon
type of item
maximum number of map objects
iterates through all valid items
returns a new item
removes item from map
direction item is facing
play sound coming from this item
polygon the item is in
sets position of item
type of item
returns whether level is finished, unfinished, or failed
check this in Triggers.cleanup() to determine whether the player(s) teleported out
whether level has extermination flag set
whether level has exploration flag set
whether fog is present
whether fog affects landscapes
values range from 0.0 to 1.0
blue
green
red
fog depth in WU
whether level is low gravity
whether level is magnetic
level name
level index in the map file (starting from 0)
checksum of map file
whether level is rebellion
whether level has repair flag set
whether level has rescue flag set
whether level has retrieval flag set
whether level is vacuum
number of lights in level
iterates through all lights in the level
returns a new light
whether light is active
tag of light
phase the light starts with
whether the light was initially active
current intensity for this light (range: 0-1)
random intensity change for this state
random period change for this state
intensity for this state
light function for this state
period for this state
number of lines in level
iterates through all lines in the level
polygon on clockwise side of line
clockwise side of line
polygon on counterclockwise side of line
counterclockwise side of line
returns line endpoint n
whether one of the line's sides has a transparent texture
height of higher adjacent polygon floor
the length of this line
this might not be accurate, if someone used Chisel's stretch plugin
height of lower adjacent polygon ceiling
whether line is solid
whether line is revealed on local player's automap
number of media (liquids) on the level
iterates through all media on the level
direction of media
height of media
high tide of media
light that controls this media's tide
low tide of media
speed of media
type of media
type of media
number of map objects in the level
iterates through all monster starting locations in the level
whether monster is activated by sight
whether monster is activated by sound
direction monster is initially facing
whether monster location z is from ceiling
whether monster will teleport in when activated
monster starting location polygon
type of monster
maximum number of monsters
iterates through all valid monsters (including player monsters)
returns a new monster
accelerates monster
current AI action of the monster
whether monster has been activated
instructs monster to attack target
damages monster
if no type is specified, fist damage is dealt
monster's current external velocity (always in the opposite direction of facing)
direction the monster is facing
the monster's vitality
monsters that haven't spawned or teleported in yet don't have vitality
current AI mode of the monster
instructs monster to move to polygon
monsters get distracted easily en route
once it gets there, it probably won't choose to stay
if monster is a player monster, the player; otherwise, nil
plays sound coming from this monster
polygon this monster is in
sets position of monster
type of monster
whether monster is still valid
monster's current vertical external velocity
whether monster is visible (e.g. has teleported in)
this has nothing to do with whether monsters are cloaked (like invisible S'pht) or not
only writable before the monster is activated
clears the level playlist
fades out the currently playing track and clears the playlist
appends all of the specified tracks to the end of the playlist
stops level music and clears the playlist
for every track passed, return true if it exists and is playable and false otherwise
number of platforms on the level
iterates through all platforms in the level
whether platform is currently active
current ceiling height of platform
direction platform is moving or will move when active
platform is a door
direction platform is moving or will move when active
current floor height of platform
platform is locked
this flag doesn't actually do anything
whether platform can be controlled by monsters
whether platform can be controlled by players
polygon of this platform
platform is secret
secret platforms aren't shown on the overhead map
platform speed
type of this platform
the only thing the engine uses type for is the platform's sound
number of map objects in the level
iterates through all player starting locations in the level
player starting location facing
whether player starting location z is from ceiling
polygon player starting location is in
which team starts at this player starting location
number of players in the game
iterates through all players in the game
prints message to all players' screens
accelerates player
only valid when read/written in idle()
disabled when the player is viewing a terminal
latched action flags are only true the first tick the key is held down
respawns, or activates platforms/doors/control panels
latched
switches to previous weapon
latched
switches to next weapon
latched
fires primary trigger
activates the net mic
can not be set to true; can be set to false
fires secondary trigger
toggles the overhead map
latched
activates terminal
color of player (shirt color, if teams are enabled)
turns all compass quadrants off, disables beacon
turns all compass quadrants on, disables beacon
whether to use the beacon
whether Lua is controlling the compass
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
beacon location
beacon location
whether crosshairs are visible
if you wish to stop the user from toggling the crosshairs, you must set the state every tick
inflicts damage on player
whether player is dead
deaths not caused by players
direction player is facing
whether player dropped out of the game
amount of suit energy player has (150 is normal red health)
angle player is looking up or down
extravision time remaining
whether player is standing in liquid
fades player's screen
if player is in range of a platform or control panel, returns a platform or side; otherwise returns nil
you can check the type of the return with is_polygon() and is_side()
returns t, x, y, z, polygon, where t is the side, polygon_floor, polygon_ceiling, monster, scenery, or polygon (if the target is the surface of a liquid) the player is looking at; and x, y, z, and polygon are the point the player is looking at
you can check the type of t with is_side(), is_polygon_floor(), is_polygon_ceiling(), is_monster(), is_scenery(), and is_polygon()
whether player is completely below liquid
infravision time remaining
player's forward velocity
player's perpendicular (sidestep) velocity
invincibility time remaining
invisibility time remaining
player will become subtly invisible if this is set higher than the standard invisibility duration (70 seconds)
how many of item the player is carrying
true if this player is the local player
normally, you shouldn't need this--you'll just make the game go out of sync
kill count against slain_player
monster that corresponds to player
whether player can view his motion sensor
currently, this also controls compass visibility
player's name
amount of oxygen player has (max is 10800)
there are 6 overlays, numbered 0 through 5
turns off overlay
text color
fills icon with solid color
icon
text
plays sound that only player can hear
if you want all players to hear the sound as if it is coming from this player, use .monster:play_sound() instead
how many points player has
polygon the player is standing on
if this gives you trouble, try .monster.polygon
set player position
prints message to player's screen
player's team (pants color)
teleports player to polygon
teleports player to level (of course, all the other players will also go to that level)
displays a texture palette instead of the classic HUD
number of slot to highlight
can be nil
how many slots the palette has
there is a maximum of 256 slots
the texture palette is visible whenever the size is greater than 0
rows/columns may change in the future based on the user's screen layout prefs
makes this slot empty
collection of this slot
texture index of this slot
texture type of this slot such as wall or sprite; see "Texture Types"
switch to another player's view
when a player's weapons are not active, he does not see weapons in hand, and can not fire
weapon the player is currently wielding
can be nil
weapon the player wants to switch to
can be nil
how many rounds are currently loaded into the weapon
attempts to force player to ready weapon
weapon the player is currently wielding
can be nil
whether player's sniper zoom is active
number of polygons in the level
iterates through all polygons in the level
returns adjacent polygon n (across from line n), if one exists, or nil
iterates through all polygons directly adjacent to this polygon
the area of this polygon
texture collection
height
texture light
texture bitmap index
texture x offset
texture y offset
texture transfer mode
whether the point is in this polygon
returns endpoint n
iterates through all of this polygon's endpoints
returns the polygon line crossed by line segment (x1, y1) (x2, y2)
can be nil if the line segment doesn't intersect a polygon line
returns polygon line n
iterates through all of this polygon's lines
polygon media (liquid)
iterates through all monsters in this polygon (including player monsters)
raw permutation index of this polygon
plays sound in center of polygon on floor
plays sound at location
if you want to play a sound at an object location, use that object's play_sound function instead
returns polygon side n if it exists
iterates through all of this polygon's sides
polygon type
whether polygon is revealed on local player's automap
center of polygon
center of polygon
shortcut for .floor.height
maximum number of projectiles
iterates through all valid projectiles
returns a new projectile
remember to set the projectile's elevation, facing and owner immediately after you've created it
removes projectile from the map
amount to scale projectile's normal damage by upon detonating
instantaneous downward velocity
vertical angle
direction
plays sound coming from this projectile
sets projectile position
monster that fired projectile, or nil
polygon the projectile is in
target of guided projectile, or nil
type of projectile
maximum number of map objects
iterates through all valid scenery
returns a new scenery
damages scenery
whether this scenery has been damaged
removes scenery from the map
direction scenery is facing
play sound coming from this scenery
polygon the scenery is in
sets position of scenery
whether this scenery is solid
type of scenery
number of sides on the level
iterates through all sides on the level
creates a new side
side must not already exist
nil if the side is not a control panel
set to true or false to create/destroy a control panel 20080707
whether projectiles destroy this switch
switch can only be activated if light > 75%
switch can only be toggled by weapons
permutation of control panel
switch is a repair switch
switch is active
type of control panel
i.e. chip insertion
texture collection
whether transparent side is empty
transparent side only
setting empty to false is a no-op; set collection and texture_index instead
texture light
texture bitmap index
texture x offset
texture y offset
texture transfer mode
play sound coming from this side
line this side is attached to
polygon this side is attached to
correct the side type (Forge can generate incorrect side types)
type of side
number of map objects in the level
iterates through all sound objects in the level
whether sound object location z is from ceiling
if sound object uses a light for volume, the light it uses
can be nil if sound object doesn't use light for volume
whether sound object is a platform sound
sound object polygon
type of sound object
volume of sound object from 0.0 to 1.0
can be nil if sound object uses light for volume
tag is active
number of terminal texts in the level
iterates through all terminal texts on the level
The string mnemonics listed below can be used for assignment and as arguments to functions. Additionally, Aleph One's Lua interpreter has been modified so that equality comparisons between userdata types and strings are possible.
For example, this script would move all players on the blue team to the red team: for p in Players() do if p.team == "blue" then p.team = "red" end end And this one would damage all major compilers with 10 points of fusion damage: for m in Monsters() do if m.type == "major compiler" then m:damage(10, "fusion") end end Each type has a read-only .index field, which represents the game's internal index: > =ItemTypes["pistol"].index 1 Each type also has a .mnemonic field, which is handy for finding the mnemonic of a given type: > =MonsterTypes["major compiler"].class.mnemonic compiler You can even use the mnemonic field to customize the mnemonics for your scenario. Note that you can only have one string mnemonic per type index: > WeaponTypes["fist"].mnemonic = "puncher" > =WeaponTypes["puncher"].index 0 > =WeaponTypes["fist"] nil If you do this, you should customize them all at the beginning of the script. Changing mnemonics mid-game will confuse anyone who tries to read your script, and probably yourself as well!
number of bitmaps in collection
bitmap index when control panel is active
class of this control panel type
collection this control panel belongs to
bitmap index when control panel is inactive/destroyed
how many items of this type are placed in the level during initial placement
maximum number of this type of item in the level and in player inventories
minimum number of this type of item in the level and in player inventories
chance from 0 to 1.0 this item will appear in a respawn period
whether items of this type spawn in random locations
total number of items of this type that can be spawned in this level
-1 means infinite items are available
setting this to anything but -1 will only be effective if changed immediately when the script runs, before item placement is done
monster will try an attack immediately
monster cannot be skipped during placement
class of monster type
whether monster class is an enemy
whether monster class is a friend
type of effect generated when monster gets hit by a bleeding projectile
whether monster type is immune to damage type
how many monsters of this type are placed in the level during initial placement
height of monster
type of item the monster drops when it dies
monster is major
maximum number of this type of monster in the level
minimum number of this type of monster in the level
monster is minor
type of effect generated when monster gets hit by a melee projectile
radius of monster
chance from 0 to 1.0 this monster will appear in a respawn period
whether monsters of this type spawn in random locations
total number of monsters of this type that can be spawned in this level
-1 means infinite monsters are available
setting this to anything but -1 will only be effective if changed immediately when the script runs, before monster placement is done
whether monster type has a weakness to damage type
monster will sit and fire if he has a clear shot
--[[
This is an example of an icon in the format used by Aleph One's overlay
functions.
The first characters are a digit string describing the number of colors. (in
this example, it's 7.
The first character that is not a digit is ignored, as are all the characters
following it that are the same character. (i.e. I could use a q instead of a
newline here.
Then, for every color, it reads a character, followed by a six-digit hex
string, which is the HTML-style color corresponding to that character in the
image. After reading this string, it ignores the next character, whatever it
is.
Once it has read every color, it reads all the following characters, and for
every character it reads for which a color has defined, it puts that color into
the icon as the next pixel. Other characters are ignored. (see below.)
Icons are always 16x16.
]]
[[
7
0000FF
#000000
.FFFFFF
$7FAE20
%EBD52A
,45983C
*5B4714
*************# The fact
*************# that it
*$$$#*********# ignores
$$$$$#********# characters
$$$$$#$$******# that
$$##$##$$*****# are
$$$$##.#$$#**# not colors
$%%$$#.,#$#**# can be
%%%%%%##,#$$# exploited to interesting
%%%%%%%##$$# effect by a sufficiently
#%%%%%%%$$$$# resourceful and obnoxious
*##%%%%%%$$$$###
#**#%%#%%%###**#
*#*##%%#%%$$$$# person
**# #%%##%$$# such as
**# #%%%#%$# myself :)
Additionally, once it has read 256 valid characters, it ignores the rest of the
string.
]]