Getting Started with ZUI

This guide will walk you through installing ZUI and creating your first UI elements for V Rising.

📋 Prerequisites

Before you begin, make sure you have:

• ✅ V Rising installed
• ✅ BepInEx 6.0.0-be.733 (IL2CPP version) installed
• ✅ .NET 6.0 SDK (for building your mod)
• ✅ Basic knowledge of C# programming

🛠️ Installation

Step 1: Download ZUI

Download the latest ZUI release and extract it.

Step 2: Install Files

Copy the following to your V Rising BepInEx plugins folder:

<VRising Install>/BepInEx/plugins/ZUI.dll
<VRising Install>/BepInEx/plugins/Sprites/

Important: The Sprites folder contains the default UI theme assets and is required for ZUI to function properly.

Step 3: Verify Installation

Launch V Rising. In the BepInEx console, you should see:

[Info   :   ZUI] ZUI Framework loaded successfully

If you see this message, ZUI is installed correctly!

🎯 Your First UI: Main Menu Buttons

Let's create a simple mod that adds buttons to ZUI's main menu.

Step 1: Create Your Mod Project

Create a new C# project with BepInEx references. Your project structure should look like:

YourMod/
├── Plugin.cs
├── MyPluginInfo.cs
└── YourMod.csproj

Step 2: Set Up Your Plugin

MyPluginInfo.cs:

namespace YourMod
{
    public static class MyPluginInfo
    {
        public const string PLUGIN_GUID = "com.yourname.yourmod";
        public const string PLUGIN_NAME = "Your Mod";
        public const string PLUGIN_VERSION = "1.0.0";
    }
}

Step 3: Add ZUI Integration

Plugin.cs:

using BepInEx;
using BepInEx.Logging;
using BepInEx.Unity.IL2CPP;
using System;
using System.Linq;
using System.Reflection;

namespace YourMod
{
    [BepInPlugin("com.yourname.yourmod", "Your Mod", "1.0.0")]
    [BepInDependency("Zanakinz.ZUI", BepInDependency.DependencyFlags.SoftDependency)]
    public class Plugin : BasePlugin
    {
        public static ManualLogSource LogInstance { get; private set; }
        private static Type _zui;

        public override void Load()
        {
            LogInstance = Log;
            Log.LogInfo("Loading Your Mod...");

            if (InitZUI())
            {
                CreateSimpleUI();
            }
            else
            {
                Log.LogWarning("ZUI not found. UI features disabled.");
            }
        }

        private bool InitZUI()
        {
            if (!IL2CPPChainloader.Instance.Plugins.ContainsKey("Zanakinz.ZUI")) 
                return false;
                
            var assembly = AppDomain.CurrentDomain.GetAssemblies()
                .FirstOrDefault(a => a.GetName().Name == "ZUI");
            _zui = assembly?.GetType("ZUI.API.ZUI");
            return _zui != null;
        }

        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 CreateSimpleUI()
        {
            // Set your plugin name
            Call("SetPlugin", "Your Mod");
            
            // Target the main menu
            Call("SetTargetWindow", "Main");

            // Add a category
            Call("AddCategory", "My Features");
            
            // Add some buttons
            Call("AddButton", "Heal Me", ".heal");
            Call("AddButton", "Show Stats", ".stats");
            
            LogInstance.LogInfo("UI registered with ZUI!");
        }
    }
}

Step 4: Build and Test

1. Build your project
2. Copy the compiled DLL to BepInEx/plugins/
3. Launch V Rising
4. Open ZUI's main menu
5. You should see "Your Mod" with "My Features" category containing your buttons!

🎨 Your First Custom Window

Now let's create a standalone custom window with a specific layout.

Add this method to your Plugin class:

private void CreateCustomWindow()
{
    // Set plugin context
    Call("SetPlugin", "Your Mod");
    
    // Create a custom window named "MyPanel"
    Call("SetTargetWindow", "MyPanel");
    
    // Set window size (width x height in pixels)
    Call("SetUI", 500, 300);
    
    // Set the title with color
    Call("SetTitle", "<color=#4ECDC4>My Control Panel</color>");
    
    // Add some text
    Call("AddText", "Welcome to my custom UI!", 20f, 50f);
    Call("AddText", "Version 1.0", 20f, 80f);
    
    // Add a category label
    Call("AddCategory", "<color=#FFE66D>Actions:</color>", 20f, 120f);
    
    // Add positioned buttons
    Call("AddButton", "Action 1", ".action1", 20f, 160f);
    Call("AddButton", "Action 2", ".action2", 20f, 200f);
    
    LogInstance.LogInfo("Custom window created!");
}

Then call it from your Load() method:

public override void Load()
{
    LogInstance = Log;
    Log.LogInfo("Loading Your Mod...");

    if (InitZUI())
    {
        CreateSimpleUI();      // Main menu buttons
        CreateCustomWindow();  // Custom window
    }
}

📐 Understanding Positioning

When creating custom windows, elements are positioned using X/Y coordinates:

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

Example:

Call("AddButton", "Click Me", ".cmd", 50f, 100f);
// This button is 50 pixels from the left, 100 pixels from the top

Tip: Use the ZUI Visual Designer to design your layout visually instead of calculating coordinates manually!

🎨 Using the Visual Designer

Instead of manually coding coordinates, you can use the web-based designer:

1. Visit https://zanakinz.github.io/ZUI
2. Set your desired window size
3. Drag and drop UI elements (buttons, text, images, categories)
4. Adjust positions and sizes visually
5. Click "Export Code"
6. Copy the generated Call() statements into your mod

This is much faster than trial-and-error with coordinates!

✅ Next Steps

Now that you have ZUI integrated and working, explore these topics:

• API Reference - Learn all available ZUI methods
• Custom Windows - Deep dive into window creation
• Integration Guide - Soft vs hard dependencies explained
• Examples & Tutorials - More practical examples
• Working with Images - Add custom graphics to your UI
• Color & Styling - Make your UI look great

🔧 Hard Dependency Integration (Not Recommended)

Important: ZUI is a client-side mod, while most V Rising mods are server-side. Mixing client-side and server-side dependencies can cause compatibility issues and prevent your mod from loading on servers without ZUI installed.

Why Soft Dependencies Are Better

• ✅ Your mod works with or without ZUI
• ✅ No crashes if ZUI isn't installed
• ✅ Server-side mods remain compatible
• ✅ Users can install ZUI optionally for UI features

Hard Dependency Approach (If You Must)

If you absolutely need ZUI as a hard dependency (e.g., your mod is purely client-side):

Plugin.cs:

using BepInEx;
using BepInEx.Unity.IL2CPP;
using ZUI.API;

namespace YourMod
{
    [BepInPlugin("com.yourname.yourmod", "Your Mod", "1.0.0")]
    [BepInDependency("Zanakinz.ZUI", BepInDependency.DependencyFlags.HardDependency)]
    public class Plugin : BasePlugin
    {
        public override void Load()
        {
            Log.LogInfo("Loading Your Mod...");
            
            // Direct API access (no reflection needed)
            ZUI.SetPlugin("Your Mod");
            ZUI.SetTargetWindow("Main");
            ZUI.AddCategory("Features");
            ZUI.AddButton("Test", ".test");
            
            Log.LogInfo("UI registered!");
        }
    }
}

YourMod.csproj:

<ItemGroup>
    <!-- Add ZUI.dll as a reference -->
    <Reference Include="ZUI">
        <HintPath>path/to/ZUI.dll</HintPath>
        <Private>false</Private>
    </Reference>
</ItemGroup>

Drawbacks of Hard Dependencies

• ❌ Mod won't load without ZUI - Users must install ZUI or your mod fails
• ❌ Server compatibility issues - Server-side mods with client-side dependencies cause problems
• ❌ Load order problems - Your mod must load after ZUI or it crashes
• ❌ Distribution complexity - Users need to install multiple mods

Recommendation

Always use soft dependencies as shown in the main guide above. This ensures maximum compatibility and a better user experience.

For more details on integration patterns, see the Integration Guide page.

🔍 Troubleshooting

UI doesn't appear:

• Check that ZUI.dll and Sprites folder are installed
• Verify InitZUI() returns true
• Look for errors in BepInEx console

Methods not found:

• Verify you're calling methods with the correct number of parameters
• Check the API Reference for correct signatures

Window not showing:

• Ensure SetUI(width, height) is called before adding elements
• Verify SetTargetWindow() uses a unique name

For more help, see the Troubleshooting page.

You're all set! Start building amazing UIs with ZUI!