🔄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.

Version 4.0 is currently in alpha/beta. It may have stability issues. Consider keeping a backup of your v3.x project.

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")

Version 4.0 does NOT support the built-in render pipeline, HDRP, or earlier Unity versions.

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

Critical: Exit Unity First!

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

See the full getting started guide here.

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.

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

Important: Keep Unity closed for this step!

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 (for Windows) and here (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 Hologram Container (found under Orbit Controls in the example scene)

   • The Final Pass Canvas object

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 [email protected]

• Join our Discord community

• Check the v4.0 documentation

• Consider using the stable v3.x plugin 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.