Working with Images

Updated 6 days ago

Working with Images

Learn how to add custom images, logos, and backgrounds to your ZUI interfaces for professional branding and visual appeal.

📋 Table of Contents

Overview

ZUI supports adding custom images to your UI:

  • ✅ PNG and JPG formats
  • ✅ Logos and branding
  • ✅ Background images
  • ✅ Icons and decorations
  • ✅ Custom button graphics

Note: Images must be embedded as resources in your mod's DLL - they cannot be loaded from external files.

Image Requirements

Supported Formats

✅ Supported:

  • PNG (recommended for logos with transparency)
  • JPG/JPEG (good for photos, backgrounds)

❌ Not supported:

  • GIF (no animation support)
  • BMP (not recommended)
  • WebP (not supported by Unity)

Size Recommendations

File size:

  • Small images (logos): < 100KB
  • Medium images (panels): < 300KB
  • Large images (backgrounds): < 500KB
  • Absolute maximum: 1MB per image

Dimensions:

  • Use power-of-2 dimensions when possible (128, 256, 512, 1024)
  • Minimum: 32x32 pixels
  • Maximum: 2048x2048 pixels
  • Recommended: 512x512 or smaller

Why power-of-2? Unity handles these more efficiently, resulting in better performance and memory usage.

Image Optimization

Before embedding images:

  1. Resize appropriately - Don't use 4K images for small logos
  2. Compress - Use PNG optimization tools
  3. Remove metadata - Strip EXIF data
  4. Test - Ensure quality after compression

Optimization tools:

  • TinyPNG (https://tinypng.com) - Online PNG compression
  • ImageOptim (Mac) - Local image optimization
  • PNGGauntlet (Windows) - Batch PNG optimization

Embedding Images

Images must be embedded as resources in your mod's DLL.

Step 1: Add Image to Project

  1. Create a folder in your project: Resources/ or Images/
  2. Copy your image file into this folder
  3. Make sure the image is included in your project

Step 2: Set Build Action

In Visual Studio or your IDE:

  1. Right-click the image file
  2. Select Properties
  3. Set Build Action to Embedded Resource
  4. Set Copy to Output Directory to Do not copy

File structure example:

MyMod/
├── Plugin.cs
├── Resources/
│   ├── logo.png
│   ├── background.jpg
│   └── icon.png
└── MyMod.csproj

Step 3: Verify Embedding

Check your .csproj file contains:

<ItemGroup>
  <EmbeddedResource Include="Resources\logo.png" />
  <EmbeddedResource Include="Resources\background.jpg" />
</ItemGroup>

Adding Images to UI

Basic Syntax

Call("AddImage", "imageName.ext", x, y, width, height);

Parameters:

  • imageName.ext - Filename of embedded image (case-sensitive!)
  • x - Horizontal position (pixels from left)
  • y - Vertical position (pixels from top)
  • width - Display width in pixels
  • height - Display height in pixels

Simple Example

Call("SetPlugin", "MyMod");
Call("SetTargetWindow", "BrandedPanel");
Call("SetUI", 600, 400);
Call("SetTitle", "My Mod");

// Add logo at top center
Call("AddImage", "logo.png", 200f, 20f, 200f, 100f);

// Add content below logo
Call("AddText", "Welcome!", 20f, 150f);
Call("AddButton", "Start", ".start", 20f, 200f);

Image as Background

Call("SetPlugin", "MyMod");
Call("SetTargetWindow", "StyledPanel");
Call("SetUI", 800, 600);

// Background covers entire window (position 0,0)
Call("AddImage", "background.jpg", 0f, 0f, 800f, 600f);

// Content rendered on top
Call("AddText", "<color=#FFFFFF><size=18>Title</size></color>", 50f, 100f);
Call("AddButton", "Action", ".cmd", 50f, 200f);

Common Use Cases

Logo at Top

private void RegisterBrandedWindow()
{
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "MainPanel");
    Call("SetUI", 600, 500);
    Call("SetTitle", "My Awesome Mod");
    
    // Logo centered at top
    // X = (600 - 200) / 2 = 200
    Call("AddImage", "logo.png", 200f, 20f, 200f, 100f);
    
    // Content starts below logo
    Call("AddText", "<size=14>Control Panel</size>", 20f, 150f);
    Call("AddCategory", "Features", 20f, 200f);
    Call("AddButton", "Feature 1", ".feat1", 20f, 240f);
    Call("AddButton", "Feature 2", ".feat2", 20f, 290f);
}

Icon Next to Text

private void RegisterWithIcon()
{
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "IconPanel");
    Call("SetUI", 500, 300);
    
    // Small icon on left
    Call("AddImage", "icon.png", 20f, 50f, 32f, 32f);
    
    // Text next to icon
    Call("AddText", "Status: Online", 70f, 55f);
    
    // Another row
    Call("AddImage", "icon.png", 20f, 100f, 32f, 32f);
    Call("AddText", "Players: 15/50", 70f, 105f);
}

Background with Overlay

private void RegisterOverlayWindow()
{
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "OverlayPanel");
    Call("SetUI", 700, 500);
    
    // Full background
    Call("AddImage", "background.jpg", 0f, 0f, 700f, 500f);
    
    // Semi-transparent overlay (using alpha in text colors)
    Call("AddText", 
         "<color=#FFFFFFCC><size=20><b>Dashboard</b></size></color>", 
         50f, 50f);
    
    // Content with good contrast
    Call("AddCategory", 
         "<color=#FFFFFF>Quick Actions</color>", 
         50f, 120f);
         
    Call("AddButton", "Action 1", ".act1", 50f, 170f);
    Call("AddButton", "Action 2", ".act2", 50f, 220f);
}

Image Gallery

private void RegisterGallery()
{
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "Gallery");
    Call("SetUI", 650, 700);
    Call("SetTitle", "Image Gallery");
    
    // Grid of images (3x2)
    float startX = 25f;
    float startY = 50f;
    float imageSize = 200f;
    float spacing = 200f;
    
    // Row 1
    Call("AddImage", "image1.png", startX, startY, imageSize, imageSize);
    Call("AddImage", "image2.png", startX + spacing, startY, imageSize, imageSize);
    Call("AddImage", "image3.png", startX + spacing * 2, startY, imageSize, imageSize);
    
    // Row 2
    Call("AddImage", "image4.png", startX, startY + spacing + 50, imageSize, imageSize);
    Call("AddImage", "image5.png", startX + spacing, startY + spacing + 50, imageSize, imageSize);
    Call("AddImage", "image6.png", startX + spacing * 2, startY + spacing + 50, imageSize, imageSize);
}

Decorative Elements

private void RegisterDecoratedPanel()
{
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "DecoratedPanel");
    Call("SetUI", 600, 400);
    
    // Decorative corners
    Call("AddImage", "corner_tl.png", 0f, 0f, 64f, 64f);
    Call("AddImage", "corner_tr.png", 536f, 0f, 64f, 64f);
    Call("AddImage", "corner_bl.png", 0f, 336f, 64f, 64f);
    Call("AddImage", "corner_br.png", 536f, 336f, 64f, 64f);
    
    // Content in center
    Call("AddText", "<size=18><b>Styled Panel</b></size>", 250f, 170f);
    Call("AddButton", "Action", ".action", 250f, 220f);
}

Optimization Tips

Choose the Right Format

Use PNG when:

  • Image has transparency
  • Logo or icon
  • Sharp edges or text
  • Need lossless quality

Use JPG when:

  • Photo or background
  • No transparency needed
  • Can accept slight quality loss
  • Want smaller file size

Resize Before Embedding

// Bad: Using huge image, scaling down
Call("AddImage", "logo_4k.png", 20f, 20f, 200f, 100f);
// File: 3840x2160, 5MB - wastes memory!

// Good: Image sized appropriately
Call("AddImage", "logo_small.png", 20f, 20f, 200f, 100f);
// File: 400x200, 50KB - perfect!

Rule: Never use images larger than 2x their display size.

Compression

Before embedding:

  1. Optimize PNG files with TinyPNG
  2. Save JPG with 85% quality (good balance)
  3. Remove unnecessary metadata
  4. Consider converting large PNGs to JPG if no transparency needed

Loading Performance

Tips for better performance:

  • Use fewer, larger images rather than many small ones
  • Reuse images where possible
  • Keep total image data under 2-3MB per mod
  • Test load times with all images

Troubleshooting

Image Not Appearing

Check 1: Build Action

Ensure Build Action = Embedded Resource in project properties

Check 2: Filename Case

// Case-sensitive!
Call("AddImage", "Logo.png", ...);  // Won't work if file is "logo.png"
Call("AddImage", "logo.png", ...);  // Correct

Check 3: File Extension

// Include extension
Call("AddImage", "logo", ...);      // Wrong
Call("AddImage", "logo.png", ...);  // Correct

Check 4: Assembly

// The image loader uses Assembly.GetCallingAssembly()
// Must be called from your mod's code, not a helper method

Image Quality Issues

Problem: Blurry image

- Image too small, being upscaled
- Solution: Use higher resolution image

Problem: Pixelated image

- Using low quality JPG
- Solution: Use PNG or higher quality JPG

Problem: Wrong colors

- Color space issues
- Solution: Save as sRGB color space

Performance Issues

Problem: Slow loading

- Images too large
- Solution: Optimize and compress images

Problem: High memory usage

- Too many large images
- Solution: Reduce image count or size

Complete Examples

Professional Branded Panel

public class ImageConfig
{
    public const string LOGO = "logo.png";
    public const string BACKGROUND = "bg_panel.jpg";
    public const string ICON_HEALTH = "icon_health.png";
    public const string ICON_MANA = "icon_mana.png";
}

private void RegisterBrandedPanel()
{
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "BrandedPanel");
    Call("SetUI", 700, 600);
    Call("SetTitle", "Professional Panel");
    
    // Background
    Call("AddImage", ImageConfig.BACKGROUND, 0f, 0f, 700f, 600f);
    
    // Logo centered at top
    Call("AddImage", ImageConfig.LOGO, 250f, 30f, 200f, 80f);
    
    // Status section with icons
    Call("AddText", 
         "<color=#FFFFFF><size=16><b>Status</b></size></color>", 
         50f, 150f);
    
    Call("AddImage", ImageConfig.ICON_HEALTH, 50f, 190f, 32f, 32f);
    Call("AddText", "<color=#FFFFFF>Health: 100%</color>", 95f, 195f);
    
    Call("AddImage", ImageConfig.ICON_MANA, 50f, 240f, 32f, 32f);
    Call("AddText", "<color=#FFFFFF>Mana: 75%</color>", 95f, 245f);
    
    // Actions
    Call("AddText", 
         "<color=#FFFFFF><size=16><b>Actions</b></size></color>", 
         50f, 320f);
    
    Call("AddButton", "Heal", ".heal", 50f, 370f);
    Call("AddButton", "Restore Mana", ".mana", 50f, 420f);
}

Image-based Dashboard

private void RegisterDashboard()
{
    const int WIDTH = 800;
    const int HEIGHT = 600;
    
    Call("SetPlugin", "MyMod");
    Call("SetTargetWindow", "Dashboard");
    Call("SetUI", WIDTH, HEIGHT);
    Call("SetTitle", "Server Dashboard");
    
    // Background
    Call("AddImage", "dashboard_bg.jpg", 0f, 0f, WIDTH, HEIGHT);
    
    // Header with logo
    Call("AddImage", "header_logo.png", 
         (WIDTH - 300) / 2, 20f, 300f, 100f);
    
    // Status cards with icons
    float cardY = 150f;
    float cardSpacing = 150f;
    
    // Players card
    Call("AddImage", "card_bg.png", 50f, cardY, 200f, 120f);
    Call("AddImage", "icon_players.png", 70f, cardY + 20f, 48f, 48f);
    Call("AddText", 
         "<color=#FFFFFF><size=14><b>Players</b></size></color>", 
         130f, cardY + 30f);
    Call("AddText", 
         "<color=#FFFFFF>15/50</color>", 
         130f, cardY + 60f);
    
    // Performance card
    Call("AddImage", "card_bg.png", 300f, cardY, 200f, 120f);
    Call("AddImage", "icon_performance.png", 320f, cardY + 20f, 48f, 48f);
    Call("AddText", 
         "<color=#FFFFFF><size=14><b>Performance</b></size></color>", 
         380f, cardY + 30f);
    Call("AddText", 
         "<color=#2ECC71>Excellent</color>", 
         380f, cardY + 60f);
    
    // Uptime card
    Call("AddImage", "card_bg.png", 550f, cardY, 200f, 120f);
    Call("AddImage", "icon_uptime.png", 570f, cardY + 20f, 48f, 48f);
    Call("AddText", 
         "<color=#FFFFFF><size=14><b>Uptime</b></size></color>", 
         630f, cardY + 30f);
    Call("AddText", 
         "<color=#FFFFFF>4h 32m</color>", 
         630f, cardY + 60f);
}

Best Practices

Image Naming

✅ Good names:

logo.png
background_panel.jpg
icon_health.png
card_player_stats.png

❌ Bad names:

IMG_1234.png
picture.jpg
new bitmap image.png  (has spaces!)
LOGO.PNG              (all caps can cause issues)

Rules:

  • Use lowercase
  • No spaces (use underscores)
  • Descriptive names
  • Include extension

Organization

// Organize image constants
public static class Images
{
    public const string LOGO = "logo.png";
    
    public static class Backgrounds
    {
        public const string PANEL = "bg_panel.jpg";
        public const string DASHBOARD = "bg_dashboard.jpg";
    }
    
    public static class Icons
    {
        public const string HEALTH = "icon_health.png";
        public const string MANA = "icon_mana.png";
        public const string STAMINA = "icon_stamina.png";
    }
}

// Usage
Call("AddImage", Images.LOGO, 20f, 20f, 200f, 100f);
Call("AddImage", Images.Icons.HEALTH, 50f, 100f, 32f, 32f);

Testing

  1. Test with ZUI installed

    • Verify images appear
    • Check positioning
    • Verify quality

  2. Test different resolutions

    • 1920x1080
    • 2560x1440
    • 3840x2160

  3. Test performance

    • Load times
    • Memory usage
    • Frame rate impact

Related Pages

With custom images, your ZUI interfaces can have unique branding and visual appeal!

Pages

About

Contact Us Privacy Policy Thunderstore Wiki

Developers

API Docs GitHub Repo Package Format Docs Markdown Preview Manifest Validator

Thunderstore 2024