Troubleshooting

Updated a day ago

Troubleshooting

Common issues, error messages, and solutions for ZUI integration and usage.

📋 Table of Contents

Installation Issues

ZUI doesn't load / No log messages

Symptoms:

  • No ZUI messages in BepInEx console
  • ZUI features don't work
  • No errors shown

Possible Causes:

  1. ZUI.dll not in correct location
  2. Sprites folder missing
  3. Wrong BepInEx version
  4. Corrupted download

Solutions:

✅ Verify file locations:

BepInEx/
├── plugins/
│   ├── ZUI.dll          ✓ Must be here
│   └── Sprites/         ✓ Folder must exist
│       └── (sprite files)

✅ Check BepInEx version:

  • Required: BepInEx 6.0.0-be.733 (IL2CPP)
  • Check your BepInEx version in console on startup

✅ Verify download integrity:

  • Re-download ZUI from official source
  • Extract all files (don't just copy the DLL)

✅ Check console for errors:

  • Look for any red error messages
  • Check for "Could not load" messages

"Could not load ZUI.dll" error

Error Message:

[Error  : Unity Log] Could not load 'ZUI' because...

Possible Causes:

  • Missing dependencies
  • Incompatible .NET version
  • Corrupted DLL file

Solutions:

✅ Reinstall BepInEx:

  • Download fresh BepInEx 6.0.0-be.733 IL2CPP
  • Clean installation

✅ Check .NET version:

  • ZUI requires .NET 6.0
  • Rebuild your mod with correct target framework

✅ Re-download ZUI:

  • Download fresh copy
  • Verify file isn't corrupted

Sprites folder missing warning

Warning Message:

[Warning: ZUI] Sprites folder not found

Solution:

The Sprites folder must be in the correct location:

BepInEx/plugins/Sprites/

✅ Copy the entire Sprites folder from the ZUI download ✅ Don't rename it - must be exactly "Sprites" ✅ Include all sprite files inside the folder

Integration Issues

"ZUI not available" but ZUI is installed

Symptoms:

  • Your mod logs "ZUI not available"
  • ZUI is installed and working for other mods
  • No UI appears for your mod

Possible Causes:

  1. Load order - your mod loads before ZUI
  2. Wrong assembly name in reflection code
  3. Incorrect plugin GUID

Solutions:

✅ Check load order:

// Add diagnostic logging
Log.LogInfo("Checking for ZUI...");
Log.LogInfo($"Loaded plugins: {string.Join(", ", IL2CPPChainloader.Instance.Plugins.Keys)}");

If ZUI isn't in the list, it's loading after your mod.

✅ Verify plugin GUID:

// Correct GUID
if (!IL2CPPChainloader.Instance.Plugins.ContainsKey("Zanakinz.ZUI"))

✅ Check assembly name:

// Correct assembly name is "ZUI"
var assembly = AppDomain.CurrentDomain.GetAssemblies()
    .FirstOrDefault(a => a.GetName().Name == "ZUI");

✅ Add more detailed logging:

private bool InitZUI()
{
    Log.LogInfo("Attempting to initialize ZUI...");
    
    if (!IL2CPPChainloader.Instance.Plugins.ContainsKey("Zanakinz.ZUI"))
    {
        Log.LogWarning("ZUI plugin not found in chainloader");
        return false;
    }
    
    var assembly = AppDomain.CurrentDomain.GetAssemblies()
        .FirstOrDefault(a => a.GetName().Name == "ZUI");
    
    if (assembly == null)
    {
        Log.LogWarning("ZUI assembly not found");
        return false;
    }
    
    Log.LogInfo($"Found ZUI assembly: {assembly.FullName}");
    
    _zui = assembly.GetType("ZUI.API.ZUI");
    
    if (_zui == null)
    {
        Log.LogWarning("ZUI.API.ZUI type not found");
        return false;
    }
    
    Log.LogInfo("ZUI initialized successfully!");
    return true;
}

Method not found errors

Error Message:

[Error  : YourMod] Could not find ZUI method 'SetPlugin' with 1 parameters

Possible Causes:

  1. Wrong parameter count
  2. Wrong method name (typo)
  3. ZUI version mismatch

Solutions:

✅ Check parameter count:

// Wrong - 0 parameters
Call("SetPlugin");

// Correct - 1 parameter
Call("SetPlugin", "MyMod");

✅ Check method name spelling:

// Wrong
Call("SetPlugIn", "MyMod");

// Correct
Call("SetPlugin", "MyMod");

✅ Add better error handling:

private void Call(string methodName, params object[] args)
{
    if (_zui == null)
    {
        Log.LogWarning("ZUI not initialized");
        return;
    }

    var method = _zui.GetMethods(BindingFlags.Public | BindingFlags.Static)
        .FirstOrDefault(m => m.Name == methodName && 
                             m.GetParameters().Length == args.Length);

    if (method == null)
    {
        // List available methods for debugging
        var available = _zui.GetMethods(BindingFlags.Public | BindingFlags.Static)
            .Where(m => m.Name == methodName)
            .Select(m => $"{m.Name}({m.GetParameters().Length} params)");
        
        Log.LogError($"Method '{methodName}' with {args.Length} params not found. Available: {string.Join(", ", available)}");
        return;
    }

    method.Invoke(null, args);
}

Hard dependency crash

Error Message:

[Error  : BepInEx] Could not load [YourMod] because dependency [Zanakinz.ZUI] was not found

This is expected behavior with hard dependencies.

Solutions:

✅ Switch to soft dependency:

// Change this
[BepInDependency("Zanakinz.ZUI", BepInDependency.DependencyFlags.HardDependency)]

// To this
[BepInDependency("Zanakinz.ZUI", BepInDependency.DependencyFlags.SoftDependency)]

✅ See Integration Guide for complete soft dependency implementation

UI Display Issues

UI doesn't appear

Symptoms:

  • No errors in console
  • Mod loads successfully
  • UI elements don't show

Solutions:

✅ Verify plugin name is set:

// Must call this first
Call("SetPlugin", "MyMod");

✅ Check target window:

// For main menu
Call("SetTargetWindow", "Main");

// For custom window
Call("SetTargetWindow", "MyPanel");
Call("SetUI", 600, 400);  // Required for custom windows

✅ Verify methods are being called:

private void RegisterUI()
{
    Log.LogInfo("RegisterUI called");
    
    Call("SetPlugin", "MyMod");
    Log.LogInfo("SetPlugin called");
    
    Call("SetTargetWindow", "Main");
    Log.LogInfo("SetTargetWindow called");
    
    Call("AddCategory", "Test");
    Log.LogInfo("AddCategory called");
}

✅ Check if ZUI main window is open:

  • Press the ZUI hotkey (default: check ZUI config)
  • Look for your mod's section

UI appears but is empty

Symptoms:

  • Your plugin name shows in ZUI
  • No buttons or categories appear

Possible Causes:

  1. SetPlugin called but no content added
  2. Content added to wrong window
  3. Elements added before SetPlugin

Solutions:

✅ Ensure correct order:

// Correct order
Call("SetPlugin", "MyMod");          // 1. Set plugin first
Call("SetTargetWindow", "Main");     // 2. Set target
Call("AddCategory", "Features");     // 3. Add category
Call("AddButton", "Test", ".test");  // 4. Add buttons

✅ Verify window target:

// Make sure you're targeting the right window
Call("SetTargetWindow", "Main");  // Not "MyPanel" or other name

Custom Window Issues

Custom window doesn't appear

Symptoms:

  • Main menu integration works
  • Custom window doesn't show

Solutions:

✅ Verify SetUI is called:

// Required for custom windows
Call("SetTargetWindow", "MyCustomWindow");
Call("SetUI", 600, 400);  // Must call this!

✅ Check window dimensions:

// Too small - might not be visible
Call("SetUI", 10, 10);  // ❌ Don't do this

// Reasonable size
Call("SetUI", 500, 300);  // ✓ Good

✅ Look for the window:

  • Custom windows may spawn off-screen initially
  • Try dragging from screen edges
  • Check ZUI config for window positions

Elements not positioned correctly

Symptoms:

  • Elements appear in wrong positions
  • Elements overlap
  • Elements cut off

Solutions:

✅ Check coordinate values:

// Make sure values are within window bounds
Call("SetUI", 500, 300);

// These should work
Call("AddText", "Test", 20f, 50f);    // ✓ Inside window
Call("AddText", "Test", 600f, 50f);   // ❌ Outside (500px wide)

✅ Use the Visual Designer:

✅ Add logging:

float x = 20f, y = 50f;
Log.LogInfo($"Adding button at ({x}, {y})");
Call("AddButton", "Test", ".test", x, y);

Window too small/large

Solutions:

✅ Adjust SetUI dimensions:

// Too small
Call("SetUI", 200, 100);  // Hard to use

// Good sizes
Call("SetUI", 400, 300);  // Small panel
Call("SetUI", 600, 400);  // Medium panel
Call("SetUI", 800, 600);  // Large panel

// Too large
Call("SetUI", 3000, 2000);  // Might not fit screen

✅ Consider common resolutions:

  • 1920x1080 (most common)
  • Leave room for taskbar, other windows

Image Issues

Images don't appear

Symptoms:

  • Image element added but nothing shows
  • No error messages

Solutions:

✅ Check file location:

BepInEx/plugins/Sprites/
├── your_image.png  ✓ Put images here

✅ Verify filename exactly:

// Filename is case-sensitive!
Call("AddImage", "Logo.png", 20f, 20f, 100f, 100f);  // File must be "Logo.png"
Call("AddImage", "logo.png", 20f, 20f, 100f, 100f);  // Different from "Logo.png"

✅ Check file format:

  • Supported: PNG, JPG
  • Not supported: GIF, BMP, WebP

✅ Verify dimensions:

// Make sure image is within window bounds
Call("SetUI", 500, 300);
Call("AddImage", "test.png", 20f, 20f, 460f, 260f);  // Fits inside

Images appear stretched/distorted

Cause: Images are stretched to fit the specified dimensions.

Solutions:

✅ Match aspect ratio:

// If image is 400x200 (2:1 ratio)
Call("AddImage", "banner.png", 20f, 20f, 400f, 200f);  // ✓ Correct ratio
Call("AddImage", "banner.png", 20f, 20f, 200f, 200f);  // ❌ Wrong ratio (distorted)

✅ Calculate dimensions:

// Original image: 800x600 (4:3 ratio)
float width = 400f;
float height = 300f;  // Maintain 4:3 ratio
Call("AddImage", "photo.png", 20f, 20f, width, height);

Button Issues

Buttons don't execute commands

Symptoms:

  • Button appears and is clickable
  • Command doesn't execute
  • No error in console

Solutions:

✅ Check command format:

// Correct - starts with period
Call("AddButton", "Heal", ".heal");

// Wrong - no period
Call("AddButton", "Heal", "heal");  // Won't work

✅ Verify command exists:

  • The command handler must be registered in your mod
  • Test command manually in chat first
  • Check for typos

✅ Check command registration:

// Make sure your mod registers the command
// Example from your mod's command handler:
if (message == ".heal")
{
    // Handle heal command
}

Buttons appear but are not clickable

Possible Causes:

  1. Button overlapped by another element
  2. Window layer issues
  3. Button outside window bounds

Solutions:

✅ Check positioning:

Call("SetUI", 500, 300);

// Button should be inside window
Call("AddButton", "Test", ".test", 20f, 100f);    // ✓ Inside
Call("AddButton", "Test", ".test", 600f, 100f);   // ❌ Outside (500px wide)

✅ Check for overlaps:

// Make sure elements don't overlap
Call("AddButton", "Button1", ".cmd", 20f, 100f, 200f, 40f);
Call("AddButton", "Button2", ".cmd", 20f, 150f, 200f, 40f);  // ✓ Good spacing

// These overlap
Call("AddButton", "Button1", ".cmd", 20f, 100f, 200f, 40f);
Call("AddButton", "Button2", ".cmd", 20f, 110f, 200f, 40f);  // ❌ Overlaps

Performance Issues

UI causes lag/stuttering

Symptoms:

  • Game lags when opening ZUI
  • FPS drops with UI visible
  • Slow window dragging

Solutions:

✅ Reduce number of elements:

// Too many elements
for (int i = 0; i < 1000; i++)
{
    Call("AddButton", $"Button {i}", ".cmd");  // ❌ Don't do this
}

// Reasonable number
Call("AddButton", "Button 1", ".cmd1");
Call("AddButton", "Button 2", ".cmd2");
// ... 10-20 buttons is fine

✅ Optimize images:

  • Use smaller image files (< 1MB)
  • Compress images before use
  • Don't use huge resolutions

✅ Limit window updates:

// Don't recreate UI every frame
public override void Update()
{
    // ❌ Don't do this
    RegisterUI();
}

// ✓ Register once on load
public override void Load()
{
    if (InitZUI())
    {
        RegisterUI();  // Only once
    }
}

Error Messages

Common error messages and solutions

"Assembly not found"

ZUI assembly not found
  • ZUI isn't installed or didn't load
  • Check ZUI.dll is in plugins folder
  • Verify BepInEx console for ZUI load messages

"Type not found"

ZUI.API.ZUI type not found
  • ZUI version mismatch
  • Corrupted ZUI.dll
  • Re-download and reinstall ZUI

"Could not load file or assembly"

Could not load file or assembly 'ZUI' or one of its dependencies
  • Missing .NET dependencies
  • Wrong BepInEx version
  • Reinstall BepInEx IL2CPP version

"Method not found"

Could not find ZUI method 'MethodName' with X parameters
  • Wrong parameter count
  • Typo in method name
  • ZUI version doesn't have that method
  • See API Reference for correct signatures

"NullReferenceException"

NullReferenceException: Object reference not set to an instance of an object
  • Calling ZUI methods without initializing
  • Check _zui != null before calling
  • Ensure InitZUI() returned true

Getting More Help

If you've tried these solutions and still have issues:

  1. Check the logs:

    • Open BepInEx/LogOutput.log
    • Look for error messages
    • Note the exact error text

  2. Enable debug logging:

    Log.LogDebug("Detailed debug info here");

  3. Test in isolation:

    • Disable other mods
    • Test with only ZUI and your mod
    • Identify conflicts

  4. Verify versions:

    • V Rising version
    • BepInEx version
    • ZUI version
    • Your mod version

  5. Report issues:

    • Include BepInEx log
    • Describe exact steps to reproduce
    • List all installed mods
    • Specify versions

Related Pages

Pages

About

Contact Us Privacy Policy Thunderstore Wiki

Developers

API Docs GitHub Repo Package Format Docs Markdown Preview Manifest Validator

Thunderstore 2024