Portal occlusion Library
After weeks or even months of tireless effort, you have created an environment in Unity that is perfectly detailed and completely immersive. There is just one problem - it runs at 12 frames per-second. You know what is wrong: Unity is rendering ever single room in your environment even if it can't be seen by the player. How can you fix it? How can you tell Unity to only render what can be seen?
The Portal Occlusion Library is designed for your interior levels! You can even begin adding portals and rooms to your environment after you've completed your scene. Simply place your rooms, connect them logically with portals (preferably where your doorways and windows connect) and run your scene. The Portal Occlusion Library will automatically determine your scene setup.
Features
- Easy to use. Simply drag-and-drop prefab rooms and portals into your scene.
- No Baking! Once your portals are in place, you never have to bake scene occlusion.
- No scripting required! The system runs when your game starts and figures your scene occlusion out for you.
- Configurable. Rooms and Portals can be configured to suite your scene more precisely.
- API for Advanced Users. Tie into special events to control your environment more closely.
- Dynamic Positioning. Great for levels where your rooms move, such as on a boat or in a star ship.
- Dynamic Occlusion. The scene will notice when objects leave or entire rooms and act accordingly.
- Works in VR!
Usage
Quickly make your first scene with portals or load one of the two demo scenes to see how things interact. After you have a scene ready for occlusion (or even a couple of small rooms witha doorway), follow the steps below to begin using portals.
STEP 1. Navigate to the Library/Prefabs folder and drag a Room into your scene. You should notice a cyan-colored bounding box where the room is. Move and scale the bounding box to encompass the entire contents of one of your rooms (doors and all).
Step 2. Now repeat step one for a connecting room - dragging and dropping a Room prefab then rescaling the room to fit your second room.
Step 3. Drag a Portal prefab into your scene. Position, rotate and scale the doorway to connect the two rooms you just created where the doorway would be. Make sure the portal intersects both rooms and that the orange squares mark the entry and exit points of your doorway!
Step 4. Repeat steps one through three for each room, doorway and window that connects a room.
Step 5. Place a player controller and main camera in your scene. Press play and start walking around from room to room to explore and enjoy your newly optmimized world!
Limitations
The portal occlusion library only functions if the main camera is in a room. If the camera steps outside of a room, then the system will freeze its current state and fail to process. For this reason, it is best to use the portal occlusion library for in-door "Doom-like" scenes. Additionally, the system requires that your rooms be connected by portals in a meaningful way in order to best optimize results. We recommend watching this video to better understand how to setup the portal system.
Fully Enclosed Objects
In order to make your worlds as optimized as possible, the portal library prefers that rooms completely contain their objects. With "Only Fully Enclosed Objects" ticked, rooms and portals will only manage objects (Renderers and lights) completely contained within them. With it unticked, they will also manage anything that intersects them. Note that if a rigid body intersects a portal or room that they are automatically managed regardless of this setting. By default, "Only Fully Enclosed Objects" is checked for rooms but not for portals.
Exterior Portals
Any portal which has exactly one connection is considered an exterior portal. This means you can have a group of objects act as an outside world - potentially an outside playable area - while still hiding this scene when deep within your structure's hallways. This can make your world seems a lot bigger than it really is while still optimizing framerate, or, with some careful planning, allow your player the ability to transition from an outside to an inside environment and back.
Portal: Additional Objects
This is a simple array which you can add additional geometry to which may not be connected to a room or portal. To add additional objects, set the array size to 1 or more and drag objects into the array that you want their visibility governed by the portal. Once the portal is visible, the object will also become visible. Once the portal is invisible, the object will also become invisible. This only affects objects with a Renderer component.
To setup exterior views, first make sure that your exterior portals have exactly one room connection. Then create one or more game objects which will hold your exterior geometry and populate them with models, lights or terrains. Add a Portal Object Configuration component to the new game object (just the top-level one) and tick the "Is Exterior Object".
Tips and Troubleshooting Occlusion
Occlusion Failures. Most of the time, occlusion should just work if you setup your scene correctly. Common issues that occur typically arise from a room not completely encompassing all of its parts or a portal not quite intersecting a room. Be sure to mess around with the size and positions of room and portal prefabs and eventually they should start working the way you would like.
If all else fails, portals and rooms can have their Only Fully Enclosed Objects unchecked which will cause any object intersecting to become a part of that prefab. By default, Portals have this set to false, but be careful for setting this for rooms. It can cause more geometry to be rendered in your scene than is required, causing performance issues. Consider it a last resort.
Opening/Closing Portals. A very common optimization is to close a portal when it is obstructed. The most obvious case for this is a closed door. You can create a script which takes a portal component and dynamically sets the Open attribute to true/false depending on the state of the door. For an example of how to do that, check out the "demo" scene under examples. The Door.cs script uses animation states to determine when a door's portal is open or closed. This allows the Portal Occlusion Library to finish early processing when a player is in a room with a shut door - a potentially massive performance savings!
Overlapping Rooms. Generally it is best to keep rooms seperated as much as possible. However, a little overlap is generally fine and sometimes necessary. This can occur if your rooms share geometry with another room or you are creating occlusion portals to break up long hallways. Whenever possible, try to split geometry where rooms connect. If you can't - don't worry. The portal arrangement can usually be modified to figure it out.
Rooms/Portals Become Walls. If you find yourself unable to walk through a portal or room, you might have added the room or portal to a game object as a component rather than using the prefab. That's okay, it just means the collider attached to the room or portal is not set as a trigger. Simply check the Is Trigger box on the Box Collider and the problem should go away. You might also want to go through the Room/Portal's components to be sure it's set up the way you want, as well.
Support
If you have any questions regarding the library and the above troubleshooting wasn't able to help, please send us an email here!