Desktop Homunculus 🧬

A Cross-Platform Desktop Pet Application with AI-Powered Characters

Bring your desktop to life with intelligent 3D VRM characters that can chat, react, and evolve alongside your workflow. Desktop Homunculus transforms your computer into an interactive companion experience powered by cutting-edge web technologies and AI integration.

demo.mp4

Transition smoothly to drag animations.

Sitting on the window will make it sit down.

When you right-click on a character, a menu appears. You can customize this menu freely using MODs.

You can also chat with your character. Also, you can use VoiceVox to enable speech synthesis.(Japanese only)

✨ Key Features

🤖 AI-Powered Chat Integration

• ChatGPT Integration: Engage in natural conversations with your desktop mascot
• VoiceVox Support: Characters can speak with realistic Japanese voice synthesis
• Lip Sync Animation: Watch your character's mouth move naturally when speaking
• Custom System Prompts: Define unique personalities and behaviors for each character

🎭 Advanced VRM Character System

• Multiple VRM Models: Deploy multiple 3D characters simultaneously across your desktop
• VRMA Animation Support: Create custom animations and emotional expressions
• Multi-Monitor Support: Characters can roam freely across all your displays
• Custom Avatars: Import and create your own VRM models and animations

🔌 Extensible MOD System

• TypeScript SDK: Build powerful extensions using modern web technologies
• HTTP API: Integrate with external applications via REST endpoints (localhost:3100)
• Custom Interfaces: Create floating HTML/CSS/JavaScript UI components
• Script Automation: Run JavaScript automation scripts for complex behaviors
• Real-time Communication: Event-driven architecture for responsive interactions

⚡ Power Efficient Design

• Framerate Optimization: Dynamic FPS limiting to conserve battery life

🌐 Developer-Friendly Architecture

• Bevy Game Engine: Built on Rust's high-performance ECS architecture
• WebView Integration: Embed modern web UIs directly in 3D space
• Cross-Platform: Primary support for macOS, with Windows compatibility
• Modular Plugin System: Clean separation of concerns for easy contribution

🚀 Installation

Quick Start

Download the latest release from:

• itch.io
• BOOTH

Development Setup

# Clone the repository
git clone https://github.com/your-repo/desktop_homunculus.git
cd desktop_homunculus

# Install dependencies
make setup

# Run in development mode
make dev

🪛 MOD

• Manual

You can add characters, replace animations, and add UI using MODs.

⚙️ Configuration

ChatGPT Integration Setup

To enable AI chat functionality, configure your OpenAI API key using one of these methods:

Method 1: Environment File

Create assets/.env and add:

OPENAI_API_KEY=your_openai_api_key_here

Method 2: System Environment (macOS)

# Set the environment variable system-wide
launchctl setenv OPENAI_API_KEY your_openai_api_key_here

VoiceVox Integration

1. Download and install VoiceVox
2. Launch VoiceVox before starting Desktop Homunculus
3. Characters will automatically gain speech capabilities with synchronized lip movements

🎯 Use Cases

• Coding Companion: Get coding advice and rubber duck debugging assistance
• Productivity Assistant: Set reminders, display notifications, and manage tasks
• Language Learning: Practice conversations in Japanese with native voice synthesis
• Entertainment: Interactive desktop pets with personality and humor
• Workflow Enhancement: Custom automations and desktop organization tools

🛠️ Development Commands

# Core development
make dev                    # Run with development features
cargo run --features develop  # Alternative development command

# Building
pnpm build                  # Build TypeScript frontend components
cargo build                 # Build Rust components

# Quality assurance
make fix                    # Auto-format and fix linting issues
cargo test --workspace     # Run Rust tests
pnpm check-types           # TypeScript type checking

🌍 Platform Support

Platform	Status	Notes
✅ macOS	Fully Supported	Primary development platform
⚠️ Windows	Partially Supported	Requires OpenGL due to transparency limitations
🔄 Linux	Planned	Future release target

Warning

Windows Compatibility Note: Due to limitations in winit/wgpu, Windows requires OpenGL rendering for proper transparency. This may cause stability issues on some graphics configurations.

🐛 Known Issues

• Window background covered in black on Windows 11 with RTX
• Animation transition breaks with different initial VRM poses

🗺️ Roadmap

Priority Features

• Complete Windows platform support
• MOD Registry for easy extension sharing
• English language VRM speech support
• Enhanced multi-language AI personalities

Future Enhancements

• Cloud sync for character configurations
• Mobile companion app
• Advanced facial expression recognition
• Community character marketplace

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for detailed guidelines on:

• Application development and bug fixes
• VRM/VRMA animation contributions
• UI/UX improvements
• MOD development and SDK enhancements
• Documentation updates

📄 License

This project is licensed under LGPL-3.0-only.

🙏 Credits

• Built with Bevy Game Engine
• CI/CD powered by bevy_game_template
• VRM support via bevy_vrm1
• Voice synthesis by VoiceVox

---

Ready to bring your desktop to life? Download Desktop Homunculus today and create your own AI-powered digital companion!