# AppMana (`https://appmana.com`) > AppMana is a cloud platform for building, streaming (Windows DirectX 12 / DXR & Linux Vulkan GPU containers), and publishing (WebRTC streaming & WebGL) interactive Unity 6 experiences with sub-2-second load times and zero-netcode local-to-networked multiplayer. ## Documentation & Agent Skills Index - [Documentation Home](https://appmana.com/docs): Overview of the AppMana platform, workflows, and Unity plugin. - [Getting Started](https://appmana.com/docs/getting-started): Core concepts, features, and onboarding steps. - [AppMana CLI & llms.txt Guide](https://appmana.com/docs/cli-and-llms): Creating an account, authenticating, provisioning Git LFS, and building/deploying Streamed or WebGL projects with `appmana`. - [Upgrading to Unity 6, Plugin Installation & Input/Camera Setup](https://appmana.com/docs/unity-6-migration): Proven patterns from migrating 20+ production Unity projects to Unity 6 (`6000.3+`), wiring `RemotePlayableConfiguration`, camera/canvas hierarchies, `PerUserGraphicRaycaster`, and Unity Input System actions. - [Migrating Your Project](https://appmana.com/docs/migrating): Step-by-step Unity Editor setup for `RemotePlayableConfiguration` and multi-scene mitigations. - [Input to Input System Migration](https://appmana.com/docs/migrating-input): Using `AppMana.Compatibility.Input` and migrating legacy `UnityEngine.Input` calls. - [Unity Requirements and Limitations](https://appmana.com/docs/unity-requirements-and-limitations): Render pipelines, UPM HTTPS rules, canvas space, and runtime constraints. - [Linux and Windows Builds](https://appmana.com/docs/linux-windows-builds): Choosing between Windows (DirectX 11/12/DXR) and Linux (Vulkan) streaming targets. - [Linux Build Troubleshooting](https://appmana.com/docs/linux-troubleshooting): Case-sensitive `.gitattributes` for Git LFS, shader warmup guards, and Vulkan tips. - [Pricing](https://appmana.com/docs/pricing): Free Tier (WebGL), Streaming for Developers ($100/mo), and Streaming for Production ($3,000/mo). ### Downloadable Agent `SKILL.md` Files - [SKILL: AppMana CLI — Account Creation, Builds & Deployments](https://appmana.com/skills/appmana-cli/SKILL.md) - [SKILL: Upgrading Unity Projects to Unity 6 for AppMana](https://appmana.com/skills/unity-6-migration/SKILL.md) - [SKILL: AppMana Plugin, Camera Hierarchy, PerUserGraphicRaycaster & Input System](https://appmana.com/skills/appmana-plugin-and-input/SKILL.md) --- ## SKILL 1: Using the `appmana` CLI to Create an Account, Build & Deploy Streamed or WebGL Projects ### Overview `@appmana-public/cli` (`appmana`) drives the AppMana platform via `https://appmana.com/graphql` using OAuth 2.0 Device Authorization Grant + PKCE (`clientId: "appmana-cli"`). - **Config file**: `~/.config/appmana/config.yaml` (`endpoint`, `issuer`, `clientId`, `cluster`, `namespace`, `output`). Default cluster is `appmana-cluster-03`; default namespace is `user-`. - **Credentials file**: `~/.config/appmana/credentials.json` (mode `0600`, auto-refreshes within 60s of expiry). Override with `APPMANA_CREDENTIALS_FILE` or `APPMANA_TOKEN`. - **Exit codes**: `0` (OK), `1` (GraphQL/runtime error), `2` (usage / `BAD_USER_INPUT`), `3` (`UNAUTHENTICATED`), `4` (`FORBIDDEN`), `6` (network unavailable). ### 1. Create an Account (Browserless / Agent-Friendly) or Log In Agents can register a brand-new account without a browser using `appmana account create`, which completes Keycloak self-registration, approves its own device code, stores credentials, and files an access request: ```bash umask 077 && printf '%s\n' "$PASSWORD" > ~/.config/appmana/account.password appmana account create \ --email dev@example.com \ --first-name Dev \ --last-name User \ --password-file ~/.config/appmana/account.password \ --accept-terms \ --verification-link-file /tmp/appmana-verify.url ``` For existing accounts, use interactive device login: ```bash appmana login appmana whoami --remote appmana accounts status appmana accounts request-access ``` ### 2. Install the AppMana Unity Plugin & Provision Git LFS Inside the Unity project root (where `Packages/manifest.json` lives): ```bash # Add OpenUPM scoped registry (UniTask, UniRx) and com.appmana.unity.public to Packages/manifest.json appmana unity install . --public-only # Provision unlimited Git LFS on lfs.appmana.com and merge .lfsconfig into your branch appmana lfs provision ``` LFS provisioning resumes in the same terminal after GitHub approval. If asked, link your account or select the requested repositories for the AppMana GitHub App. For multiple repositories, select them together in GitHub. In an agent terminal use `appmana lfs provision --no-browser` and present the printed approval link. The operator commits .lfsconfig. Push your project history when you are ready. ### File-first project setup From a GitHub checkout, create the settings file, publish it on the branch AppMana should track, then enroll the repository. ```bash gh auth status --hostname github.com gh api --hostname github.com user --jq .login gh repo view OWNER/REPO --json nameWithOwner,viewerPermission,defaultBranchRef appmana projects init # For a Unity project in a subdirectory, use --unity-dir path/to/Unity. # Use --target windows or --target webgl if appropriate. git add -- .appmana/settings.yaml git commit --only -m "Configure AppMana project" -- .appmana/settings.yaml git push appmana projects enroll appmana project-settings-syncs get PROJECT -o yaml ``` For a protected branch, merge the file through the usual pull request and run enroll from a checkout of the target branch. For HTTPS pushes, `gh auth setup-git --hostname github.com` lets Git use the existing GitHub CLI login. Enrollment compares the local settings against the file on GitHub before creating AppMana resources. Retry the same command after an interruption. The command reuses matching resources and reports a name collision. Future configuration changes go through the committed YAML. Enrollment is headless when the AppMana account already has GitHub linked, the AppMana GitHub App has access to the repository, and the workspace is enabled for Git settings sync. For first-time consent: 1. Open [AppMana linked accounts](https://appmana.com/api/auth/account?section=linked-accounts&returnUri=%2Fdashboard) and link the GitHub account that can access the repo. 2. Open the [AppMana GitHub App installation](https://github.com/apps/appmana-build-source-managed/installations/new), choose the repository owner, and grant it access to the intended repo. If the organization requires approval, its GitHub administrator must grant it. An agent with browser access can perform these consent steps in the signed-in browser when the account owner authorizes granting that repository access. The GitHub CLI login verifies the repository and branch. AppMana uses its linked GitHub identity and its GitHub App installation for cloud access. Keep GitHub tokens out of GraphQL variables and repository files. ### 3. Define Project & Deployment Manifests manually Create `source.yaml`, `project.yaml`, and `deployment.yaml` (replace `user-` with your namespace from `appmana whoami --remote`): ```yaml # source.yaml apiVersion: build.appmana.com/v1alpha1 kind: SourceCredentialBinding metadata: name: my-game-source namespace: user- spec: provider: github accountRef: repositoryScope: https://github.com// ``` ```yaml # project.yaml apiVersion: build.appmana.com/v1alpha1 kind: BuildProject metadata: name: my-game namespace: user- spec: displayName: My Game lfs: enabled: true unlimited: true source: provider: git git: repository: https://github.com// revision: main credentialBindingRef: name: my-game-source targets: windows: true linux: true webgl: false unity: version: automatic projectPath: . runtimeDefaults: maxBitrate: 14000000 maxEncodingDimension: 1472 ``` ```yaml # deployment.yaml apiVersion: build.appmana.com/v1alpha1 kind: StreamingDeployment metadata: name: my-game namespace: user- spec: projectRef: name: my-game clusterTargetRef: name: appmana-cluster-03 platforms: windows: true linux: true graphics: windows: direct3d12 linux: vulkan resources: requested: cpu: "2000m" memory: "4000Mi" gpuCount: 1 gpuMemoryMiB: 2048 scaling: minReplicas: 1 maxReplicas: 8 idleSeconds: 300 settings: targetFrameRate: 60 maxBitrate: 14000000 maxEncodingDimension: 1472 useHardwareEncoder: true quitInsteadOfIdle: true ``` ### 4. End-to-End Workflow A: Streamed Project (Windows DirectX 12 / Linux Vulkan) ```bash # 1. Create the BuildProject, StreamingDeployment, and SourceCredentialBinding appmana projects create \ --build-project @project.yaml \ --streaming-deployment @deployment.yaml \ --source-credential-binding @source.yaml # 2. Submit a cloud build for Windows and/or Linux appmana projects build my-game --revision main --windows --linux --no-webgl # 3. Inspect build status and query build logs appmana build-requests list --project my-game appmana pipeline-runs list appmana logs query --query '{namespace="user--build"}' --start 2026-11-17T00:00:00Z --end 2026-11-17T23:59:59Z # 4. List completed BuildArtifacts and deploy to the StreamingDeployment appmana build-artifacts list --project my-game -o json appmana projects deploy my-game --artifact --deployment my-game --dry-run appmana projects deploy my-game --artifact --deployment my-game # 5. Verify rollout readiness (status.observedGeneration == metadata.generation) appmana streaming-deployments get my-game -o json # 6. Publish a public watch route (https://appmana.com/watch/) appmana projects publish my-game --deployment my-game --alias my-game-live --dry-run appmana projects publish my-game --deployment my-game --alias my-game-live appmana artifact-aliases get my-game-live -o json ``` ### 5. End-to-End Workflow B: WebGL Project ```bash # 1. Enable the WebGL target on the BuildProject appmana projects patch my-game --input '{"spec":{"targets":{"webgl":true}}}' # 2. Trigger a WebGL build appmana projects build my-game --revision main --webgl --no-windows --no-linux # 3. Locate the completed BuildArtifact with spec.webgl.oci.digest appmana build-artifacts list --project my-game -o json # 4. Promote the OCI file artifact to a public CDN ArtifactPublication appmana projects publish-files my-game --artifact --publication my-game-webgl-v1 --dry-run appmana projects publish-files my-game --artifact --publication my-game-webgl-v1 # 5. Poll until status.phase == "Published" appmana artifact-publications get my-game-webgl-v1 -o json # 6. Select the active WebGL publication on the BuildProject appmana projects select-webgl my-game --publication my-game-webgl-v1 --dry-run appmana projects select-webgl my-game --publication my-game-webgl-v1 ``` --- ## SKILL 2: Upgrading Unity Projects to Unity 6 (`6000.3+`) 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/packages-lock.json`**: - Remove standalone `"com.unity.textmeshpro"` — TextMeshPro is merged into `"com.unity.ugui": "2.0.0"` (Unity 6.3) / `"2.5.0"` (Unity 6.5) / `"2.6.0"` (Unity 6.6). - Use HTTPS Git URLs only (never `git@github.com:` SSH URLs): ```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" } } ``` - Whenever you bump a `#tag` or commit in `Packages/manifest.json`, delete the matching entry in `Packages/packages-lock.json` so Unity does not stay pinned to the stale commit hash. 2. **Active Input Handling**: - In `ProjectSettings/ProjectSettings.asset`, set `activeInputHandler: 1` (**Input System Package (New)** exclusively, not `Both`). 3. **Unity 6 C# API Replacements**: - `rb.velocity` -> `rb.linearVelocity` - `PhysicMaterial` -> `PhysicsMaterial` - `Object.FindObjectsOfType()` -> `Object.FindObjectsByType(FindObjectsInactive.Include, FindObjectsSortMode.None)` - `Object.GetInstanceID()` (obsolete in Unity 6.5+) -> `Object.GetEntityId()` (and upgrade `com.cysharp.unitask` to `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`). - If keeping Cinemachine 2.x components 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 auto-upgrade to Cinemachine 3.x. 5. **HDRP 17.x & Graphics APIs**: - Any custom pass serialized with `[SerializeReference]` on a `CustomPassVolume` **must** have `[System.Serializable]` on the class and use `RenderGraphModule.TextureHandle` in `Execute`. - Windows target (`StandaloneWindows64`) must include both `Direct3D11` and `Direct3D12` (`m_Automatic: 0`) so D3D12 compute shaders compile. - Linux target (`StandaloneLinux64`) must use `Vulkan` first (`m_Automatic: 0`), and any `ShaderVariantCollection.WarmUp()` call must be guarded with `if (!Application.isBatchMode)` to avoid headless Vulkan swapchain crashes. - In `.gitattributes`, always track both lowercase and uppercase extensions (`*.fbx` and `*.FBX`, `*.tga` and `*.TGA`, `*.png` and `*.PNG`, `*.exr` and `*.EXR`, `*.wav` and `*.WAV`) for case-sensitive Linux build containers. --- ## SKILL 3: Camera Hierarchy, `PerUserGraphicRaycaster` & Input System Wiring ### 1. Single-Player & Multiplayer Scene Hierarchy Each streamable player slot in a scene is rooted at a GameObject with `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 (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 Elements: 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 local-to-networked multiplayer: duplicate prefab on Layer "Player 2", targetDisplay: 1) ``` ### 2. Why `PerUserGraphicRaycaster` and `PerUserPhysicsRaycaster` Are Essential - **Never use `RenderMode.ScreenSpaceOverlay`** — streamed video captures `RemotePlayableConfiguration.camera`'s `RenderTexture`, so canvases must use `RenderMode.ScreenSpaceCamera` with `worldCamera` set to the player's camera. - Standard `GraphicRaycaster` and `PhysicsRaycaster` do not filter pointer events by `InputUser` and fail when `camera.targetDisplay != 0`. - `AppMana.Multiplayer.PerUserGraphicRaycaster` (on every `Canvas`) and `AppMana.Multiplayer.PerUserPhysicsRaycaster` / `PerUserPhysics2DRaycaster` (on every player `Camera`) inspect `ExtendedPointerEventData.device`, resolve `InputUser.FindUserPairedToDevice(device)`, and ignore pointer events belonging to other connected players. - Replace `StandaloneInputModule` with `InputSystemUIInputModule` (`pointerBehavior = UIPointerBehavior.AllPointersAsIs`) and assign `Packages/com.appmana.unity.public/AppManaPublic/Input Actions.inputactions`. ### 3. Wiring Input in C# Scripts (4 Patterns) #### Pattern A: Drop-in Legacy `Input`, `Screen`, and `PlayerPrefs` Compatibility (Fastest Migration) Add type aliases at the top of any C# file using `UnityEngine.Input`, `UnityEngine.Screen`, or `UnityEngine.PlayerPrefs`: ```csharp using Input = AppMana.Compatibility.Input; using Screen = AppMana.Compatibility.Screen; using PlayerPrefs = AppMana.Compatibility.PlayerPrefs; ``` #### Pattern B: Subscribing to `RemotePlayableConfiguration.actions` in `Start()` (Multiplayer-Safe) `RemotePlayableConfiguration.Awake()` clones `m_Actions` per 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()` (never `Awake()`), and start gameplay in `m_Player.onPlayerConnected`: ```csharp using AppManaPublic.Configuration; using UnityEngine; using UnityEngine.InputSystem; public class PlayerController : MonoBehaviour { [SerializeField] private RemotePlayableConfiguration m_Player; private InputAction m_PointAction; private InputAction m_ClickAction; private void Start() { m_Player ??= GetComponentInParent(); m_PointAction = m_Player.actions.FindAction("UI/Point"); m_ClickAction = m_Player.actions.FindAction("UI/Click"); m_ClickAction.performed += OnClick; m_Player.onPlayerConnected.AddListener(OnPlayerConnected); } private void OnDestroy() { if (m_ClickAction != null) m_ClickAction.performed -= OnClick; if (m_Player != null) m_Player.onPlayerConnected.RemoveListener(OnPlayerConnected); } private void OnPlayerConnected() { // Container pre-warms in Start(); reset timers/cutscenes when the viewer connects } private void OnClick(InputAction.CallbackContext context) { if (!context.ReadValueAsButton()) return; Vector2 screenPos = m_PointAction.ReadValue(); Ray ray = m_Player.camera.ScreenPointToRay(screenPos); if (Physics.Raycast(ray, out RaycastHit hit)) { Debug.Log($"Player clicked {hit.collider.name}"); } } } ``` #### Pattern C: Inspector-Assigned `MultiplayerInputActionReference` or `IHasInputActionReferences` Use `AppMana.InteractionToolkit.MultiplayerInputActionReference` instead of raw `InputActionReference`, or implement `AppMana.ComponentModel.IHasInputActionReferences` so `RemotePlayableConfiguration.Awake()` rebinds your serialized `InputActionReference` fields to the player's cloned `InputActionAsset`: ```csharp using AppMana.ComponentModel; using UnityEngine; using UnityEngine.InputSystem; public class CharacterMotor : MonoBehaviour, IHasInputActionReferences { [SerializeField] private InputActionReference m_MoveAction; [SerializeField] private InputActionReference m_JumpAction; public IHasInputActionReferences.InputActionReferenceProperty[] inputActionReferenceProperties => new[] { new IHasInputActionReferences.InputActionReferenceProperty(() => m_MoveAction, v => m_MoveAction = v), new IHasInputActionReferences.InputActionReferenceProperty(() => m_JumpAction, v => m_JumpAction = v), }; private void Update() { Vector2 move = m_MoveAction.action.ReadValue(); if (m_JumpAction.action.WasPressedThisFrame()) { // Jump } } } ``` #### Pattern D: 3D World Pointer & Drag Events with `PerUserPhysicsRaycaster` With `PerUserPhysicsRaycaster` on the player's `Camera`, any 3D GameObject with a `Collider` can implement standard `UnityEngine.EventSystems` interfaces (`IPointerClickHandler`, `IPointerDownHandler`, `IDragHandler`, `IPointerUpHandler`) and automatically receive per-user mouse and touch events: ```csharp using UnityEngine; using UnityEngine.EventSystems; public class DraggablePiece : UIBehaviour, IPointerDownHandler, IDragHandler, IPointerUpHandler { public void OnPointerDown(PointerEventData eventData) { } public void OnDrag(PointerEventData eventData) { } public void OnPointerUp(PointerEventData eventData) { } } ```