Plugin Support

Lua Plugin Support

This document provides guidance on developing plugins using the Lua scripting interface for the application. The system provides bindings to ImGui functions and custom functionality that you can use to create interactive plugins.

Table of Contents

• Plugin Lifecycle Functions
• UI Rendering
• Input Handling
• Utility Functions
• Example Plugin

Plugin Lifecycle Functions

Initialize()

Called once when the plugin is first loaded. Use this for setup and initialization.

function Initialize()
    print("Plugin initialized")
    -- Initialization code here
end

PreRenderer()

Called before each frame is rendered, prior to UIRenderer(). Use this for logic that needs to run every frame but before UI rendering.

function PreRenderer()
    -- Update game state or other pre-render logic
end

UIRenderer()

Called each frame to render your plugin's UI. Use ImGui functions here to create your interface.

function UIRenderer()
    -- UI rendering code here
end

UI Rendering

The plugin system provides bindings to most ImGui functions with a UI prefix. Here are the available functions:

Basic UI Elements

Function	Description	Example
UIBegin()	Start a new window	UIBegin("My Window")
UIEnd()	End the current window	UIEnd()
UIText()	Display text	UIText("Hello World")
UIButton()	Create a button	if UIButton("Click Me") then ... end
UICheckbox()	Create a checkbox	UICheckbox("Enable", &enabled)
UIRadioButton()	Create a radio button	UIRadioButton("Option", &selected, 1)

Layout

Function	Description	Example
UISameLine()	Place next item on same line	UISameLine()
UINewLine()	Move to next line	UINewLine()
UISeparator()	Horizontal separator line	UISeparator()
UISpacing()	Add vertical spacing	UISpacing()
UIDummy()	Invisible item for layout	UIDummy(ImVec2(100, 50))

Input Controls

Function	Description	Example
UIInputText()	Text input field	UIInputText("Name", buffer, 256)
UISliderFloat()	Float slider	UISliderFloat("Size", &size, 0, 100)
UISliderInt()	Integer slider	UISliderInt("Count", &count, 0, 10)
UIDragFloat()	Draggable float control	UIDragFloat("Value", &value, 0.1)
UICombo()	Dropdown combo box	UICombo("Options", &selected, items, #items)

Advanced UI

Function	Description	Example
UIColorEdit3()	Color picker (RGB)	UIColorEdit3("Color", color)
UIColorEdit4()	Color picker (RGBA)	UIColorEdit4("Color", color)
UIListBox()	List box	UIListBox("Items", &selected, items, 5)
UIImage()	Display an image	UIImage(texture, ImVec2(100,100))

Input Handling

OnChat(message)

Called when a chat message is received. You can process and optionally modify the message.

function OnChat(message)
    print("Received message: "..message)
    -- Return modified message or original
    return message
end

Utility Functions

LoadImage(path)

Load an image file and return a texture ID that can be used with UIImage().

local texture = LoadImage("path/to/image.png")
UIImage(texture, ImVec2(100,100))

Example Plugin

Here's a complete example plugin demonstrating several features:

local showDemoWindow = false
local sliderValue = 50
local checkboxValue = true
local textBuffer = "Edit me"
local colorValue = {1.0, 0.5, 0.0, 1.0}

function Initialize()
    print("Example Plugin Initialized")
end

function PreRenderer()
    -- Update logic could go here
end

function UIRenderer()
    UIBegin("Example Plugin")
    
    UIText("This is a sample plugin UI")
    UISeparator()
    
    if UIButton("Toggle Demo Window") then
        showDemoWindow = not showDemoWindow
    end
    
    UICheckbox("Enable Feature", checkboxValue)
    
    UISliderInt("Slider", sliderValue, 0, 100)
    
    UIInputText("Text Input", textBuffer, 256)
    
    UIColorEdit4("Color Picker", colorValue)
    
    if UIButton("Print Values") then
        print("Slider:", sliderValue)
        print("Checkbox:", checkboxValue)
        print("Text:", textBuffer)
        print("Color:", table.unpack(colorValue))
    end
    
    UIEnd()
    
    if showDemoWindow then
        -- Show ImGui demo window
        UIBegin("ImGui Demo")
        UIShowDemoWindow()
        UIEnd()
    end
end

function OnChat(message)
    if message:lower() == "!test" then
        return "Plugin is working!"
    end
    return message
end

Best Practices

1. Error Handling: Always validate inputs and use pcall for operations that might fail
2. Performance: Keep UI rendering efficient - don't do heavy computations in UIRenderer()
3. Memory: Avoid creating new objects every frame
4. User Experience: Make your UI intuitive and responsive
5. Testing: Test your plugin with different screen sizes and configurations

Troubleshooting

• If your UI isn't appearing, check that:
  • You're calling UIBegin() and UIEnd() properly
  • There are no Lua errors (check the console)
• For input issues:
  • Ensure you're passing variables by reference when needed (e.g., &variable)
  • Check that buffers are large enough for text input