/unity-version-split

name: unity-version-split
description: "Split a C# file into Unity 6.5+ and pre-Unity 6.5 variants. Use when a file needs different implementations for different Unity versions due to API changes (e.g., EntityId vs int, GetEntityId vs GetInstanceID)."
argument-hint: "[path to the .cs file that needs splitting]"

Unity Version Split

Split a C# source file into two variants: one for Unity 6.5+ (`UNITY_6000_5_OR_NEWER`) and one for older versions (pre-Unity 6.5).

When to Use

Unity 6.5 introduced breaking changes including:

• `EntityId` replaces `int` for instance IDs (`GetEntityId()` replaces `GetInstanceID()`)
• `EditorUtility.EntityIdToObject(EntityId)` replaces `EditorUtility.InstanceIDToObject(int)`
• Implicit `EntityId <-> int` conversions are marked `[Obsolete(..., true)]` (compile error)

When a file needs different code for these Unity versions, split it into two files following the project convention.

File Naming Convention

| File | Purpose | Preprocessor Guard | |---|---|---| | `FileName.cs` | Unity 6.5+ (newer version) | `#if UNITY_6000_5_OR_NEWER` | | `FileName.pre-Unity.6.5.cs` | Pre-Unity 6.5 (older version) | `#if !UNITY_6000_5_OR_NEWER` |

For files that also have Editor/Runtime variants, combine the guards: | File | Guard | |---|---| | `FileName.Editor.cs` | `#if UNITY_EDITOR && UNITY_6000_5_OR_NEWER` | | `FileName.Editor.pre-Unity.6.5.cs` | `#if UNITY_EDITOR && !UNITY_6000_5_OR_NEWER` | | `FileName.Runtime.cs` | `#if !UNITY_EDITOR && UNITY_6000_5_OR_NEWER` | | `FileName.Runtime.pre-Unity.6.5.cs` | `#if !UNITY_EDITOR && !UNITY_6000_5_OR_NEWER` |

Step-by-Step Process

Step 1 — Read the Source File

Read `$ARGUMENTS` (the target file path). Identify which parts need version-specific code.

Step 2 — Identify the Split Points

Common differences between Unity 6.5+ and pre-6.5:

| Unity 6.5+ | Pre-Unity 6.5 | |---|---| | `EntityId` | `int` | | `EntityId.None` | `0` | | `go.GetEntityId()` | `go.GetInstanceID()` | | `EditorUtility.EntityIdToObject(entityId)` | `EditorUtility.InstanceIDToObject(instanceID)` | | `ObjectRef.InstanceID` is `EntityId` | `ObjectRef.InstanceID` is `int?` |

Step 3 — Create the Two Files

1. **Update the original `.cs` file** to contain only the Unity 6.5+ version:

• Set the preprocessor guard to include `UNITY_6000_5_OR_NEWER`
• Use `EntityId`, `GetEntityId()`, etc.

2. **Create the `.pre-Unity.6.5.cs` file** with the pre-6.5 version:

• Set the preprocessor guard to include `!UNITY_6000_5_OR_NEWER`
• Use `int`, `GetInstanceID()`, etc.

Both files must:

• Start with `#nullable enable`
• Have the same copyright header as the original
• Use the same namespace and class name (partial classes)
• End with `#endif` matching the opening `#if`

Step 4 — Refresh Assets

Run `assets-refresh` tool to let Unity generate `.meta` files and recompile.

**IMPORTANT: Do NOT manually create `.meta` files.** Unity auto-generates them after `assets-refresh` or any AssetDatabase.Refresh() call.

Step 5 — Verify

Check for compilation errors using `console-get-logs` tool.

Example

Given `GameObjectUtils.Runtime.cs` with `#if !UNITY_EDITOR` that uses both `EntityId` and `int` with `#if UNITY_6000_5_OR_NEWER` inside:

**Before (single file with nested #if):**

#if !UNITY_EDITOR
// ...
#if UNITY_6000_5_OR_NEWER
        public static GameObject? FindByInstanceID(EntityId instanceID) { ... }
#else
        public static GameObject? FindByInstanceID(int instanceID) { ... }
#endif
#endif

**After (two clean files):**

`GameObjectUtils.Runtime.cs`:

#if !UNITY_EDITOR && UNITY_6000_5_OR_NEWER
// ...
        public static GameObject? FindByInstanceID(EntityId instanceID) { ... }
#endif

`GameObjectUtils.Runtime.pre-Unity.6.5.cs`:

#if !UNITY_EDITOR && !UNITY_6000_5_OR_NEWER
// ...
        public static GameObject? FindByInstanceID(int instanceID) { ... }
#endif

Reference Files

Existing examples of this pattern in the codebase:

• `Runtime/Data/ObjectRef.cs` / `ObjectRef.pre-Unity.6.5.cs`
• `Runtime/Data/GameObjectRef.cs` / `GameObjectRef.pre-Unity.6.5.cs`
• `Runtime/Utils/GameObjectUtils.Editor.cs` / `GameObjectUtils.Editor.pre-Unity.6.5.cs`
• `Tests/Editor/Tool/Assets/AssetsPrefabCreateTests.cs` / `AssetsPrefabCreateTests.pre-Unity.6.5.cs`