Creating a User Interface

Scripts can create user interfaces using Dear Imgui. Currently it's beyond the scope of this document to provide a full tutorial on using imgui, but you can check out imgui_demo.cpp to get a feel for how to create uis, and use it as a reference. It can be helpful to look at the ingame imgui demo by enabling the GUI.EnableDemoUI setting.

Creating a basic user interface

We'll start by creating a basic user interface that shows our character's current stance. Create a new script and put in the following:

-- some hud configuration
local minWindowSize = Vector2.new(200, 60)
local maxWindowSize = Vector2.new(99999, 99999)

-- create our hud
local myHud = game.CreateHud("My Stance")

-- Handler for myHud.onPreRender. This gets called before the hud is rendered.
-- We can use it to set our window constraints, or window position for example.
local myHud_onPreRender = function()
  -- give our hud some window size constraints
  ImGui.SetNextWindowSizeConstraints(minWindowSize, maxWindowSize)
end

-- Handler for myHud.OnRender. This gets called each time this hud should render
-- its contents. We do all the drawing of controls here.
local myHud_onRender = function()
  -- display some text with our current character stance
  ImGui.Text("Current Stance: " .. tostring(game.Character.Stance))
end

-- subscribe to hud events, with the handlers we defined above
myHud.OnPreRender.Add(myHud_onPreRender)
myHud.OnRender.Add(myHud_onRender)

-- subscribe to the onScriptEnd event and clean up our hud
game.OnScriptEnd.Once(function()
  -- unsubscribe from hud events
  myHud.OnPreRender.Remove(myHud_onPreRender)
  myHud.OnRender.Remove(myHud_onRender)

  -- destroy the hud
  myHud.Dispose()
end)

Accepting user input

Here's an example of accepting text input from a user, along with a button to print it out to the chat window:

-- some hud configuration
local minWindowSize = Vector2.new(300, 120)
local maxWindowSize = Vector2.new(99999, 99999)

-- this will store our text from the ui
local myText = ""

-- create our hud
local myHud = game.CreateHud("My Input")

-- Handler for myHud.onPreRender. This gets called before the hud is rendered.
-- We can use it to set our window constraints, or window position for example.
local myHud_onPreRender = function()
  -- give our hud some window size constraints
  ImGui.SetNextWindowSizeConstraints(minWindowSize, maxWindowSize)
end

-- Handler for myHud.OnRender. This gets called each time this hud should render
-- its contents. We do all the drawing of controls here.
local myHud_onRender = function()
  -- display our current text value
  ImGui.Text("Current Text: " .. myText)

  -- display a text input, inputChaged is a bool that tells us if the input
  -- value has changed, and textResult is the new value it was set to. 500
  -- is the max length this input accepts
  local inputChanged, textResult = ImGui.InputText("myText Input", myText, 500)

  if inputChanged then
    myText = textResult
    print("myText was changed to:", myText)
  end

  -- display a button to print myText to chat
  -- ImGui.Button returns true if the button was clicked
  if ImGui.Button("Print myText to chat") then
    print("myText is", myText)
  end
end

-- subscribe to hud events, with the handlers we defined above
myHud.OnPreRender.Add(myHud_onPreRender)
myHud.OnRender.Add(myHud_onRender)

-- subscribe to the onScriptEnd event and clean up our hud
game.OnScriptEnd.Once(function()
  -- unsubscribe from hud events
  myHud.OnPreRender.Remove(myHud_onPreRender)
  myHud.OnRender.Remove(myHud_onRender)

  -- destroy the hud
  myHud.Dispose()
end)