The UserInterface Mod is used to quickly create, hookup, and manage game UI. This is best used when working with UI created with XML but also supports script-created UI. It also comes with a number of handy UI templates such as red pips and big hand.

• Create and manage UI layouts
• Hookup XML layouts with child frame references
• Common UI templates for tutorials and game systems

Download the demo maps HERE or play them on the arcade:

• UI Demo

• To use this mod, add the gmui registry module to your project using the latest version ^1.0.0.

Have an idea for additional features or UI templates? Let @coffee know!

The following functions can be used with any layouts created with Layout:New() and can be used such as:

local gmui = require("gmui")

local layout = gmui.Layout:New({
    parent = DCEI.GetUiRoot(),
    name = "Standard/Layer/Mask"
})

-- initialize
layout:HideImmediate()

Note that the following are template functions and don't actually do anything until overwritten:

• Layout:OnShow()
• Layout:OnHide()
• Layout:OnPress()

layout:Show()

Shows the layout's root frame and runs any related functions. Specifically:

• Runs the layout's OnShow() method
• Runs the layout's on_show_animation if it has one
• Sets the layout's is_active property to true

Note that Show/Hide set the root frame's active state and should not be used with DCEI.SetActive().

layout:Hide()

Hides the layout's root frame and runs any related functions. Specifically:

• Runs the layout's OnHide() method
• Runs the layout's on_hide_animation if it has one
• Sets the layout's is_active property to false

Note that Show/Hide set the root frame's active state and should not be used with DCEI.SetActive().

layout:HideImmediate()

Hides the layout's root frame as in Layout:Hide() but does not play the on_hide_animation. This is useful for initializing frames that are not visible on map start.

layout:Destroy()

Destroys the layout by running DCEI.Destroy(self.Frame) and clearing any references to the layout (such as with Layout:AddFrameReference()). This is the preferred method of destroying a layout (compared to calling DCEI.Destroy() directly), otherwise the global layout reference list may grow indefinitely.

layout:AddFrameReference( frame_to_add_reference_for )

Adds a reference that can be used to get the layout from the specified frame.

local layout01 = gmui.Layout:New()
local layout02 = gmui.Layout:New()
layout01:AddFrameReference(layout02.Frame)

function layout02:OnShow()
    local other_layout = gmui.GetLayoutFromFrameReference(self.Frame)

    -- sets the parent frame background to bright red when the child frame is shown
    DCEI.SetBackgroundImageColor(other_layout.Frame, 1, 0, 0, 1)
end

layout02:Show()

layout:OnShow()

An empty function that can be overwritten to execute functions when the layout is shown.

local layout = gmui.Layout:New({
    parent = ui.lower.Frame,
    name = "Menu/Leaderboard"
})

function layout:OnShow()
    -- shows the lower screen mask when the leaderboard is shown
    ui.lower.mask:Show()
end

layout:OnHide()

An empty function that can be overwritten to execute functions when the layout is hidden.

local layout = gmui.Layout:New({
    parent = ui.lower.Frame,
    name = "Menu/Leaderboard"
})

function layout:OnHide()
    -- hides the lower screen mask when the leaderboard is hidden
    ui.lower.mask:Hide()
end

layout:OnPress()

An empty function that exists for each layout to be overriden. This one has no explicit usage by itself, but is suggested for use if the layout is a button.

layout:Exists()

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

layout:GetChildCollection( collection_name )

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.

-- 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.SetText(child.Label, index)
end

gmui.Layout:New(args)

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.

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

local layout = gmui.Layout:New()
DCEI.SetSize(layout.Frame, 100, 100)
DCEI.SetBackgroundImageColor(layout.Frame, 1, 0, 0, 0.5)

• table args arguments for hooking up the layout.
  • (optional) Transform parent the parent frame to use when creating this layout. If no parent is given then DCEI.GetUiRoot() will be used instead.
  • (optional) xmlReference name 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.
  • (optional) AnimationPreset on_show_animation if used, this animtion preset will be run when the layout is shown.
  • (optional) AnimationPreset on_hide_animation if used, this animtion preset will be run when the layout is hidden.
  • (optional) Transform frame if used, a new layout will be created using the given frame.
  • (optional) boolean recursive_hookup if set, any child frames in the named XML using the include tag will be hooked up recursively as a layout instead of a frame.

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

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

local ui = {
    Root = DCEI.GetUiRoot()
}

function NewButton()
    local layout = gmui.Layout:New({
        parent = ui.Root,
        name = "Standard/Button/Button",
        on_show_animation = gmui.Animations.BackIn
    })

    -- layout
    DCEI.SetBackgroundImage(layout.Button, "btn_red")
    DCEI.SetText(layout.Label, "Press Me!")

    -- initialize
    layout:HideImmediate()
    return layout
end

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

gmui.GetLayoutFromFrameReference(frame)

Returns the layout table associated with the given frame. The frame must either be the root frame of a layout or a frame that has been associated with a layout via Layout:AddFrameReference().

local layout = gmui.Layout:New()
local layout_ref = gmui.GetLayoutFromFrameReference(layout.Frame)

-- note that (layout == layout_ref)
DCEI.SetSize(layout_ref.Frame, 100, 100)
DCEI.SetBackgroundImageColor(layout_ref.Frame, 1, 0, 0, 0.5)

gmui.AnimateFrameBetweenUnits(args)

Animates a frame from the position of one unit to another with the given arguments. Useful for creating world-position UI animations.

• table args arguments for the function.
  • Transform frame the frame to animate.
  • Unit unit1 the unit to animate from.
  • Unit unit2 the unit to animate to.
  • (optional) boolean no_loop if set, the animation will only play once.
  • (optional) number duration used to set the duration of the animation. If no duration is specified, 1.5 seconds will be used.
  • (optional) string loop_type choose the loop type. If no loop type is specified, Restart will be used. For loop types and how they function, see SetAnimationLoops()

local unit1 = DCEI.CreateUnitWithFacing(1, 1, "Standard MeleeUnit", 16, 16, 1, 0)
local unit2 = DCEI.CreateUnitWithFacing(1, 1, "Standard MeleeUnit", 13, 16, 1, 0)
    
local frame = DCEI.NewFrame(DCEI.GetUiRoot())
DCEI.SetSize(frame, 100, 100)
DCEI.SetBackgroundImageColor(frame, 1, 0, 0, 0.5)

local args = {
    frame = frame,
    unit1 = unit1,
    unit2 = unit2,
    duration = 3
}
gmui.AnimateFrameBetweenUnits(args)

gmui.AnimateFrameBetweenFrames(args)

Animates a frame from the position of one unit to another with the given arguments. Useful for creating world-position UI animations.

• table args arguments for the function.
  • Transform frame the frame to animate.
  • Transform start_frame the frame to animate from.
  • Transform end_frame the frame to animate to.
  • (optional) boolean preserve if set to true, the frame won't be destroyed
  • (optional) boolean no_loop if set, the animation will only play once.
  • (optional) number duration used to set the duration of the animation. If no duration is specified, 1.5 seconds will be used.
  • (optional) string loop_type choose the loop type. If no loop type is specified, Restart will be used. For loop types and how they function, see SetAnimationLoops()

    
local frame_1 = DCEI.NewFrame(DCEI.GetUiRoot())
DCEI.SetSize(frame_1, 100, 100)
DCEI.SetBackgroundImageColor(frame_1, 1, 0, 0, 0.5)

local frame_2 = DCEI.NewFrame(DCEI.GetUiRoot())
DCEI.SetSize(frame_2 , 100, 100)
DCEI.SetBackgroundImageColor(frame_1, 0, 1, 0, 0.5)
DCEI.SetVerticalOffsetInParent(frame_2, 100)
DCEI.SetHorizontalOffsetInParent(frame_2, 100)

local frame_3 = DCEI.NewFrame(DCEI.GetUiRoot())
DCEI.SetSize(frame_3 , 100, 100)
DCEI.SetBackgroundImageColor(frame_3, 0, 0, 1, 0.5)
DCEI.SetVerticalOffsetInParent(frame_3, -100)
DCEI.SetHorizontalOffsetInParent(frame_3, -100)

local args = {
    frame = frame_1,
    start_frame = frame_2,
    end_frame = frame_3,
    duration = 3
}
gmui.AnimateFrameBetweenFrames(args)

gmui.NewBigHand(args)

Creates and returns layout for an animated "Big Hand" from the given arguments. This is commonly used for building tutorial sequences.

The bighand can (and should) be destroyed with layout:Dimiss() when no longer needed:

local layout = gmui.NewBigHand()
DCEI.TriggerAddTimerEventElapsed(
    function()
        layout:Dismiss()
    end,
    2
)

• table args arguments for hooking up the layout.
  • (optional) Transform parent the parent frame to use when creating this layout. If no parent is given then DCEI.GetUiRoot() will be used instead.
  • (optional) float scale sets the scale of the big hand (default is 1 for 100% scale)
  • (optional) float horizontal_offset adds a horizontal offset to the position of the big hand.
  • (optional) float vertical_offset adds a vertical offset to the position of the big hand.
  • (optional) boolean flip if true, flips the big hand horizontally.
  • (optional) Transform frame if used, the big hand will be created at the position of the given frame. Can't be used with unit.
  • (optional) Unit unit if used, the big hand will be attached to the given unit. Can't be used with frame.
  • (optional) table unit_label_options used in conjunction with unit to provide attachment options as per the options parameter of DCEI.AttachToUnit().

local options = {
    frame = ui.glue_menu.post_score.Button,
    vertical_offset = -25,
    flip = true
}

ui.big_hand = gmui.NewBigHand(options)

gmui.NewBigHandBetweenUnits(args)

Animates a bighand from the position of one unit to another in a dragging motion.

• table args arguments for hooking up the layout.
  • Unit unit1 the unit to animate from.
  • Unit unit2 the unit to animate to.
  • (optional) boolean no_loop if set, the animation will only play once.
  • (optional) number duration used to set the duration of the
  • (optional) Transform parent the parent frame to use when creating this layout. If no parent is given then DCEI.GetUiRoot() will be used instead.
  • (optional) float scale sets the scale of the big hand (default is 1 for 100% scale)
  • (optional) float horizontal_offset adds a horizontal offset to the position of the big hand.
  • (optional) float vertical_offset adds a vertical offset to the position of the big hand.
  • (optional) boolean flip if true, flips the big hand horizontally.
  • (optional) table unit_label_options used in conjunction with unit to provide attachment options as per the options parameter of DCEI.AttachToUnit().

local unit1 = DCEI.CreateUnitWithFacing(1, 1, "Standard MeleeUnit", 16, 16, 1, 0)
local unit2 = DCEI.CreateUnitWithFacing(1, 1, "Standard MeleeUnit", 13, 16, 1, 0)

local args = {
    unit1 = unit1,
    unit2 = unit2,
    duration = 3
}
gmui.NewBigHandBetweenUnits(args)

gmui.NewPip(args)

Creates and returns layout for an animated "Red Pip" from the given arguments. This is commonly used for bringing player attention to specific UI elements.

The pip is initially hidden when created and can be shown with an attention grabbing animation by using layout:ShowAnimated() as such:

local layout = gmui.NewPip()
layout:ShowAnimated()

• table args arguments for hooking up the layout.
  • (optional) Transform parent the parent frame to use when creating this layout. If no parent is given then DCEI.GetUiRoot() will be used instead.
  • (optional) string anchor used to anchor the pip to the top left or top right of the parent frame. Accepts values "top_left" and "top_right" (defaults to "top_left").

local ui = {
    Root = DCEI.GetUiRoot()
}

function NewButton()
    local layout = gmui.Layout:New({
        parent = ui.Root,
        name = "Standard/Button/Button",
        on_show_animation = gmui.Animations.BackIn
    })

    -- layout
    DCEI.SetBackgroundImage(layout.Button, "btn_red")
    DCEI.SetText(layout.Label, "Press Me!")

    local pip = gmui.NewPip({
        parent = layout.Frame
    })

    -- functions
    function layout:OnShow()
        pip:ShowAnimated()
    end

    -- initialize
    layout:Show()
    return layout
end

ui.button = NewButton()

This mod comes with a number of animation templates that can easily be applied to any layout using the on_show_animation/on_hide_animation parameters (ex on_hide_animation = gmui.Animations.BackOut).

• BackIn
• BackOut
• UpIn
• UpOut
• DownIn
• DownOut
• FadeIn
• FadeOut

This mod comes with a number of ready-to-use XML frame templates.

• Standard/Menu/PauseMenu a simple pause menu with a stack for adding menu options
• Standard/Layer/Mask a fullscreen dark mask
• Standard/Layer/Fullscreen a fullscreen frame, useful for creating UI layers
• Standard/Helper/RedPip a red pip, used in the NewPip layout
• Standard/Helper/BigHand a big hand, used in the BigHand layout
• Standard/Button/UpgradeButton a basic upgrade button with a cost label and icon
• Standard/Button/ResourceFrame a non-button resource frame
• Standard/Button/ResourceFramePlusButton a resource frame as a button, perfect for hookup up to an in-game shop
• Standard/Button/PauseButton a pause button resembling the default game pause button
• Standard/Button/PauseButton_InGame a pause button in the same position as the default game pause button, useful for overriding the default pause button functionality
• Standard/Button/Button a basic labeled button

• AnimateFrameBetweenFrames has a "preserve" arg so the frame isn't destroyed after animating
• Fixed a bug where AnimateFrameBetweenFrames didn't use default value for "ease"

• Layout is_active property is now set on initialization based on whether or not the root frame is actually active, rather than defaulting to true
• Added Layout:Exists() to check if a layout frame still exists
• Added Layout:GetChildCollection() to get a table of ordered children frames

• Layout child id references are now hookedup automatically and don't need to be declared in refs
• Added new function AnimateFrameBetweenUnits()
• Added new function NewBigHandBetweenUnits()

• Added Layout:Destroy() to destroy a layout and update the layout references list
• Fixed an issue with default animation templates that could cause frames to become stuck when Hiding/Showing too quickly
• Show/Hide/HideImmediate actions will no longer be called subsequently if the layout is already in the relevant state
• Add some small improvements to the UI test map (dimiss repeated score notifications, use new Destroy method)

• UI Mod released