Third Room Unity Exporter
Export Third Room scenes from Unity. Powered by UnityGLTF.
Contents
- Installation
- Scene Setup
- Spawn Points
- Portals
- Colliders
- Skybox
- Audio
- Lights and Lightmaps
- Reflection Probes
- Optimization and Uploading
- Getting Help
Installation
First you'll need a copy of Unity which can be downloaded here.
Internally we use Unity 2021.3.17f1 (LTS), Unity versions 2020.3+ should be supported, but we can't make any promises. 2021.3+ would be preferred.
You should use the Universal Render Pipeline (URP) to maximize compatibility with UnityGLTF.
WARNING
If you are a macOS user and see this error when trying to import packages via git URL:
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Run xcode-select --install
in order for git import of packages to function properly.
This package depends on a branch of UnityGLTF that needs to be installed before you install the exporter.
- Open
Window > Package Manager
- In Package Manager, click + and select Add Package from git URL
- Paste
https://github.com/matrix-org/UnityGLTF.git?path=/UnityGLTF/Assets/UnityGLTF#thirdroom/dev
- Click Add.
After that is installed you can do the same thing for the Third Room Exporter:
- In Package Manager, click + and select Add Package from git URL
- Paste
https://github.com/matrix-org/thirdroom-unity-exporter.git?path=/Packages/thirdroom-unity-exporter
- Click Add.
You'll also probably want to add the Sample Scenes which contains an example scene, a portal asset, and default settings assets for you to use in your project.
Install the sample scenes in the Package Manager by pressing Import under the Samples dropdown.
Scene Setup
Whether you're working with an existing scene or starting one from scratch there's a few things you'll want to check before you get started.
Project Settings
- Open
Edit > Project Settings...
- Ensure that Color Space is set to
Linear
- Ensure that Lightmap Encoding is set to
Normal Quality
- If you're using Unity 2022, ensure that HDR Cubemap Encoding is set to
Normal Quality
If these settings aren't set, your lighting may look fine in Unity, but it'll look off when exporting and importing into Third Room.
Render Pipeline Settings
You can find your render pipeline assets in your project's Settings
directory. New projects are typically set up to use the High Fidelity render pipeline while in the editor. Open up the asset and ensure that HDR is turned on. It should be already.
Lighting Settings
You will need to setup Lighting Settings properly in order to export as glTF from Unity3D.
- Open
Window > Rendering > Lighting
- Select
ThirdRoomDefaultLightingSettings
as the Lighting Settings Asset - At the botton of the Lighting panel, make sure to click the
Generate Lighting
button before exporting as glTF
Materials
We find that the UnityGLTF/PBRGraph
material works best for exported scenes. You can convert to UnityGLTF/PBRGraph
material from the following shaders with automatic conversions:
Standard
URP/Lit
URP/Unlit
To do so change the shader on the selected material to UnityGLTF/PBRGraph
.
For all new materials, set the UnityGLTF/PBRGraph
shader before you start setting properties.
Note that Third Room does not yet have support for the following extensions:
- KHR_matrials_irridescence
- KHR_materials_specular
- KHR_materials_clearcoat
Upon import those extensions will be ignored. We hope to support them in the future.
More information on UnityGLTF's materials can be found here.
Exporting a Scene
Once you have a scene ready to be exported to Third Room follow these steps to export it and test it out:
- Click
Assets > UnityGLTF > Export active scene as glTF
- Pick an output directory
- Open https://thirdroom.io/viewer in your browser.
- Drag and drop the entire contents of the output directory into the viewer.
You should see your output scene in the viewer. If you haven't placed a spawn point yet you'll be flying around the space. It may also be lit incorrectly and be very expensive to render. In the following sections we'll go over all of the supported features of the Third Room Unity Exporter.
Camera
If one or more camera is included in your exported scene, the first camera will be used as the "preview camera" that is shown when you've loaded an environment, but not yet entered the world.
A quick and easy way to position this camera is:
- Move your viewport to the position and orientation you'd like to set.
- Select your camera
- Click
GameObject > Align With View
The camera's projection will also be exported along with the scene so you can set the appropriate settings there as well.
Spawn Points
When you click Enter World
Spawn points are where your avatar will be placed. A spawn point is chosen at random when you enter the world.
To place a spawn point:
- Create a new empty object
- Click
Add Component
- Search for
Spawn Point Behavior
- Position your spawn point so that it is slightly above the ground beneath it and so that the arrow inside the capsule is facing forward.
Colliders
Colliders can be easily exported with the Third Room Unity Exporter. The following colliders are exported:
- Box Collider
- Sphere Collider
- Capsule Collider
- Mesh Collider
Physic materials and the Is Trigger
properties are not yet supported. And all colliders will be static rigid bodies when they are imported into Third Room (they don't move). This does mean that your player will collide with them and can walk around on them though.
Typically you should pick the simplest collider for your meshes instead of using a complex mesh collider. Try creating approximations of mesh colliders out of multiple primitive colliders like boxes, spheres, and capsules.
Skybox
The Third Room Unity Exporter will export the skybox set in the scene's environment settings.
You'll want to make sure a couple settings are set here for best results:
- Set the environment reflection resolution to 128 (or whatever resolution your reflection probes are set to)
- Set the environment reflection compression to
Uncompressed
. We're going to compress with Basis Universal anyway so no need to compress twice.
To set your own skybox:
- Open
Window > Rendering > Lighting
- Open the
Environment
tab - Replace the skybox material with any compatible material.
Upon export the skybox will be captured as a cubemap and exported. Dynamic skybox shaders will be captured as they are.
Portals
Portals represent links to other Worlds across the Matrix network and eventually, virtual worlds across the entire metaverse.
Portal Prefab
The thirdroom-unity-exporter package contains a default portal prefab in the samples that you may have imported from the Package Manager window.
- In the Project go to the
Samples > Third Room Unity Exporter > x.x.x > Sample Scenes > Prefabs
directory. - Drag the
Portal
prefab into your scene where you want to place it. - Select the
Portal Target
object inside the Portal GameObject you just placed in theHierarchy
panel. - In the inspector there is a component
MX Portal Behaviour
with a single propertyUri
. You can change this to any Matrix Room URI (we'll explain the URI format below). For now you can keep this set tomatrix:r/terra-1:thirdroom.io
which represents a link to the room#terra-1:thirdroom.io
- Replace the thumbnail of the portal by replacing the material on the prefab's
Portal Thumbnail
object. We recommend that you set theRender Face
toBoth
and set both aBase Color Map
andEmissive Map
so that the portal can be seen from both sides and seems to glow even in dark environments.
Custom Portals
However, you can make a portal out of any object and make them look like whatever you want.
To create a custom portal you:
- Add a collider to act as the "Portal Target" this will be used to check if the user is hovering over the portal.
- Add the
MX Portal Behaviour
component to the same object as the collider. - Set a valid Matrix URI
Matrix URIs
Matrix URIs replace the #
or !
character with r/
or roomid/
respectively. So #myroom:myhomeserver.com
becomes matrix:r/myroom:myhomeserver.com
and !1234abcdefg:myhomeserver.com
becomes matrix:roomid/1234abcdefg:myhomeserver.com
You can read more on the Matrix URI spec here.
Audio
The Third Room Unity Exporter supports exporting both positional and global audio emitters.
Audio support is broken into three components:
- Audio Clips
- Audio Sources
- Audio Emitters
Global Audio Emitters
Global audio emitters are stereo or mono emitters that do not have any spatialization. They can represent ambient audio that should be heard throughout the map.
To create a global audio emitter:
- Create a new empty object
- Add the
KHR Global Audio Emitter Behavior
- Set the appropriate gain
- Set one or more sources (described below in a later section)
Positional Audio Emitters
Positional audio emitters are spatialized and have a cone-based model to simulate audio falloff.
To create a positional audio emitter:
- Create a new empty object
- Add the
KHR Positional Audio Emitter Behavior
- Set the appropriate gain and positional properties. They are described more in detail here.
- Set one or more sources (described below)
Audio Sources
Audio sources are used to control and synchronize the playback of an audio clip on one or more audio emitters. They are represented as Scriptable Objects in Unity so that you can reference them in multiple audio emitters.
To create an audio source:
- Right click inside a directory in your
Project
. - Click
Create > UnityGLTF > AudioSource
- Set the
Clip
property to any MP3 audio clip (it must be a .mp3) - Set the gain appropriately
- Auto Play will play this clip once the environment is loaded.
- Loop will continue looping the audio clip once it is finished.
Lights and Lightmaps
The Third Room Unity Exporter has native support for exporting Unity's lightmaps and it's generally preferred over exporting dynamic lights.
Realtime, mixed, and dynamic lights are supported. The current supported light types are:
- Directional Light (Only one is supported in Third Room and currently the position matters)
- Spot Light
- Point Light
All lights currently cast shadows so that setting has no effect for realtime lights. We're still working on getting dynamic/mixed lighting support up to the level of quality we'd like to see. And the performance of mixed/dynamic lighting is still quite bad. If you are going to use dynamic lights, use one directional light set to "Mixed" lighting and orient it so that it is in view of the place you'd like to cover with shadows. We're adding support for cascading shadow maps soon, so the position of the directional light is only a temporary measure.
The preferred workflow for lighting is baked lighting.
If you're new to baked lighting in Unity you can read more on the process here. Third Room will include the baked lightmaps on export and place lightmap UVs on the second UV set. Third Room needs a few lightmap settings to be set correctly for the exported lightmap to work correctly.
Lightmap Settings
Included in the samples directory is a ThirdRoomDefaultLightingSettings
file which has some decent default lighting settings for most scenes.
The important bits of the lighting settings are:
- Lighting Mode:
Baked Indirect
- Directional Mode:
Non-Directional
You may have to tweak the lightmap resolution depending on the size and complexity of your scene. If it's taking too long start low with something like 4 texels per unit and work your way up. You may also want to boost your max lightmap size to reduce the number of lightmaps needed and reduce the wasted space on your lightmaps. Experiment with different settings until you get the look and file size you want.
Reflection Probes
Unity's reflection probes are also exported with the scene.
Reflection probes should have the following settings set:
- Type:
Baked
- Box Projection: Should be unchecked, Third Room doesn't support it.
- Box Offset: Should be set to 0,0,0 Third Room doesn't support it.
- Resolution:
128
recommended for performance, you can change the resolution, but the important thing is that they are all the same. - HDR: Must be checked
Third Room also uses the Environment Reflections settings in the Lighting window under the Environment tab. They should be set to:
- Source:
Skybox
- Resolution:
128
or whatever you set for all the other reflection probes.
Postprocessing
We support exporting your global Unity Postprocessing settings. Currently we only support the following properties from Bloom: threshold, intensity, and scatter.
Optimization and Uploading
Third Room uses a custom glTF-Transform pipeline to apply optimizations to the final glTF files. These optimizations include:
- Removing unused glTF accessors, images, materials, and meshes
- Resizing textures: 2048x2048 for baseColorTexture and emissiveTexture, 1024x1024 for metallicRoughnessTexture, occlusionTexture, and normalTexture
- Marking nodes using the same mesh for instanced rendering
- Compressing textures with Basis Texture compression or OptiPNG (RGBM encoded lightmaps and reflection probes)
To optimize you assets follow these steps:
- Export your glTF scene by clicking
Assets > UnityGLTF > Export active scene as glTF
- Select your output directory
- Open https://thirdroom.io/pipeline
- Drag and drop the files from your output directory onto the pipeline page
- Open your browser's console to see the optimization pipeline's logs
- Wait a while... compressing textures takes a while. It's multithreaded, using WASM, but it's still going to take time.
- Find the final optimized file in your download folder.
- Test it out on https://thirdroom.io/viewer
- If you're satisfied with the results create a new world or change the scene of one of your worlds using the output .glb file.
Getting Help
This exporter and our asset pipeline in general has yet to be put through its paces. Especially outside our team. If you find a bug, please report it here in GitHub issues. If you're having a hard time figuring something out and need help, join us in the Third Room Matrix Room here. Also, we'd love to see progress of your work! Send us your progress shots in the Matrix Room or tag us on Twitter (@thirdroomio).