Unity MCP UnityCompatShims: Cross-Version Unity API Compatibility Layer

Unity MCP UnityCompatShims provide a centralized compatibility layer that isolates version-specific Unity API changes, allowing the Model Context Protocol bridge to run seamlessly across Unity 2021 LTS through Unity 6.x CoreCLR without CS0618 warnings or runtime crashes.

The CoplayDev/unity-mcp repository solves Unity's API fragmentation problem through a dedicated shim architecture. Instead of scattering conditional compilation directives throughout the codebase, the project centralizes all version-specific logic in helper classes under MCPForUnity/Runtime/Helpers, with UnityCompatShims.cs serving as the navigational anchor and policy documentation hub.

What Are Unity MCP UnityCompatShims?

UnityCompatShims.cs is an empty marker class whose sole purpose is to document the active shims, establish policies for adding new ones, and define implementation patterns. According to the source code (lines 10-22), shims should only be added when an API is marked [Obsolete] and cannot simply be removed, excluding hot-path engine APIs and undocumented editor internals.

The shim layer prevents CS0618 and CS0619 warnings from breaking CI builds while ensuring the same compiled binary runs on Unity 2021.3, 2022.3, or Unity 6.8 CoreCLR without modification.

Version Compatibility Shims Covered

UnityFindObjectsCompat

The UnityFindObjectsCompat.cs file handles the migration from Object.FindObjectsOfType and Object.FindObjectOfType to the modern Object.FindObjectsByType (introduced in Unity 2022.3) and Object.FindAnyObjectByType APIs.

For older Unity versions, the shim uses cached MethodInfo objects to invoke legacy APIs via reflection, avoiding obsolete warnings while maintaining functionality. The implementation provides a unified FindAll<T>() method that returns the appropriate collection regardless of the underlying Unity version.

UnityObjectIdCompat

UnityObjectIdCompat.cs manages Unity's transition from 32-bit int InstanceIDs to 64-bit EntityId values introduced in Unity 6.5. The shim converts between these formats while preserving the original int wire format for MCP communication.

It also handles the updated InstanceIDToObject API introduced in Unity 6.6, providing GetInstanceIDCompat() and InstanceIDToObjectCompat() methods that work across all supported editor versions.

UnityPhysicsCompat

The physics shim in UnityPhysicsCompat.cs bridges the gap between the deprecated Physics.autoSyncTransforms and Physics2D.autoSyncTransforms properties (removed in Unity 2022.2) and the new Physics.simulationMode enum. It maps the boolean auto-sync flags to the appropriate SimulationMode values automatically.

UnityAssembliesCompat

UnityAssembliesCompat.cs provides version-agnostic assembly enumeration, transitioning from AppDomain.GetAssemblies to UnityEngine.Assemblies.CurrentAssemblies for CoreCLR 6.8 compatibility. This ensures MCP tools can reflect over loaded assemblies regardless of whether running on Mono or CoreCLR runtimes.

Implementation Patterns and Architecture

The UnityCompatShims employ a three-tier strategy for handling API discrepancies:

1. Compile-time gating – When the new API is available, the code uses #if UNITY_XXXX_OR_NEWER blocks to call the new method directly, eliminating reflection overhead on current versions.

2. Runtime reflection fallback – For older SDKs, the shim caches MethodInfo objects (e.g., LegacyFindObjectsOfType) to invoke legacy APIs via reflection. This keeps the source free of obsolete warnings while maintaining backward compatibility.

3. Fail-soft semantics – If a reflected method is missing, the shim returns an empty array or null rather than throwing, enabling callers to treat the result as a no-op rather than crashing the editor.

Why UnityCompatShims Matter for MCP Development

Without this abstraction layer, every tool calling Object.FindObjectsOfType would generate warnings on Unity 2022.3+ and compilation errors when the API is eventually removed. By funneling all version-specific calls through the shim layer, MCP avoids:

• CI build failures triggered by CS0618 warnings on newer Unity SDKs
• Frequent recompilation when Unity releases major versions—only the relevant shim file requires updates
• Runtime crashes on older editors where newer APIs do not exist

Core MCP tools such as ManageMaterial.cs and RefreshUnity.cs call UnityFindObjectsCompat.FindAll<T>() instead of directly invoking Unity APIs, guaranteeing consistent behavior across the entire version matrix.

Practical Usage Examples

using MCPForUnity.Runtime.Helpers;
using UnityEngine;

// Find every active Camera in a version-agnostic way
Camera[] cameras = UnityFindObjectsCompat.FindAll<Camera>();

// Resolve an InstanceID that may be an EntityId on newer Unity
int handle = someObject.GetInstanceIDCompat();

#if UNITY_EDITOR
Object obj = UnityObjectIdCompat.InstanceIDToObjectCompat(handle);
#endif

// Query physics simulation mode uniformly
#if UNITY_2022_2_OR_NEWER
Physics.simulationMode = SimulationMode.Script;
#else
Physics.autoSyncTransforms = false;   // shim translates internally
#endif

Summary

• UnityCompatShims.cs acts as the central catalog and policy document for all compatibility shims, located at MCPForUnity/Runtime/Helpers/UnityCompatShims.cs
• Four primary shims cover FindObjects APIs, Object IDs, Physics settings, and Assembly enumeration across Unity 2021 LTS to Unity 6.x
• Implementation uses compile-time gates for new SDKs and reflection fallbacks for legacy versions, with cached MethodInfo objects for performance
• Fail-soft semantics ensure graceful degradation when APIs are unavailable, returning empty collections rather than throwing exceptions
• Core MCP tools like ManageMaterial.cs rely on these shims to work across Unity 2021.3 through Unity 6.8 without version-specific branches

Frequently Asked Questions

What Unity versions do UnityCompatShims support?

The compatibility layer supports Unity 2021 LTS through Unity 6.x CoreCLR. It specifically handles breaking changes introduced in Unity 2022.2 (physics simulation mode), Unity 2022.3 (FindObjectsByType), Unity 6.5 (EntityId), and Unity 6.6 (InstanceIDToObject updates), ensuring the same MCP bridge binary runs across all these versions.

Why not just use #if directives everywhere instead of UnityCompatShims?

Centralizing compatibility logic prevents code duplication and makes version-specific behavior testable. According to the policy documented in UnityCompatShims.cs (lines 10-22), scattering #if UNITY_* directives throughout business logic would clutter the codebase and make CI maintenance impossible, as every new Unity version would require updating dozens of files rather than a single shim implementation.

How do UnityCompatShims handle APIs that don't exist in older Unity versions?

They use cached MethodInfo reflection to invoke legacy APIs at runtime. For example, UnityFindObjectsCompat.cs caches the legacy FindObjectsOfType method and invokes it via reflection when running on Unity 2021.3, while using direct calls on Unity 2022.3+. If the reflected method is missing, the shim returns an empty array or null for fail-soft behavior rather than throwing MissingMethodException, ensuring the MCP bridge remains stable.

Which MCP tools specifically use these compatibility shims?

Core tools such as ManageMaterial.cs and RefreshUnity.cs call UnityFindObjectsCompat.FindAll<T>() instead of directly invoking Object.FindObjectsOfType<T>(). This abstraction guarantees that asset management and scene refresh operations work identically whether the Unity editor is version 2021.3, 2022.3, or 6.8 CoreCLR.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}