AOE2 DE Lua API

Use this guide to write Lua scripts for WololoLabs. Copy a complete example, load it, and then change one small part at a time.

Lua engine version: 1.1.1
Game target: 101.103.54800.0 (#185872 / 25464371)

Version note: This guide describes the API in this application release. Use the guide that ships with the release that you run.

Start here

1. Follow Get started to load one small script.
2. Copy an example that is close to your goal.
3. Read Script callbacks before you keep match state.
4. Use the reference pages for exact arguments and results.
5. Use the API name index when you know part of a name.

The index marks compatibility calls that are not implemented. Check their fixed returns and warning behavior before using an older script or example.

Preferred API style

Write new scripts with global functions for actions and methods on returned values for data. This style keeps scripts short and matches the examples in this guide.

local player = GetAssignedPlayer()
if player ~= nil then
    local selected = player:GetSelectedObject()
    if selected ~= nil then
        UnitsMove({ selected }, Vector2(42, 42))
    end
end

Use : for a method on Player, Object, or MapTile. Use globals such as UnitsMove, RenderText, and GetGameTime for actions and general queries.

The api table remains available for older scripts and a few shortcut queries. It is not the preferred API for new scripts. See Legacy api namespace when you must use it.

API map

Area	Use it for
Commands	Move, train, research, build, or change unit behavior.
Game data and world	Read players, objects, map data, resources, and match state.
Lua values and game objects	Work with Player, Object, MapTile, vectors, and colors.
Rendering	Draw text, shapes, world markers, and minimap markers.
Enumerations	Use named constants for units, technologies, resources, and keys.
Advanced	Use compatibility, diagnostic, and version-sensitive functions.
Unimplemented APIs	Identify placeholders that only log a warning and return a fixed value.

Result rules

Game data can be unavailable during menus, loading, and match transitions. Check each result before you use it.

• Lookups often return nil when no value is available.
• Numeric queries often return 0 when no value is available.
• Collection queries return an empty array when they find nothing.
• A command result of true means that the request entered WololoLabs' queue. It does not prove native submission or that the game completed the action.

Read fresh data on a later Update before you make a dependent decision.

Common Lua shapes

Value	Lua shape
Position	{ x = number, y = number }
World position	{ x = number, y = number, z = number }
Color	{ r = number, g = number, b = number, a = number }
Object list	Dense Lua array. Iterate it with ipairs.
Object, Player, MapTile	Values returned by API queries. Do not construct them.

Use Vector2 and Vector3 when you want a position with distance methods. Use Color for readable color values.