convez.ai
MCP Server
pokelege

UnityRuntimeMCP

pokelege/UnityRuntimeMCP

Ver no GitHub
InicialPluginScore · de 0 a 100

UnityRuntimeMCP is an implementation of the Model Context Protocol (MCP) as a BepInEx 6 plugin for Unity IL2CPP games. It enables external AI agents to interact with the game runtime via reflection-based tools.

Instalação

$npx convez-ai pokelege/UnityRuntimeMCP

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v1.0.5
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

UnityRuntimeMCP

UnityRuntimeMCP is an implementation of the Model Context Protocol (MCP) as a BepInEx 6 plugin for Unity IL2CPP games. It enables external AI agents to interact with the game runtime via reflection-based tools.

Features

  • Live Inspection & Object Caching: Discovery and inspection of Unity GameObject/Component instances, as well as non-Unity reference types (classes and arrays).
  • Stable Identity Mapping: Maintains a weak-reference cache of all encountered Unity Objects and non-Unity reference types. Non-Unity objects are assigned dynamic IDs starting at 1,000,000,000 to guarantee reference stability across frames.
  • Deep Reflection & Serialization: Access to fields, properties, and methods on derived types in IL2CPP environments. Automatically serializes collections and arrays up to 20 elements, caching nested non-Unity objects for further inspection.
  • Runtime Modification: Reading and writing values to object fields and properties with support for nested dot-notation paths.
  • Visual Feedback: Capture of game view screenshots in Base64 PNG format or saved to a cross-platform temporary directory.
  • Thread Safety: Automatic dispatching of Unity API calls to the main thread.
  • Lifecycle Management: Protection against scene cleanup and IL2CPP-specific object destruction.

Provided Tools

The server registers the following MCP tools:

ToolDescription
find_objectsFinds active GameObjects by class name. Returns identity objects with instance_id. Returns an empty list if the class is missing.
get_hierarchyReturns immediate parent and children IDs for Unity GameObjects/Components. Restricted to Unity objects.
inspect_objectDetailed member view. Supports Unity and cached non-Unity objects. include_methods defaults to false for efficiency.
read_fieldReads a value. Supports dot-notation paths (e.g., transform.parent.name). Returns null for broken paths.
write_fieldWrites a value. Supports nested paths. Suggests preferring property setters over private backing fields to ensure side-effects execute.
invoke_methodExecutes a method on Unity or cached non-Unity objects. Supports generic methods via type_args.
take_screenshotCaptures the game screen. Supports scale (0.1 to 1.0, default 0.5) and save_to_file (boolean). Uses a stable custom pipeline to avoid IL2CPP native JPG crash.

Feature Highlights

  • Identity Mapping & Cache: The server maintains a weak-reference cache of all encountered Unity Objects and non-Unity reference types (assigned dynamic IDs >= 1,000,000,000). This ensures that instance_id references remain stable across frames, even for objects that are inactive or difficult to locate via standard searches.
  • Robust Path Traversal: Dot-notation support in read_field and write_field allows for deep inspection in a single call. The system handles null segments gracefully, returning standard JSON null instead of errors.
  • Generic Method Resolution: Agents can invoke generic Unity methods by providing type_args (a list of full type names), enabling advanced operations like GetComponent<TextMeshProUGUI>().
  • Custom Screenshot Engine: Avoids native IL2CPP AccessViolationException crashes by bypassing the native EncodeToJPG delegate. Instead, it blits the native screen buffer to a scaled RenderTexture and encodes it to a PNG. Scaled output reduces payload size, and setting save_to_file saves directly to the system temp directory (C:\Users\Public\UnityRuntimeMCP_Temp on Windows, /tmp/UnityRuntimeMCP_Temp on macOS/Linux).

Installation

  1. Install BepInEx 6 (IL2CPP) in the target game.
  2. Place UnityRuntimeMCP.dll in the BepInEx/plugins directory.
  3. Launch the game; the MCP server initializes on the configured port.

Configuration

Configuration is managed via BepInEx/config/me.pokelege.unityruntimemcp.cfg:

  • Port: Server listening port (Default: 3000).
  • Host: Server binding address (Default: 127.0.0.1).

Building

If you are not using a pre-built release, you can build the plugin from source:

Prerequisites

  • .NET 6.0 SDK
  • Unity game assemblies placed in the libs/ directory (these are already included in the repository for reference).

Build Commands

To build the project, run one of the following commands in the project root:

  • Debug Build:

    dotnet build
    

    The compiled DLL will be located at bin/Debug/net6.0/UnityRuntimeMCP.dll.

  • Release Build:

    dotnet build -c Release
    

    The compiled DLL will be located at bin/Release/net6.0/UnityRuntimeMCP.dll.

Connection

The server utilizes HTTP/SSE transport.

Client Configuration

MCP clients should connect to the following endpoint: http://127.0.0.1:3000/mcp

Technical Specifications

  • Protocol: JSON-RPC 2.0 over Server-Sent Events (SSE).
  • Initialization: Requires standard MCP initialize handshake.
  • Session Management: Supports request ID tracking for JSON-RPC compliance.

Technical Architecture

  • Main Thread Dispatcher: A persistent MonoBehaviour managing a thread-safe execution queue.
  • IL2CPP Bridge: Custom type resolution mapping IL2CPP internal types to managed System.Type for reflection accuracy.
  • Modular Design: Tool implementations are decoupled for extensibility.

Prohibited Use

This software is provided for research and development purposes. Use of this software to facilitate cheating in multiplayer or online games is strictly prohibited. Users assume all risk regarding detection by anti-cheat systems and subsequent account actions.

License

This project is licensed under the GNU Lesser General Public License v2.1. See the LICENSE file for the full license text and disclaimer.

Ver o original no GitHub

Relacionados