Upgrading to Unity 6 & Input Setup

Proven patterns, camera/canvas hierarchies, PerUserGraphicRaycaster setup, and Input System examples from migrating 20+ production projects to Unity 6.

This guide distills the engineering patterns used across 20+ production Unity projects migrated to Unity 6 (6000.3+) on AppMana—covering package setup, Unity 6 API migrations, single-player and multiplayer camera/canvas hierarchies, PerUserGraphicRaycaster, and Input System action wiring.

Coding agents can also load the standalone skills directly from /skills/unity-6-migration/SKILL.md and /skills/appmana-plugin-and-input/SKILL.md.


1. Packages/manifest.json & Unity 6 Package Upgrades

Replace Standalone TextMeshPro with com.unity.ugui 2.0+

In Unity 6, com.unity.textmeshpro is merged into com.unity.ugui (2.0.0 in Unity 6.3, 2.5.0 in Unity 6.5, 2.6.0 in Unity 6.6). Remove "com.unity.textmeshpro" from Packages/manifest.json and install "com.appmana.unity.public" via appmana unity install . --public-only or by editing Packages/manifest.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"
  }
}

Critical UPM Rules

  1. HTTPS Git URLs Only: Never use git@github.com:... SSH URLs in Packages/manifest.json; cloud builders authenticate over HTTPS.
  2. Clear Stale packages-lock.json Entries: Whenever you update a #tag or commit SHA on a Git dependency in Packages/manifest.json, delete the matching entry in Packages/packages-lock.json so Unity does not stay pinned to the old commit hash.
  3. Case-Sensitive .gitattributes for Linux Builders: Ensure .gitattributes lists both lowercase and uppercase extensions (*.fbx and *.FBX, *.tga and *.TGA, *.png and *.PNG, *.exr and *.EXR, *.wav and *.WAV, *.psd and *.PSD).

2. Unity 6 C# API & Graphics Migration Checklist

Across our Unity 6 (6000.3 – 6000.6) migrations, these are the most common API and project-setting updates required:

Legacy API / Setting Unity 6 Replacement
rigidbody.velocity rigidbody.linearVelocity
PhysicMaterial PhysicsMaterial
Object.FindObjectsOfType<T>(true) Object.FindObjectsByType<T>(FindObjectsInactive.Include, FindObjectsSortMode.None)
Object.GetInstanceID() (error in 6.5+) Object.GetEntityId() (and upgrade com.cysharp.unitask to 2.5.11+)
tmpText.enableWordWrapping = true tmpText.textWrappingMode = TextWrappingModes.Normal
TMP_InputField AppMana.UI.TMPro.TMP_InputSystemInputField (+ InputSystemTMPInputFieldModule on player root)
activeInputHandler: 0 or 2 (Both) activeInputHandler: 1 (Input System Package (New) exclusively)
Windows Graphics APIs (StandaloneWindows64) Disable Auto Graphics API (m_Automatic: 0) and include both Direct3D11 and Direct3D12
Linux Graphics APIs (StandaloneLinux64) Disable Auto Graphics API (m_Automatic: 0) and place Vulkan first

HDRP 17.x & Linux Batchmode Guards

  • HDRP [SerializeReference] Custom Passes: Any CustomPass subclass serialized on a CustomPassVolume must be annotated with [System.Serializable] and use UnityEngine.Rendering.RenderGraphModule.TextureHandle in Execute(CustomPassContext ctx).
  • Guard ShaderVariantCollection.WarmUp() on Linux: Headless Vulkan has no swapchain during -batchmode startup; guard WarmUp() calls with if (!Application.isBatchMode).
  • Cinemachine 2.x vs 3.x: AppMana.InteractionToolkit.CinemachinePressableInputProvider supports both Cinemachine 2.x (CinemachineVirtualCamera) and Cinemachine 3.x (Unity.Cinemachine.CinemachineCamera). If keeping Cinemachine 2.x scripts on Unity 6000.6+, pin com.unity.cinemachine via a local tarball (file:com.unity.cinemachine-2.10.7.tgz) or embedded package so Unity does not replace it with 3.x.

3. Camera, Canvas & RemotePlayableConfiguration Hierarchy

In AppMana, each streamable player slot in a scene is rooted at an active GameObject with RemotePlayableConfiguration (AppManaPublic.Configuration.RemotePlayableConfiguration).

Single-Player Hierarchy

Scene Root
├── Player
│   ├── Components:
│   │   ├── RemotePlayableConfiguration
│   │   │   ├── m_Camera -> Player/Camera
│   │   │   ├── m_AudioListener -> Player/Camera (AudioListener)
│   │   │   ├── m_Actions -> Input Actions (Packages/com.appmana.unity.public/AppManaPublic/Input Actions.inputactions)
│   │   │   └── m_CanvasScalers -> [Player/Camera/Canvas (CanvasScaler)]
│   │   └── InputSystemTMPInputFieldModule (required if using TMP_InputSystemInputField)
│   └── Camera (Tag: MainCamera)
│       ├── Components:
│       │   ├── Camera (targetDisplay: 0)
│       │   ├── AudioListener
│       │   ├── UniversalAdditionalCameraData (URP) or HDAdditionalCameraData (HDRP)
│       │   ├── CinemachineBrain (if using Cinemachine)
│       │   └── PerUserPhysicsRaycaster (AppMana.Multiplayer.PerUserPhysicsRaycaster)
│       │       └── m_RemotePlayableConfiguration -> Player
│       └── Canvas
│           ├── Components:
│           │   ├── Canvas (RenderMode: ScreenSpaceCamera, worldCamera: Player/Camera, planeDistance: 10)
│           │   ├── CanvasScaler (uiScaleMode: ConstantPhysicalSize or ScaleWithScreenSize)
│           │   └── PerUserGraphicRaycaster (AppMana.Multiplayer.PerUserGraphicRaycaster)
│           │       └── m_RemotePlayableConfiguration -> Player
│           └── [UI Elements: Buttons, TMP_InputSystemInputField, HUD]
├── vCams
│   └── Orbiting Camera
│       ├── CinemachineVirtualCamera
│       └── CinemachinePressableInputProvider
│           ├── XYAxis -> Input Actions (UI/Delta)
│           ├── m_EnableWhenPressed -> Input Actions (UI/Click)
│           └── m_RemotePlayableConfiguration -> Player
└── Event System
    ├── EventSystem
    └── InputSystemUIInputModule
        ├── m_ActionsAsset -> Input Actions (Packages/com.appmana.unity.public/AppManaPublic/Input Actions.inputactions)
        └── m_PointerBehavior -> AllPointersAsIs (2)

Local-to-Networked Multiplayer Hierarchy (2+ Players in One Scene)

To make a local multiplayer game playable over the web by multiple remote browsers simultaneously, place two or more player prefab instances in your scene on separate layers (Player 1 on Layer 6, Player 2 on Layer 7):

Scene Root
├── Player 1 (Layer: 6 "Player 1")
│   ├── RemotePlayableConfiguration (m_Camera -> Player 1/Camera, m_CanvasScalers -> [Player 1/Camera/Canvas])
│   ├── vCams (Layer: 6) -> [CinemachineVirtualCamera (Layer: 6)]
│   ├── Camera (Layer: 6, targetDisplay: 0, cullingMask: Default | Player 1, excludes Layer 7 "Player 2")
│   │   ├── PerUserPhysicsRaycaster (m_EventMask: Default | Player 1, m_RemotePlayableConfiguration -> Player 1)
│   │   └── Canvas (Layer: 6, RenderMode: ScreenSpaceCamera, worldCamera: Player 1/Camera)
│   │       ├── CanvasScaler (ConstantPhysicalSize)
│   │       └── PerUserGraphicRaycaster (m_RemotePlayableConfiguration -> Player 1)
│   └── Event System (Layer: 6)
│       ├── MultiplayerEventSystem
│       └── InputSystemUIInputModule (m_PointerBehavior: AllPointersAsIs, m_ActionsAsset -> Input Actions)
│
└── Player 2 (Layer: 7 "Player 2")
    ├── RemotePlayableConfiguration (m_Camera -> Player 2/Camera, m_CanvasScalers -> [Player 2/Camera/Canvas])
    ├── vCams (Layer: 7) -> [CinemachineVirtualCamera (Layer: 7)]
    ├── Camera (Layer: 7, targetDisplay: 1, cullingMask: Default | Player 2, excludes Layer 6 "Player 1")
    │   ├── PerUserPhysicsRaycaster (m_EventMask: Default | Player 2, m_RemotePlayableConfiguration -> Player 2)
    │   └── Canvas (Layer: 7, RenderMode: ScreenSpaceCamera, worldCamera: Player 2/Camera)
    │       ├── CanvasScaler (ConstantPhysicalSize)
    │       └── PerUserGraphicRaycaster (m_RemotePlayableConfiguration -> Player 2)
    └── Event System (Layer: 7)
        ├── MultiplayerEventSystem
        └── InputSystemUIInputModule (m_PointerBehavior: AllPointersAsIs, m_ActionsAsset -> Input Actions)

4. Per-User UI & Physics Raycasting (PerUserGraphicRaycaster & PerUserPhysicsRaycaster)

Why Standard Raycasters Fail in Streamed & Multi-User Scenes

  1. No ScreenSpaceOverlay Canvases: AppMana encodes video directly from RemotePlayableConfiguration.camera's RenderTexture. Canvases set to ScreenSpaceOverlay are not rendered into a camera's RenderTexture. Always set Canvas.renderMode = RenderMode.ScreenSpaceCamera and assign Canvas.worldCamera = playerCamera.
  2. Device-to-Player Filtering: Unity's InputSystemUIInputModule emits ExtendedPointerEventData carrying the InputDevice that triggered the pointer event, but standard GraphicRaycaster and PhysicsRaycaster do not filter by which InputUser owns that device—and Unity's built-in GraphicRaycaster fails in player builds when camera.targetDisplay != 0.

How PerUserGraphicRaycaster and PerUserPhysicsRaycaster Work

  • AppMana.Multiplayer.PerUserGraphicRaycaster (placed on every Canvas instead of GraphicRaycaster)
  • AppMana.Multiplayer.PerUserPhysicsRaycaster / PerUserPhysics2DRaycaster (placed on every player Camera instead of PhysicsRaycaster / Physics2DRaycaster)

Each component holds a reference to its player's RemotePlayableConfiguration (auto-resolved in Start() from parent/children if left unassigned). During Raycast(PointerEventData eventData, List<RaycastResult> resultAppendList):

  1. It checks eventData as ExtendedPointerEventData and looks up InputUser.FindUserPairedToDevice(extendedPointerEventData.device).
  2. If remotePlayableConfiguration.user != user, it returns immediately with zero hits so Player 2's clicks never trigger Player 1's UI or 3D objects.
  3. In the Editor, it synchronizes Display.m_ActiveEditorGameViewTarget with camera.targetDisplay so multi-display Game Views raycast accurately; in built players, it forces camera.targetDisplay = 0 to work around Unity's multi-display GraphicRaycaster bug.

5. Wiring Input System Actions in C# (Code Examples)

Pattern 1: Drop-in Legacy Input, Screen, and PlayerPrefs Compatibility

For existing single-player scripts that call Input.GetKey, Input.GetMouseButton, Input.GetAxis, Input.mousePosition, Screen.width, or PlayerPrefs, add type aliases at the top of each file:

using Input = AppMana.Compatibility.Input;
using Screen = AppMana.Compatibility.Screen;
using PlayerPrefs = AppMana.Compatibility.PlayerPrefs;

If you read Keyboard.current directly in custom code, always guard with if (Keyboard.current != null) because headless containers start before a remote keyboard device is paired.

Pattern 2: Subscribing to RemotePlayableConfiguration.actions in Start()

In RemotePlayableConfiguration.Awake(), AppMana clones m_Actions (Instantiate(m_Actions)) for each player and binds that clone to the player's isolated virtual devices (MouseRemoteForPlayer{i}, KeyboardRemoteForPlayer{i}, TouchscreenRemoteForPlayer{i}, GamepadRemoteForPlayer{i}).

Always resolve actions from m_Player.actions in Start() (after Awake() has created the per-player clone), and start gameplay in m_Player.onPlayerConnected:

using AppManaPublic.Configuration;
using UnityEngine;
using UnityEngine.InputSystem;

public class PlayerAimAndFire : MonoBehaviour
{
    [SerializeField] private RemotePlayableConfiguration m_Player;
    private InputAction m_PointAction;
    private InputAction m_ClickAction;
    private InputAction m_DeltaAction;

    private void Start()
    {
        m_Player ??= GetComponentInParent<RemotePlayableConfiguration>();

        // Retrieve actions from the player's cloned InputActionAsset in Start()
        m_PointAction = m_Player.actions.FindAction("UI/Point");
        m_ClickAction = m_Player.actions.FindAction("UI/Click");
        m_DeltaAction = m_Player.actions.FindAction("UI/Delta");

        m_ClickAction.performed += OnClickPerformed;
        m_Player.onPlayerConnected.AddListener(OnPlayerConnected);
    }

    private void OnDestroy()
    {
        if (m_ClickAction != null)
        {
            m_ClickAction.performed -= OnClickPerformed;
        }
        if (m_Player != null)
        {
            m_Player.onPlayerConnected.RemoveListener(OnPlayerConnected);
        }
    }

    private void OnPlayerConnected()
    {
        // Containers pre-warm in Start() before a viewer connects.
        // Start intro sequences, timers, or audio here.
    }

    private void OnClickPerformed(InputAction.CallbackContext context)
    {
        if (!context.ReadValueAsButton()) return;

        Vector2 screenPosition = m_PointAction.ReadValue<Vector2>();
        Ray ray = m_Player.camera.ScreenPointToRay(screenPosition);
        if (Physics.Raycast(ray, out RaycastHit hit))
        {
            Debug.Log($"Player clicked {hit.collider.name} at {hit.point}");
        }
    }
}

Pattern 3: Using MultiplayerInputActionReference or IHasInputActionReferences

If your MonoBehaviour exposes serialized InputActionReference fields in the Inspector, raw InputActionReference.action points at the shared asset on disk rather than the player's runtime clone. Use MultiplayerInputActionReference or implement IHasInputActionReferences so RemotePlayableConfiguration.Awake() automatically rebinds and enables your references for that player:

using AppMana.ComponentModel;
using UnityEngine;
using UnityEngine.InputSystem;

public class CharacterControllerInput : MonoBehaviour, IHasInputActionReferences
{
    [SerializeField] private InputActionReference m_MoveAction;
    [SerializeField] private InputActionReference m_JumpAction;

    public IHasInputActionReferences.InputActionReferenceProperty[] inputActionReferenceProperties => new[]
    {
        new IHasInputActionReferences.InputActionReferenceProperty(
            () => m_MoveAction,
            value => m_MoveAction = value),
        new IHasInputActionReferences.InputActionReferenceProperty(
            () => m_JumpAction,
            value => m_JumpAction = value),
    };

    private void Update()
    {
        Vector2 move = m_MoveAction.action.ReadValue<Vector2>();
        if (m_JumpAction.action.WasPressedThisFrame())
        {
            // Jump
        }
    }
}

Pattern 4: 3D World Clicking & Dragging via EventSystem + PerUserPhysicsRaycaster

With PerUserPhysicsRaycaster attached to the player's Camera, any 3D GameObject with a Collider can implement IPointerClickHandler, IPointerDownHandler, IDragHandler, and IPointerUpHandler—working identically for desktop mouse and mobile touch and isolated per player:

using UnityEngine;
using UnityEngine.EventSystems;
using UnityEngine.InputSystem.UI;

public class DraggableBoardPiece : UIBehaviour, IPointerDownHandler, IDragHandler, IPointerUpHandler
{
    public void OnPointerDown(PointerEventData eventData)
    {
        if (eventData is ExtendedPointerEventData extended)
        {
            Debug.Log($"Picked up by device {extended.device}");
        }
    }

    public void OnDrag(PointerEventData eventData)
    {
        if (eventData.pointerCurrentRaycast.isValid)
        {
            transform.position = eventData.pointerCurrentRaycast.worldPosition;
        }
    }

    public void OnPointerUp(PointerEventData eventData) { }
}