Bos Wars Scripting API: User Interface (UI)

Intro - Introduction to UI functions and variables

Conceptual

Text formatting

When the engine displays text on the screen, it recognizes the following format codes.

"~~"

Displays a single "~" character.

"~!"

Marks the following character as a hot key and draws it in a different color, usually UI.ReverseFontColor. Highlighting works even in those widgets that do not support hot keys.

"~<" and "~>"

Marks the text between these strings as a hot key and draws it in a different color. Use this if the name of the hot key is multiple characters long, e.g. "Cancel (~<Esc~>)" or "Help (~<F1~>)". If a translation to another language changes the name of the Esc key, then the engine will recognize both the "Esc" name and the translated name as referring to that key.

"~color~" and "~>"

Displays the text between these strings with the specified color, if such a color name has been defined with CFontColor:New. For example, "the ~red~original~> sin" would display "the original sin", where "original" would be red.

Functions

DefineButton({tag1 = value1, tag2 value2, ...})

Pos = number

The position in which the button will appear in the button panel or in the pie menu.

0 1 2
3 4 5
6 7 8

Level = number

Visible when in this button level (0 default, 9 cancel-only).

The engine normally returns to button level 0 when the player selects a unit. Level 0 is also the default for buttons that you define without explicitly specifying Level = number.

Button level 9 should contain only a Cancel button (Action = "cancel"). The engine selects level 9 when it expects the player to choose a target location or a target unit on the map.

Icon = "icon-name"

Name of the icon to display.

Action = "action"

Action to perform when the player clicks the button. Can be any of the following:

"move"

The selected unit will follow the target unit or move to the target location. In the former case, the selected unit will stop following if it reaches the target unit.

"stop"

The selected unit stops. The orders queue of the selected unit is also erased. The selected unit then waits for an order but can react by itself.

"attack"

The selected unit will attack only the target unit, or move to the target location and attack any opponent on the way.

"repair"

The selected unit will repair the target unit.

"harvest"

The selected unit will harvest resources from the target unit. After the target unit is destroyed, the selected unit will try to find more resources of the same type, unless it has another order in its queue.

"button"

Switches to a different button level; changes the button panel to show the buttons of that level.

You must set Value = number. The engine will show the allowed buttons that have Level = that number.

"build"

The selected unit will build a new unit at the target location. The new unit will appear on the map as soon as the selected unit begins building it.

You must set Value = "unit-name". This is the type of the new unit that the selected unit will build. Normally, you would specify a building type here.

"train-unit"

The selected unit will train a new unit within itself. When training completes, the new unit will appear next to the unit that trained it, or further away if it doesn't fit any closer. Normally, you would specify a building type in the ForUnit list.

You must set Value = "unit-name". This is the type of the new unit that the selected unit will train.

"patrol"

The selected unit will patrol between target location and its current location and attack any opponent on the way.

"stand-ground"

The selected unit will not move. It will stay at its location until it receives a new order. It will however fire at any opponents that come too close.

"attack-ground"

The selected unit will attack the target location. Useful for units with splash damage.

"cast-spell"

The selected unit will cast a spell.

You must set Value = "spell-ident". This is the unique identifier of the spell, as defined with DefineSpell.

"unload"

The selected unit will unload all the units that it is carrying. Useful for unit types defined with CanTransport = true. If the selected unit cannot move (its unit type has no move animation defined), then the engine assumes it is a bunker, and it will unload its inhabitants where it is. If the selected unit can move, then the engine assumes it is a transporter; the player must select a target location on the map, and the transporter will unload its passengers there. There are some exceptions to these rules.

"cancel"

The engine stops waiting for the player to choose a target. The action for which the engine wants a target is not yet in the order queue of the selected unit, so the button does not affect the unit. This kind of cancel should be used only with Level = 9.

"cancel-train-unit"

The selected unit stops training units. All unit-training orders (Action = "train-unit") are erased from the order queue of the selected unit. (In principle, if there is some other type of order in between, then unit-training orders that follow it are not erased. However, units that can train typically cannot do anything else.)

"cancel-build"

The selected unit stops being built and is destroyed. Any workers who were building it are freed.

Value = arg

Optional value associated with the Action.

Allowed = "check-name"

Optional check to see if a button is allowed. Can be any of the following:

"check-true"

No restriction on this button.

"check-false"

The button is forbidden. FIXME : ? to be removed. What is its usage ?

"check-units-or"

The button is allowed if the player has at least one unit of any of the specified types. Need AllowArg = {"unit-name1", "unit-name2"}

"check-units-and"

The button is allowed if the player has at least one unit of each of the specified types. Need AllowArg = {"unit-name1", "unit-name2"}

"check-network"

The button is allowed only during a network game.

"check-no-network"

The button is allowed only during a non-network game.

"check-no-work"

The button is allowed unless the selected unit is training a unit (with Action = "train-unit").

"check-attack"

The button is allowed if the selected unit can attack at all, i.e. its unit type was defined with CanAttack = true.

If you do not specify Allowed, then the engine decides whether the button is allowed, based on which units the player has selected and which Action the button has. For example, if the button has Action = "patrol", and the player selects a building that cannot move, then the button is not allowed by default. If you do specify Allowed, it overrides these default checks, but the ForUnit list still applies.

AllowArg = {"arg1", ...}

Optional argument used by the allowed function.

Hint = "string"

Hint to be displayed for the button. To define a shortcut key for the button, use the "~!", "~<", and "~>" format codes described in Text formatting.

ForUnit = {"unit-name1", ...} or {"*"}

List of units the button applies to, or {"*"} for all units.

Example

DefineButton( { Pos = 8, Level = 0, Icon = "icon-build-advanced",
  Action = "button", Value = 2,
  Allowed = "check-units-or", AllowArg = {"unit-elven-lumber-mill", "unit-keep"},
  Hint = "BUILD AD~!VANCED STRUCTURE",
  ForUnit = {"unit-peasant"} } )

DefineButtonStyle(style, {tag = value, ...})

Size = {x, y}

Size of the button.

Font = font-name

Name of the font to use.

TextNormalColor = color, TextReverseColor = color

Color to use for the normal and reverse text.

TextAlign = align

Align the text. Possible values are "Left", "Right", and "Center".

TextPos = {posx, posy}

Set the position of the text relative to the upper left corner of the image.

Default = {tag = value, ...}, Hover = {}, Selected = {}, Clicked = {}, Disabled = {}

Set attributes for when the mouse is over the button (Hover), the button is Selected, Clicked, Disabled, or the Default setting. Possible tags:

File = file

The filename.

Size = size

The size of the image (only needed when using an image with multiple frames).

Frame = frame

Select the frame number from an image (only needed when using an image with multiple frames).

TextNormalColor = color, TextReverseColor = color

Color to use for the normal and reverse text (overrides the main colors).

TextPos = {x, y}

Display the text at this position (overrides the main position).

Border = { Color = color, Size = size}

Draw a border with the specified color and size.

Example

DefineButtonStyle("main", {
  Size = {128, 20},
  Font = "game",
  TextNormalColor = "yellow",
  TextReverseColor = "white",
  TextAlign = "Center",
  TextPos = {64, 4},
  Default = {
    File = "ui/buttons_1.png", Size = {300, 144}, Frame = 4,
  },
  Hover = {
    TextNormalColor = "white",
  },
  Selected = {
    Border = {
      Color = {252, 252, 0}, Size = 1,
    },
  },
  Clicked = {
    File = "ui/buttons_1.png", Size = {300, 144}, Frame = 5,
    TextNormalColor = "white",
    TextPos = {66, 6},
  },
  Disabled = {
    File = "ui/buttons_1.png", Size = {300, 144}, Frame = 3,
    TextNormalColor = "grey",
    TextReverseColor = "grey",
  },
})

DefineCursor({tag = value, ...})

Name = "ident"

Unique identifier of the cursor, used to reference it in config files and during startup.

File = "icon-file"

Path to the image graphic.

HotSpot = {x, y}

Hot spot of the cursor in pixels. Relative to the sprite origin {0, 0}. The hot spot of a cursor is the point to which Bos Wars refers in tracking the cursor's position.

Size = {width, height}

Size of the cursor in pixels.

Rate = millisecond

Rate of changing the frames if using an animated cursor. The "rate" tells the engine how many milliseconds to hold each frame of the animation.

Example

DefineCursor({
  Name = "cursor-cross",
  File = "ui/cursors/small_green_cross.png",
  HotSpot = {8,  8},
  Size = {18, 18}})

DefineViewports("mode", mode, "viewport", {mapx, mapy}, ...)

"mode", number

Number corresponding to the viewport mode. See the ViewportMode enum. FIXME

"viewport", {mapx, mapy}

X, Y coordinate of the map tile.

Example

-- Defines the viewports to use mode 1 (split horizontal) with the first
-- viewport having map coordinates 82,31 and the second having coordinates 64,31.
DefineViewports("mode", 1, "viewport", {82, 31},
                           "viewport", {64, 31})

SetGameCursor("cursor-ident")

"cursor-ident"

Unique identifier of the cursor.

Example

-- Set the game cursor to 'cursor-point'.
SetGameCursor("cursor-point")

HandleCommandKey("key", ctrl, alt, shift)

The Lua script must define this function. The engine calls it when the user presses a key that the engine does not handle on its own, and no menu is open. The engine can call this function during the game, in the map editor, or in the patch editor. To handle different keys in different situations, the Lua script can redefine this function when the user enters or leaves an editor.

"key"

The name of the key that the user pressed; for example, "a" or "escape". The name does not depend on which the language the user selected.

ctrl

true if the user pressed the Control key too, false if not.

alt

true if the user pressed the Alt key too, false if not.

shift

true if the user pressed the Shift key too, false if not.

RETURNS

true if HandleCommandKey handled the key, false if the engine should try to handle the key in some other way.

Variables

UI

This variable refers to an object that has at least the following properties: ButtonPanel.ShowCommandKey ReverseFontColor Resources

Do not change the UI variable itself from Lua, even though the engine may allow that.

UI.ButtonPanel.ShowCommandKey = boolean

Enable/disable the display of the command keys in buttons.

UI.ReverseFontColor = string

The name of the font color generally used for highlighting in text formatting. The font color must be defined with CFontColor:New.

UI.Resources = table

How the engine displays the resource costs of a command. This table contains a CResourceInfo instance for each type of resource. The indices of the table are resource type identifiers, i.e. integers between 0 and MaxCosts-1 (even though indices typically start from 1 in Lua).

Types

CColor

The CColor type represents an RGBA color.

In the following subsections, color denotes a CColor instance.

CColor([r], [g], [b], [a])

Constructs a CColor instance with the specified Red, Green, Blue, and Alpha component values. All arguments are optional.

color.R

The red component, between 0 and 255.

color.G

The green component, between 0 and 255.

color.B

The blue component, between 0 and 255.

color.A

The alpha component, between 0 and 255. Not premultiplied.

Currently, the engine ignores the alpha component of all CColor instances that Lua code can access:

• fontColor.Colors
• UI.ButtonPanel.AutoCastBorderColorRGB
• UI.CompletedBarColorRGB

CFontColor

Each CFontColor instance represents a named set of colors for use in text formatting.

In the following subsections, fontColor denotes a CFontColor instance.

fontColor.Colors

An array of CColor instances. There are MaxFontColors elements in the array. The engine ignores the alpha component of these CColor instances.

CFontColor:Get("name")

Finds a font color by name. Returns a CFontColor instance if found. If no such font color has been defined, which indicates a bug, then this function returns nil instead.

CFontColor:New("name")

Finds a font color by name, or allocates a new one. Returns a CFontColor instance. If it is a new one, then its Colors array is all black, so you should set that before you use the font color in text formatting.

MaxFontColors

This constant integer is the number of elements in the Colors array in CFontColor instances.

CResourceInfo

In the UI.Resources table, there is one CResourceInfo instance for each type of resource. These objects control how the engine displays the resource costs of a command. Each CResourceInfo instance has the following properties:

G

The CGraphic instance that contains the resource icon.

IconFrame

The frame number of the resource icon within the graphic. See Frame numbers and flipping.

IconX

Obsolete since r8638 (2007-03-28): The coordinates are hardcoded. The X coordinate of the resource icon on the screen, for resources held by the player.

IconY

Obsolete since r8638 (2007-03-28): The coordinates are hardcoded. The Y coordinate of the resource icon on the screen, for resources held by the player.

TextX

Obsolete since r8638 (2007-03-28): The coordinates are hardcoded. The X coordinate of the text that describes the amount of resource held by the player.

TextY

Obsolete since r8638 (2007-03-28): The coordinates are hardcoded. The Y coordinate of the text that describes the amount of resource held by the player.

These properties can be accessed with expressions like UI.Resources[EnergyCost].G.

CGraphic

A CGraphic instance is a graphic image that can be loaded from a file and then displayed on the screen.

In the following subsections, graphic denotes a CGraphic instance.

CGraphic:New("filename", [width], [height])

Creates a CGraphic instance that refers to the specified image file, unless one exists already.

"filename"

The name of the file from which CGraphic::Load will load the graphic.

width

The width of each frame in the graphic, or 0 (default) to use the whole graphic as just one frame.

height

The height of each frame in the graphic, or 0 (default) to use the whole graphic as just one frame.

RETURNS

A CGraphic instance that refers to the specified image file. If one had already been created, then CGraphic::New returns that and increments its reference count; otherwise, CGraphic::New creates a new CGraphic instance. In either case, CGraphic:Free will have to be called.

CGraphic:Free(graphic)

Decrements the reference count of a CGraphic instance, and frees it if the reference count becomes zero.

The reference counts of CGraphic instances are not currently connected to Lua garbage collection. CGraphic:Free must be called explicitly. If a CGraphic instance is used after it has been freed, the engine will probably crash.

graphic

The CGraphic instance that the method should free.

RETURNS

Nothing.

graphic:Load()

Loads the graphic from the image file whose name was given to CGraphic:New, unless it has already been loaded.

graphic

The CGraphic instance that the method should load.

RETURNS

Nothing.

graphic:Resize(width, height)

Resizes the graphic to the specified size. Because CGraphic:New returns the same CGraphic instance when given the same file name, resizing can affect other uses of the same graphic. To prevent such problems, you should use this method only on graphics that are displayed in one place at a time and are always resized before use.

graphic

The CGraphic instance that the method should resize.

width

The new width of the graphic, in pixels.

height

The new height of the graphic, in pixels.

RETURNS

Nothing.