---
name: unity-6-migration
description: Use this skill when upgrading a Unity 2021/2022/2023 project to Unity 6 (6000.3+) for AppMana cloud builds and GPU streaming or WebGL delivery.
---

# Upgrading Unity Projects to Unity 6 (`6000.3+`) for AppMana

Distilled from migrating 20+ production Unity projects (`unity-starter`, `the-heretic`, `battleblocks`, `wendysbasketball`, `oreoverse`, `virtualtestdrive`, `virtualrunways`, `dinkydiner`, `tennis-academy`, `holotable`, `lbxx`, `bonneville`, `fifawwc`) to Unity 6 (`6000.3.10f1` – `6000.6.8f1`).

## 1. `Packages/manifest.json` & `packages-lock.json`
1. **Replace standalone TextMeshPro with `com.unity.ugui` 2.0+**:
   - Remove `"com.unity.textmeshpro"` from `Packages/manifest.json`.
   - Set `"com.unity.ugui"` to `"2.0.0"` (Unity 6.3), `"2.5.0"` (Unity 6.5), or `"2.6.0"` (Unity 6.6).
2. **Add `com.appmana.unity.public` and Required Dependencies**:
   ```json
   {
     "scopedRegistries": [
       {
         "name": "OpenUPM",
         "url": "https://package.openupm.com",
         "scopes": ["com.cysharp", "com.neuecc"]
       }
     ],
     "dependencies": {
       "com.appmana.unity.public": "https://github.com/AppMana/appmana-unity-plugin.git#v3.0.5",
       "com.cysharp.unitask": "2.5.11",
       "com.neuecc.unirx": "7.1.0",
       "com.unity.inputsystem": "1.18.0",
       "com.unity.nuget.newtonsoft-json": "3.2.1",
       "com.unity.ugui": "2.0.0"
     }
   }
   ```
3. **HTTPS Git URLs Only**:
   - Replace any `git@github.com:org/repo.git` URL in `Packages/manifest.json` with `https://github.com/org/repo.git`.
4. **Clear Stale Lock Entries**:
   - Whenever changing a Git URL or tag in `Packages/manifest.json`, remove the corresponding entry from `Packages/packages-lock.json` so Unity resolves the new tag.

## 2. Player Settings (`ProjectSettings/ProjectSettings.asset`)
- **Active Input Handling**: Set `activeInputHandler: 1` (**Input System Package (New)** exclusively, never `0` or `2` / `Both`).
- **Windows Graphics APIs (`StandaloneWindows64`)**: Disable Auto Graphics API (`m_Automatic: 0`) and include both `Direct3D11` (`02000000`) and `Direct3D12` (`12000000`) so D3D12 compute shaders and NVENC external memory paths compile.
- **Linux Graphics APIs (`StandaloneLinux64`)**: Disable Auto Graphics API (`m_Automatic: 0`) and set `Vulkan` (`15000000`) first.

## 3. Common C# API Fixes for Unity 6
- `rigidbody.velocity` -> `rigidbody.linearVelocity`
- `PhysicMaterial` -> `PhysicsMaterial`
- `Object.FindObjectsOfType<T>(true)` -> `Object.FindObjectsByType<T>(FindObjectsInactive.Include, FindObjectsSortMode.None)`
- `Object.GetInstanceID()` (obsolete error in Unity 6.5+) -> `Object.GetEntityId()` (and ensure `com.cysharp.unitask` is `>= 2.5.11`)
- `tmpText.enableWordWrapping = true` -> `tmpText.textWrappingMode = TextWrappingModes.Normal`

## 4. Cinemachine 2.x vs 3.x
- `AppMana.InteractionToolkit.CinemachinePressableInputProvider` supports both Cinemachine 2.x (`CinemachineVirtualCamera`) and Cinemachine 3.x (`Unity.Cinemachine.CinemachineCamera`).
- On Unity 6000.6+, Unity substitutes registry `com.unity.cinemachine` 2.x with 3.x unless pinned via a local tarball (`"com.unity.cinemachine": "file:com.unity.cinemachine-2.10.7.tgz"`) or embedded under `Packages/`.

## 5. HDRP 17.x & Linux Batchmode Guards
- **HDRP Custom Passes**: Every `CustomPass` subclass serialized via `[SerializeReference]` on a `CustomPassVolume` **must** carry `[System.Serializable]` and use `UnityEngine.Rendering.RenderGraphModule.TextureHandle` in `Execute(CustomPassContext ctx)`.
- **Linux Vulkan `ShaderVariantCollection.WarmUp()`**: Guard all `ShaderVariantCollection.WarmUp()` calls with `if (!Application.isBatchMode)` because headless Vulkan has no onscreen swapchain during batchmode startup.
- **Case-Sensitive Git LFS (`.gitattributes`)**: Ensure `.gitattributes` includes both lowercase and uppercase patterns (`*.fbx` and `*.FBX`, `*.tga` and `*.TGA`, `*.png` and `*.PNG`, `*.exr` and `*.EXR`, `*.wav` and `*.WAV`, `*.psd` and `*.PSD`).
