GMUI Overview

The GMUI 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.

For legacy projects, see the older version of this mod, gmui.

Documentation

All of the GMUI functionality is documented with annotations, meaning when once you include GMUI with local GMUI = require("GMUI") hovering over or typing the "GMUI" variable name will display help text about all of the contained classes and functions. These annotations have been exported as a wiki page of Documentation as well.

How to install:

First open the Project Settings Window and add GMUI as a registry dependency:
image
Then include in your lua file with local GMUI = require("GMUI:Simulation")

Example Usage & Demo Map

See the GMUI Feature Demo map: https://platform.wildsky.dev/arcade/game/989 (Click "Source" to download)

Here is a Lua snippet from the most recent demo to give you a quick rundown of how to use GMUI for UI in Lua. Be sure to download the project for a closer look, and reference the rest of this document for more documentation on the GMUI mod. 

-- LIBRARIES
local Core = require("Core:Simulation")
local GMUI = require("GMUI:Simulation")
local data = require("game_data")

-- SCRIPT EXPORTS
local ui = {}

-- =======================================================================================
-- ANCHOR (1) LAYOUT BASICS
-- start here for the basics on how to use GMUI layouts, their methods, and xml states
-- =======================================================================================
-- NOTE: will hook up all includes as a hierarchy of layout object references
ui.glue = GMUI.Layout.New({
    name = "Glue",
    recursive_hookup = true,
})

-- GAME PAGE
-- since "Glue/Pages" was included in "Glue" with id "pages", it can now be referenced as `ui.glue.pages`
-- and since "Glue/Pages/Game" was in "Glue/Pages" with id "game", it can be referenced as `ui.glue.pages.game`
local layout = ui.glue.pages.game

-- NOTE: a layout is just a class object that represents XML defined in data
-- you can add properties to it, just like any other table
layout.button_press_count = 0

function layout:Initialize()
    -- NOTE: the root frame of a layout is automatically assigned the id "Frame" by GMUI
    -- we can create a mask by adjusting the root frame's image color on init
    DCEI.SetFrameImageColor(self.Frame, { r = 0, g = 0, b = 0, a = 0.5 })

    -- set this layout as initialized
    self.is_initialized = true
end

function layout:Update()
    -- initialize this layout the first time it updates
    if not self.is_initialized then
        self:Initialize()
    end

    -- NOTE: any frame within the XML can be referenced by its id; here we're updating `ToggleCountLabel`
    -- note how "{[x]}"" in the translation text is replaced by the `x` key value
    local text = DCEI.GetTranslationText("ui/game/buttons_pressed", { x = self.button_press_count })
    DCEI.SetTextFrameText(self.ToggleCountLabel, text)
end

Features

Layout Class

LazyLayout Class

LayoutComponent

UiHelper

InputState

Debug