Unity Generator

🏗️ Project Status

🔒 Quality & Security

💻 Tech Stack

Unity Generator is a lightweight desktop app for generating Unity C# code and assets (text, images, and audio) using cloud AI providers. It ships an Electron + Vue UI with a local FastAPI backend orchestrated by Semantic Kernel, including a custom plug-in: Unity MCP server. All API keys are provided by the user and stored locally. The app is designed to be a fast, local-first assistant for Unity developers, with a focus on incremental asset generation and seamless integration with active Unity projects.

Why this exists

Unity Generator is a small, local-first studio assistant. It keeps the UI fast, the backend lightweight, and prompts flexible so you can iterate on Unity code and assets without wiring multiple tools together. It’s not a full IDE or asset pipeline replacement - it’s just a quick way to generate and save Unity-ready code snippets, text, images, and audio assets using your choice of providers. It’s designed to slot into your existing workflow and let you iterate on generated assets in an active Unity project without friction.

What it can do

• Generate Unity-ready C# snippets and project scaffolds
• Create text drafts, image prompts, and audio placeholders
• Unity UI Elements: Generate Unity UI prefabs (health bars, buttons, dialogue boxes, HUD layouts) for both uGUI and UI Toolkit
• Incremental Asset Generation: Save assets directly into an active Unity project
• Pixel-Art Sprites: Generate and process 2D sprite sheets with automatic cropping
• Unity MCP Integration: Real-time interaction with the Unity Editor using Unity-MCP-SK-Plugin and Unity-MCP-Server
• Save and reuse provider settings and preferences locally
• Configure global and per-request system key prompts for tailored generation
• Keep output structured so Unity can open it right away
• Run on Windows, Linux, and macOS with full feature parity
• Package as native installers with Electron (no Docker dependency for end users)
• Open-source and extensible with a modular architecture

Workspace Structure

• frontend/ - Electron + Vue UI
• backend/ - FastAPI + Semantic Kernel backend
• config/ - Local API key storage
• agents/ - Modular Semantic Kernel agents
• services/ - Provider wrappers (LLM, image, audio)
• db/ - SQLite storage for user preferences
• output/ - Generated Unity projects and assets
• logs/ - Backend logs

Status

Scaffolded and functional. See docs for development and packaging details. The project is in early stages and may have rough edges, but the core architecture is in place. Contributions are welcome!

Documentation

• Architecture overview
• Development guide
• Packaging and distribution
• System Prompts guide

Integrated Tooling

Unity Generator is optimized for development with VS Code:

• Native Workflow: Use the Dev: Backend + Frontend launch configuration to debug both stacks simultaneously.
• Docker Support: Integrated tasks for docker-compose and remote machine debugging are provided for isolated testing.
• Editor Setup: Configured for Volar (Vue 3) and TypeScript, with type checking mapped to internal monorepo paths.
• Architecture: While Docker is used for dev/CI, the final product uses the Electron framework for a zero-dependency installation experience.

All contributions must follow the SRP, KISS, and Clean Architecture principles outlined in the development guide.

🔥 Cross-Platform Support

Unity Generator runs on Windows, Linux, and macOS with full feature parity.

Development Setup (All Platforms)

# Install dependencies (works on all platforms)
pnpm run setup

# Start backend (cross-platform)
pnpm run backend:dev

# Start frontend (cross-platform)
pnpm run dev

Containerized Development

All platforms support Docker/Docker Compose:

docker-compose up

Validation

The project maintains cross-platform compatibility through:

• Automated CI: Tests run on Ubuntu, Windows, and macOS on every PR
• Path Handling: Uses pathlib.Path throughout for safe cross-platform file operations
• Shell Scripts: Build and dev scripts use cross-platform npm/pnpm commands
• Configuration: Platform-agnostic JSON/YAML configs (no hardcoded paths)

See CONTRIBUTING.md for platform-specific development guidelines.

Quick Start

For Development

Most development doesn't require building the full installer:

# 1. Install dependencies
pnpm run setup

# 2. Start dev servers (backend + frontend with hot reload)
pnpm run dev

This launches the app in development mode with live reloading.

For Local Packaging

To build the full native installer locally:

1. Build the package:

   pnpm run package

   This creates the native installer using Electron Forge:
   • Windows: .exe installer
   • Linux: .deb and .AppImage packages
   • macOS: .dmg installer

For Production Releases (Automated)

You don't need to build installers manually. CI automatically builds for all platforms:

1. Tag a release: git tag -a v1.0.0 -m "Release v1.0.0" && git push origin v1.0.0
2. GitHub Actions builds Windows/Linux/macOS installers
3. Download from the Releases page

How it works

1. The Vue + Electron UI collects prompts and settings.
2. The FastAPI backend routes each request to an agent.
3. Agents call provider wrappers (LLM, image, audio) using your keys.
4. Responses are normalized and returned to the UI.
5. Unity project requests are written to output/ with Unity metadata.
6. Active Projects: Individual assets can be auto-saved to any active Unity project workspace. The UI keeps a session-scoped project name and path; when you create a scene, that path is sent to the backend and injected into the Unity agent so MCP tools (e.g. save_*, contract) receive the correct project path.

Configuration

API keys are stored locally in config/api_keys.json. Use the Settings panel to configure keys and set preferred providers. The UI uses dropdown menus to let you easily select from supported providers and models.

Supported providers

LLM:

• openai
• deepseek
• openrouter
• groq
• google
• anthropic
• huggingface
• replicate (chat via Replicate predictions API; default model meta/llama-2-7b)

Image:

• stability
• flux
• openai
• replicate (e.g. Flux)

Audio:

• elevenlabs
• playht
• replicate (e.g. MusicGen)

The backend selects providers by priority when no explicit provider is set. Replicate LLM uses a custom Semantic Kernel adapter that calls the predictions API (create + poll) instead of an OpenAI-compatible endpoint. See backend/app/services/providers/connectors/replicate.py. Priority order is defined in the provider registry and in services/llm_provider.py, services/image_provider.py, and services/audio_provider.py.

Preferences

The UI stores preferred providers in the local SQLite DB:

• preferred_llm_provider
• preferred_image_provider
• preferred_audio_provider

Backend API

Base URL: http://127.0.0.1:35421

Health:

• GET /health

Generation:

• POST /generate/code
• POST /generate/text
• POST /generate/image
• POST /generate/audio
• POST /generate/sprites
• POST /generate/unity-ui

Request body (standard generation):

{
  "prompt": "Generate a Unity player controller",
  "provider": "openai",
  "project_path": "C:/Projects/MyUnityGame",
  "options": {"model": "gpt-4o-mini", "temperature": 0.2}
}

Unity UI generation (/generate/unity-ui):

{
  "prompt": "Create a health bar with smooth fill animation",
  "provider": "openai",
  "ui_system": "ugui",
  "element_type": "health_bar",
  "output_format": "script",
  "anchor_preset": "stretch",
  "color_theme": "dark red with gold accents",
  "include_animations": true,
  "options": {"model": "gpt-4o-mini", "temperature": 0.4}
}

Unity project generation:

• POST /generate/unity-project

Request body:

{
  "project_name": "MyUnityProject",
  "code_prompt": "Create a player controller",
  "text_prompt": "Write a short quest description",
  "image_prompt": "Fantasy landscape",
  "audio_prompt": "Calm ambient loop",
  "provider_overrides": {"code": "openai", "image": "stability"},
  "options": {
    "code": {"model": "gpt-4o-mini"},
    "image": {"aspect_ratio": "1:1"}
  }
}

Configuration:

• GET /config/keys
• POST /config/keys

Preferences:

• GET /prefs/{key}
• POST /prefs

Output:

• GET /output/latest

Outputs

• Generated assets and Unity projects land in output/ by default.
• When an active project is set, files are saved directly to its Assets/ subfolders:
  • Scripts: Assets/Scripts/
  • Text: Assets/Text/
  • Images/Sprites: Assets/Sprites/
  • Audio: Assets/Audio/
• Every saved asset includes an automatically generated .meta file.

Test Isolation & Mocking

All tests in this repository are fully isolated from the real filesystem and network:

• Frontend unit/integration tests: All network requests are globally mocked using MSW. No real HTTP requests are made; all dependencies must be mocked in each test.
• Backend unit/integration tests: All filesystem operations are globally mocked using pyfakefs. No real files or directories are created, modified, or deleted during tests. All network dependencies must be mocked in each test.
• E2E tests: All backend API endpoints are intercepted and mocked using Playwright’s route interception. No real backend or network is required for E2E tests; all dependencies are mocked for deterministic, fast, and safe runs.

Note: Any test that attempts to access the real filesystem or network will fail by default. If you add new dependencies, ensure they are properly mocked in your tests.

See the test setup files in frontend/src/test/setup.ts and backend/tests/conftest.py for details.

---

Tests

# Total validation (Lint + Typecheck + Test)
pnpm check:all

# All tests (Backend & Frontend)
pnpm run test:all

# Backend only
pnpm run test:backend

# Frontend unit tests
pnpm run test:frontend

# E2E tests
pnpm run test:e2e

Packaging

See docs/PACKAGING.md for bundling the backend sidecar and building the Electron app.

Docker

docker-compose.yml provides a dev/CI runner. See docs/PACKAGING.md.

Troubleshooting

• If the UI cannot reach the backend, confirm the backend is running on port 35421.
• If generation fails, verify your provider keys in config/api_keys.json.
• If a provider request errors, check logs/ for the failed request log.
• If a Docker build is slow, ensure node_modules/ and venvs are ignored.

Unity MCP Integration

See docs/UNITY_MCP_INTEGRATION.md for details on the Semantic Kernel MCP integration, configuration, and usage.

Download

You can download prebuilt packages from GitHub:

• Latest stable builds (recommended):
  https://github.com/Ozymandros/Unity-Generator/releases

• CI artifacts from latest workflow runs:
  https://github.com/Ozymandros/Unity-Generator/actions/workflows/build.yml

Note: GitHub Actions artifacts are tied to a workflow run and may expire.
For permanent downloads, use Releases.