Lua API

This is an automatically generated listing of the new Lua map scripting API, generated for release-20141029 of OpenRA.

OpenRA allows custom maps and missions to be scripted using Lua 5.1. These scripts run in a sandbox that prevents access to unsafe functions (e.g. OS or file access), and limits the memory and CPU usage of the scripts.

You can access this interface by adding the LuaScript trait to the world actor in your map rules (note, you must replace the spaces in the snippet below with a single tab for each level of indentation):

Rules:
	World:
		LuaScript:
			Scripts: myscript.lua

Map scripts can interact with the game engine in three ways:

• Global tables provide functions for interacting with the global world state, or performing general helper tasks. They exist in the global namespace, and can be called directly using <table name>.<function name>.
• Individual actors expose a collection of properties and commands that query information or modify their state.
  • Some commands, marked as queued activity, are asynchronous. Activities are queued on the actor, and will run in sequence until the queue is empty or the Stop command is called. Actors that are not performing an activity are Idle (actor.IsIdle will return true). The properties and commands available on each actor depends on the traits that the actor specifies in its rule definitions.
• Individual players expose a collection of properties and commands that query information or modify their state. The properties and commands available on each actor depends on the traits that the actor specifies in its rule definitions.

Global Tables

Actor
int BuildTime(string type)	Returns the build time (in ticks) of the requested unit type.
Actor Create(string type, bool addToWorld, LuaTable initTable)	Create a new actor. initTable specifies a list of key-value pairs that defines the initial parameters for the actor's traits.
int CruiseAltitude(string type)	Returns the cruise altitude of the requested unit type (zero if it is ground-based).

Camera
WPos Position { get; set; }	The center of the visible viewport.

CPos
CPos New(int x, int y)	Create a new CPos with the specified coordinates.
CPos Zero { get; }	The cell coordinate origin.

CVec
CVec New(int x, int y)	Create a new CVec with the specified coordinates.
CVec Zero { get; }	The cell zero-vector.

DateTime
int GameTime { get; }	Get the current game time (in ticks)
bool IsHalloween { get; }	True on the 31st of October.
int Minutes(int minutes)	Converts the number of minutes into game time (ticks).
int Seconds(int seconds)	Converts the number of seconds into game time (ticks).

Map
Actor[] ActorsInBox(WPos topLeft, WPos bottomRight, LuaFunction filter = nil)	Returns a table of all actors within the requested rectangle, filtered using the specified function.
Actor[] ActorsInCircle(WPos location, WRange radius, LuaFunction filter = nil)	Returns a table of all actors within the requested region, filtered using the specified function.
WPos BottomRight { get; }	Returns the location of the bottom-right corner of the map.
WPos CenterOfCell(CPos cell)	Returns the center of a cell in world coordinates.
string Difficulty { get; }	Returns the difficulty selected by the player before starting the mission.
bool IsNamedActor(Actor actor)	Returns true if actor was originally specified in the map file.
bool IsSinglePlayer { get; }	Returns true if there is only one human player.
Actor NamedActor(string actorName)	Returns the actor that was specified with a given name in the map file (or nil, if the actor is dead or not found).
Actor[] NamedActors { get; }	Returns a table of all the actors that were specified in the map file.
CPos RandomCell()	Returns a random cell inside the visible region of the map.
CPos RandomEdgeCell()	Returns a random cell on the visible border of the map.
WPos TopLeft { get; }	Returns the location of the top-left corner of the map.

Media
void DisplayMessage(string text, string prefix = Mission)	Display a text message to the player.
void PlayMovieFullscreen(string movie, LuaFunction func = nil)	Play a VQA video including the file extension.
void PlaySoundNotification(Player player, string notification)	Play a sound listed in notifications.yaml
void PlaySpeechNotification(Player player, string notification)	Play an announcer voice listed in notifications.yaml

Player
Player GetPlayer(string name)	Returns the player with the specified internal name, or nil if a match is not found.
Player[] GetPlayers(LuaFunction filter)	Returns a table of players filtered by the specified function.

Reinforcements
Actor[] Reinforce(Player owner, String[] actorTypes, CPos[] entryPath, int interval = 25, LuaFunction actionFunc = nil)	Send reinforcements consisting of multiple units. Supports ground-based, naval and air units. The first member of the entryPath array will be the units' spawnpoint, while the last one will be their destination. If actionFunc is given, it will be executed once a unit has reached its destination. actionFunc will be called as actionFunc(Actor actor)
LuaTable ReinforceWithTransport(Player owner, string actorType, String[] cargoTypes, CPos[] entryPath, CPos[] exitPath = nil, LuaFunction actionFunc = nil, LuaFunction exitFunc = nil)	Send reinforcements in a transport. A transport can be a ground unit (APC etc.), ships and aircraft. The first member of the entryPath array will be the spawnpoint for the transport, while the last one will be its destination. The last member of the exitPath array is be the place where the transport will be removed from the game. When the transport has reached the destination, it will unload its cargo unless a custom actionFunc has been supplied. Afterwards, the transport will follow the exitPath and leave the map, unless a custom exitFunc has been supplied. actionFunc will be called as actionFunc(Actor transport, Actor[] cargo). exitFunc will be called as exitFunc(Actor transport).

Trigger
void AfterDelay(int delay, LuaFunction func)	Call a function after a specified delay. The callback function will be called as func().
void Clear(Actor a, string triggerName)	Removes the specified trigger from this actor.Note that the removal will only take effect at the end of a tick, so you must not add new triggers at the same time that you are calling this function.
void ClearAll(Actor a)	Removes all triggers from this actor.Note that the removal will only take effect at the end of a tick, so you must not add new triggers at the same time that you are calling this function.
void OnAddedToWorld(Actor a, LuaFunction func)	Call a function when this actor is added to the world. The callback function will be called as func(Actor self).
void OnAllKilled(Actor[] actors, LuaFunction func)	Call a function when all of the actors in a group are killed. The callback function will be called as func().
void OnAllRemovedFromWorld(Actor[] actors, LuaFunction func)	Call a function when all of the actors in a group have been removed from the world. The callback function will be called as func().
void OnAnyKilled(Actor[] actors, LuaFunction func)	Call a function when one of the actors in a group is killed. The callback function will be called as func(Actor killed).
void OnCapture(Actor a, LuaFunction func)	Call a function when this actor is captured. The callback function will be called as func(Actor self, Actor captor, Player oldOwner, Player newOwner).
void OnDamaged(Actor a, LuaFunction func)	Call a function when the actor is damaged. The callback function will be called as func(Actor self, Actor attacker).
int OnEnteredFootprint(CPos[] cells, LuaFunction func)	Call a function when a ground-based actor enters this cell footprint.Returns the trigger id for later removal using RemoveFootprintTrigger(int id).The callback function will be called as func(Actor a, int id).
int OnExitedFootprint(CPos[] cells, LuaFunction func)	Call a function when a ground-based actor leaves this cell footprint.Returns the trigger id for later removal using RemoveFootprintTrigger(int id).The callback function will be called as func(Actor a, int id).
void OnIdle(Actor a, LuaFunction func)	Call a function each tick that the actor is idle. The callback function will be called as func(Actor self).
void OnInfiltrated(Actor a, LuaFunction func)	Call a function when this actor is infiltrated. The callback function will be called as func(Actor self, Actor infiltrator).
void OnKilled(Actor a, LuaFunction func)	Call a function when the actor is killed. The callback function will be called as func(Actor self, Actor killer).
void OnObjectiveAdded(Player player, LuaFunction func)	Call a function when this player is assigned a new objective. The callback function will be called as func(Player player, int objectiveID).
void OnObjectiveCompleted(Player player, LuaFunction func)	Call a function when this player completes an objective. The callback function will be called as func(Player player, int objectiveID).
void OnObjectiveFailed(Player player, LuaFunction func)	Call a function when this player fails an objective. The callback function will be called as func(Player player, int objectiveID).
void OnPlayerLost(Player player, LuaFunction func)	Call a function when this player fails any primary objective. The callback function will be called as func(Player player).
void OnPlayerWon(Player player, LuaFunction func)	Call a function when this player completes all primary objectives. The callback function will be called as func(Player player).
void OnProduction(Actor a, LuaFunction func)	Call a function when this actor produces another actor. The callback function will be called as func(Actor producer, Actor produced).
void OnRemovedFromWorld(Actor a, LuaFunction func)	Call a function when this actor is removed from the world. The callback function will be called as func(Actor self).
void RemoveFootprintTrigger(int id)	Removes a previously created footprint trigger.

Utils
bool All(LuaValue[] collection, LuaFunction func)	Returns true if func returns true for all elements in a collection.
bool Any(LuaValue[] collection, LuaFunction func)	Returns true if func returns true for any element in a collection.
void Do(LuaValue[] collection, LuaFunction func)	Calls a function on every element in a collection.
CPos[] ExpandFootprint(CPos[] footprint, bool allowDiagonal)	Expands the given footprint one step along the coordinate axes, and (if requested) diagonals.
LuaValue Random(LuaValue[] collection)	Returns a random value from a collection.
int RandomInteger(int low, int high)	Returns a random integer x in the range low <= x < high.
LuaTable Skip(LuaTable table, int numElements)	Skips over the first numElements members of a table and return the rest.

WPos
WPos New(int x, int y, int z)	Create a new WPos with the specified coordinates.
WPos Zero { get; }	The world coordinate origin.

WRange
WRange FromCells(int numCells)	Create a new WRange by cell distance
WRange New(int r)	Create a new WRange.

WVec
WVec New(int x, int y, int z)	Create a new WVec with the specified coordinates.
WVec Zero { get; }	The world zero-vector.

Actor Properties / Commands

Combat
void Attack(Actor target)	Fly an attack against the target actor. Requires Trait: AttackPlane
void AttackMove(CPos cell, int closeEnough = 0) Queued Activity	Move to a cell, but stop and attack anything within range on the way. closeEnough defines an optional range (in cells) that will be considered close enough to complete the activity. Requires Traits: AttackBase, IMove
void Hunt() Queued Activity	Seek out and attack nearby targets. Requires Traits: AttackBase, IMove
void Patrol(CPos[] waypoints, bool loop = True, int wait = 0) Queued Activity	Patrol along a set of given waypoints. The action is repeated by default, and the actor will wait for `wait` ticks at each waypoint. Requires Traits: AttackBase, IMove
void PatrolUntil(CPos[] waypoints, LuaFunction func, int wait = 0) Queued Activity	Patrol along a set of given waypoints until a condition becomes true. The actor will wait for `wait` ticks at each waypoint. Requires Traits: AttackBase, IMove

General
bool AcceptsUpgrade(string upgrade)	Check whether this actor accepts a specific upgrade. Requires Trait: UpgradeManager
void CallFunc(LuaFunction func) Queued Activity	Run an arbitrary Lua function.
WPos CenterPosition { get; }	The actor position in world coordinates.
void Destroy() Queued Activity	Remove the actor from the game, without triggering any death notification.
int Facing { get; }	The direction that the actor is facing.
void GrantTimedUpgrade(string upgrade, int duration)	Grant a limited-time upgrade to this actor. Requires Trait: UpgradeManager
void GrantUpgrade(string upgrade)	Grant an upgrade to this actor. Requires Trait: UpgradeManager
bool HasProperty(string name)	Test whether an actor has a specific property.
int Health { get; set; }	Current health of the actor. Requires Trait: Health
bool IsDead { get; }	Specifies whether the actor is alive or dead.
bool IsIdle { get; }	Specifies whether the actor is idle (not performing any activities).
bool IsInWorld { get; set; }	Specifies whether the actor is in the world.
void Kill()	Kill the actor. Requires Trait: Health
CPos Location { get; }	The actor position in cell coordinates.
int MaxHealth { get; }	Maximum health of the actor. Requires Trait: Health
Player Owner { get; set; }	The player that owns the actor.
void RevokeUpgrade(string upgrade)	Revoke an upgrade that was previously granted using GrantUpgrade. Requires Trait: UpgradeManager
string Stance { get; set; }	Current actor stance. Returns nil if this actor doesn't support stances.
void StartBuildingRepairs(Player repairer = nil)	Start repairs on this building. `repairer` can be an allied player. Requires Trait: RepairableBuilding
void Stop()	Attempt to cancel any active activities.
void StopBuildingRepairs(Player repairer = nil)	Stop repairs on this building. `repairer` can be an allied player. Requires Trait: RepairableBuilding
void Teleport(CPos cell) Queued Activity	Instantly moves the actor to the specified cell.
string Type { get; }	The type of the actor (e.g. "e1").
void Wait(int ticks) Queued Activity	Wait for a specified number of game ticks (25 ticks = 1 second).

Guard
void Guard(Actor targetActor) Queued Activity	Guard the target actor. Requires Traits: IMove, Guard

Harvester
void FindResources() Queued Activity	Search for nearby resources and begin harvesting. Requires Trait: Harvester

Movement
void Move(CPos cell, int closeEnough = 0) Queued Activity	Moves within the cell grid. closeEnough defines an optional range (in cells) that will be considered close enough to complete the activity. Requires Trait: Mobile
void Move(CPos cell) Queued Activity	Fly within the cell grid. Requires Trait: Helicopter
void Move(CPos cell) Queued Activity	Fly within the cell grid. Requires Trait: Plane
void MoveIntoWorld(CPos cell) Queued Activity	Moves from outside the world into the cell grid Requires Trait: Mobile
void Scatter() Queued Activity	Leave the current position in a random direction. Requires Trait: Mobile
void ScriptedMove(CPos cell) Queued Activity	Moves within the cell grid, ignoring lane biases. Requires Trait: Mobile

Production
bool Build(String[] actorTypes, LuaFunction actionFunc = nil)	Build the specified set of actors using a TD-style (per building) production queue. The function will return true if production could be started, false otherwise. If an actionFunc is given, it will be called as actionFunc(Actor[] actors) once production of all actors has been completed. The actors array is guaranteed to only contain alive actors. Requires Traits: ProductionQueue, ScriptTriggers
bool IsPrimaryBuilding { get; set; }	Query or set the factory's primary building status Requires Trait: PrimaryBuilding
bool IsProducing(string actorType)	Check whether the factory's production queue that builds this type of actor is currently busy.Note: it does not check whether this particular type of actor is being produced. Requires Traits: ProductionQueue, ScriptTriggers
void Produce(string actorType, string raceVariant = nil) Queued Activity	Build a unit, ignoring the production queue. The activity will wait if the exit is blocked. Requires Trait: Production
CPos RallyPoint { get; set; }	Query or set a factory's rally point Requires Trait: RallyPoint

Support Powers
void Chronoshift(LuaTable unitLocationPairs, int duration = 0, bool killCargo = False)	Chronoshift a group of actors. A duration of 0 will teleport the actors permanently. Requires Trait: ChronoshiftPower

Transform
void Deploy() Queued Activity	Queue a new transformation. Requires Trait: Transforms

Transports
bool HasPassengers { get; }	Specifies whether transport has any passengers. Requires Trait: Cargo
void LoadPassenger(Actor a)	Teleport an existing actor inside this transport. Requires Trait: Cargo
void Paradrop(CPos cell) Queued Activity	Command transport to paradrop passengers near the target cell. Requires Traits: ParaDrop, Cargo
Actor UnloadPassenger()	Remove the first actor from the transport. This actor is not added to the world. Requires Trait: Cargo
void UnloadPassengers() Queued Activity	Command transport to unload passengers. Requires Trait: Cargo

Player Properties / Commands

Diplomacy
bool IsAlliedWith(Player targetPlayer)	Returns true if the player is allied with the other player.
void SetStance(Player targetPlayer, string newStance)	Changes the current stance of the player against the target player. Allowed keywords for new stance: Ally, Neutral, Enemy.

MissionObjectives
int AddPrimaryObjective(string description) Queued Activity	Add a primary mission objective for this player. The function returns the ID of the newly created objective, so that it can be referred to later.
int AddSecondaryObjective(string description) Queued Activity	Add a secondary mission objective for this player. The function returns the ID of the newly created objective, so that it can be referred to later.
string GetObjectiveDescription(int id) Queued Activity	Returns the description of an objective.
string GetObjectiveType(int id) Queued Activity	Returns the type of an objective.
bool HasNoRequiredUnits() Queued Activity	Returns true if this player has lost all units/actors that have the MustBeDestroyed trait.
bool IsObjectiveCompleted(int id) Queued Activity	Returns true if the objective has been successfully completed, false otherwise.
bool IsObjectiveFailed(int id) Queued Activity	Returns true if the objective has been failed, false otherwise.
void MarkCompletedObjective(int id) Queued Activity	Mark an objective as completed. This needs the objective ID returned by AddObjective as argument. When this player has completed all primary objectives, (s)he has won the game.
void MarkFailedObjective(int id) Queued Activity	Mark an objective as failed. This needs the objective ID returned by AddObjective as argument. Secondary objectives do not have any influence whatsoever on the outcome of the game.

Player
Actor[] GetGroundAttackers()	Returns an array of actors representing all ground attack units of this player.
string Name { get; }	The player's name.

Production
bool Build(String[] actorTypes, LuaFunction actionFunc = nil)	Build the specified set of actors using classic (RA-style) production queues. The function will return true if production could be started, false otherwise. If an actionFunc is given, it will be called as actionFunc(Actor[] actors) once production of all actors has been completed. The actors array is guaranteed to only contain alive actors. Note: This function will fail to work when called during the first tick Requires Traits: ScriptTriggers, ClassicProductionQueue
bool IsProducing(string actorType)	Check whether the production queue that builds this type of actor is currently busy.Note: it does not check whether this particular type of actor is being produced. Requires Traits: ScriptTriggers, ClassicProductionQueue

Resources
int Cash { get; set; }	The amount of cash held by the player. Requires Trait: PlayerResources
int ResourceCapacity { get; }	The maximum resource storage of the player. Requires Trait: PlayerResources
int Resources { get; set; }	The amount of harvestable resources held by the player. Requires Trait: PlayerResources