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