Mod Tools

WIP, not in release builds yet

Mod tools are similar to scripts except they can create GUIs.

Functions

-- These 4 functions return a table that represent the GUI element.
gui.create_dockpanel(lastChildFill : boolean) -> table
gui.create_stackpanel(isVertical : boolean)   -> table
gui.create_button(text : string)              -> table
gui.create_text(text : string)                -> table

-- Sets the GUI's root panel to draw
gui.set_root_panel(panel : table)

Functions for all GUI elements

-- Horizontally aligns this element relative to the parent. Can be "stretch", "left", "center" or "right"
set_align_h(align : string)

-- Vertically aligns this element relative to the parent. Can be "stretch", "top", "center" or "bottom"
set_align_v(align : string)

DockPanel functions

-- Adds an element docked to either "left", "top", "right" or "bottom"
add(dock : string, element : table)
-- Adds an element docked to the left. Ideally only use for the last child when lastChildFill is true
add(element : table)

StackPanel functions

-- Adds an element
add(element : table)

Button functions

-- Sets the function that runs when the user clicks then releases their mouse on the button
set_press_function(callback : function)

-- Sets the function that is called in a loop while the user has left-click pressed.
-- The 'delta' parameter is the amount of time since the callback was last called, in seconds. 
-- Note! Do not create your own loop inside of this, because the outer loop will pump any queued messages automatically.
-- If you need a loop, call `pump.try_run_messages()` often
set_holding_function(callback : function(delta : number) -> boolean)

-- Sets the button's text
set_text(text : string)

Note

The holding function is provided the delta time between each callback invocation. On the first run, it will be very very small. You should use this if you need to, for example, increase a float on the console at a fixed rate (e.g. 25.0 per second).

Example: engine.writenumber(addr, "float", 25.0 * delta)

Text Block functions

-- Sets the text of the text block
set_text(text : string)

Example

press_btn_counter = 0
holding_btn_counter = 0

function CreateTestDock(side)
    -- create a dock panel that won't fill the last child control, 
    -- since we want a left and right dock
    local dock = gui.create_dockpanel(false)

    -- create a horizontal stack panel
    local bottom_spL = gui.create_stackpanel(true)
    bottom_spL.add(bottom_spL, gui.create_button(side .. " left btn 1"))
    bottom_spL.add(bottom_spL, gui.create_button(side .. " left btn 2"))
    bottom_spL.add(bottom_spL, gui.create_button(side .. " left btn 3"))  

    -- create a horizontal stack panel
    local bottom_spR = gui.create_stackpanel(true)
    bottom_spR.add(bottom_spR, gui.create_button(side .. " right btn 1"))
    bottom_spR.add(bottom_spR, gui.create_button(side .. " right btn 2"))
    bottom_spR.add(bottom_spR, gui.create_button(side .. " right btn 3"))

    -- add panels to the dock
    dock.add(dock, "left", bottom_spL)
    dock.add(dock, "right", bottom_spR)

    return dock
end

-- create our root panel, which will fill the last child (tmpstack)
-- to the window contents (inbetween the top and bottom docks ofc)
local root = gui.create_dockpanel(true)
root.add(root, "top", CreateTestDock("Top "))
root.add(root, "bottom", CreateTestDock("Bottom "))

-- create a vertical stack panel
local tmpstack = gui.create_stackpanel(true)
tmpstack.add(tmpstack, gui.create_text("Hello!"))

local tmpbutton1 = gui.create_button("Click to incr per press")
tmpbutton1.set_press_function(tmpbutton1, function ()
    press_btn_counter = press_btn_counter + 1
    tmpbutton1.set_text(tmpbutton1, press_btn_counter)
end)

tmpstack.add(tmpstack, tmpbutton1)

local tmpbutton2 = gui.create_button("Click to incr while holding")
tmpbutton2.set_holding_function(tmpbutton2, function (delta)
    holding_btn_counter = holding_btn_counter + 1
    tmpbutton2.set_text(tmpbutton2, holding_btn_counter)
end)

tmpstack.add(tmpstack, tmpbutton2)

root.add(root, tmpstack)

-- assign root panel to the GUI
gui.set_root_panel(root)

-- the important part. In order for button clicks to work, 
-- pump.run_messages() must be called often
while true do 
    pump.run_messages()
end