API Reference

Complete reference documentation for all ZUI API methods. ZUI supports two integration methods: Client-Side (via reflection) and Server-Side (via chat packets).

All client-side methods are accessed through the ZUI class in the ZUI.API namespace. Server-side methods use the same names but are sent as JSON packets.

📋 Table of Contents

• Integration Methods
• Context Methods
• Window Methods
• Content Methods
• Server-Side Specific Methods
• Event Methods
• Method Signatures

Integration Methods

Client-Side (Reflection)

Use reflection to call ZUI methods from your client mod:

private void Call(string methodName, params object[] args)
{
    if (_zui == null) return;
    var method = _zui.GetMethods(BindingFlags.Public | BindingFlags.Static)
        .FirstOrDefault(m => m.Name == methodName && m.GetParameters().Length == args.Length);
    method?.Invoke(null, args);
}

// Usage
Call("SetPlugin", "MyMod");
Call("AddButton", "Test", ".test");

Server-Side (Chat Packets)

Send formatted chat messages from your server mod:

private void SendZUIPacket(string type, Dictionary<string, string> data)
{
    var packet = new { Type = type, Plugin = "MyServerMod", Window = "ServerUI", Data = data };
    string message = "[[ZUI]]" + JsonSerializer.Serialize(packet);
    ServerChatUtils.SendSystemMessageToUser(userEntity, message);
}

// Usage
SendZUIPacket("AddButton", new Dictionary<string, string> {
    { "Text", "Test" }, { "Cmd", ".test" }
});

Context Methods

These methods set up the context for subsequent API calls.

SetPlugin

Sets the plugin identifier for all subsequent registrations.

Signature:

void SetPlugin(string pluginName)

Parameters:

• pluginName (string) - Your plugin's display name

Example:

// Using reflection (client-side)
Call("SetPlugin", "MyMod");

// Using packets (server-side)
SendZUIPacket("SetPlugin", new Dictionary<string, string> { { "Plugin", "MyMod" } });

// Direct (hard dependency - not recommended)
ZUI.SetPlugin("MyMod");

Notes:

• Call this FIRST before any other ZUI methods
• All subsequent calls will be associated with this plugin
• Used to organize UI elements by mod

SetTargetWindow

Sets the target window for subsequent content additions.

Signature:

void SetTargetWindow(string windowName)

Parameters:

• windowName (string) - Either "Main" for the main menu, or a custom window name

Example:

// Target main menu (client-side)
Call("SetTargetWindow", "Main");

// Target custom window (client-side)
Call("SetTargetWindow", "MyControlPanel");

// Server-side packet
SendZUIPacket("SetTargetWindow", new Dictionary<string, string> { { "Window", "MyControlPanel" } });

Notes:

• Use "Main" to add buttons to the main ZUI menu
• Use any other name to create/target a custom window
• Custom windows must call SetUI() to define dimensions

Window Methods

Methods for creating and configuring custom windows.

SetUI

Creates a custom window with specified dimensions.

Signature:

void SetUI(int width, int height)

Parameters:

• width (int) - Window width in pixels
• height (int) - Window height in pixels

Example:

Call("SetUI", 600, 400);

Notes:

• Must be called after SetTargetWindow() (with a custom window name)
• Recommended dimensions: 300-2000 pixels
• Window will be draggable and resizable by users
• Position is saved automatically

SetTitle

Sets the title displayed in the window's title bar.

Signature:

void SetTitle(string title)

Parameters:

• title (string) - The title text (supports Unity Rich Text)

Example:

Call("SetTitle", "My Control Panel");
Call("SetTitle", "<color=#FF6B6B>Admin Panel</color>");

Notes:

• Supports Unity Rich Text color tags
• Only applies to custom windows (not "Main")
• See Color & Styling for formatting options

Content Methods

Methods for adding UI elements to windows.

AddCategory

Adds a category label to organize content.

Signatures:

void AddCategory(string categoryName)
void AddCategory(string categoryName, float x, float y)

Parameters:

• categoryName (string) - Category label text (supports Unity Rich Text)
• x (float) - X coordinate in pixels (positioned overload only)
• y (float) - Y coordinate in pixels (positioned overload only)

Examples:

// Main menu (no position)
Call("SetTargetWindow", "Main");
Call("AddCategory", "Admin Tools");

// Custom window (positioned)
Call("SetTargetWindow", "MyPanel");
Call("SetUI", 500, 300);
Call("AddCategory", "<color=#FFE66D>Settings:</color>", 20f, 50f);

Notes:

• In main menu: categories organize buttons into collapsible groups
• In custom windows: categories are positioned labels
• Supports Rich Text formatting

AddButton

Adds a clickable button that executes a chat command.

Signatures:

void AddButton(string text, string command)
void AddButton(string text, string command, string tooltip)
void AddButton(string text, string command, float x, float y)
void AddButton(string text, string command, float x, float y, float width, float height)

Parameters:

• text (string) - Button label text
• command (string) - Chat command to execute (e.g., ".heal")
• tooltip (string) - Hover tooltip text (optional)
• x (float) - X coordinate in pixels
• y (float) - Y coordinate in pixels
• width (float) - Button width in pixels
• height (float) - Button height in pixels

Examples:

// Main menu button
Call("SetTargetWindow", "Main");
Call("AddCategory", "Tools");
Call("AddButton", "Heal", ".heal");
Call("AddButton", "Heal", ".heal", "Restores full health");

// Custom window - positioned
Call("SetTargetWindow", "MyPanel");
Call("SetUI", 500, 300);
Call("AddButton", "Execute", ".command", 20f, 100f);

// Custom window - positioned with size
Call("AddButton", "Wide Button", ".cmd", 20f, 150f, 460f, 40f);

Notes:

• Commands should start with a period (e.g., ".heal")
• Position/size parameters only work in custom windows
• Default button size in custom windows: approximately 150x30 pixels
• Buttons in "Main" are automatically sized/positioned

AddText

Adds a text label at a specific position.

Signature:

void AddText(string text, float x, float y)

Parameters:

• text (string) - Text to display (supports Unity Rich Text)
• x (float) - X coordinate in pixels
• y (float) - Y coordinate in pixels

Example:

Call("SetTargetWindow", "MyPanel");
Call("SetUI", 500, 300);
Call("AddText", "Welcome to my mod!", 20f, 50f);
Call("AddText", "<color=#4ECDC4>Status: Ready</color>", 20f, 80f);

Notes:

• Only works in custom windows (not "Main")
• Supports multi-line text with \n
• Supports Rich Text formatting
• Text is not interactive (use buttons for clickable elements)

AddImage

Adds an image from the Sprites folder.

Signature:

void AddImage(string filename, float x, float y, float width, float height)

Parameters:

• filename (string) - Image filename (e.g., "logo.png")
• x (float) - X coordinate in pixels
• y (float) - Y coordinate in pixels
• width (float) - Image width in pixels
• height (float) - Image height in pixels

Example:

Call("SetTargetWindow", "MyPanel");
Call("SetUI", 600, 400);
Call("AddImage", "banner.png", 50f, 50f, 500f, 100f);

Notes:

• Only works in custom windows (not "Main")
• Images must be in BepInEx/plugins/Sprites/ folder
• Supported formats: PNG, JPG
• Images are stretched to fit specified dimensions
• Filename is case-sensitive

Server-Side Specific Methods

These methods are primarily used when sending packets from server mods.

RegisterImage

Registers an image from a web URL for download and caching on the client.

Packet Format:

{
  "Type": "RegisterImage",
  "Plugin": "MyServerMod",
  "Window": "ServerUI",
  "Data": {
    "Name": "logo.png",
    "Url": "https://yourdomain.com/logo.png"
  }
}

Parameters:

• Name (string) - The name to reference this image (e.g., "logo.png")
• Url (string) - HTTP/HTTPS URL to download the image from

Example:

SendZUIPacket("RegisterImage", new Dictionary<string, string> {
    { "Name", "server_logo.png" },
    { "Url", "https://example.com/logo.png" }
});

// Then use it
SendZUIPacket("AddImage", new Dictionary<string, string> {
    { "Img", "server_logo.png" },
    { "X", "20" }, { "Y", "20" },
    { "W", "100" }, { "H", "100" }
});

Notes:

• Images are downloaded asynchronously
• Cached in memory for the session
• Supports PNG and JPG formats
• Requires HTTP or HTTPS URLs

SetUICustom

Alternative to SetUI, used in server-side packets to create custom windows.

Packet Format:

{
  "Type": "SetUICustom",
  "Plugin": "MyServerMod",
  "Window": "ServerUI",
  "Data": {
    "W": "600",
    "H": "400"
  }
}

Parameters:

• W (string) - Window width in pixels
• H (string) - Window height in pixels

Example:

SendZUIPacket("SetUICustom", new Dictionary<string, string> {
    { "W", "600" },
    { "H", "400" }
});

Notes:

• Functionally equivalent to SetUI
• Used in packet format with string parameters
• Creates a draggable, resizable window

Open

Forces a window to open immediately (server-side).

Packet Format:

{
  "Type": "Open",
  "Plugin": "MyServerMod",
  "Window": "ServerUI",
  "Data": {}
}

Example:

// After creating all UI elements, force the window to open
SendZUIPacket("Open", new Dictionary<string, string>());

Notes:

• Automatically opens the target window
• Useful for server-initiated UIs
• Window will appear in front of others

Event Methods

OnButtonsChanged

Event that fires when UI buttons are updated.

Signature:

event Action OnButtonsChanged

Example:

// Subscribe to the event
ZUI.OnButtonsChanged += () => {
    Console.WriteLine("UI has been updated!");
};

Notes:

• Fires when any plugin adds/removes buttons
• Useful for refreshing UI state
• Not commonly needed for basic integrations

Method Signatures

Quick reference table for all methods:

📐 Coordinate System

All positioning uses a pixel-based coordinate system:

• Origin (0, 0) is at the top-left corner
• X-axis increases moving right
• Y-axis increases moving down

(0,0) ────────────► X
  │
  │
  │
  ▼
  Y

Example positions:

• (0, 0) - Top-left corner
• (width, 0) - Top-right corner
• (0, height) - Bottom-left corner
• (width, height) - Bottom-right corner

💡 Usage Patterns

Client-Side Main Menu Registration

Call("SetPlugin", "MyMod");
Call("SetTargetWindow", "Main");
Call("AddCategory", "Features");
Call("AddButton", "Action", ".command");

Client-Side Custom Window

Call("SetPlugin", "MyMod");
Call("SetTargetWindow", "CustomPanel");
Call("SetUI", 600, 400);
Call("SetTitle", "My Panel");
Call("AddText", "Content", 20f, 50f);
Call("AddButton", "Click", ".cmd", 20f, 100f);

Server-Side Custom Window with Web Image

// Register image from URL
SendZUIPacket("RegisterImage", new Dictionary<string, string> {
    { "Name", "logo.png" },
    { "Url", "https://example.com/logo.png" }
});

// Create window
SendZUIPacket("SetUICustom", new Dictionary<string, string> { { "W", "500" }, { "H", "300" } });
SendZUIPacket("SetTitle", new Dictionary<string, string> { { "Text", "Server Panel" } });

// Add content
SendZUIPacket("AddImage", new Dictionary<string, string> {
    { "Img", "logo.png" },
    { "X", "200" }, { "Y", "20" },
    { "W", "100" }, { "H", "100" }
});

SendZUIPacket("AddButton", new Dictionary<string, string> {
    { "Text", "Server Action" },
    { "Cmd", ".servercommand" },
    { "X", "20" }, { "Y", "150" },
    { "W", "460" }, { "H", "40" }
});

// Force open
SendZUIPacket("Open", new Dictionary<string, string>());

Multiple Windows

Call("SetPlugin", "MyMod");

// First window
Call("SetTargetWindow", "Panel1");
Call("SetUI", 500, 300);
Call("SetTitle", "Panel 1");
// ... add content ...

// Second window
Call("SetTargetWindow", "Panel2");
Call("SetUI", 600, 400);
Call("SetTitle", "Panel 2");
// ... add content ...

🎨 Visual Designer

Don't want to calculate coordinates manually? Use the ZUI Visual Designer to design your layout visually and export the code!

Related Pages

• Getting Started - Setup and first UI
• Custom Windows - Deep dive into windows
• Examples & Tutorials - Practical examples
• Color & Styling - Text formatting guide
• Working with Images - Image integration