Mods UserInterface Mod - funovus/editor-wiki GitHub Wiki
Table of Contents
|
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:
- 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: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 totrue
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 tofalse
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)
.
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 thenDCEI.GetUiRoot()
will be used instead. - (optional) xmlReference
name
if used, the layout will be created from the given XML reference. If noname
orframe
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 theinclude
tag will be hooked up recursively as a layout instead of a frame.
- (optional) Transform
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.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()
-
Transform
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()
-
Transform
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 thenDCEI.GetUiRoot()
will be used instead. - (optional) float
scale
sets the scale of the big hand (default is1
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 withunit
. - (optional) Unit
unit
if used, the big hand will be attached to the given unit. Can't be used withframe
. - (optional) table
unit_label_options
used in conjunction withunit
to provide attachment options as per theoptions
parameter of DCEI.AttachToUnit().
- (optional) Transform
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 thenDCEI.GetUiRoot()
will be used instead. - (optional) float
scale
sets the scale of the big hand (default is1
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 withunit
to provide attachment options as per theoptions
parameter of DCEI.AttachToUnit().
-
Unit
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 thenDCEI.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"
).
- (optional) Transform
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