# Unity MCP UnityCompatShims: Cross-Version Unity API Compatibility Layer

> Ensure seamless Model Context Protocol operation across Unity 2021 LTS to Unity 6.x CoreCLR with Unity MCP UnityCompatShims.  Avoid CS0618 warnings and crashes with this compatibility layer.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: internals
- Published: 2026-07-06

---

**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`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityCompatShims.cs) serving as the navigational anchor and policy documentation hub.

## What Are Unity MCP UnityCompatShims?

[`UnityCompatShims.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/ManageMaterial.cs) and [`RefreshUnity.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/RefreshUnity.cs) call `UnityFindObjectsCompat.FindAll<T>()` instead of directly invoking Unity APIs, guaranteeing consistent behavior across the entire version matrix.

## Practical Usage Examples

```csharp
using MCPForUnity.Runtime.Helpers;
using UnityEngine;

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

```

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

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

```

```csharp
// 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`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityCompatShims.cs)** acts as the central catalog and policy document for all compatibility shims, located at [`MCPForUnity/Runtime/Helpers/UnityCompatShims.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/ManageMaterial.cs) and [`RefreshUnity.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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.