MOD Creation Guide

This comprehensive guide will walk you through creating your first MOD for Desktop Homunculus. By the end of this section, you'll understand how to structure, configure, and develop fully functional MODs.

Overview

Creating a MOD involves several key steps:

Setting up the directory structure - Organizing your files properly
Writing the configuration file - Defining your MOD's metadata and behavior
Configuring menus - Adding entries to character context menus
Setting up system menus - Integrating with the system tray
Creating startup scripts - Running code when the application starts

Quick Start Example

Let's create a simple "Hello World" MOD to demonstrate the basic concepts:

1. Create the Directory

assets/mods/hello-world/
├── mod.json
├── index.html
└── icon.png

2. Basic Configuration (`mod.json`)

{
  "name": "hello-world",
  "version": "1.0.0",
  "description": "A simple Hello World MOD",
  "author": "Your Name",
  "menus": [
    {
      "text": "Hello World",
      "thumbnail": "hello-world/icon.png",
      "webview": {
        "source": "hello-world/index.html",
        "resolution": [
          300,
          200
        ],
        "transparent": true,
        "position": {
          "offset": [
            -350,
            -200
          ]
        }
      }
    }
  ]
}

3. Simple Interface (`index.html`)

<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            padding: 20px;
            background: rgba(255, 255, 255, 0.9);
            border-radius: 10px;
            text-align: center;
        }

        button {
            padding: 10px 20px;
            background: #007acc;
            color: white;
            border: none;
            border-radius: 5px;
            cursor: pointer;
        }

        button:hover {
            background: #005999;
        }
    </style>
</head>
<body>
<h2>Hello World!</h2>
<p>This is your first Desktop Homunculus MOD.</p>
<button onclick="sayHello()">Click Me!</button>

<script>
    function sayHello() {
        alert("Hello from your MOD!");
    }
</script>
</body>
</html>

4. Testing Your MOD

Place your MOD directory in assets/mods/hello-world/
Restart Desktop Homunculus
Right-click on any VRM character
Select "Hello World" from the context menu
Your MOD interface should appear!

MOD Loading Process

Understanding how MODs are loaded helps you debug issues:

Discovery: Desktop Homunculus scans the assets/mods/ directory on startup
Configuration Parsing: Each mod.json file is read and validated
Asset Registration: All files in MOD directories are registered as available assets
Menu Integration: Menu items defined in configuration are added to the UI
Script Execution: Any startup scripts are executed in the builtin Deno runtime