GMUI
InputState
Layout
LayoutComponent
LazyLayout
PresentationFunctions
SimulationFunctions
SimulationGMUI
UiHelper
_APIOffsets
_AnimateFrameToCanvasPositionArgs
_BlockInputOptions
_NewLayoutOptions
_NewLazyLayoutOptions
_OffsetOptions
_WhitelistWorldPositionArgs

GMUI

RunFunctionAfterTimeElapsed

function GMUI.RunFunctionAfterTimeElapsed(callback: function, duration: number)

Runs a function after a duration, similar to DCEI.TriggerAddTimerEventElapsed but presentation compatible.

InputState

Contains functions for managing input state

Layout

Class for creating and managing UI layouts

LayoutComponent

LayoutComponents are used to create layout logic templates that can be applied to new Lazy|Layouts as needed.

LazyLayout

Inherits Layouts, but with lazy loading so UI elements are only initialized when they are first shown

UiHelper

UiHelper is a library of helper functions.

ui

Table containing all UI elements. It's advised you add your own UI to this table as well.
This will enable GMUI to get your frame from a given frame address with UiHelper.GetLayoutFromLayoutAddress

InputState

Contains functions for managing input state. This module can be accessed from both presentation and simulation.

BlockUserInput

function InputState.BlockUserInput(key?: string)

Blocks user input. Use InputState.UnblockUserInput() to unblock user input after this is called.

@param key — If provided, user input will only be able to be unblocked by calling InputState.UnblockUserInput() with the same key.

BlockUserInputExcept

function InputState.BlockUserInputExcept(args: _BlockInputOptions)

Blocks user input except for the specified whitelisted objects. Use InputState.UnblockUserInput() to unblock user input after this is called.
Note that any subsequent calls to this function will overwrite the previous whitelist.

@param args — allows you to pass keys or objects to whitelist

UnblockUserInput

function InputState.UnblockUserInput(key?: string)

Attempts to unblocks user input.

@param key — Used to unblock user input if InputState.BlockUserInput() was previously called with the same key.

Layout

The Layout class is the backbone of GMUI, allowing you to hook up XML as a Layout which can be more easily manipulated in Lua. The Layout class is accessible in both Simulation and Presentation scripts, though the UI created by Layouts always exists on the Presentation layer.

Destroy

(method) Layout:Destroy()

Destroys the layout by running DCEI.Destroy(self.Frame).

DoesExist

(method) Layout:DoesExist()
  -> exists: boolean

@return exists — Returns true if the layout's root frame still exists.

GetChildCollection

(method) Layout:GetChildCollection(name: string)
  -> InGameUILayoutComponent[]

Returns a list of child layouts or frames with ids that match the collection_name appended with "_n" where n will be the child's collection index. Useful creating and hooking up tables of layouts with many static child items, such as inventory slots or attribute lists.

Example Usage
-- for a layout with children "item_1", "item_2", and "item_3", the collection would contain these 3 frames
layout.items = layout:GetChildCollection("item")
for index, child in ipairs(layout.items) do
    DCEI.SetTextFrameText(child.Label, index)
end

GetContext

(method) Layout:GetContext()

Returns any context registered to the layout. You can register a function or lua table from simulation layer as context by using GMUI.RegisterUiLayoutContext()

Hide

(method) Layout:Hide()

Hides the layout's root frame and runs the layout's OnHide() method.

Note that Hide sets the root frame's active state DCEI.SetFrameActive(self.Frame, false).

IsActive

(method) Layout:IsActive()
  -> is_active: boolean

@return is_active — Returns true if this Layout's root frame is active (visible) using DCEI.IsFrameActive(self.Frame)

New

function Layout.New(args: _NewLayoutOptions)
  -> layout_instance: Layout

Returns a new layout from the given arguments. A layout is a table that represents a UI element and has some built-in functionality with the Layout Methods. Layouts can be built from UI frames defined in XML or in script.

Layouts created from XML will have each child frame with id added to the layout using the id as the frame's key. For instance, if a layout contains a child with the id TitleLabel, this child frame can be referenced as layout.TitleLabel.

Root Frame

Regardless of how the layout was constructed, the root frame can be gotten with layout.Frame such as:

local layout = GMUI.Layout.New()
DCEI.SetFrameSize(layout.Frame, 100, 100)
DCEI.SetFrameImageColor(layout.Frame, {r = 1, g = 0, b = 0, a = 0.5})
Parameters
Example Usage

Using an XML frame named "Standard/Button/Button" such as:

<Frame>
    <Button id="Button" height="108" width="224">
        <Text id="Label" text="Continue" fontSizeMin="22" fontSizeMax="32" maxWidth="188" maxHeight="26" />
    </Button>
</Frame>

The lua:

local ui = GMUI.ui

function CreateButtonFrame()
    local layout = GMUI.Layout.New({
        parent = ui.Root,
        name = "Standard/Button/Button",
    })
    -- layout
    DCEI.SetFrameImage(layout.Button, "btn_red")
    DCEI.SetTextFrameText(layout.Label, "Press Me!")

    -- initialize
    layout:Hide()
    return layout
end

-- creates a button that appears after 2 seconds
ui.button = CreateButtonFrame()
DCEI.TriggerAddTimerEventElapsed(function()
    ui.button:Show()
end, 2)

OnHide

(method) Layout:OnHide()

Function to run when layout is hidden; blank by default so that it can be overridden.

OnShow

(method) Layout:OnShow()

Function to run when layout is shown; blank by default so that it can be overridden.

SetOnLayoutInitializeCallback

function Layout.SetOnLayoutInitializeCallback(callback: function)

Sets a function to run when any layout finishes initializing when created with Layout.New(). The newly created layout will be passed as a parameter to this function.
For an example, this could be used to set a state for all layouts on creation to iOS or Android to adjust UI to account for iphone notch depending on device type.

Show

(method) Layout:Show()

Shows the layout's root frame and runs the layout's OnShow() method

Note that Show sets the root frame's active state DCEI.SetFrameActive(self.Frame, true)

Update

(method) Layout:Update()

Function to run to update the layout; blank by default so that it can be overridden.

Frame

InGameUILayoutComponent

The layout's root frame - the actual in-game UI instance. Reference this Layout.Frame any time you're using a DCEI API's that reference UI, like animation APIs.

LayoutComponent

LayoutComponents are used to create layout logic templates that can be applied to new Lazy|Layouts as needed.

GetLayout

(method) LayoutComponent:GetLayout()
  -> Layout

Returns the layout definition for this LayoutComponent. Add methods to this layout as you would a regular Layout or LazyLayout

Initialize

(method) LayoutComponent:Initialize(layout_instance: Layout)

@param layout_instance — the layout to apply

New

function LayoutComponent.New()
  -> LayoutComponent

Creates and returns a LayoutComponent, useful for defining layout methods for sub-layouts of Layouts or LazyLayouts.
This can be used to break down the logic for complex layouts into multiple submodules for organization and readability.
For instance, if you have a particularly complex LazyLayout (such as a combat UI with status bars, buff bars, and an
attribute panel), you can split the logic for each include to be its own submodule with its own Initialize method

LazyLayout

Inherits from the Layout class, which makes creating and manipulating UI from XML in the UI Editor easier.
LazyLayouts make initial load times lower by only creating the UI once a method/property is first accessed. (e.g. the UI wont actually be created until you use :Show)
LazyLayout is accessible in both Presentation and Simulation scripts, though the actual UI elements created always live on the Presentation layer.

DoesExist

(method) LazyLayout:DoesExist()
  -> exists: boolean

@return exists — Returns true if the layout's root frame still exists.

Returns false if the LazyLayout hasn't been initialized yet.

Initialize

(method) LazyLayout:Initialize(layout: Layout)

Intentionally blank so it can be overridden.
This method should be defined for each layout in its script file (ex, UI/Game/trait_page.lua.txt).
Use this method for setting the layout's initial state and hooking up any child layouts

IsActive

(method) LazyLayout:IsActive()
  -> is_active: boolean

@return is_active — Returns true if this Layout's root frame is active (visible) using DCEI.IsFrameActive(self.Frame)

Returns false if the LazyLayout hasn't been initialized yet.

IsInitialized

(method) LazyLayout:IsInitialized()
  -> boolean

Returns whether or not the layout has been initialized yet. Calling this will not initialize the layout

New

function LazyLayout.New(args: _NewLazyLayoutOptions)
  -> layout_instance: LazyLayout

Returns a new "lazy" layout from the given arguments. A layout is a table that represents a UI element and has some built-in functionality with the Layout Methods. Layouts can be built from UI frames defined in XML or in script.

Lazy layouts, unlike normal layouts, do not actually create UI frames. That is, until a key value is retrieved from a LazyLayout (including most method calls) at which point the Lazy Layout will initialized and be turned into a normal Layout with instanced game UI frames.
The most common way to initialize a LazyLayout is by calling :Show().

As an exception, these methods won't trigger the initialization,

Layouts created from XML will have each child frame with id added to the layout using the id as the frame's key. For instance, if a layout contains a child with the id TitleLabel, this child frame can be referenced as layout.TitleLabel.

Root Frame

Regardless of how the layout was constructed, the root frame can be gotten with layout.Frame such as:

local layout = GMUI.LazyLayout.New()
DCEI.SetFrameSize(layout.Frame, 100, 100)
DCEI.SetFrameImageColor(layout.Frame, {r = 1, g = 0, b = 0, a = 0.5})
Parameters
Example Usage

Using an XML frame named "Standard/Button/Button" such as:

<Frame>
    <Button id="Button" height="108" width="224">
        <Text id="Label" text="Continue" fontSizeMin="22" fontSizeMax="32" maxWidth="188" maxHeight="26" />
    </Button>
</Frame>

The lua:

local ui = GMUI.ui

function CreateButtonFrame()
    local layout = GMUI.LazyLayout.New({
        parent = ui.Root,
        name = "Standard/Button/Button"
    })

    -- layout
    DCEI.SetFrameImage(layout.Button, "btn_red")
    DCEI.SetTextFrameText(layout.Label, "Press Me!")

    -- initialize
    layout:HideImmediate()
    return layout
end

ui.button = CreateButtonFrame()
DCEI.TriggerAddTimerEventElapsed(
    function()
        ui.button:Show()
    end,
    2
)

PresentationFunctions

These functions are for the presentation layer only.

GetUnitFromUnitReference

function PresentationFunctions.GetUnitFromUnitReference(unit_ref: string)
  -> Unit

Converts a unit reference into a unit. The unit must first be converted into a unit reference in simulation layer using GMUI.CreateUnitReference

RegisterPresentationEvent

function PresentationFunctions.RegisterPresentationEvent(event_id: string, callback: function)

Registers a presentation event with the given id and callback function. This event callback can be called from presentation layer by using
GMUI.SendPresentationEvent(event_id, data, context),

RunSimulationCallback

function PresentationFunctions.RunSimulationCallback(callback: any, data?: any)

Send a command from presentation layer to run a simulation callback function in the simulation layer.
the 'callback' parameter must be a simulation function that has been passed as context to the presentation layer.

RunSimulationFunction

function PresentationFunctions.RunSimulationFunction(function_name: string, command_data?: any, context?: function|table)

Send a command from presentation layer to run a global function in the simulation layer.

SendSimulationEvent

function PresentationFunctions.SendSimulationEvent(event_id: string, data?: any, context?: function|table)

Send an event from presentation layer to simulation. Events need to be added with Core.Event.RegisterPresentationEvent(event_id, callback) first.
The callback will be called using the data and context passed with this function.

SimulationFunctions

Simulation functions which are accessed from simulation layer scripts.

CreateUnitReference

function SimulationFunctions.CreateUnitReference(unit: Unit)
  -> string

Converts a unit into a unit reference so it can be more easily shared with the presentation. Takes a unit and returns a string representing the unit.

RegisterSimulationEvent

function SimulationFunctions.RegisterSimulationEvent(event_id: string, callback: function)

Registers a simulation event with the given id and callback function. This event callback can be called from presentation layer by using
GMUI.SendSimulationEvent(event_id, data, context),

RegisterUiLayoutContext

function SimulationFunctions.RegisterUiLayoutContext(layout_address: string, context: function|table)

Registers a function or table object as context for a ui layout that can be returned using the layout:GetContext method

RunPresentationFunction

function SimulationFunctions.RunPresentationFunction(function_name: string, command_data?: any, context?: function|table)

Send a command from simulation layer to run a global function in the presentation layer.

SendPresentationEvent

function SimulationFunctions.SendPresentationEvent(event_id: string, data?: any, context?: function|table)

Send an event from simulation layer to presentation. Events need to be added with Core.Event.RegisterPresentationEvent(event_id, callback) first.
The callback will be called using the data and context passed with this function.

SendUiLayoutCommand

function SimulationFunctions.SendUiLayoutCommand(layout_address: string, layout_method: string, command_data?: any, context?: function|table)

Order a Layout to execute a function with provided data.
The Layout address such as "ui.top_bar.gold" will be recognized as a layout table if such reference exists in the ui hierarchy,
and it will run the function provided if available, with the provided data passed as the first parameter to the function.

@param layout_address — The address of the layout as a string, e.g. "ui.top_bar.gold".

@param layout_method — The name of the function the layout should run.

@param command_data — The argument to send to the function. If you need to send multiple parameters, include them in a table.

@param context — The simulation context to pass to the layout method. This context will be read-only in presentation layer as the method's second parameter.

SimulationGMUI

InputState

Contains functions for managing input state

Layout

The Layout class makes creating and manipulating UI from XML in the UI Editor easier.

LayoutComponent

LayoutComponents are used to create layout logic templates that can be applied to new Lazy|Layouts as needed.

LazyLayout

The Layout class makes creating and manipulating UI from XML in the UI Editor easier. Lazy Layouts make initial load times
lower by only creating the UI once a method/property is first accessed. (e.g. the UI wont actually be created until you use :Show)

UiHelper

UiHelper is a module of helper functions

ui

ui is a table containing all UI elements. It's advised you add your own UI to this table as well.

UiHelper

UiHelper includes general purpose helpful UI functions which are accessible to the presentation scripting layer.

AnimateFrameToCanvasPosition

function UiHelper.AnimateFrameToCanvasPosition(frame: InGameUILayoutComponent, target_pos: Point, duration: number, ease: string|"Flash"|"InBack"|"InBounce"|"InCirc"...(+30), args?: _AnimateFrameToCanvasPositionArgs)

Animates frame a to a canvas position.
Supports options of various types of offsets.

@param frame — Frame to move.

@param target_pos — Target point to move the frame to.

@param duration — Duration over which the animation should occur.

@param ease — Easing for the animation.

@param args — Offset options.

ease:
    | "Linear"
    | "InSine"
    | "OutSine"
    | "InOutSine"
    | "InQuad"
    | "OutQuad"
    | "InOutQuad"
    | "InCubic"
    | "OutCubic"
    | "InOutCubic"
    | "InQuart"
    | "OutQuart"
    | "InOutQuart"
    | "InQuint"
    | "OutQuint"
    | "InOutQuint"
    | "InExpo"
    | "OutExpo"
    | "InOutExpo"
    | "InCirc"
    | "OutCirc"
    | "InOutCirc"
    | "InElastic"
    | "OutElastic"
    | "InOutElastic"
    | "InBack"
    | "OutBack"
    | "InOutBack"
    | "InBounce"
    | "OutBounce"
    | "InOutBounce"
    | "Flash"
    | "InFlash"
    | "OutFlash"

AnimateFrameToFrame

function UiHelper.AnimateFrameToFrame(a: InGameUILayoutComponent, b: InGameUILayoutComponent, duration: number, ease: string|"Flash"|"InBack"|"InBounce"|"InCirc"...(+30), args?: _AnimateFrameToCanvasPositionArgs)

Animates frame a to the position of frame b.
Supports options of various types of offsets.

@param a — Frame to move.

@param b — Target frame to move the first frame to.

@param duration — Duration over which the animation should occur.

@param ease — Easing for the animation.

@param args — Offset options.

ease:
    | "Linear"
    | "InSine"
    | "OutSine"
    | "InOutSine"
    | "InQuad"
    | "OutQuad"
    | "InOutQuad"
    | "InCubic"
    | "OutCubic"
    | "InOutCubic"
    | "InQuart"
    | "OutQuart"
    | "InOutQuart"
    | "InQuint"
    | "OutQuint"
    | "InOutQuint"
    | "InExpo"
    | "OutExpo"
    | "InOutExpo"
    | "InCirc"
    | "OutCirc"
    | "InOutCirc"
    | "InElastic"
    | "OutElastic"
    | "InOutElastic"
    | "InBack"
    | "OutBack"
    | "InOutBack"
    | "InBounce"
    | "OutBounce"
    | "InOutBounce"
    | "Flash"
    | "InFlash"
    | "OutFlash"

GetLayoutFromLayoutAddress

function UiHelper.GetLayoutFromLayoutAddress(layout_address: string)
  -> InGameUILayoutComponent

Converts a string such as "ui.top_bar.gold" into a layout table or frame reference,
if such reference exists in the ui hierarchy.

@param layout_address — A string such as "ui.top_bar.gold"

MoveFrameToCanvasPositionUsingOffsets

function UiHelper.MoveFrameToCanvasPositionUsingOffsets(frame: InGameUILayoutComponent, target_pos: Point, args?: _OffsetOptions)

Moves frame a to a canvas position, using offsets.

@param frame — UI Frame component to move.

@param target_pos — Target point as a table with the format {x = 0, y = 0}

@param args — x_offset and y_offset for offsetting the move position. Can be skipped with skip_x_offset and skip_y_offset.

MoveFrameToFrame

function UiHelper.MoveFrameToFrame(a: InGameUILayoutComponent, b: InGameUILayoutComponent, offset: _APIOffsets)

Moves frame a to position of frame b. Only frames that are direct children of root can be moved in this way.

MoveFrameToFrameUsingOffsets

function UiHelper.MoveFrameToFrameUsingOffsets(a: InGameUILayoutComponent, b: InGameUILayoutComponent, args?: _OffsetOptions)

Moves frame a to position of frame b, using offsets.

@param a — Frame to move.

@param b — Target frame to move the first frame to.

@param args — x_offset and y_offset for offsetting the move position. Can be skipped with skip_x_offset and skip_y_offset.

MoveFrameToUnitUsingOffsets

function UiHelper.MoveFrameToUnitUsingOffsets(frame: InGameUILayoutComponent, unit: Unit, args?: _OffsetOptions)

Moves frame a to position of a unit, using offsets.

@param args — x_offset and y_offset for offsetting the move position. Can be skipped with skip_x_offset and skip_y_offset.

_APIOffsets

A table for setting offsets for UiHelper.MoveFrameToFrame

front

number

Forwards/backwards offset. (Closer or further away from the screen)

number

Right/left (horizontal) offset.

up

number

Up/down (vertical) offset.

_AnimateFrameToCanvasPositionArgs

end_offset_x

number

x (horizontal) offset for the ending position.

end_offset_y

number

y (vertical) offset for the ending position.

horizontal_ease

string|"Flash"|"InBack"|"InBounce"|"InCirc"...(+30)

Easing for the horizontal movement of the animation.

offset_x

number

x (horizontal) offset for the overall movement.

offset_y

number

y (vertical) offset for the overall movement.

start_offset_x

number

x (horizontal) offset for the starting position.

start_offset_y

number

y (vertical) offset for the starting position.

vertical_ease

string|"Flash"|"InBack"|"InBounce"|"InCirc"...(+30)

Easing for the vertical movement of the animation.

_BlockInputOptions

key

string

If provided, user input will only be able to be unblocked by calling InputState.UnblockUserInput() with the same key.

whitelist_frame

InGameUILayoutComponent

If provided, user input will be allowed on this frame (use this when calling from presentation).

whitelist_frame_address

string

If provided, user input will be allowed on this frame (use this when calling from simulation).

whitelist_unit

Unit

If provided, user input will be allowed on this unit.

whitelist_world_position

_WhitelistWorldPositionArgs

If provided, user input will be allowed at this world position.

_NewLayoutOptions

Frame

InGameUILayoutComponent

If used, a new layout will be created using the given frame.

name

string

If used, the layout will be created from the given XML reference. If no name or Frame is given, a new blank frame will be created for the layout.

parent

InGameUILayoutComponent

The parent frame to use when creating this layout. If no parent is given then the root frame will be used instead.

_NewLazyLayoutOptions

name

string

If used, the layout will be created from the given XML reference. If no name is given, a new blank frame will be created for the layout.

parent

InGameUILayoutComponent

The parent frame to use when creating this layout. If no parent is given then the root frame will be used instead.

_OffsetOptions

skip_x_offset

boolean

Set to true to skip this offset.

skip_y_offset

boolean

Set to true to skip this offset.

x_offset

integer

x (horizontal) offset.

y_offset

integer

y (vertical) offset.

_WhitelistWorldPositionArgs

radius

number

the radius around the x/z position to whitelist

x

number

the x position on the terrain to whitelist

z

number

the z position on the terrain to whitelist