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 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 every second:

tick = 0

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