What is MOD?

A MOD (modification) in Desktop Homunculus is a custom extension that allows you to add new functionality, user interfaces, and behaviors to your desktop companion. MODs are the primary way to customize and extend your Desktop Homunculus experience.

Core Capabilities

MODs enable you to:

🎨 Create Custom User Interfaces

• Build interactive HTML/CSS/JavaScript interfaces
• Create floating windows, control panels, and overlays
• Position UI elements relative to your VRM characters
• Design transparent or styled windows that integrate seamlessly with your desktop

🤖 Control VRM Characters

• Spawn, position, and animate VRM characters using 3D transforms
• Make characters speak using VoiceVox integration and AI-powered chat
• Play VRMA animations with precise control over repeat patterns and transitions
• Access character bone hierarchy for detailed pose manipulation
• Implement character state machines and automated routines

🎮 Add Interactive Features

• Respond to user clicks, drags, and keyboard input
• Create context menus that appear when right-clicking characters
• Add system tray menu items for quick access to MOD features
• Implement real-time communication between different parts of your MOD

🌐 Integrate External Services

• Connect to web APIs and external services
• Implement custom AI integrations beyond the built-in GPT support
• Create bridges to other applications and services

🎵 Add Audio and Visual Effects

• Play sound effects and background music
• Display visual effects like stamps and animations
• Control screen overlays and atmospheric effects
• Synchronize effects with character actions and speech

MOD Architecture

MODs in Desktop Homunculus are built around several key components:

📁 Asset-Based Structure

MODs are organized as directories containing:

• HTML files for user interfaces
• JavaScript/TypeScript files for scripting logic
• Images and icons for visual elements
• Audio files for sound effects
• Configuration files defining MOD behavior

⚙️ Configuration-Driven

MODs use a mod.json file to declare:

• Basic MOD metadata (name, version, author)
• Menu items and user interface entry points
• Startup scripts that run when the application starts
• System integrations like tray menu items

🌐 Web Technology Based

MODs leverage familiar web technologies:

• HTML/CSS for rich user interface design
• JavaScript/TypeScript for interactive behavior
• Standard web APIs for common functionality
• Custom SDK for Desktop Homunculus specific features

🔄 Real-Time Communication

MODs can communicate through:

• HTTP REST API for request/response operations (localhost:3100)
• Server-Sent Events for real-time data streaming and character events
• Command system for cross-MOD communication via pub/sub patterns
• Event streams for reacting to user interactions (clicks, drags, state changes)
• Deno Runtime providing secure JavaScript/TypeScript execution environment

Types of MODs

UI-Focused MODs

Perfect for creators who want to build interactive interfaces:

• Chat interfaces for conversing with AI-powered characters
• Settings panels for configuring application behavior
• Status displays showing real-time information
• Control dashboards for managing multiple characters

Script-Focused MODs

Ideal for automating character behavior:

• Automated routines that run on schedules
• Character AI behaviors that respond to events
• Data processing scripts that work with external APIs
• Background services that enhance the core experience

Hybrid MODs

Combining UI and scripting for complex functionality:

• Interactive games where users play with their characters
• Productivity tools that integrate with work workflows
• Entertainment systems providing music, videos, or stories
• Social features connecting with friends and communities

Getting Started

Ready to create your first MOD? The journey involves:

1. Planning Your MOD: Define what you want to build and how users will interact with it
2. Setting Up the Structure: Create the directory layout and configuration files
3. Building the Interface: Design HTML/CSS interfaces if your MOD needs UI
4. Adding Functionality: Write JavaScript/TypeScript code for interactive behavior

The next section will guide you through creating your first MOD step by step.

Next: MOD Creation Guide