A Unity Editor extension that enables secure, deterministic AI-assisted scene creation and editing by constraining intent execution through a guarded control kernel.
Warning
EXPERIMENTAL & IN-DEVELOPMENT
This project is currently an active research prototype. APIs, security protocols, and core logic are subject to rapid, breaking changes. This software performs mutations on the Asset Database and Scene; MANDATORY BACKUPS are required before use.
A production-grade AI control interface for deterministic, undo-safe Unity Editor operations.
UnityVibeBridge is a professional-grade intelligent interface that transforms the Unity Editor into a Governed Creation Kernel. It allows AI agents to interact safely, deterministically, and artistically with Unity’s core engine—turning natural language intents into professional production operations.
The UnityVibeBridge operates as a Split-Plane Kernel:
- Intent Plane (MCP Server): A Python-based server that receives high-level commands from AI agents. It audits these commands via the
SecurityGateand queues them invibe_queue/inbox. - Execution Plane (Unity Editor): A C# kernel inside Unity that polls the queue. It uses a Hardened Async Kernel (
UniTask) for non-blocking operations and Zero-Reflection IPC (MemoryPack) for secure, high-speed data transfer. - Audit Plane (Write-Ahead Log): Every transaction is logged to
logs/vibe_audit.jsonland bracketed by a Git-safety snapshot for forensic verification.
Important
Dynamic Path Resolution: To maintain portability across different developer environments, all scripts MUST use dynamic path resolution (e.g., os.path.abspath(os.path.dirname(__file__))). Hardcoded home directory paths are strictly forbidden.
UnityVibeBridge is not a toy, a prompt wrapper, or a "magic AI button."
It is a reference implementation of AI-assisted systems design in a high-fidelity, stateful environment. It allows Large Language Models (LLMs) to safely operate inside Unity without risking project corruption, infinite import loops, or runaway execution.
This project answers a critical engineering question:
How do you let an AI act inside a complex, stateful application—without trusting it?
The answer is: You don’t. You constrain it.
| Capability | Feature |
|---|---|
| 🛡️ Iron Box | Zero-trust security via the Kernel Guard, Token-Auth, and AST-validated IPC. |
| ⚛️ Kernel Integrity | Real-time invariant enforcement (No mutations during domain reloads, atomic transactions). |
| 📦 LFS Anchored | High-scale binary assets (.fbx, .png) tracked via Git LFS for stable state hashing. |
| 🧪 Triple-Order Invariance | Layered reality (1st), causal (2nd), and epistemic (3rd) constraints preventing drift. |
| 🛰️ Single-Agent Determinism | Unified control model with strict state enforcement and air-gapped context sandboxing. |
| 🏃 Stable Lifecycle | Time-budgeted main-loop dispatching (5ms slices) ensuring a smooth 60+ FPS. |
| 🧠 Epistemic Control | Truth-reconciliation tools (telemetry, vibe_status) that prevent AI hallucinations. |
If you are evaluating this project as an engineer or hiring manager, this repository is a working demonstration of AI Systems Engineering:
- Control-Plane vs. Execution-Plane Separation: LLMs generate intent (Mechanistic Intents), never raw code execution.
- Adversarial Security: Hardened via local binding, session-token authentication, and Recursive AST Auditing of Python payloads.
- Triple-Order Invariance: Implements a "Triple-Lock" system:
- Mechanical: Hard engine guards (No mutations during compile).
- Contextual: Force-feeding WAL hashes and monotonic ticks into every response.
- Semantic: Mandatory "Proof of Work" (Rationale + State Hash) required for every commit.
- Single-Agent Control: Unified orchestration where the agent manages the engine kernel via filtered, engine-agnostic IPC, ensuring a single point of truth and atomic state transitions.
- Transactional State Mutation: Every operation is wrapped in undo-safe, atomic blocks. One AI request = One Undo step.
- Performance Budgeting: Implements 5ms Main-Thread Time Budgeting and adheres to the Unity Freeze-Proof Guide to ensure the Unity Editor maintains 60+ FPS even during heavy AI automation.
- Forensic Audit Trail (Git Logging): Every mutation is logged to a cryptographically chained Write-Ahead Log (WAL). For local setup, we recommend configuring Git to track the
logs/directory as a secondary immutable ledger (see Setup). - Truth Reconciliation Loop: Tools like
get_telemetry_errorsforce the agent to verify reality against intent in a closed feedback loop.
- Install: Drag the
unity-package/folder into your Unity project'sAssets/. - Initialize: Wait for compilation. The Kernel starts automatically on port
8085. - Connect: Point your AI agent (Claude Desktop, Goose, etc.) to the bridge using
scripts/python mcp-server/server.py. - Create: Ask the AI: "Spawn a red cube at the origin and name it 'TestCube'."
- Audit: Ask the AI: "Run a mesh audit on my selected object and tell me the polycount."
Requirements:
- Unity: 2019.4 LTS or newer.
- OS: Windows, Linux, or macOS.
- Unity Dependencies: UniTask, MemoryPack, and Editor Coroutines are required for the hardened async kernel.
- Install Unity Packages:
Run the automation script from your Unity project root:
This adds UniTask and MemoryPack to your project via Git URL.
python /path/to/UnityVibeBridge/scripts/setup_unity_deps.py
- Install VibeBridge: Copy the
unity-package/directory into your project'sAssets/folder. - Initialize: Wait for Unity to compile. The Kernel starts automatically on port
8085. - Handshake: Point your MCP-compatible AI agent (e.g., Goose, Claude Desktop) to the bridge.
- Monitor: Open http://localhost:22005 to view the live System Pulse and Chained Audit Trail.
New to AI development in Unity? Start here to understand the philosophy, safety mechanisms, and how to avoid common pitfalls like "AI Psychosis".
👉 Read the Comprehensive Guide for Beginners
The AI interacts with Unity via Mechanistic Tools. Below are typical requests the agent can execute autonomously once connected:
| Intent | Tool Call | Result |
|---|---|---|
| Placement | world/spawn(asset="path/to.prefab", pos="0,1,0") |
Spawns object at coordinates with Undo registration. |
| Rig Check | audit/avatar(path="sem:MainBody") |
Returns mesh, vertex, and material report for the target. |
| Automation | texture/crush(path="root", maxSize=512) |
Batch-downscales all textures in a single 5ms frame slice. |
| Visual Fix | material/set-color(path="sem:Face", index=0, color="1,0,0,1") |
Safely changes material properties via SerializedObjects. |
| Logic Batch | system/execute-recipe(tools_json="...") |
Executes multiple tools in one atomic, reversible transaction. |
Unlike standard script-bridges, UnityVibeBridge treats the AI as an untrusted operator.
- Pentest Suite: We include a
security_tests/pentest_suite.pythat tests for 48 known attack vectors. - Forensic Ledger: Every mutation is logged to an immutable, cryptographically chained audit log (
vibe_audit.jsonl). - Human Kill-Switch: The Kernel includes a mechanical
system/vetotool that instantly locks the creation perimeter.
inspect_object: Forces the agent to verify its assumptions about components and state.get_telemetry_errors: Streams the last 50 console logs to the agent for "Truth Loop" verification.list_available_tools: Dynamic discovery of installed Payloads and capabilities.- Stale Session Guard: Automatically invalidates beliefs if Unity restarts (via
sessionNoncetracking).
transaction_begin/commit: Atomic Undo-Group management.system/veto: Physical stop-button for all creation primitives.- Kernel Guard: Blocks mutations during Compilation or Play Mode.
- Time-Budgeting: Kernel-level enforcement of 5ms execution windows per frame.
get_hierarchy: Recursive dump of InstanceIDs and names for scene mapping.system/search: High-performance Regex and Layer-based discovery for massive scenes.rename_object/reparent_object: Precise transform and identity adjustments.clone_object/delete_object: Managed lifecycle for GameObjects with Undo support.select_object: Focus-aware "Stealth Framing" that respects the user's active viewport.
object/set-value: Safe, reflection-based mutation of public fields and properties.vram_footprint: Numerical analysis of GPU memory usage by textures.texture_crush: Batch-downscales textures with hardware safety caps (8k max).swap_to_quest_shaders: Automated material transition to mobile-safe shaders.opt/fork: Creates non-destructive optimization variants with isolated material clones.
world/spawn: Safe instantiation of prefabs from the project database.asset/rename/move: Safe filesystem operations without breaking GUID links.export/validate: Checks for scale sanity, non-zero rotations, and missing scripts.view/screenshot: High-speed visual feedback via Port 8085.
The bridge is hardened via four distinct layers:
- AST Auditing: All incoming tool calls are audited by
scripts/security_gate.pyfor forbidden patterns. - Token Authentication: Port 8085 requires an
X-Vibe-Tokenmatching the current session. - Iron Box Protocol: Every mutation is wrapped in atomic
Undogroups. One AI Request = One Undo Step. - The Guard: The bridge physically disables mutations if
vibe_status.jsonis not "Ready".
- Full Feature Manifest: Authoritative list of all functional abilities and roadmap.
- Technical Installation & Engineering: Deep dive into the Kernel architecture, security, and advanced setup.
- AI Philosophy & Safety: Learn how to manage AI behavior and prevent "AI Psychosis."
UnityVibeBridge is part of a trinity of tools designed for seamless AI-assisted creation:
- BlenderVibeBridge: The companion kernel for high-fidelity 3D modeling and rigging.
- VibeSync: The orchestration layer that synchronizes state between Unity and Blender.
While our "Iron Box" security model is strict, it is designed to empower creators, not restrict them. The guardrails exist so you can experiment freely without fear of destroying your work.
New to the project? Don't be intimidated by the technical intensity. We welcome contributors of all skill levels. If you have an idea for a new Payload or a better way to visualize data, jump in! Our Beginner's Guide and Contributing Guidelines are there to help you navigate the Kernel safely.
- For Hiring Managers: In-depth engineering audit and systems design breakdown.
- Vision & Philosophy: Deep dive into the architectural goals and problem space.
- Technical Architecture: High-level overview of the Control-Plane vs. Execution-Plane.
- Final Invariance Blueprint: Authoritative map of the distributed proof system and data flow.
- Triple-Lock Invariance: Details on the Layer 1-3 security model preventing hallucination.
- Epistemic Integrity: Third-order invariants preventing systemic self-deception and drift.
- Unity Freeze-Proof Guide: Canonical reference for preventing Editor and Runtime hangs.
- Non-Goals & Doctrine: The intentional limitations and philosophical guardrails of the project.
- Security Threat Acceptance: Formal definition of the boundary of responsibility and residual risks.
- Engineering Constraints: The strict technical rules governing all code generation.
- Failure Modes & Recovery: Taxonomy of system failures and recovery protocols.
- Contributing: Guidelines for extending the Kernel or adding new Payloads.
Copyright (C) 2026 B-A-M-N (The "Author")
This project is distributed under a Dual-Licensing Model. By using this software, you agree to be bound by the terms in the LICENSE file.
- THE OPEN-SOURCE PATH: GNU AGPLv3: Free for hobbyists and non-commercial research.
- THE COMMERCIAL PATH: "WORK-OR-PAY": For revenue-generating entities. Requires Significant Maintenance Contributions or a License Fee.
Full Privacy Policy | Security Mandates
Created by the Vibe Bridge Team.