Map scripting

The map scripting feature of OpenRA allows you to create custom shellmaps, minigames, single player/co-op missions and more.

The Lua scripting language is used in OpenRA for scripting maps. There is no need to download Lua from the website; a custom build of Lua is included with recent versions of the game.

Setting up Lua for your map

This guide assumes you have knowledge of creating and editing OpenRA maps (See Mapping).

Lua script code is to be contained in one or more .lua files within the map archive, next to map.yaml and map.bin. All script files for a particular map must be within the map's archive.

To actually have this Lua code executed, you must add a trait to the World actor in map.yaml like so:

World:
	LuaScriptInterface:
		LuaScripts: <filename>, ...

LuaScripts is a list of Lua script filenames. These script files will be loaded when the map is loaded.

In one of the script files you may have a function named WorldLoaded. This function will be called when the game world is loaded. You can place script initialization code that depends on the game state inside this function.

You may also have a function named Tick, called 25 times per second during gameplay if you have implemented it. Try to not have long-running code in this function, because it will hold up the game.

The following code will display "Hello world" in the game once per second:

tick = 0

Tick = function()
	tick = tick + 1
	if tick % 25 == 0 then
		print("Hello world")
	end
end

You can now go ahead and implement your scripts. You should make use of the standard library in this process, which is explained below.

Standard library

OpenRA comes with a suite of standard Lua files that are usable from all scripted maps. It is strongly recommended to use these functions over rolling your own, or your mission may stop working in later OpenRA versions if there are breaking changes.

The standard library is located in mods/common/lua. A short description of each file follows:

• actor.lua - For creating and manipulating game actors.
• map.lua - For working with maps.
• media.lua - For media playback.
• mission.lua - Mission-specific functionality.
• openra.lua - General game engine functionality.
• reinforcements.lua - For working with reinforcements.
• rules.lua - Game rule lookups.
• supportpowers.lua - For working with support powers.
• team.lua - Utilities for collectively manipulating teams of actors.
• utils.lua - Miscellaneous Lua utilities.

TODO: Talk about the functions/tables themselves

Map actor interaction

You can easily interact with placed actors in your map by giving them a name in map.yaml and then referring to them using their names. For example:

map.yaml:

...
FootSoldier: e1
	Location: 49,59
	Owner: Soviets
...
...
World:
	LuaScriptInterface:
		LuaScripts: map.lua

map.lua:

WorldLoaded = function()
	Actor.Scatter(FootSoldier)
end

This will make the map actor named FootSoldier scatter to an adjacent cell immediately after the map is loaded.

Examples

• Red Alert mission 1
• Tiberian Dawn shellmap