A comprehensive example mod demonstrating how to use the ZUI API for VRising mods, including both legacy button integration and custom UI window creation.
Purpose: This mod showcases two different approaches to using ZUI - adding buttons to the main menu and creating fully custom UI windows.
This example mod demonstrates:
dotnet build
Copy the compiled ZUIExampleMod.dll to your VRising BepInEx plugins folder:
<VRising Install>/BepInEx/plugins/
If you want to test the image functionality:
When you load the game with ZUI installed, this mod creates two different UI demonstrations:
Adds a "Simple Stuff" category to ZUI's main menu with two buttons:
.say Hello command.kill commandCreates a completely custom 500x350 pixel window named "YourWindowName" featuring:
The plugin uses reflection to safely call ZUI methods, making it work as a soft dependency:
private void Call(string name, params object[] args)
{
if (_zui == null) return;
var method = _zui.GetMethods(BindingFlags.Public | BindingFlags.Static)
.FirstOrDefault(m => m.Name == name && m.GetParameters().Length == args.Length);
if (method != null) method.Invoke(null, args);
else LogInstance.LogError($"Could not find ZUI method '{name}' with {args.Length} parameters.");
}
private void CreateCustomUI()
{
Call("SetPlugin", "YourPluginName");
Call("SetTargetWindow", "YourWindowName");
Call("SetUI", 500, 350); // Width x Height
Call("SetTitle", "<color=#B30000>ZUIExampleMod</color>");
Call("AddText", "<color=#61c200>Custom text here</color>", 15f, 210f);
Call("AddButton", "Test", ".ignorethis", 320f, 220f);
Call("AddCategory", "<color=#ffd700>README:</color>", 15f, 190f);
Call("AddImage", "CHANGENAME.png", 20f, 40f, 460f, 150f);
}
ZUIExampleMod/
├── Plugin.cs # Main plugin - creates UI elements
├── MyPluginInfo.cs # Plugin metadata
└── ZUIExampleMod.csproj # Project configuration
Perfect for basic functionality that just needs a few buttons:
Call("SetPlugin", "MyMod");
Call("SetTargetWindow", "Main");
Call("AddCategory", "My Features");
Call("AddButton", "Do Something", ".mycommand");
For complex UIs with custom layouts:
Call("SetPlugin", "MyMod");
Call("SetTargetWindow", "MyCustomWindow");
Call("SetUI", 600, 400); // Set window size
// Position elements exactly where you want
Call("AddText", "Welcome!", 10f, 10f);
Call("AddButton", "Click Me", ".command", 10f, 50f, 200f, 30f);
Call("AddImage", "logo.png", 10f, 100f, 580f, 200f);
| Method | Description | Usage |
|---|---|---|
SetPlugin(string) |
Sets the plugin identifier | Call("SetPlugin", "MyMod"); |
SetTargetWindow(string) |
Targets "Main" menu or a custom window name | Call("SetTargetWindow", "Main"); |
SetUI(int, int) |
Creates custom window with width × height dimensions | Call("SetUI", 500, 350); |
SetTitle(string) |
Sets window title (supports HTML color tags) | Call("SetTitle", "<color=#FF0000>My Window</color>"); |
AddCategory(string) |
Adds category label in main menu | Call("AddCategory", "Admin"); |
AddCategory(string, float, float) |
Adds category label at specific X, Y position | Call("AddCategory", "README:", 15f, 190f); |
AddButton(string, string) |
Adds button to main menu with text and command | Call("AddButton", "Heal", ".heal"); |
AddButton(string, string, float, float) |
Adds button at X, Y position | Call("AddButton", "Test", ".cmd", 320f, 220f); |
AddButton(string, string, float, float, float, float) |
Adds button with position (X, Y) and size (W, H) | Call("AddButton", "Long", ".cmd", 20f, 280f, 460f, 20f); |
AddText(string, float, float) |
Adds text at specific X, Y coordinates | Call("AddText", "Hello!", 15f, 210f); |
AddImage(string, float, float, float, float) |
Adds image with filename, X, Y, width, height | Call("AddImage", "logo.png", 20f, 40f, 460f, 150f); |
Want to design your custom UI visually?
Use the official ZUI Canvas Designer at https://zanakinz.github.io/ZUI
This interactive tool allows you to:
Instead of manually calculating X/Y coordinates, use the designer to drag and drop elements, then copy the generated code into your mod!
Coordinates are in pixels from top-left (0, 0):
ZUI supports Unity Rich Text color tags:
"<color=#FF0000>Red Text</color>"
"<color=#00FF00>Green Text</color>"
"<color=#B30000>Dark Red</color>"
"<color=#ffd700>Gold</color>"
Mod loads but no UI appears:
"ZUI not found" or mod works without errors but no UI:
Custom window doesn't appear:
SetUI(width, height) is called before adding elementsSetTargetWindow() uses a unique nameImages not showing:
Build errors:
This example demonstrates:
MyPluginInfo.csCreateSimpleUI()CreateCustomUI()This is example code for educational purposes. Modify and use as needed!
Happy modding!