Essence Engine Three

Essence Engine Wiki

Dawn of War 3

Scripting UI

Scripting UI

There are a number of SCAR functions that can be used to modify the HUD to create custom HUD elements or dialogs, these functions include:

  • float UI_GetViewportWidth()
  • float UI_GetViewportHeight()
  • void UI_ButtonAdd(const char* path, const char* name, float x, float y, float width, float height, const char* callback, bool enabled, const char* icon, ButtonIconStyle style, const char* tag, LocString text)
  • void UI_ButtonSetCallback(const char* path, const char* callback)
  • void UI_ButtonSetEnabled(const char* path, bool enabled)
  • void UI_ButtonSetIcon(const char* path, const char* icon)
  • void UI_ButtonSetTag(const char* path, const char* tag)
  • void UI_ButtonSetText(const char* path, LocString text)
  • void UI_LabelAdd(const char* path, const char* name, float x, float y, float width, float height, LabelAlignHorizontal alignHorizontal, LabelAlignVertical alignVertical, bool bold, bool italic, float size, LocString text)
  • void UI_LabelSetText(const char* path, LocString text)
  • void UI_IconAdd(const char* path, const char* name, float x, float y, float width, float height, const char* icon)
  • void UI_IconSetIcon(const char* path, const char* icon)
  • void UI_PanelAdd(const char* path, const char* name, float x, float y)
  • void UI_StatusIndicatorAdd(const char* path, const char* name, float x, float y, float width, float height, float value)
  • void UI_StatusIndicatorSetValue(const char* path, float value)
  • void UI_ControlSetColour(const char* path, int red, int green, int blue, int alpha)
  • void UI_ControlSetPosition(const char* path, float x, float y)
  • void UI_ControlSetRect(const char* path, float x, float y, float width, float height)
  • void UI_ControlRemove(const char* path)
  • void UI_ControlClear(const char* path)

ButtonIconStyle:

  • BIS_Icon
  • BIS_IconState

LabelAlignHorizontal:

  • LAH_Justify
  • LAH_Left
  • LAH_Center
  • LAH_Right

LabelAlignVertical:

  • LAV_None
  • LAV_Top
  • LAV_Center
  • LAV_Bottom

Synchronizing Buttons

It is important to note that the dialog is local only to the player running the script. In the case of button callbacks, you can synchronize all players by making use of the Command_PlayerBroadcastMessage function and GE_BroadcastMessage event:

-- Define a message type to distinguish this message from other messages (each button could have its own message type).
MESSAGE_TYPE_CALLBACK = 1.0

-- The button's callback will raise a GE_BroadcastMessage event for all players passing in the local player as the sender and the button's tag (you can substitute any custom string for tag).
function buttonCallback(tag)
    Command_PlayerBroadcastMessage(Game_GetLocalPlayer(), Game_GetLocalPlayer(), MESSAGE_TYPE_CALLBACK, tag)
end

function messageCallback(player, messageType, message)
    if messageType == MESSAGE_TYPE_CALLBACK then
        -- Do something synchronized with player’s message (which is the button's tag in this example)...
    end
end

-- Register messageCallback to run when GE_BroadcastMessage events are received.
Rule_AddGlobalEvent(messageCallback, GE_BroadcastMessage)

Creating Controls

There is also a helper function UI_AddControl in UI.scar which will take a table and call the appropriate functions to build the UI, e.g:

function buttonCallback(tag)
       print(tag)
end

dialog =
{
       controlType = "panel",
       name = "dialog",
       x = 100.0,
       y = 100.0,
       width = 280.0,
       height = 176.0,
       margin = 12.0,
       children =
       {
              {
                     controlType = "icon",
                     icon = "ModIcons_22f515a26a4a426f8eb76d4111d55eac_panel",
              },
              {
                     controlType = "label",
                     height = 28.0,
                     text = LOC("Hello World"),
                     alignHorizontal = LAH_Center,
                     alignVertical = LAV_Center,
                     bold = false,
                     italic = false,
                     size = 16.0,
              },
              {
                     controlType = "statusIndicator",
                     name = "statusIndicator",
                     top = 28.0,
                     height = 28.0,
                     value = 1.0,
              },
              {
                     controlType = "button",
                     name = "button",
                     top = 56.0,
                     width = 64.0,
                     height = 64.0,
                     callback = "buttonCallback",
                     enabled = true,
                     icon = "Icons_tooltips_blizzard",
                     style = BIS_Icon,
                     tag = "blizard",
                     text = LOC("Blizard")
              },
       },
}
-- Add the dialog defined by the table:
UI_AddControl(dialog)

 -- Do something with the dialog:
UI_StatusIndicatorSetValue("dialog.statusIndicator", 0.5)

 -- Remove the dialog:
UI_ControlRemove(“”, “dialog”)