This is an old revision of the document!
With our GUI API you can easily build your own UI purely in LUA. Each rendered frame the “Gameloop.Draw” - Event gets called. You need to register a function for this event and let it draw/build your UI. There are no c++ sided objects created or maintained, everything you have to do in LUA.
GUI Overview:
To get an overview what is possible with the UI, open the ingame console (CTRL + C) and execute this command:
ml_gui.showtestwindow = true
If you find in that testwindow what you need but you are unsure how to build the same in lua, you can have a look in the c++ source of this testwindow : https://github.com/ocornut/imgui/blob/master/imgui_demo.cpp, the used function names and syntax in there are 99% the same, just the arguments may be slightly different due to lua not supporting references.
IMPORTANT INFO:
Underlined function arguments are optional!
Example:
GUI:Begin(string name, bool open, windowflags flags)
IMPORTANT INFO:
Most UI Elemet “names” or “labels” are at the same time their internal identifier.
Example: Name is internal identifier
GUI:Begin(“Banana”, true)
Example: Same name in UI, different internal identifier
GUI:Begin(“Banana##123hohoho”, true)
GUI:Begin(“Banana##hohoho456”, true)
Example: Different name in UI, same internal identifier
GUI:Begin(“Banana###123hohoho”, true)
GUI:Begin(“Pineapple###123hohoho”, true)
To get you started, let's draw a simple window with a slider, create a new .lua file, add it to your addon's module.def and put the following code into that new lua file:
-- Draws a Window with a Slider: my_gui = {} my_gui.open = true my_gui.visible = true my_gui.hue = 125 function my_gui.Draw( event, ticks ) if ( my_gui.open ) then GUI:SetNextWindowSize(250,400,GUI.SetCond_FirstUseEver) -- set the next window size, only on first ever, GUI.SetCond_FirstUseEver is one of many possible enums. --GUI:Begin takes in two arguments, the name of the window and the current "is open" bool. It returns "is visible/is not collapsed" and the "is open" bool again. --If the user would close our Window, "is open" would return "false", else it will keep returning "true" as long as the window is open. my_gui.visible, my_gui.open = GUI:Begin("My Fancy GUI", my_gui.open) if ( my_gui.visible ) then -- visible is true/false depending if the window is collapsed or not, we don't have to render anything in it when it is collapsed -- Again the typical syntax, passing the current value "hue" to the function as argument and receiving back the (un-)changed value. my_gui.hue = GUI:SliderInt("Master HUE",my_gui.hue,0,255) d(my_gui.hue) -- spam print out the current value end GUI:End() -- THIS IS IMPORTANT! For EVERY BEGIN() you NEED to ALWAYS call END(), it does not matter if the window is visible/open or not! Same goes with BeginChild() & EndChild() and others ! end end RegisterEventHandler("Gameloop.Draw", my_gui.Draw)
Usage: GUI:ShowTestWindow( isopen )
ShowTestWindow(bool isopen)
ShowMetricsWindow(bool isopen)
RenderManager:WorldToScreen(table worldpos)
Usage: GUI:Begin( … )
Begin(string name, bool open, windowflags flags)
End()
BeginChild(string name, int sizeX, int sizeY, bool border, windowflags flags
EndChild()
GetContentRegionMax()
GetContentRegionAvail()
GetContentRegionAvailWidth()
GetWindowContentRegionMin()
GetWindowContentRegionMax()
GetWindowContentRegionWidth()
GetWindowFontSize()
SetWindowFontScale( number scale)
GetWindowPos()
GetWindowSize()
GetWindowWidth()
GetWindowHeight()
IsWindowCollapsed()
SetNextWindowPos( number X, number Y, SetCondflags flags)
SetNextWindowPosCenter( SetCondflags flags)
SetNextWindowSize( number X, number Y, SetCondflags flags)
SetNextWindowContentSize( number X, number Y)
SetNextWindowContentWidth( number width)
SetNextWindowCollapsed( bool collapsed, SetCondflags flags)
SetNextWindowFocus()
SetWindowPos( number X, number Y, SetCondflags flags)
SetWindowPos( string name, number X, number Y, SetCondflags flags)
SetWindowSize( number X, number Y, SetCondflags flags)
SetWindowSize( string name, number X, number Y, SetCondflags flags)
SetWindowCollapsed( bool collapsed, SetCondflags flags)
SetWindowCollapsed( string name, bool collapsed, SetCondflags flags)
SetWindowFocus( string name)
GetScrollX()
GetScrollY()
GetScrollMaxX()
GetScrollMaxY()
SetScrollX( number scrollX)
SetScrollY( number scrollX)
SetScrollHere( number center_y_ratio)
SetScrollFromPosY( number pos_y, number center_y_ratio)
SetKeyboardFocusHere(number offset)
Usage: GUI:PushStyleColor( … )
PushStyleColor(ImGuiCol flags, number R, number G, number B, number A)
PopStyleColor( number count )
PushStyleVar(StyleVar flags, number val, number val2)
PopStyleVar( number count )
GetColorU32( number r, number g, number b, number a )
PushItemWidth( number item_width )
PopItemWidth( )
CalcItemWidth( )
PushTextWrapPos( number wrap_pos_x )
PopTextWrapPos( )
PushAllowKeyboardFocus( bool val )
PopAllowKeyboardFocus( )
PushButtonRepeat( bool repeat)
PopButtonRepeat( )
Usage: GUI:BeginGroup( … )
BeginGroup( )
EndGroup( )
Separator( )
SameLine( number local_pos_x, number spacing_w )
NewLine()
Spacing( )
Dummy( number sizeX, number sizeY )
Indent( )
Unindent( )
Columns( number count, string name, bool border )
NextColumn( )
GetColumnIndex( )
GetColumnOffset( int column_index )
SetColumnOffset( int column_index, number offset_x )
GetColumnWidth( int column_index )
GetColumnsCount( )
AlignFirstTextHeightToWidgets( )
GetTextLineHeight( )
GetTextLineHeightWithSpacing( )
GetItemsLineHeightWithSpacing( )
If you are creating widgets in a loop you most likely want to push a unique identifier so ImGui can differentiate them. You can also use “##extra” within your widget name to distinguish them from each others. Usage: GUI:PushID( … )
PushID( string id)
PopID( )
GetID( string id)
Usage: GUI:GetCursorPos( … )
GetCursorPos( )
GetCursorPosX( )
GetCursorPosY( )
SetCursorPos( number x, number y )
SetCursorPosX( number x )
SetCursorPosY( number y )
GetCursorStartPos( )
GetCursorScreenPos( )
SetCursorScreenPos( number x, number y )
Usage: GUI:AddCircleFilled( 300, 300, 475,GUI:ColorConvertFloat4ToU32(0.9,0.1,0.12,0.5)) IMPORTANT: Use GUI:ColorConvertFloat4ToU32() to calculatethe required numbercolor argument!!
AddLine( number X1, number Y1, number X2, number Y2, number color, number thickness = 1.0,)
AddRect( number X1, number Y1, number X2, number Y2, number color, number rounding= 0.0, number rounding_corners = 0.0)
AddRectFilled( number X1, number Y1, number X2, number Y2, number color, number rounding= 0.0, number rounding_corners = 0.0)
AddTriangleFilled( number X1, number Y1, number X2, number Y2, number X3, number Y3, number color)
AddCircle( number X1, number Y1, number radius, number color, number num_segments= 12)
AddCircleFilled( number X1, number Y1, number radius, number color, number num_segments= 12)
AddText( number X1, number Y1, number color, string text)
AddImage( string texturepath, number X1, number Y1, number X2, number Y2)
Usage: GUI:Text( … )
Text( string text)
TextColored( number R, number G, number B, number A,string text)
TextDisabled( string text)
TextWrapped( string text)
TextUnformatted( string text)
LabelText( string label, string text)
Bullet( )
BulletText( string text)
Button( string label, number sizeX, number sizeY)
SmallButton( string label)
InvisibleButton( string label, number sizeX, number sizeY)
FreeButton( string label, number posX, number posY, number sizeX, number sizeY)
FreeImageButton( /string internalid, string filepath, number posX, number posY, number sizeX, number sizeY)
ImageButton(string internalid, string filepath, number sizeX, number sizeY, number UV0_x, number UV0_y, number UV1_x, number UV1_y, number framepadding,number bg_col_R, number bg_col_G, number bg_col_B, number bg_col_A, number tint_col_R, number tint_col_G, number tint_col_B, number tint_col_A )
Image(string filepath, number sizeX, number sizeY, number UV0_x, number UV0_y, number UV1_x, number UV1_y, number bg_col_R, number bg_col_G, number bg_col_B, number bg_col_A, number tint_col_R, number tint_col_G, number tint_col_B, number tint_col_A )
CollapsingHeader( string label, string id, bool display_frame, bool default_open)
Checkbox( string label, bool checked)
CheckboxFlags( string label, number flags, number flags_value)
RadioButton( string label, bool active)
RadioButton( string label, number val, bool active)
Combo( string label, number current_item_listindex, table itemlist, number height_in_items)
ColorButton( number R, number G, number B, number A, bool small_height, bool outline_border)
ColorEdit3( string label, number R, number G, number B)
ColorEdit4( string label, number R, number G, number B, number A)
ColorEditMode( ColorEditMode mode)
ProgressBar( number fraction, number SizeX, number SizeY, string overlay )
(tip: ctrl+click on a drag box to input text) Usage: GUI:Text( … )
DragFloat( string label, number val, number v_speed, number v_min, number v_max, string display_format, number power)
DragFloatRange2( string label, number v_current_min, number v_current_max, number v_speed, number v_min, number v_max, string display_format, string display_format_max, number power)
DragInt( string label, number val, number v_speed, number v_min, number v_max, string display_format)
DragIntRange2( string label, number v_current_min, number v_current_max, number v_speed, number v_min, number v_max, string display_format, string display_format_max)
Usage: GUI:InputText( … )
InputText( string label, string text, InputTextFlags flags)
InputTextMultiline( string label, string text, number sizeX, number sizeY , InputTextFlags flags)
InputFloat( string label, number val, number step, number step_fast, number decimal_precision, InputTextFlags flags)
InputFloat2( string label, number val, number val2, number decimal_precision, InputTextFlags flags)
InputFloat3( string label, number val, number val2, number val3, number decimal_precision, InputTextFlags flags)
InputFloat4( string label, number val, number val2, number val3, number val4, number decimal_precision, InputTextFlags flags)
InputInt( string label, number val, number step, number step_fast, InputTextFlags flags)
InputInt2( string label, number val, number val2, InputTextFlags flags)
InputInt3( string label, number val, number val2, number val3, InputTextFlags flags)
InputInt4( string label, number val, number val2, number val3, number val4, InputTextFlags flags)
Usage: GUI:SliderFloat( … )
SliderFloat( string label, number val, number v_min, number v_max, string display_format, number power)
SliderFloat2( string label, number val, number val2, number v_min, number v_max, string display_format, number power)
SliderFloat3( string label, number val, number val2, number val3, number v_min, number v_max, string display_format, number power)
SliderFloat4( string label, number val, number val2, number val3, number val4, number v_min, number v_max, string display_format, number power)
SliderAngle( string label, number v_rad, number v_degrees_min, number v_degrees_max)
SliderInt( string label, number val, number v_min, number v_max, string display_format)
SliderInt2( string label, number val, number val2, number v_min, number v_max, string display_format)
SliderInt3( string label, number val, number val2, number val3, number v_min, number v_max, string display_format)
SliderInt4( string label, number val, number val2, number val3, number val4, number v_min, number v_max, string display_format)
VSliderFloat( string label, number sizeX, number sizeY, number val, number v_min, number v_max, string display_format, number power)
VSliderInt( string label, number sizeX, number sizeY, number val, number v_min, number v_max, string display_format)
Usage: GUI:TreeNode( … )
TreeNode( string label)
TreePush( string id)
TreePop( )
SetNextTreeNodeOpened( bool opened, SetCond cond )
Usage: GUI:Selectable( … )
Selectable( string label, bool selected, SelectableFlags flags, number sizeX, number sizeY )
ListBox( string label, number current_listitem_index, table itemlist, number height_in_items )
ListBoxHeader( string label, number items_count, number height_in_items )
ListBoxFooter( )
Usage: GUI:SetTooltip( … )
SetTooltip( string label )
BeginTooltip( )
EndTooltip( )
Usage: GUI:BeginMainMenuBar( … )
BeginMainMenuBar( )
EndMainMenuBar( )
BeginMenuBar( )
EndMenuBar( )
BeginMenu( string label, bool enabled )
EndMenu( )
MenuItem( string label, string shortcut, bool selected, bool enabled)
Usage: GUI:OpenPopup( … )
OpenPopup( string id)
BeginPopup( string id)
BeginPopupModal( string name, bool opened, WindowFlags flags)
BeginPopupContextItem( string id, number mouse_button)
BeginPopupContextWindow( bool also_over_items, string id, number mouse_button)
BeginPopupContextVoid( string id, number mouse_button)
EndPopup( )
CloseCurrentPopup( )
Usage: GUI:IsItemHovered( … )
IsItemHovered( )
IsItemHoveredRect( )
IsItemClicked( int mousebutton == 0)
IsItemActive( )
IsItemVisible( )
IsAnyItemHovered( )
IsAnyItemActive( )
GetItemRectMin( )
GetItemRectMax( )
GetItemRectSize( )
SetItemAllowOverlap( )
IsWindowHovered( )
IsWindowFocused( )
IsRootWindowFocused( )
IsRootWindowOrAnyChildFocused( )
IsRectVisible( number x, number y)
IsPosHoveringAnyWindow( number x, number y)
GetTime( )
GetFrameCount( )
CalcItemRectClosestPoint( number x, number y, bool on_edge, number outward)
CalcTextSize( string text)
CalcListClipping( number items_count, number items_height, number out_items_display_start, number out_items_display_end)
BeginChildFrame( number guiID, number sizex, number sizey, WindowFlags flags)
EndChildFrame( )
ColorConvertU32ToFloat4( number U32val)
ColorConvertFloat4ToU32( number val1,number val2,number val3,number val4 )
ColorConvertRGBtoHSV( number r, number g, number b)
ColorConvertHSVtoRGB( number h, number s, number v)
GetScreenSize()
IsKeyDown( number virtualkey)
IsKeyPressed( number virtualkey, bool repeat)
IsKeyReleased( number virtualkey)
IsMouseDown( number button)
IsMouseClicked( number button, bool repeat)
IsMouseDoubleClicked( number button)
IsMouseReleased( number button)
IsMouseHoveringWindow( number button)
IsMouseHoveringAnyWindow( number button)
IsMouseHoveringAnyWindow( number pos_minX, number pos_minY, number pos_maxX, number pos_maxY, bool clip)
IsMouseDragging( number button, number lock_threshold)
GetMousePos( )
GetMousePosOnOpeningCurrentPopup( )
GetMouseDragDelta( number button, number lock_threshold)
ResetMouseDragDelta( number button)
These are registered values in the GUI metatable. Usage: d(GUI.WindowFlags_NoMove) will print “2” into the console.
This minionlib library is holding the core functionality on which all our bots are running. You can freely use the available functions for your Addon, in order to do that, you just need to open your module.def and set the dependency of your Addon to the minionlib:
[Module] Name=YourAddon Dependencies=minionlib Version=1 Files=myluacode.lua Enabled=1
The Minion Menu is the main menu used by minion to access all settings and addons. 3rd-party developers may add custom options to the menu in several different ways.
The minion is layered into 3 distinct parts, components, members, and submembers.
All components must have a header and (optionally) members, which are displayed when the header is clicked (and the menu is open).
All component headers require the following properties: bool expanded
, string name
, string id
All component headers optionally contain the following properties: string texture
Members are displayed below their component containers, and they represent the rows that appear directly below the header.
Members may optionally contain submembers.
All members require the following properties: string name
, string id
All members optionally contain the following properties: string texture
, string tooltip
, function onClick
, bool sort
Submembers are displayed to the right and grow vertically downward. They are useful if you wish to section off a large amount of events.
Submembers will be sorted in alphabetical order by name if the sort
tag is specified on the parent member.
All submembers require the following properties: string name
, string id
All submembers optionally contain the following properties: string texture
, string tooltip
, function onClick
ml_gui.ui_mgr:AddComponent( table component)
ml_gui.ui_mgr:AddMember( table member, string componentid)
ml_gui.ui_mgr:AddComponent( table submember, string componentid, string memberid)
local ffxiv_mainmenu = { header = { id = "FFXIVMINION##MENU_HEADER", expanded = false, name = "FFXIVMinion", texture = GetStartupPath().."\\GUI\\UI_Textures\\ffxiv_shiny.png"}, members = { } } ml_gui.ui_mgr:AddComponent(ffxiv_mainmenu) ml_gui.ui_mgr:AddMember({ id = "FFXIVMINION##MENU_DEV1", name = "Dev1", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER") ml_gui.ui_mgr:AddMember({ id = "FFXIVMINION##MENU_DEV2", name = "Dev2", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER") ml_gui.ui_mgr:AddMember({ id = "FFXIVMINION##MENU_DEV3", name = "Dev3", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER") ml_gui.ui_mgr:AddMember({ id = "FFXIVMINION##MENU_DEV4", name = "Dev4", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER") ml_gui.ui_mgr:AddMember({ id = "FFXIVMINION##MENU_DEV5", name = "Dev5", onClick = function() Dev.GUI.open = not Dev.GUI.open end, sort = true},"FFXIVMINION##MENU_HEADER") ml_gui.ui_mgr:AddSubMember({ id = "FFXIVMINION##DEV_1", name = "DevA", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER","FFXIVMINION##MENU_DEV5") ml_gui.ui_mgr:AddSubMember({ id = "FFXIVMINION##DEV_2", name = "DevE", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER","FFXIVMINION##MENU_DEV5") ml_gui.ui_mgr:AddSubMember({ id = "FFXIVMINION##DEV_3", name = "DevM", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER","FFXIVMINION##MENU_DEV5") ml_gui.ui_mgr:AddSubMember({ id = "FFXIVMINION##DEV_4", name = "DevC", onClick = function() Dev.GUI.open = not Dev.GUI.open end, tooltip = "Open the Dev monitor."},"FFXIVMINION##MENU_HEADER","FFXIVMINION##MENU_DEV5")
For every I/O function, you need to use double dashes! Example: FolderExists(“c:\\minionapp\\ILikeBeer\\Folder”)
GetStartupPath()
GetLuaModsPath()
FileExists(string fullpathtofile)
FileLoad(string fullpathtofile)
FileSave(string fullpathtofile, variant data)
FileWrite(string fullpathtofile, string data)
FileWrite(string fullpathtofile, string data, bool arg)
FileDelete(string fullpathtofile)
FolderExists(string fullpathtofolder)
FolderCreate(string fullpathtofolder)
FolderDelete(string fullpathtofolder)
FolderList(string fullpathtofolder, string pattern=““, bool includeFolders=false)
The following functions extend the default string from the lua library. Usage: string.contains(..)
contains(string arg, string arg2)
empty(string arg)
ends(string arg, string arg2)
split(string arg, string seperator)
starts(string arg, string arg2)
toboolean(string arg)
totable(string arg, string seperator)
trim(string arg, int num)
valid(string arg)
starts(string str, string starts)
ends(string str, string ends)
hash(string arg)
The following functions extend the default table from the lua library. Usage: table.valid(..)
clear(table arg )
contains(table table, value)
deepcopy(table arg, bool skipMetaTable )
deepcompare(table table1, table table2, bool ignore_metatable)
delete(table table, variant object)
find(table table, value)
invert(table arg )
merge(table table1, table table2, bool keepexistingentries)
pairsbykeys(table table1, function sort)
pairsbyvalue(table table1, function sort)
print(table arg )
randomvalue(table arg )
shallowcopy(table arg )
size(table arg )
valid(table arg )
The following functions extend the default math from the lua library. Usage: math.distance3d(..)
angle(table heading1, table heading2)
approxequal(number num1, number num2)
crossproduct(table pos1, table pos2)
distance2d(number x, number y, number x1, number y1)
distance3d(table pos1, table pos2)
distance3d(number x, number y, number z, number x1, number y1, number z1)
distancepointline(table p1, table p2, table p3)
magnitude(table pos)
round(number num, integer decimals)
randomize(integer int)
d(…)
Exit()
ml_debug( string str )
ml_error( string str )
ml_log( string str )
Now()
RegisterEventHandler(string eventtoregisterfor,function handler)
Reload()
TimeSince(integer previousTime)
Unload()
QueueEvent( string eventname, string args, …)
PathDistance(table posTable)