Tutorial; ATITextTemplate - HWRM/KarosGraveyard GitHub Wiki

Step 1: create a lua file containing the template to use

Let's create a file named ATI.lua and put it in data:LevelData\ATI.lua. Note that we can put it anywhere except in the multiplayer folder (where it would be mistakenly taken for a gamerule).

There we create a template called "Message" with the following script:

SCAR_ATITemplates =
{
    Message =
    {
        {
            stringParam = 0,
            text =
            {
                colour = {1,1,1,1},
                dropshadow = 1,
                renderFlags = {"justifyLeft"},
                LODs =
                {
                    1, "SPSubtitleFont",
                }
            },
            placement2D =
            {
                factorX = -0.05,
                factorY = -1,
                minATIArea = 0,
                maxATIArea = 1,
                visibility = {},
            },
        },
    },
}

This is a simple format displaying white non-transparent text, justified on the left of the display rectangle, using the fonts of subtitles, with a drop shadow. The stringParam variable is used to enable the gamerule to set the text shown on screen by the display function.

Step 2: use the template from within a game file

All this part is done within the game file, ie the gamerule .lua file for multiplayer or each scenario .lua file in single player. If you have no idea of what it means, have a look into the files in the data:LevelData folder and read the tutorials about SP level creation on this site.

In the gamerule file, do not forget to load the template. The best way not to oversee this step is to do it in the oninit() function.

Then create a function that will display the text in the appropriate rectangle. The rectangle is in normalized wide- and height- screen coordinates (float between 0 and 1, from the left bottom corner). Call the function with the appropriate arguments.

In the following example, the function is called with two arguments: the text and the rectangle (so it can be used to display different messages at different locations). In the example, it is being used to show a "welcome" message on the bottom center of the screen.

function OnInit()
    ATI_LoadTemplates("data:LevelData\ATI.lua")
    local message = "Welcome"
    local rect = {0.49, 0.2, 0, 0}
    Display_Message(message, rect)
end

function Display_Message(message, rect)
    ATI_Clear()
    ATI_CreateParameters(1)
    ATI_AddString(0, message)
    ATI_Display2D("Message", rect, 0)
end

Note that text displayed that way is persistent. Therefore you must call the display function a second time with an empty string to clean up the screen, or call ATI_Clear() in another chunk.

Step 3: how to customise colour

To be able to change the colour of the text from the gamerule, we must use a second parameter in addition to the string parameter. First we modify the ATI script by cancelling the colour definition and referring to a colour parameter:

SCAR_ATITemplates =
{
    Message =
    {
        {
            stringParam = 0,
            colourParam = 1,
            text =
            {
                --colour = {1,1,1,1},
                dropshadow = 1,
                renderFlags = {"justifyLeft"},
                LODs =
                {
                    1, "SPSubtitleFont",
                }
            },
            placement2D =
            {
                factorX = -0.05,
                factorY = -1,
                minATIArea = 0,
                maxATIArea = 1,
                visibility = {},
            },
        },
    },
}

Then we can display the text in whatever colour we like using ATI_AddColour() in the game rule. To this end, we add another argument for colour to our Display_Message() function:

function OnInit()
    ATI_LoadTemplates("data:LevelData\ATI.lua")
    local message = "Welcome in yellow"
    local rect = {0.49, 0.2, 0, 0}
    local colour = {1, 1, 0, 1}
    Display_Message(message, rect, colour)
end

function Display_Message(message, rect, colour)
    ATI_Clear()
    ATI_CreateParameters(2)
    ATI_AddString(0, message)
    ATI_AddColour(1, colour)
    ATI_Display2D("Message", rect, 0)
end

Step 4: how to display several messages at the same time

It is possible to have several messages displayed and periodically updated on screen. All messages must be kept together in the same function because ATI_Clear() clears everything. Following is an example with a timer:

function OnInit()
    ATI_LoadTemplates("data:LevelData\campaign\tutorial\m02\ATI.lua")
    message = {}
    rect = {}
    colour = {}
    rect[1] = {0.49, 0.2, 0, 0}
    rect[2] = {0.49, 0.3, 0, 0}
    colour[1] = {1, 1, 0, 1}
    colour[2] = {1, 0, 0, 1}
    iTime = 70
    Rule_AddInterval("Rule_Timer", 1)
    Rule_AddInterval("Rule_DisplayMessage", 1)
    Rule_AddInterval("Rule_Message", 2)
end

function Rule_Timer()
    iTime = iTime - 1
    if iTime > 0 then
        local m = floor(iTime/60)
        local s = iTime - m*60
        message[1] = format("REMAINING TIME: %02d:%02d", m, s)
    else
        message[1] = "TIMER OUT"
    end
end

function Rule_Message()
    if iTime > 35 then
        message[2] = "You still have plenty of time."
    else
        message[2] = "Hurry up!!"
    end
end

function Rule_DisplayMessage()
    ATI_Clear()
    for i, iCount in message do
        ATI_CreateParameters(2)
        ATI_AddString(0, message[i])
        ATI_AddColour(1, colour[i])
        ATI_Display2D("Message", rect[i], 0)
    end
end

Updated 25 June 2006
SunTzu

Have you managed to change the color of the text using the gamerule? All my attempts have failed.

--Mikali (2006-06-17 01:52:17)

I never tried. I will now :D

--SunTzu (2006-06-19 04:22:18)

Colour customisation added

--SunTzu (2006-06-21 17:16:32)

does the ATI_Clear() only clear the current ATI template (in this case message?) <br />
If I added a message and then a timer, the timer updating every second and the message updating programatically, will it clear the message everytime the timer is updated? I'd like to see an example of a regularly updated ATI as well as a periodic update (interval rule and a single rule)

--EvilleJedi (2006-06-25 15:34:14)

Timer example added

--SunTzu (2006-06-26 06:13:18)

Updated Formatting? Initial
Updated for HWRM? Initial