# Migrating from Unity Plugin v3.x to v4.0
## Introduction
This guide will walk you through migrating your Looking Glass Unity project from plugin version 3.x to the new 4.0 alpha version. Version 4.0 brings major performance improvements (2x to 4x faster!) but requires Unity 6 with Universal Render Pipeline and has fewer features.
{% hint style="warning" %}
Version 4.0 is currently in alpha/beta. It may have stability issues. Consider keeping a backup of your v3.x project.
{% endhint %}
## Before You Begin
### Requirements for v4.0
* Unity 6000.0.39 to 6000.1.5
* Universal Render Pipeline v17.0.4 to v17.1.0
* Forward or Forward+ rendering
* RenderGraph enabled
* Looking Glass device (Go, 16", or 27")
{% hint style="warning" %}
Version 4.0 does NOT support the built-in render pipeline, HDRP, or earlier Unity versions.
{% endhint %}
### Create a Backup
Before starting the migration:
1. Make a complete backup of your project
2. Consider using version control to create a new branch
3. Document any custom modifications you've made to the v3.x plugin
## Step 1: Remove the Old Plugin
{% hint style="warning" %}
#### Critical: Exit Unity First!
{% endhint %}
You MUST close Unity before deleting the old plugin. Unity holds references to the plugin files while open, which can cause errors if you try to delete them from within the editor.
1. **Save your project** and close Unity completely
2. Navigate to your project folder using Windows Explorer (Windows) or Finder (Mac)
3. Delete the old Looking Glass plugin folder and the Looking Glass post-processing folder:
* Typically located at: `Assets/LookingGlass` and `Assets/LookingGlass Post-Processing 3.2.2`
* Or wherever you imported the v3.x package
### Clean Up Meta Files
After deleting the plugin folder:
1. Delete the corresponding `.meta` file for the Looking Glass folder
2. Search for and remove any orphaned Looking Glass-related meta files
## Step 2: Prepare Your Project for v4.0
### Upgrade to Unity 6
If you're not already using Unity 6:
1. Open Unity Hub
2. Install Unity version 6000.0.39 to 6000.1.5
3. Open your project with the new Unity version
4. Allow Unity to upgrade your project (this may take some time)
### Convert to Universal Render Pipeline
If your project isn't using URP:
1. Install URP via Package Manager
2. Create a URP Asset: `Create > Rendering > URP Asset (with Universal Renderer)`
3. Go to `Edit > Project Settings > Graphics`
4. Assign your URP Asset to the Scriptable Render Pipeline Settings
### Enable RenderGraph
1. Go to `Edit > Project Settings > Graphics > URP`
2. Scroll to the bottom of the page
3. Ensure that `Compatibiliity Mode` is disabled
## Step 3: Install the New Plugin
{% hint style="info" %}
See the full getting started guide [here](https://lfdocs.lookingglassfactory.com/software/index/unity-plugin-4.0-alpha).
{% endhint %}
Close the Unity Editor before proceeding.
### Download and Extract
1. Download the Unity Plugin 4.0 zip for your version of Unity — downloads available [here](https://lfdocs.lookingglassfactory.com/software/index/unity-plugin-4.0-alpha).
2. Extract the zip file. You'll find:
* `com.unity.render-pipelines.core` folder
* `com.unity.render-pipelines.universal` folder
* `jp.keijiro.klak.syphon` folder
* `jp.keijiro.klak.spout` folder
* `Looking Glass Unity Plugin 4.0.1-alpha.unitypackage`
* A readme file
### Install Package Dependencies
{% hint style="info" %}
**Important**: Keep Unity closed for this step!
{% endhint %}
1. Navigate to your project's `Packages` folder
2. Copy these four folders into the Packages folder:
* `com.unity.render-pipelines.core`
* `com.unity.render-pipelines.universal`
* `jp.keijiro.klak.syphon`
* `jp.keijiro.klak.spout`
### Import the Unity Package
1. Open your Unity project
2. Go to `Assets > Import Package > Custom Package`
3. Select the `Looking Glass Unity Plugin 4.0.1-alpha.unitypackage`
4. Import all files
### Configure Project Settings
1. In the Project window, navigate to `Looking Glass Plugin/Settings/`
2. Select the `Project Setup` object
3. In the Inspector, you'll see buttons for each render pipeline location
4. Click each button to automatically configure the settings
### Launch the Preview Window App
1. Download the preview window applications (for Windows or MacOS) here.
2. Follow instructions [here](https://lfdocs.lookingglassfactory.com/software/index/unity-plugin-4.0-alpha/..#preview-window-on-windows) (for Windows) and [here](https://lfdocs.lookingglassfactory.com/software/index/unity-plugin-4.0-alpha/..#preview-window-on-macos) (for MacOS) to run the app.
## Step 4: Update Your Scenes
### Test the Example Scene
1. Open `Looking Glass Plugin/Scenes/Multiview Example Scene`
2. Enter Play mode to verify everything is working
3. If you see the example content, the plugin is installed correctly
### Migrate Your Existing Scenes
The new plugin uses a different architecture. Here's how to update your scenes:
**Replace the Old Hologram Camera**
1. Delete the old Hologram Camera from v3.x
2. From the new plugin, add:
* The `Multiview Container` (found under Orbit Controls in the example scene)
* The `Final Pass Canvas` object
3. In the `Final Pass Canvas` object, open the `Multiview Cams` array and add your `Hologram Camera` to the list
### Add Preview Support
For live preview in the Editor:
1. Add a `Klak Preview Sender` object from `Looking Glass Plugin/Prefabs`
2. Download and set up the Preview Window app (see plugin documentation)
## Common Issues and Solutions
#### Unity Won't Delete Old Plugin Files
**Solution**: Make sure Unity is completely closed. Use Task Manager (Windows) or Activity Monitor (Mac) to ensure no Unity processes are running.
#### Missing References After Migration
**Solution**: Re-assign Looking Glass components in your scenes. The new plugin uses different component names and structures.
#### Performance Issues
**Solution**: Ensure RenderGraph is enabled in your URP settings. Check that you're using Forward or Forward+ rendering.
#### Preview Window Shows Black Screen
**Solutions**:
* Enter Play mode in Unity
* Ensure Looking Glass Bridge is running
* Restart the Unity Editor
* Check that the Klak Preview Sender is in your scene
## Best Practices
#### Don't Modify Plugin Files
Never add your assets to the `Looking Glass Plugin` folder or modify its contents. Future updates will require deleting and replacing this folder.
#### Keep Both Versions During Transition
Consider keeping a separate project with v3.x while you test v4.0, especially for production projects.
#### Test Thoroughly
v4.0 is in alpha/beta. Test all functionality before deploying:
* Interactive features
* Build processes for your target platforms
* Performance on your target hardware
## Need Help?
If you encounter issues during migration:
* Email us at
* Join our [Discord community](https://discord.gg/ZUZDs65t)
* Check the [v4.0 documentation](https://docs.lookingglassfactory.com/software/index/unity-plugin-4.0-alpha)
* Consider using the stable [v3.x plugin](https://docs.lookingglassfactory.com/software/index) if you need reliability
Remember, v4.0 is still in development. Your feedback helps us improve! Please [fill out our survey if you have feedback](https://lookingglass.typeform.com/to/wrLysfEY).
