New Lua API - UberWaffe/OpenRA GitHub Wiki
This is an automatically generated lising of the new Lua map scripting API, generated for playtest-20140709 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 of 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 explose a collection of properties and commands that query information of modify their state. The properties and commands available on each actor depends on the traits that the actor specifies in its rule definitions.
| 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 definite initial parameters for the actor's traits. |
| int CruiseAltitude(string type) | Returns the cruise altitude of the requested unit type (zero if it 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. |
| Map | |
|---|---|
| LuaTable ActorsInCircle(WPos location, WRange radius, LuaFunction filter) | Returns a table of all actors within the requested region, filtered using the specified function. |
| 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 |
| LuaTable 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. |
| Player | |
|---|---|
| Player GetPlayer(string name) | Returns the player with the specified internal name, or nil if a match is not found. |
| LuaTable GetPlayers(LuaFunction filter) | Returns a table of players filtered by the specified function. |
| Trigger | |
|---|---|
| void AfterDelay(int delay, LuaFunction func) | Call a function after a specified delay. The callback function will be called as func(). |
| void OnAllKilled(LuaTable 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 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). |
| 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 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 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). |
| Utils | |
|---|---|
| bool All(LuaTable table, LuaFunction func) | Returns true if func returns true for all values in table. |
| bool Any(LuaTable table, LuaFunction func) | Returns true if func returns true for any value in table. |
| WPos CenterOfCell(CPos cell) | Returns the center of a cell in world coordinates. |
| void Do(LuaTable table, LuaFunction func) | Calls a function on every value in table. |
| LuaTable ExpandFootprint(LuaTable cells, bool allowDiagonal) | Expands the given footprint one step along the coordinate axes, and (if requested) diagonals |
| LuaValue Random(LuaTable table) | Returns a random value from table. |
| int RandomInteger(int low, int high) | Returns a random integer x in the range low <= x < high. |
| WPos | |
|---|---|
| WPos New(int x, int y, int z) | Create a new WPos with the specified coordinates. |
| WPos Zero { get; } | The world coordinate origin. |
| WVec | |
|---|---|
| WVec New(int x, int y, int z) | Create a new WVec with the specified coordinates. |
| WVec Zero { get; } | The world zero-vector. |
| Combat | |
|---|---|
|
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: IMove, AttackBase |
|
void Hunt()
Queued Activity |
Seek out and attack nearby targets.
Requires Traits: IMove, AttackBase |
| General | |
|---|---|
|
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. |
| 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 Invulnerable { get; set; } |
Set or query unit invulnerablility.
Requires Trait: ScriptInvulnerable |
| bool IsDead { get; } |
Specifies whether the actor is alive or dead.
Requires Trait: Health |
| 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. |
| CPos Location { get; } | The actor position in cell coordinates. |
| int MaxHealth { get; } |
Maximum health of the actor.
Requires Trait: Health |
| Player Owner { get; } | The player that owns the actor. |
| string Stance { get; set; } | Current actor stance. Returns nil if this actor doesn't support stances. |
| void Stop() | Attempt to cancel any active activities. |
|
void Teleport(CPos cell)
Queued Activity |
Instantly moves the actor to the specified cell. |
|
void Wait(int ticks)
Queued Activity |
Wait for a specified number of game ticks (25 ticks = 1 second). |
| 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 ScriptedMove(CPos cell)
Queued Activity |
Moves within the cell grid, ignoring lane biases.
Requires Trait: Mobile |
| Production | |
|---|---|
|
void Produce(string actorType, string raceVariant = )
Queued Activity |
Build a unit, ignoring the production queue. The activity will wait if the exit is blocked
Requires Trait: Production |
| 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 |
| 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: Cargo, ParaDrop |
|
void UnloadPassengers()
Queued Activity |
Command transport to unload passengers.
Requires Trait: Cargo |
| 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 |