---
name: appmana-plugin-and-input
description: Use this skill when installing the AppMana Unity Plugin, setting up RemotePlayableConfiguration and the Camera/Canvas hierarchy, configuring PerUserGraphicRaycaster and PerUserPhysicsRaycaster, or wiring Unity Input System actions for single-player and multiplayer streaming.
---

# AppMana Plugin, Camera Hierarchy, `PerUserGraphicRaycaster` & Input System Skill

## 1. Scene & Prefab Hierarchy (`RemotePlayableConfiguration`)
Every streamable player slot in a scene is represented by an active root GameObject with `RemotePlayableConfiguration` (`AppManaPublic.Configuration.RemotePlayableConfiguration`):

```text
Scene Root
├── Player 1 (Layer: "Player 1" for multiplayer, or "Default" for single-player)
│   ├── Components:
│   │   ├── RemotePlayableConfiguration
│   │   │   ├── m_Camera -> Player 1/Camera
│   │   │   ├── m_AudioListener -> Player 1/Camera (AudioListener)
│   │   │   ├── m_Actions -> Input Actions (Packages/com.appmana.unity.public/AppManaPublic/Input Actions.inputactions)
│   │   │   └── m_CanvasScalers -> [Player 1/Camera/Canvas (CanvasScaler)]
│   │   └── InputSystemTMPInputFieldModule (required if using TMP_InputSystemInputField)
│   ├── Camera (Tag: MainCamera)
│   │   ├── Components:
│   │   │   ├── Camera (cullingMask excludes other players' private UI layers)
│   │   │   ├── AudioListener
│   │   │   ├── UniversalAdditionalCameraData (URP) or HDAdditionalCameraData (HDRP)
│   │   │   ├── CinemachineBrain (optional)
│   │   │   └── PerUserPhysicsRaycaster (AppMana.Multiplayer.PerUserPhysicsRaycaster)
│   │   │       └── m_RemotePlayableConfiguration -> Player 1
│   │   └── Canvas
│   │       ├── Components:
│   │       │   ├── Canvas (RenderMode: ScreenSpaceCamera, worldCamera: Player 1/Camera, planeDistance: 10)
│   │       │   ├── CanvasScaler (uiScaleMode: ConstantPhysicalSize or ScaleWithScreenSize)
│   │       │   └── PerUserGraphicRaycaster (AppMana.Multiplayer.PerUserGraphicRaycaster)
│   │       │       └── m_RemotePlayableConfiguration -> Player 1
│   │       └── [UI Children: Buttons, TMP_InputSystemInputField, HUD]
│   └── Event System
│       ├── MultiplayerEventSystem (or EventSystem in single-player)
│       └── InputSystemUIInputModule
│           ├── m_ActionsAsset -> Input Actions (Packages/com.appmana.unity.public/AppManaPublic/Input Actions.inputactions)
│           └── m_PointerBehavior -> AllPointersAsIs (2)
└── Player 2 (for multiplayer: duplicate prefab on Layer "Player 2", targetDisplay: 1)
```

### Key Hierarchy Rules
1. **No `ScreenSpaceOverlay` Canvases**: Streamed cameras encode from `Camera.targetTexture` (`RenderTexture`). Always set `Canvas.renderMode = RenderMode.ScreenSpaceCamera` and assign `Canvas.worldCamera` to the player's `Camera`.
2. **Use `PerUserGraphicRaycaster` & `PerUserPhysicsRaycaster`**:
   - Attach `AppMana.Multiplayer.PerUserGraphicRaycaster` to each `Canvas` (replaces `GraphicRaycaster`) and wire `remotePlayableConfiguration`.
   - Attach `AppMana.Multiplayer.PerUserPhysicsRaycaster` (3D) or `PerUserPhysics2DRaycaster` (2D) to each player's `Camera` (replaces `PhysicsRaycaster`) and wire `remotePlayableConfiguration`.
   - These components inspect `ExtendedPointerEventData.device`, find the paired `InputUser`, and reject hits from other players' pointers.
3. **Replace `StandaloneInputModule` with `InputSystemUIInputModule`**:
   - Set `pointerBehavior` to `UIPointerBehavior.AllPointersAsIs` (`2`) and `actionsAsset` to `Packages/com.appmana.unity.public/AppManaPublic/Input Actions.inputactions`.
4. **Start Gameplay in `onPlayerConnected`**:
   - Streaming containers pre-warm in `Awake()`/`Start()` before a viewer joins. Hook intro animations, timers, and audio cues to `remotePlayableConfiguration.onPlayerConnected`.

## 2. Wiring Unity Input System Actions

### Option 1: Drop-in Compatibility (`AppMana.Compatibility`)
For rapid migration of legacy `UnityEngine.Input`, `UnityEngine.Screen`, and `UnityEngine.PlayerPrefs` code, add aliases at the top of each `.cs` file:
```csharp
using Input = AppMana.Compatibility.Input;
using Screen = AppMana.Compatibility.Screen;
using PlayerPrefs = AppMana.Compatibility.PlayerPrefs;
```

### Option 2: Reading Per-Player Cloned Actions (`RemotePlayableConfiguration.actions`)
`RemotePlayableConfiguration.Awake()` instantiates a per-player clone of `m_Actions` and pairs it to that player's virtual devices (`MouseRemoteForPlayer{i}`, `KeyboardRemoteForPlayer{i}`, `TouchscreenRemoteForPlayer{i}`, `GamepadRemoteForPlayer{i}`). Always resolve actions from `m_Player.actions` in `Start()` (after `Awake()`):
```csharp
using AppManaPublic.Configuration;
using UnityEngine;
using UnityEngine.InputSystem;

public class PlayerLookAndClick : 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>();
        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;
    }

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

    private void OnClickPerformed(InputAction.CallbackContext ctx)
    {
        if (!ctx.ReadValueAsButton()) return;
        Vector2 pointerPos = m_PointAction.ReadValue<Vector2>();
        Ray ray = m_Player.camera.ScreenPointToRay(pointerPos);
        if (Physics.Raycast(ray, out RaycastHit hit))
        {
            Debug.Log($"Clicked {hit.collider.name}");
        }
    }
}
```

### Option 3: `MultiplayerInputActionReference` & `IHasInputActionReferences`
When using inspector-assigned `InputActionReference` fields on components under a `RemotePlayableConfiguration`, either use `AppMana.InteractionToolkit.MultiplayerInputActionReference` or implement `AppMana.ComponentModel.IHasInputActionReferences` so `RemotePlayableConfiguration.Awake()` rewrites the references to the player's cloned `InputActionAsset` and enables them:
```csharp
using AppMana.ComponentModel;
using UnityEngine;
using UnityEngine.InputSystem;

public class PlayerMovement : MonoBehaviour, IHasInputActionReferences
{
    [SerializeField] private InputActionReference m_Move;
    [SerializeField] private InputActionReference m_Jump;

    public IHasInputActionReferences.InputActionReferenceProperty[] inputActionReferenceProperties => new[]
    {
        new IHasInputActionReferences.InputActionReferenceProperty(() => m_Move, v => m_Move = v),
        new IHasInputActionReferences.InputActionReferenceProperty(() => m_Jump, v => m_Jump = v),
    };

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

### Option 4: Text Input Fields (`TMP_InputSystemInputField`)
Replace `TMP_InputField` with `AppMana.UI.TMPro.TMP_InputSystemInputField` and attach `AppMana.UI.TMPro.InputSystemTMPInputFieldModule` to the `RemotePlayableConfiguration` root GameObject so virtual keyboard and clipboard events work across streamed sessions.
