Please see Usage for more examples and best practices.

Table of Contents

• Functions
  • GUI.createMenu(…)
  • GUI.addButton(…)
  • GUI.setActiveMenu(…)
  • GUI.tick()
  • GUI.updateStatusText(…)
  • GUI.isActiveButtonToggledOn()
  • GUI.isButtonToggledOn(…)
  • GUI.toggleButtonState(…)
  • GUI.removeButton(…)
  • GUI.removeMenu(…)
• Variables
  • GUI.navButtons = { … }
  • GUI.titleColor = { … }
  • GUI.buttonColor = { … }
  • GUI.activeButtonColor = { … }
  • GUI.sound = { … }

Functions

GUI.createMenu(…)

GUI.createMenu(menuName, prevMenu, title, menuX, menuY, buttonWidth, buttonHeight, buttonSpacing, fontSize, fontName, saveLastButtonPos)

• menuName  <string>  Name of the menu that GUI.createMenu is creating
• prevMenu  <string>  Name of the menu that the navBack key should take the user to when inside this menu. Set to nil to close the menu altogether.
• title  <string>  Text that appears at the top, above the buttons
• menuX  <number>  Top left of the menu starting x position
• menuY  <number>  Top left of the menu starting y position
• buttonWidth  <number>  How wide each button should be in the x direction
• buttonHeight  <number>  How tall each button should be in the y direction
• buttonSpacing  <number>  How tall the gap should be between each button
• fontSize  <number>  How tall the font should be in pixels
• fontName  <string>  Name of .ttf file to use for the font (suggested bold.ttf)
• saveLastButtonPos  <boolean>  After exiting and re-entering the menu, should the button the user on be remembered? If false, it will be reset back to the first button.
• Returns: nothing

--the g(lobal) table is used to keep non-tabled global variables from being leaked across multiple lua files. See Usage.
g = {}
g.menuX = 10
g.menuY = 10
g.buttonWidth = 225
g.buttonHeight = 50
g.buttonSpacing = 3
g.fontSize = 23
g.fontName = "bold.ttf"
g.saveLastButtonPos = true

GUI.createMenu("main", nil, "Mod Menu", g.menuX, g.menuY, g.buttonWidth, g.buttonHeight, g.buttonSpacing, g.fontSize, g.fontName, g.saveLastButtonPos)

GUI.addButton(…)

GUI.addButton(parentMenu, text, funct, args, toggleable, textScale, font)

• parentMenu  <string>  What menu this button belongs to.
• text  <string>  Text drawn on the button
• funct  <function>  Callback function for when the user presses the select key
• args  <table>  Up to 20 arguments to feed into the defined funct. {arg1, ..., arg20}. Can also be a single  <string> ,  <boolean> , or  <number> 
• toggleable  <boolean>  Should button be a toggleable button? Will have [ON] or [OFF] appended to the end of the button text, and the state can be grabbed at any time
• textScale <number>  how tall the font should be in pixels (aka font size)
• font <string>  name of .ttf file to use for the font (suggested bold.ttf)
• Returns: nothing

Adds a button to a menu that has already been created. parentMenu must match the name of a menu already created, otherwise this will not work.

The position in the menu, and the index of the button are dependent on when the button is added. If you want button x to appear before button y, you will need to addButton() x first.

See GUI.createMenu for what g can be in the example below.

GUI.createMenu("main", nil, "Mod Menu", g.menuX, g.menuY, g.buttonWidth, g.buttonHeight, g.buttonSpacing, g.fontSize, g.fontName, g.saveLastButtonPos)
GUI.addButton("main", "Player Menu >", GUI.setActiveMenu, "player_functions", false, g.fontSize, g.fontName)
GUI.addButton("main", "Vehicle Menu >", GUI.setActiveMenu, "vehicle_functions", false, g.fontSize, g.fontName)
GUI.addButton("main", "Empty Menu >", GUI.setActiveMenu, "empty_menu", false, g.fontSize, g.fontName)
GUI.addButton("main", "Exit", GUI.setActiveMenu, nil, false, g.fontSize, g.fontName)

GUI.setActiveMenu(…)

GUI.setActiveMenu(menuName)

• menuName  <string>  Name of the menu the menu that should be drawn currently
• Returns: nothing

Will start drawing menuName immediately. Often used as a callback for GUI.addButton to create a sub menu. Set funct = GUI.setActiveMenu and args = "NameOfMenu". Can also be called at any time.

GUI.setActiveMenu("main")
--or
GUI.addButton("main", "Player Menu >", GUI.setActiveMenu, "player_functions", false, g.fontSize, g.fontName)

GUI.tick()

GUI.tick()

• Returns: nothing

Must be called by draw() in order for the GUI to function. If you add it to the tick() function, it will be called out of order when rendering the menu and won’t appear.

function draw()
    GUI.tick()
end

GUI.updateStatusText(…)

GUI.updateStatusText(text, time)

• text <string>  Text to display as a message
• time <number>  Time in seconds for how long message should last
• Returns: nothing

Think of this as a toast message. text will appear on the screen for time in big letters, so the user knows what is happening at a glance.

GUI.updateStatusText("Enabled God mode!", 2.5)

GUI.isActiveButtonToggledOn()

GUI.isActiveButtonToggledOn()

• Returns:  <boolean>  True if button is set to [ON], false otherwise.

Returns the state of the button the user currently has highlighted. This seems useless at first glance, but it’s very handy when a toggle-able button is mapped to a function, and you need to know if you should enable or disable said function.

main.toggleGodMode = function()
    if(GUI.isActiveButtonToggledOn()) then
        --do something
        GUI.updateStatusText("Enabled God mode", 2.5)
    else
        --do something
        GUI.updateStatusText("Disabled God mode", 2.5)
    end
end

GUI.createMenu("main", "", "Mod Menu", g.menuX, g.menuY, g.buttonWidth, g.buttonHeight, g.buttonSpacing, g.fontSize, g.fontName, g.saveLastButtonPos)
GUI.addButton("main", "God mode", main.toggleGodMode, nil, true, g.fontSize, g.fontName)

GUI.isButtonToggledOn(…)

GUI.isButtonToggledOn(menu, index)

• menu <string>  Menu that the button belongs to
• index <number>  index of button in menu. Index starts at 1 (not 0 like most other languages)
• Returns:  <boolean>  True if button is set to [ON], false otherwise.

Similar to GUI.isActiveButtonToggledOn(), except you can check a specific button instead.

local toggled = GUI.isButtonToggledOn("player_functions", 3)

GUI.toggleButtonState(…)

GUI.toggleButtonState(menu, index)

• menu <string>  Menu that the button belongs to
• index <number>  index of button in menu. Index starts at 1 (not 0 like most other languages)
• Returns: nothing

Gives you the ability to manually toggle a button on or off. Useful if other buttons rely on a different button to be on or off.

some_cool_menu.turnOffAbilities = function()
	if(GUI.isButtonToggledOn("some_cool_menu", 5)) then
		GUI.toggleButtonState("some_cool_menu", 5)
	end

	if(GUI.isButtonToggledOn("some_cool_menu", 6)) then
		GUI.toggleButtonState("some_cool_menu", 6)
	end
end

some_cool_menu.turnOffAbilities()

GUI.removeButton(…)

GUI.removeButton(menu, index)

• menu <string>  Menu that the button belongs to
• index <number>  index of button in menu. Index starts at 1 (not 0 like most other languages)
• Returns: nothing

Removes button index from menu. Useful for menus that are actively changing (e.g. a list of players currently in the session)

GUI.removeButton("some_cool_menu", 4)

GUI.removeMenu(…)

GUI.removeMenu(menu)

• menu <string>  Menu that is being deleted
• Returns: nothing

Sets menu to nil - making it unable to be drawn again.

GUI.removeMenu("some_uncool_menu")

These functions have been documented for reference, but should not be called. They are internal functions for the GUI library.

Variables

GUI.navButtons = { … }

GUI.navButtons is designed to take 0, 1, or multiple keys as variables. The keys variable is a table of  <string> . A list of available keys can be found on the Teardown API.

GUI.menuOpen.menu is the menu  <string>  that will open when any of the menuOpen keys are pressed.

Definition:

GUI.navButtons = {
	menuOpen = {
		keys = {<string>},
		menu = <string>
	}, 
	menuClose = {keys = {<string>}},
	navUp = {keys = {<string>}},
	navDown = {keys = {<string>}},
	select = {keys = {<string>}},
	navBack = {keys = {<string>}}
}

Example:

GUI.navButtons = {
    menuOpen = {
        keys = {"m"},
        menu = "main"
    },
    menuClose = {keys = {}},
    navUp = {keys = {"i", "up"}},
    navDown = {keys = {"k", "down"}},
    select = {keys = {"l", "return", "right"}},
    navBack = {keys = {"j", "left"}}
}

GUI.titleColor = { … }

Sets the color for the menu title via RGBA. The color is for every menu created. A tad bit of transparency a is recommended so the player can see what’s behind the menu. 1 is completely opaque, 0 is transparent. Set this when initiating the GUI.

Definition:

GUI.titleColor = {
	r = <number>[0-255],
	g = <number>[0-255],
	b = <number>[0-255],
	a = <number>[0-1]
}

Example:

GUI.titleColor = {
	r = 255, 
	g = 100, 
	b = 100, 
	a = .9
}

GUI.buttonColor = { … }

Sets the color of the buttons via RGBA. The color is across every menu created. A tad bit of transparency a is recommended so the player can see what’s behind the menu. 1 is completely opaque, 0 is transparent. Set this when initiating the GUI.

Definition:

GUI.buttonColor = {
	r = <number>[0-255],
	g = <number>[0-255],
	b = <number>[0-255],
	a = <number>[0-1]
}

Example:

GUI.buttonColor = {
	r = 20,
	g = 20,
	b = 20,
	a = .9
}

GUI.activeButtonColor = { … }

Sets the color of the button currently active (the one the user has selected) via via RGBA. The color is across every menu created. A tad bit of transparency a is recommended so the player can see what’s behind the menu. 1 is completely opaque, 0 is transparent. Set this when initiating the GUI.

This color should be different from GUI.buttonColor.

Definition:

GUI.activeButtonColor = {
	r = <number>[0-255],
	g = <number>[0-255],
	b = <number>[0-255],
	a = <number>[0-1]
}`

Example:

GUI.activeButtonColor = {
	r = 20,
	g = 20,
	b = 20,
	a = .9
}

GUI.sound = { … }

GUI.sound.tick_down is played when the user navigates up or down.

GUI.sound.tick_up is played when the user presses select.

See the game API on LoadSound.

Example:

GUI.sound = {
	tick_up = LoadSound("media/tick_up.ogg"),
	tick_down = LoadSound("media/tick_down.ogg")
}