Migrating Your Project
Rapidly add the AppMana Unity Plugin to an existing project by example
Install
Install the AppMana Plugin. Follow the instructions on its GitHub page.
Once you have added the package(s) to your manifest.json, observe that you will be prompted that a "New Scoped
Registry" has been added: Click Close.
Observe you are prompted:
This project is using the new input system package but the native platform backends for the new input system are not enabled in the player settings. This means that no input from native devices will come through. Do you want to enable the backends? Doing so will RESTART the editor.
Click Yes and allow the editor to restart.
When you restart, you will see an error in the console:
Validation Error: You must enable Input System as the exclusive Input handling backend under Player Settings > Active Input Handling. This will correctly log errors if your game executes Input methods, like GetAxis, including third party libraries, at runtime.
Make this change. Visit Project Settings > Player > Active Input Handling, click the dropdown to change it from * Both* to Input System (New). Restart your editor again.
Do you use multiple scenes? You'll see a warning in your console:
Validation Error: You are building multiple scenes. You can only load additional scenes additively. Using SceneManager.LoadScene is not supported because AppMana cannot guarantee you do not destroy the streaming camera.
We'll deal with this later.
Configure
Navigate to File > Build Settings.... Look at the list of checkmarked scenes under Scenes to Build. Open the first checked scene on this list. Just like with a built player, this is the first scene players will see.
Select your "Main Camera" game object. Click Add Component in the Inspector, then choose Remote Playable Configuration.
Resolve the errors in the Inspector for this component. This means you can click Set to main camera; then click * *Set to pre-existing audio listener...**, then click Replace with Input System Event System modules.. If you have Canvas Scalers in your scene, you'll see Assign missing canvas scalers, and click it too.
Input Migration
Once you have configured your project, you will need to transition the use of Input to the new Unity Input System.
Follow these instructions to use our compatibility layer, or follow Unity's documentation here.
Test
Now that you have set up the Remote Playable Configuration and fixed usage of Input., hit Play.
If you currently use a Screen Space Overlay canvas in your scenes, you will see a warning in the console:
A Screen Space Overlay canvas was found and is not supported by AppMana by the name of Canvas. Switching to RenderMode.ScreenSpaceCamera and using camera Main Camera. Remove this warning by changing the Render Mode of the camera to Screen Space - Camera and choosing an appropriate Distance.
Follow these instructions to resolve the warning permanently.
Migrating Multiple Scenes
At this stage, your game will be working. You will click a button in your "Main Menu" scene, and as soon as you change
scenes, some issues may occur. The plugin will automatically employ mitigations to correct these issues when
your RemotePlayableConfiguration component's Enable Multiple Scene Mitigations is checked. The following
mitigations are employed by default:
- Prevents the
RemotePlayableConfigurationobject from being destroyed across scene loads. - Prevents the streamed camera from being destroyed across scene loads.
- Manages multiple main cameras in a multi-scene setup by adjusting their parent constraints to match a specified configuration. This method subscribes to the scene loaded observable to automatically manage main cameras when a new scene is loaded.
- Disables other input modules to prevent conflicts in a multi-scene setup, preserving only the input module from the original scene.
- Fixes issues with raycasters in a multi-scene setup to ensure UI elements interact correctly. This method subscribes
to the scene loaded observable to automatically fix raycasters when a new scene is loaded. Raycasters should be "per
user" by using the
PerUserGraphicRaycaster,PerUserPhysicsRaycasterandPerUserPhysics2DRaycasterraycaster components. - Converts Canvas objects from
RenderMode.ScreenSpaceOverlaytoRenderMode.ScreenSpaceCamerato ensure they render correctly in a multi-scene setup.
You can manually perform these mitigations. If you disable mitigations, you may observe these errors:
The console prints "InvalidOperationException: You are trying to read Input using the UnityEngine.Input class, but you have switched active Input handling to Input System package in Player Settings."
This occurs because the scene you are switching to contains a Standalone Input Module component in it. Now that you are using Input System (New), components like these must be migrated. In each of your scenes, select the **Event System ** game object, then under the Standalone Input Module component in the Inspector, click "Replace with InputSystemUIInputModule".
You do not see a picture in the Game View.
Your RemotePlayableConfiguration component was destroyed. You must DontDestroyOnLoad it. You must also only have one
camera streaming in the scene. This is the camera that is set as the Camera field on
the RemotePlayableConfiguration component.
