Desktop Mascot Maker - DirectComposition Edition

#

A Unity asset for creating desktop mascots (desktop accessories) on Windows.

日本語版はこちら / Japanese version

Table of Contents

#

1. About This Asset
2. System Requirements
3. New Features (v3.0.0)
4. Getting Started
5. MascotMakerDComp Component Reference
6. MascotMakerDComp API Reference
7. Event Callbacks
8. Example Scenes
9. Troubleshooting
10. Performance and Optimization
11. Known Limitations
12. Contact

About This Asset

#

Desktop Mascot Maker - DirectComposition Edition is a Unity asset that allows you to display characters and animations created in Unity as Windows desktop mascots (desktop accessories).

Key Features

#

• High-Performance Rendering: GPU hardware acceleration using DirectComposition + Direct3D 11
• Zero-Copy Texture Sharing: Direct sharing of Unity RenderTexture on GPU, eliminating CPU transfer
• Significant CPU Load Reduction: 70-90% reduction in CPU usage compared to the previous version (v2.2.0 GDI/WinForms edition)
• Two Window Modes:
  • Rectangle Window: Fast and lightweight rectangular window mode
  • Alpha Mask Window: Cell-based window shape formation mode
• Context Menu Support: Display custom menus with right-click
• IL2CPP Support: Supports both Mono and IL2CPP build backends
• Rich Event System: Handle mouse and window events with UnityEvent

Differences from Previous Version

#

The previous version (v2.2.0) used WinForms + GDI/UpdateLayeredWindow, but this version (v3.0.0) adopts DirectComposition to solve the following problems:

• ❌ Previous Version Issues:

  • High CPU load (texture copy from GPU→CPU every frame)
  • GDI/GDI+ is not GPU accelerated
  • Issues with DPI scaling in high-DPI and multi-monitor environments
  • Only Mono build backend supported (no IL2CPP support)

• ✅ DirectComposition Edition Improvements:

  • 70-90% CPU usage reduction (zero-copy processing on GPU)
  • Hardware acceleration via DirectComposition
  • Full support for high-DPI and multi-monitor environments
  • IL2CPP build backend support

If you wish to use the previous version (v2.2.0), please import and use DesktopMascotMakerV220.unitypackage.

System Requirements

#

Required Environment

#

Important Settings

#

1. Set Graphics API to Direct3D 11

#

Steps:

1. Edit → Project Settings → Player
2. Other Settings section
3. Remove all except Direct3D 11 from Graphics APIs for Windows
4. Ensure Direct3D 11 is at the top (priority)

Note: Direct3D 12, Vulkan, and OpenGL are not supported.

2. When Using IL2CPP

#

IL2CPP build backend is fully supported. No additional settings required.

New Features (v3.0.0)

#

Significant Performance Improvements with DirectComposition

#

• 70-90% CPU usage reduction: Significant reduction in CPU load through zero-copy texture sharing on GPU
• Hardware Acceleration: GPU rendering via DirectComposition
• High-DPI Support: Resolved scaling issues in multi-monitor and high-DPI environments

Two Window Modes

#

Alpha Mask Window Mode

#

• Divides the rendering area into cells and forms a window only with cells containing opaque pixels
• ✓ Transparent cells allow click-through
• ✓ Draggable (opaque cells only)
• △ Performance (window shape update cost)
• Recommended use: Complex-shaped mascots, when click-through is required

Rectangle Window Mode (Default)

#

• Simple rectangular window
• ✗ No click-through (entire window accepts clicks)
• ✓ Draggable (choose “anywhere” or “opaque regions only” with Draggable Area)
• ✓ Good performance (no window shape updates, alpha mask only used for DragOpaqueOnly)
• Recommended use: Simple mascots, performance-critical applications

Context Menu

#

• Display custom menus with right-click
• Dynamically add/remove custom items
• Built-in “Close” and “Exit Application” menu items
• Automatic separator insertion

IL2CPP Support

#

• Previous version (v2.2.0) only supported Mono
• v3.0.0 fully supports IL2CPP build backend
• Allow 'unsafe' Code option is not required (was required in previous version)

Other Improvements

#

• No .NET Framework Required: DirectComposition native plugin uses only Windows API
• Clean Code: Minimized debug logs, well-commented for users
• Source Code Distribution: C++ DLL source code and detailed build documentation included

Getting Started

#

1. Project Setup

#

Graphics API Settings

#

1. Edit → Project Settings → Player
2. Other Settings → Graphics APIs for Windows
3. Remove all except Direct3D 11

2. Basic Usage

#

Step 1: Prepare Camera

#

1. Create a camera to capture the character you want to display as a desktop mascot
2. Set camera’s Clear Flags to Solid Color
3. Set Background color alpha value to 0 (fully transparent)

Step 2: Attach MascotMakerDComp Component

#

1. Attach MascotMakerDComp component to the camera
2. Adjust settings in Inspector (see next section for details)

Step 3: Verify in Play Mode

#

1. Run Unity Editor Play mode
2. Mascot window will appear on desktop
3. Drag the mascot to move it

3. Minimal Example

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

using UnityEngine;
using DesktopMascotMaker;

public class SimpleMascot : MonoBehaviour
{
    void Start()
    {
        var mascot = GetComponent<MascotMakerDComp>();

        // Show window
        mascot.Show();
    }
}

MascotMakerDComp Component Reference

#

Basic Settings

#

Window Position

#

Appearance

#

Window Mode

#

Rectangle Window Settings (Used in Rectangle Window mode)

#

Alpha Mask Settings (Used in Alpha Mask Window mode)

#

Context Menu Settings

#

How to add custom menu items:

1. Increase size of Context Menu Items
2. Enter menu display text in Label for each item
3. Set up processing for when selected in OnSelected event

MascotMakerDComp API Reference

#

Window Show/Hide

#

void Show()

#

Shows the window (also initializes if not yet initialized).

1

mascot.Show();

void Hide()

#

Hides the window (window is not destroyed).

1

mascot.Hide();

bool IsVisible { get; }

#

Gets whether the window is currently visible.

1
2
3
4

if (mascot.IsVisible)
{
    Debug.Log("Window is visible");
}

Window Position

#

int Left { get; set; }

#

int Top { get; set; }

#

Gets or sets the window position (screen coordinates, top-left origin).

1
2
3
4
5
6
7

// Get position
int x = mascot.Left;
int y = mascot.Top;

// Set position
mascot.Left = 200;
mascot.Top = 200;

Window Size

#

Vector2 MascotWindowSize { get; set; }

#

Gets or sets the window size (in pixels).

1
2

// Get size
Vector2 size = mascot.MascotWindowSize;

Important: Window size cannot be changed after initialization. Only set before initialization (before Awake/Start). Even if you change the size at runtime, the initial value will continue to be used.

Context Menu

#

void AddContextMenuItem(string label, UnityAction onSelected = null)

#

Adds a context menu item at runtime.

1
2
3
4
5
6
7

// Simple addition
mascot.AddContextMenuItem("Custom Action");

// Add with action
mascot.AddContextMenuItem("Execute Action", () => {
    Debug.Log("Action was executed");
});

void ClearContextMenuItems()

#

Clears all custom context menu items.

1

mascot.ClearContextMenuItems();

Window Mode

#

WindowMode Mode { get; set; }

#

Gets or sets the window mode.

1
2
3
4
5

// Set to Rectangle Window mode
mascot.Mode = MascotMakerDComp.WindowMode.RectangleWindow;

// Set to Alpha Mask Window mode
mascot.Mode = MascotMakerDComp.WindowMode.AlphaMaskWindow;

Alpha Mask Settings

#

float AlphaThreshold { get; set; }

#

Gets or sets the alpha mask threshold (0.0-1.0).

1
2

// Consider pixels with alpha value greater than 0.3 as opaque
mascot.AlphaThreshold = 0.3f;

HitTestPrecision Precision { get; set; }

#

Gets or sets the alpha mask precision. Generally, Low is sufficient.

1
2
3
4
5
6
7
8

// Fast and lightweight (recommended)
mascot.Precision = MascotMakerDComp.HitTestPrecision.Low;

// Balanced
mascot.Precision = MascotMakerDComp.HitTestPrecision.Medium;

// High precision mode
mascot.Precision = MascotMakerDComp.HitTestPrecision.High;

HitTestUpdateMode UpdateMode { get; set; }

#

Gets or sets the alpha mask update mode.

1
2
3
4
5
6
7
8

// Update every frame (for animations)
mascot.UpdateMode = MascotMakerDComp.HitTestUpdateMode.EveryFrame;

// Periodic update (recommended)
mascot.UpdateMode = MascotMakerDComp.HitTestUpdateMode.Periodic;

// Manual update only (best performance)
mascot.UpdateMode = MascotMakerDComp.HitTestUpdateMode.Manual;

void UpdateAlphaMask()

#

Manually updates the alpha mask (used when Update Mode is Manual).

1
2
3
4
5

// Update on specific animation frame
if (animationFrameChanged)
{
    mascot.UpdateAlphaMask();
}

Mouse State Query

#

Vector2 GetMousePosition()

#

Gets the mouse position within the mascot window.

1
2

Vector2 mousePos = mascot.GetMousePosition();
Debug.Log($"Mouse position: {mousePos}");

bool IsMouseOver()

#

Gets whether the mouse is over the mascot window.

1
2
3
4

if (mascot.IsMouseOver())
{
    Debug.Log("Mouse is over mascot");
}

bool IsLeftButtonPressed()

#

bool IsRightButtonPressed()

#

bool IsMiddleButtonPressed()

#

Gets whether each mouse button is pressed.

1
2
3
4

if (mascot.IsLeftButtonPressed())
{
    Debug.Log("Left button is pressed");
}

Other

#

void Shutdown()

#

Closes the window and releases resources (normally called automatically).

1

mascot.Shutdown();

Event Callbacks

#

MascotMakerDComp can handle mouse and window events with UnityEvent.

Mouse Events

#

Left Mouse Button

#

• OnLeftMouseDown: When left mouse button is pressed (receives Vector2 mousePos)
• OnLeftMouseUp: When left mouse button is released (receives Vector2 mousePos)
• OnLeftDoubleClick: When left mouse button is double-clicked (receives Vector2 mousePos)

1
2
3

mascot.OnLeftMouseDown.AddListener((mousePos) => {
    Debug.Log($"Left clicked at: {mousePos}");
});

Right Mouse Button

#

• OnRightMouseDown: When right mouse button is pressed (receives Vector2 mousePos)
• OnRightMouseUp: When right mouse button is released (receives Vector2 mousePos)
• OnRightDoubleClick: When right mouse button is double-clicked (receives Vector2 mousePos)

1
2
3

mascot.OnRightMouseDown.AddListener((mousePos) => {
    Debug.Log($"Right clicked at: {mousePos}");
});

Middle Mouse Button

#

• OnMiddleMouseDown: When middle mouse button is pressed (receives Vector2 mousePos)
• OnMiddleMouseUp: When middle mouse button is released (receives Vector2 mousePos)
• OnMiddleDoubleClick: When middle mouse button is double-clicked (receives Vector2 mousePos)

1
2
3

mascot.OnMiddleMouseDown.AddListener((mousePos) => {
    Debug.Log($"Middle clicked at: {mousePos}");
});

Mouse Wheel

#

• OnMouseWheel: When mouse wheel is scrolled (receives int delta)

1
2
3

mascot.OnMouseWheel.AddListener((delta) => {
    Debug.Log($"Wheel scrolled: {delta}");
});

Window Events

#

• OnMove: When window is moved (receives Vector2 windowPos)

1
2
3

mascot.OnMove.AddListener((windowPos) => {
    Debug.Log($"Window moved to: {windowPos}");
});

• OnDestroyed: Just before MascotMakerDComp component is destroyed

1
2
3
4

mascot.OnDestroyed.AddListener(() => {
    Debug.Log("Mascot is being destroyed");
    // Perform cleanup of associated GameObjects, etc.
});

Context Menu Events

#

• OnContextMenuOpening: Just before context menu opens (allows dynamic menu item addition/removal)

1
2
3
4
5

mascot.OnContextMenuOpening.AddListener(() => {
    // Dynamically add menu items
    mascot.ClearContextMenuItems();
    mascot.AddContextMenuItem("Current time: " + System.DateTime.Now.ToString("HH:mm"));
});

Note: Selection events for custom menu items are handled in each ContextMenuItem’s OnSelected event.

Example Scenes

#

Demo01_Event

• Demo to verify mouse events, window events, and context menu events
• Context menu demo

Demo02_MultipleMascot

• Demo displaying multiple mascot characters
• AI script that automatically moves windows
• Rectangle Window Mode

Demo03_AlphaMaskWindow

• Demo to verify Alpha Mask Window shape (Alpha Mask Window Mode)
• Character Orbital View
• Context Menu Close

Troubleshooting

#

Window Does Not Appear

#

Causes and Solutions:

1. Graphics API is not Direct3D 11

   • Check Project Settings → Player → Graphics APIs for Windows
   • Enable only Direct3D 11

2. DLL Not Found

   • Check for DllNotFoundException error in Unity Console
   • Verify that Assets/DesktopMascotMaker/Plugins/x86_64/DCompMascot.dll (64-bit) or Assets/DesktopMascotMaker/Plugins/x86/DCompMascot.dll (32-bit) exists

3. Play On Awake is Disabled

   • Check if Play On Awake is checked in Inspector
   • Or call mascot.Show() from script

Window Click Detection is Strange

#

For Rectangle Window mode:

• In Rectangle Window mode, the entire window is the hit detection area
• Transparent parts are also clickable (affects underlying windows)
• If you need cell-based transparency detection, switch to Alpha Mask Window mode

For Alpha Mask Window mode:

1. Adjust Alpha Threshold

   • Pixels with alpha value greater than this threshold are considered opaque
   • Default: 0.5 (0.0-1.0)

2. Adjust Precision

   • Low: 12x16 grid (fastest, lower accuracy)
   • Medium: 24x32 grid (recommended, balanced)
   • High: 48x64 grid (high accuracy, somewhat heavy)

Poor Performance (Low FPS)

#

Solutions:

1. Use Rectangle Window mode

   • Alpha Mask Window mode has higher load than Rectangle Window

2. Lower Precision

   • When using Alpha Mask Window mode, change Precision from Medium → Low

3. Set Update Mode to Periodic or Manual

   • EveryFrame updates every frame, causing high load
   • For static mascots, Manual is recommended

4. Increase Periodic Update Interval

   • Increasing update interval from 0.1s → 0.2s or more will reduce load

5. Reduce Window Size

   • Larger windows increase load

6. Check Camera Settings

   • Disable unnecessary Post-Processing effects

Performance and Optimization

#

Performance Improvements with DirectComposition

#

Compared to the previous version (v2.2.0 GDI/WinForms), the DirectComposition edition (v3.0.0) achieves the following improvements:

• 70-90% CPU usage reduction: Zero-copy texture sharing on GPU
• Frame rate stabilization: Stable rendering with GPU hardware acceleration
• Memory bandwidth reduction: Elimination of texture copy between CPU↔GPU

Performance by Window Mode

#

Optimization Tips

#

1. Window Mode Selection

   • Use Rectangle Window mode unless you have a specific reason
   • Use Alpha Mask Window only when click-through is required

2. Precision Adjustment

   • Low provides sufficient accuracy (12x16 grid, 192 cells)
   • For more complex shapes, try Medium (24x32 grid, 768 cells)

3. Update Mode Selection

   • Static mascots: Use Manual and call UpdateAlphaMask() only when needed
   • Animations: Use Periodic with Interval set to 0.2s or more
   • Real-time changes: Use EveryFrame (highest load)

4. Optimization for Multiple Mascots

   • Randomize Periodic Update Interval for each mascot (automatically offset)
   • Unify Precision to Low
   • Hide unnecessary mascots with Hide()

Known Limitations

#

Supported Platforms

#

• Windows 10/11 only: DirectComposition is a Windows-exclusive API
• macOS, Linux, mobile platforms not supported

Graphics API

#

• Only Direct3D 11 supported: Direct3D 12, Vulkan, OpenGL not supported
• Must use Direct3D 11 in both Unity Editor and Standalone Build

Window Features

#

• Window size cannot be changed after initialization: Runtime resizing is not supported
• No minimize/maximize buttons: Borderless window for desktop mascot purposes
• Not shown in taskbar: By design as a desktop accessory

Multi-Monitor

#

• Generally supported: Window can move between multiple monitors
• Initial position is on primary monitor: Left / Top are based on primary monitor screen coordinates

Contact

#

Technical Support

#

If you encounter problems or have questions, please contact:

• Email: support@panzersoft.com

Bug Reports

#

When reporting bugs, please include the following information:

1. Unity version
2. OS version (Windows 10/11)
3. Steps to reproduce
4. Error messages from Unity Console
5. (If possible) Minimal reproduction sample project

Thank you for choosing Desktop Mascot Maker - DirectComposition Edition!