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 two ways to get a script to run - level specific MML, and selecting a script at the gather network game dialog. To use level specific MML, put the script in a TEXT resource in the map file. Then put in TEXT resource 128 MML telling A1 where to find the script, which in its most basic form is this:
<marathon_levels>
<level index="0">
<lua resource="1000"/>
</level>
</marathon_levels>
By convention we use TEXT resource 1000+x to hold the script for level x, so the first level in the map file (which has level index 0) gets its script in TEXT resource 1000.
This works fine for single player games. It will also work for multiplayer games, but only if every player has a copy of the map file and selects it in enviroment prefs.
To use a script via the network game dialog, put then script in a text file. Then, at the gather network game dialog, select "use script", then select your script file.
When playing network games, even if you are not gathering, it's important not to have a map file with level specific MML selected in your environment prefs, unless it's the map file for the map you are playing. A1 will run the script for that map file, your game will go out of sync, and you'll be unhappy.
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. :)
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 }
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
whenever a player uses a light switch
not called when a projectile (e.g., fists) toggles a light switch
whenever a player uses a platform switch
not called when a projectile (e.g., fists) toggles a platform 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 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 detonates, after it has done any area of effect damage
These are tables (technically, userdata) defined in Aleph One which scripts can use to access objects in the game.
There is one important difference: 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. However, by prepending an underscore, custom fields can be indexed. These custom fields will be associated with the object until it is destroyed.
Each table also has a read-only .index variable that corresponds to the engine's index
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 map objects
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
type of effect
number of endpoints in level
iterates through all endpoints in the level
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
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
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"
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
type of item
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
whether level is rebellion
whether level is vacuum
number of lights in level
iterates through all lights in the level
whether light is active
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
number of media (liquids) on the level
iterates through all media on the level
type of media
maximum number of monsters
iterates through all valid monsters (including player monsters)
returns a new 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
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
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
direction platform is moving or will move when active
current floor height of platform
whether platform can be controlled by monsters
whether platform can be controlled by players
polygon of this platform
platform speed
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
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
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
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
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
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
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
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
type of side
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 1Each type also has a .mnemonic field, which is handy for finding the mnemonic of a given type:
> =MonsterTypes["major compiler"].class.mnemonic compilerYou 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"] nilIf 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
class of monster type
whether monster class is an emeny
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
height of monster
type of item the monster drops when it dies
type of effect generated when monster gets hit by a melee projectile
radius of monster
whether monster type has a weakness to damage type
--[[
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.
]]