Aleph One Lua Scripters' Guide

Document created: July 10, 2003, by James Willson
Revised: September 5, 2003
Posted on web: May 23, 2005, by Bill Catambay

Known Contributors:


0.0 General

0.1 What is This?

This is a reference for writing lua scripts to work in A1.
At the time of creation, it lists every trigger and function available to lua scripts.
It is expected that lua functionality will grow in A1, 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 for that.

0.2 Units

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

1.0 Triggers

These are functions scripts can define which A1 will call at specific times or events.


At beginning of level.


At end of the level.
Primarily this is intended as a last chance for changing netgame scores before the postgame report.


At each tick.

start_refuel(type, player, side_index)

Whenever a player starts to use a refuel panel.

end_refuel(type, player, side_index)

Whenever a player stops using a refuel panel.

tag_switch(tag, player)

Whenever a player uses a tag switch.
Not called when a projectile (e.g., fists) uses a tag switch.

light_switch(light, player)

Whenever a player uses a light switch.
Not called when a projectile (e.g., fists) uses a light switch.

platform_switch(platform, short player)

Whenever a player uses a platform switch.
Not called when a projectile (e.g., fists) uses a platform switch.

terminal_enter(terminal_id, player)

Whenever a player starts using a terminal.

terminal_exit(terminal_id, player)

Whenever a player stops using a terminal.

pattern_buffer(buffer_id, player)

Whenever a player uses a pattern buffer.

got_item(type, player)

Whenever a player picks up an item.
Also whenever a player gets an item when a script calls add_item().


Whenever a light is activated or deactivated.


Whenever a platform is activated or deactivated.


Whenever a player revives. (Presumably only happens in a netgame)
Not called when a player first enters into a level.

player_killed(player, aggressor_player, action, projectile)

Whenver a player dies.
aggressor_player is the player index of who killed em, possibly emself, or -1 if killed by non-player.
There are no mnemonics for "action" at this time, making its use difficult.
projectile is the projectile that delivered the final blow, or -1 if there is no such projectile.

player_damaged(victim_player_index, aggressor_player_index, aggressor_monster_index, damage_type, damage_amount, projectile)

Whenever a player has taken damage, but before he dies if applicable.
aggressor_player_index will be -1 if the victim was damaged by a non-player.
aggressor_monster_index will be -1 if the victim was damaged by neither a player nor a monster.
damage_type is one of the Damage Types, e.g. _damage_fusion.
damage_amount is the amount recently subtracted from the player. If _damage_oxygen_drain, damage_amount was
assessed against player's oxygen; else against player's suit energy.
projectile is the projectile that delivered the damage, or -1 if there is no such projectile.
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.

2.0 A1 Functions

These are functions defined in A1 which scripts can call.

2.1 Players

number_of_players ()

Returns the number of players in the game.

inflict_damage(player, amount [, type])

Inflicts damage on player.
"amount" is how much damage is dealt; type is the damage type used.
If no type is specified, crusher damage is dealt.


Returns the shield/oxygen level of player.

set_life(player, shield)

Sets the shield level of player to the amount specified or triple energy (full purple), whichever is less.

set_oxygen(player, oxygen)

Sets the oxygen level of player to the amount specified or one full tank, whichever is less.

get_player_position (player)

Returns three values - the x, y, and z coordinates of player in W.U.

get_player_polygon (player)

Returns the polygon player is standing on.

get_player_angle (player)

Return both the facing (yaw) and the elevation (pitch) of player.

get_player_team (player)

Returns the team of player.

get_player_name (player)

Returns the name of player.

player_is_dead (player)

Returns true if player is dead, false if alive.

select_weapon(player, type)

Attempt to force player to ready the specifiec weapon.

player_control (player, move_type, value)

(jkvw: not sure how this works)
tiennou: In fact you can use it, but it's behavior is not really useful, and it's pretty hard to have a viable script with it. It's use is like "tell 'player' to 'move_type' by 'value' steps" (altought steps is not appropriate...)

teleport_player (player, poly)

Teleports player to poly, similarly to using a teleporter

teleport_player_to_level (player, level)

Teleports player to level. Of course, all the other players will also go to that level.
(Note from tiennou: I'm not sure this actually work correctly, because the level index could be off by one... If anyone ever use this thing, tell me if it goes wrong)
(jkvw: Also be aware that the life of a script expires when you change levels. (regardless of whether it was initiated by mml or network gather dialog))


Enable/Disable a player. The player cannot move...

player_to_monster (player)

Returns the monster index of player.

local_player ()

Returns the index of the local player.
In the normal case, you shouldn't needed this.
You'll just make the game go out of sync.

(jkvw: internal velocity is movement caused by the player running or sidestepping. Everything else is external velocity.)

get_player_external_velocity (player)
set_player_external_velocity (player, x, y, z)

Gets/Sets the x, y, and z components of the player's external velocity.

add_to_player_velocity (player, x, y, z)

Adds the vector defined by x, y, and z to the player's external velocity.

accelerate_player (player, vertical_velocity, angle, velocity)

Gives the player a burst of acceleration.

2.2 Monsters

new_monster (type, poly [, facing [, height]])

Creates a new monster of the chosen type in poly.
Facing is in degrees. (default 0)
Height is distance above the poly floor. (default 0)
Returns the new monster's monster index.
(Make sure another monster of the same type is already present on the map)

activate_monster (monster)
deactivate_monster (monster)

Activates/Deactivates monster

damage_monster (monster, amount [, type])

Inflicts damage on monster.
"amount" is how much damage is dealt; type is the damage type used.
If no type is specified, fist damage is dealt.

attack_monster (attack_monster, target_monster)

Instructs attack_monster to attack target_monster.

move_monster (monster, poly)

Instructs monster to move to poly.
Once it gets there, it probably won't choose to stay.

select_monster (type, poly)

If there is a monster of type in poly, then returns the index of such a monster.

get_monster_position (monster)
get_monster_facing (monster)
get_monster_polygon (monster)

Returns the position/angle/polygon of monster.

get_monster_immunity (monster, type)
set_monster_immunity (monster, type, state)

Sets/Queries monster's immunity to type damage.

get_monster_weakness (monster, type)
set_monster_weakness (monster, type, state)

Sets/Queries monster's weakness to type damage.

get_monster_friend (monster, type)
set_monster_friend (monster, type, state)

Sets/Queries monster's friendliness to monsters of class type.

get_monster_enemy (monster, type)
set_monster_enemy (monster, type, state)

Sets/Queries monster's "enemyness?" to monsters of class type.

get_monster_item (monster)
set_monster_item (monster, type)

Sets/Queries the item monster drops when it dies.
Set it to -1 for none.

get_monster_vitality (monster)
set_monster_vitality (monster)

Sets/Queries the vitality of monster.
A monster's vitality is none (-1) before it gets activated. Make sure the monster you modify was already activated...

get_monster_action (monster)

Queries the current AI action of monster.

get_monster_mode (monster)

Queries the current AI mode of monster.

2.3 Items

new_item (type, poly [, height])
Creates a new monster of the chosen type in poly.
Height is distance above the poly floor. (default 0)
Returns the new item's item index.
(Currently no function makes use of item indicies)

add_item (player, type)

Attempts to give one item of the specified type to player.
Uses marathon's rules for item aquisition.
(for example, you can't use this to give a player a third shotgun
or more ammo than e is allowed to carry.)
Can be used to give players items that don't normally appear in inventory.
(such as invisibility)

remove_item (player, type)

Takes away one item of the specified type from player.
This only works for items that appear in inventory.
(jkvw: Bad things happen when you try to gank balls with this. Use destroy_ball for that.)

count_item (player, type)

Returns the number of items of the specified type player has ininventory.
(jkvw: In some cases this will return -1, not 0, if a player has none of the specified item. (I've observed this with balls and with dead players))

destroy_ball (player)

If player is carrying a ball, this destroys it.
Otherwise, it does nothing.

2.4 Tags

get_tag_state (tag)

Returns true iff there exists a platform or light which is both active and is associated with the chosen tag.

set_tag_state (tag, state)

Activate/Deactivate all lights and platforms associated with tag

2.5 Lights

set_light_state (light, state)

Activate or deactivate light depending on state.

get_light_state (light)

Return true if light is active; false if inactive.

2.6 Polygons

get_polygon_floor_height (poly)
get_polygon_ceiling_height (poly)
set_polygon_floor_height (poly, height)
set_polygon_ceiling_height (poly, height)

Sets/Queries the floor/ceiling height of poly.
(jkvw: Is changing poly floor/ceiling heights on the fly a good idea)
(tiennou: There is no real problem with changing, the only thing I was able to see is texture misalignement... You can also use this to make platform with both floor & ceiling moving)
(jkvw: A careless mapmaker may create an untextured wall with this, too. But yeah, using this is fine.)

number_of_polygons ()

Returns the number of polygons in the map.

2.7 Platforms

set_platform_state (poly, state)

If poly is a platform, activate or deactivate it depending on state.

get_platform_state (poly)

If poly is a platform, return true if active; false if inactive.

set_platform_player_control (poly, state)
get_platform_player_control (poly)

Sets/Queries the "player controllable" flag.

set_platform_monster_control (poly, state)
get_platform_monster_control (poly)

Sets/Queries the "monster controllable" flag.

set_platform_speed (poly, speed)
get_platform_speed (poly)

Sets/Queries the platforms speed.

set_platform_movement (poly, state)
get_platform_movement (poly)

Sets/Queries the current moving state of the platform. Extending is true, contracting is false...

get_platform_floor_height (poly)
get_platform_ceiling_height (poly)
set_platform_floor_height (poly, height)
set_platform_ceiling_height (poly, height)

These operate on the platform's heights.
(that is, not on the polygon floor/ceiling, but the position of the platform itself)

2.8 Camera


Adds a new Lua camera.

add_path_point(camera_index, polygon, point_x, point_y, point_z)

Add a point 'x,y,z' to camera 'camera_index' and put it in 'polygon'.

add_path_angle(camera_index, yaw, pitch, time)

Adds an angle 'yaw,pitch' to camera 'camera_index' with 'time'.
(tiennou: someone who knows what is the 'time' argument write something more useful here...)

activate_camera(player, camera_index)

Starts the camera 'camera_index' for player. Works only on local player.

deactivate_camera(player, camera_index)
Stops the camera 'camera_index' for player. Only useful on local player.

2.9 Display

(jkvw: Don't be scared off by "working only on local player" - these operate correctly, just in a roundabout way. A1 compares the player index passed in to the local player index, calling the appropriate funciton if the indicies are the same. (and does nothing otherwise) So in a net game, screen_print(2, "hi") ends up printing "hi" to player 2 and doing nothing for the other players.)

screen_print([player,] message)

Prints message on the screen of player.
If no player is specified, prints to everyone.
Works only on local player.

screen_fade([player,] fade)

Make the fade 'fade_index' start for player.
If no player is specified, fades for everyone.
Works only on local player.

set_motion_sensor_state (player, state)

Turn on/off the motion sensor for player. Works only on local player.

get_motion_sensor_state (player)

Returns true if player's motion sensor is enabled, false if it is disabled. Works only on local player.


Hides/Shows the HUD of player. Works only on local player.

set_fog_color(r, g, b)
set_underwater_fog_color(r, g, b)

(tiennou: actually, fog is broken, but those specify the fog parameters (color & depth)

set_crosshairs_state(player, state)

Gets/Sets the crosshairs state for player. Works only on local player.

set_zoom_state(player, state)

Gets/Sets the tunnel (sniper-mode) vision for player. Works only on local player.

2.10 Scoring

(jkvw: different game types are scored differently.
Time based games have scores in units of ticks.
Every Man For Himself doesn't use network score at all - it relies on kills)

award_points (player, amount)

Increases player's network game score by amount.
Negative values take points away.

award_kills (aggressor_player, slain_player, amount)

Increases aggressor_player's kill count against slain_player by amount.
Negative values take kills away.
Setting agressor_player and slain_player the same awards suicides.
These changes will affect slain_player's death count.

set_points (player, amount)

Sets player's network game score to amount.

set_kills (aggressor_player, slain_player, amount)

Sets aggressor_player's kill count against slain_player.
If aggressor_player and slain_player are the same, it sets suicides.
This will affect slain_player's death count.

get_points (player)

Returns player's network game score.

get_kills (aggressor_player, slain_player)

Returns the kill count of aggressor_player against slain player.
And of course, if they are the same, it returns the number of suicides.

2.11 Compass

use_lua_compass ([player,] state)

Set who controls where the network compass points, either lua or normal network rules.
If player is specified, change only applies to that player.

set_lua_compass_state (player, compass_direction)

Points player's compass in the specified directon. (if the lua compass is enabled)
The special value _network_compass_use_beacon doesn't point the compass in a specific direction;
it tells the lua compass to point at the location specified by set_lua_compass_beacon.
The "single wedge" mneumonics can be added to get bigger wedges.
(so to point compass N you can do _network_compass_nw + _network_compass_ne)

set_lua_compass_beacon (player, x, y)

Points player's compass towards the location x, y.
(if the lua compass is enabled and _network_compass_use_beacon is set for that player's lua compass state)

2.12 Projectiles

get_projectile_type (projectile)

Returns the projectile's type.

2.13 Other

global_random ()

Returns a random number from A1's global random number generator.
(jkvw: so for a random integer in [0, n-1], you can do "math.mod (global_random (), n)")
This is preferred over random number functionality from lua.
(jkvw: Using lua's functions you may get out of sync in net games and incorrect film playback.)

local_random ()

Returns a random number from A1's local random number generator.
This is a good way to put net games out of sync.

get_terminal_text_number (poly, line)

Return the permutation field (the terminal script ID) of the terminal of the line contained in poly.

set_terminal_text_number (poly, line, terminal_text_id)

Sets the permutation field (the terminal script ID) of the terminal of the line contained in poly to terminal_text_id. It can be used to display multiple terminal messages without having to add hundred of terminals hidden behind the first...

play_sound(player, sound, pitch)

Plays sound to player at pitch. See the mnemonics for the sound list


Stops the execution of the script.
(No more triggers will activate, but whichever one called kill_script() will continue normally.)

3.0 Mnemonics

Symbols for referring to A1 item types, monster types, and such.

3.1 Items


3.2 Monsters


3.3 Monster Classes


3.4 Damage Types


3.5 Monster Actions


3.6 Monster Modes


3.7 Faders


3.8 Sounds


3.9 Refuel Panels


3.10 Compass Directions


3.11 Projectile Types