Mod API Reference:Client MapLayers

Put the function in a file named Client_MapLayers.lua:

function Client_MapLayers(game, layers)
    local layer = layers.Create('Territory IDs', true);
    for terrID, _ in pairs(game.Map.Territories) do
        layer.AddLabel(terrID, tostring(terrID));
    end
end

Client_Visual draws a visual for one order. This hook instead draws map layers: labels and shapes that stay on the map for as long as the game is open. Examples are territory IDs, zones of control, or a mod's own borders.

Players turn each layer on or off with checkboxes in a "Map layers" dialog, which opens from a button in the game's menu. That button only appears in games where a mod created at least one layer. The device remembers each player's choice for each mod and layer name.

The client calls the hook when the game loads and every time it refreshes, and redraws the layers each time. Turning a layer on or off doesn't run the hook again.

Layers are drawn above territories and bonus links, and below army numbers.

Like Client_Visual, layers are shown in the app and on the website in 3D mode, but not on the website in 2D mode. In 2D mode, the "Map layers" dialog says that layers aren't supported.

Argument	Type	Description
game	ClientGame	Information about the game.
layers	table	The object you create layers with. See below.

layers.Create

layers.Create(name, defaultVisible)

Creates a layer and returns it.

• name: the name shown next to the layer's checkbox, under your mod's name. Names are cut to 50 characters. Creating a layer with a name you've already used in this call returns that same layer, so you can add to it from several places.
• defaultVisible: whether the layer is shown before the player has changed its checkbox. Optional; defaults to true.

A mod can create up to 10 layers.

layer.AddLabel

layer.AddLabel(territoryID, text, options)

Adds a text label at a territory's middle point. It returns the layer, so calls can be chained.

• territoryID: the territory to put the label on.
• text: the text to show. Text is cut to 100 characters.
• options: optional. A table with any of these fields:

Field	Default	Description
FontSize	10	The size of the text, from 4 to 40.
FillColor	0 (black)	The color of the text, as a number in the form 0xRRGGBB, such as 0xFF0000 for red.
OffsetX	0	How far right of the territory's middle to put the label, in map units.
OffsetY	-18	How far below the territory's middle to put the label, in map units. The default puts it just above the army number.

A layer can have up to 1000 labels.

layer.AddShape

layer.AddShape()

Adds a shape and returns an object with the same functions as the visual object in Client_Visual:

• SetVertices, SetTriangles and SetColors
• SetFrames, SetRestTime and SetDepthTest
• SetAnchorTerritory and SetAnchorPoint

Shapes don't animate. A shape is drawn at its rest pose: the pose at the time given to SetRestTime, which defaults to 1 (the last frame). For a shape that doesn't change, SetVertices is simplest.

A layer can have up to 200 shapes. Problems with a shape are written to the mod log, the same as for Client_Visual. A shape that can't be drawn, such as one with a triangle index past the last vertex, is skipped.

-- a green square on each of the player's territories, hidden until the player turns it on
if (game.Us ~= nil) then
    local mine = layers.Create('My territories', false);
    for terrID, standing in pairs(game.LatestStanding.Territories) do
        if (standing.OwnerPlayerID == game.Us.ID) then
            mine.AddShape()
                .SetAnchorTerritory(terrID)
                .SetVertices({ {-8, -8}, {8, -8}, {8, 8}, {-8, 8} })
                .SetTriangles({ 1, 2, 3, 1, 3, 4 })
                .SetColors('#8000FF00');
        end
    end
end