Awesome
Vision - CullingGroup API for everyone
Created by Hiroya Aramaki (Makihiro)
What is CullingGroup API ?
CullingGroup offers a way to integrate your own systems into Unityโs culling and LOD pipeline.
- Simulating a crowd of people, while only having full GameObjects for the characters that are actually visible right now.
- Building a GPU particle system driven by Graphics.DrawProcedural, but skipping rendering particle systems that are behind a wall.
- Tracking which spawn points are hidden from the camera in order to spawn enemies without the player seeing them โpopโ into view.
- Switching characters from full-quality animation and AI calculations when close, to lower-quality cheaper behaviour at a distance.
- Having 10,000 marker points in your scene and efficiently finding out when the player gets within 1m of any of them.
Unity Manual: https://docs.unity3d.com/Manual/CullingGroupAPI.html
Why Vision ?
CullingGroup is a great feature, but its implementation is a difficult because it can only be accessed through scripts and its usage is quirky.
Vision has made such a CullingGroup available to everyone.
Vision Features
- Components for easy access to CullingGroup.
- Intuitive visual editor.
- High performance
<a id="index" href="#index"> Table of Contents </a>
<a id="installation" href="#installation"> ๐ฅ Installation </a>
Download any version from releases.
Releases: https://github.com/mackysoft/Vision/releases
Install via Open UPM
Or, you can install this package from the Open UPM registry.
More details here.
openupm add com.mackysoft.vision
<a id="usage" href="#requirements"> ๐ฐ Usage </a>
<a id="create-the-culling-group-proxy" href="#create-the-culling-group-proxy"> 1. Create the CullingGroupProxy </a>
First, create a CullingGroupProxy
, which is the core of Vision.
1. From the Tools/Vision/Create New CullingGroupProxy
menu, create a CullingGroupProxy
.
2. Set the key to the created CullingGroupProxy
.
Set the key by clicking the Key
popup in CullingGroupProxy
. By default, there is a Main
key.
If you don't see the key, open settings from the
<add key>
orTools/Vision/Open Settings
menu. You can define a new key in theGroupKeyDefinitions
list.
3. Distances
By setting DistanceReferencePoint
and BoundingDistances
of CullingGroupProxy
, you can calculate the relative distance between a reference point (for example, camera, player) and the bounding sphere's.
If BoundingDistances
is set to { 10f, 20f, 30f }
,
Distance Level | Range |
---|---|
Level 0 | 0m ~ 10m |
Level 1 | 10m ~ 20m |
Level 2 | 20m ~ 30m |
The last level and beyond will be treated as invisible.
If Distances is empty, { 0f , Mathf.Infinity }
will be used as a fallback. In that case, currentDistance will always be 1.
BoundingDistances
can be adjusted visually from the scene view !
<a id="attach-the-culling-target-behaviour" href="#attach-the-culling-target-behaviour"> 2. Attach the CullingTargetBehaviour </a>
CullingTargetBehaviour
is a component that attaches to the object to be culled.
1. Attach CullingTargetBehaviour
from Component/MackySoft/Vision/Culling Group Behaviour
menu.
Attach this component to objects that you want to show/hide depending on their visibility, or change their quality depending on their relative distance.
2. Set the group key to the attached CullingGroupBehaviour
.
The GroupKey
of the CullingGroupBehaviour
is used to find a CullingGroupProxy
with the same key specified,
and the CullingGroupBehaviour
will be registered with the found CullingGroupProxy
.
3. Adjust the radius of CullingGroupBehaviour
.
The bounding sphere of the CullingGroupBehaviour
is used to calculate the visibility by the CullingGroup
. Completely enclose the object you want to cull with the bounding sphere.
Radius can be adjusted visually from the scene view !
Also, during play mode, the color changes depending on visibility.
<img src="https://user-images.githubusercontent.com/13536348/111074733-bf061e00-8527-11eb-8e19-e6796e56c63a.jpg" height="200" title="CullingTargetBehaviour_Visible" /> <img src="https://user-images.githubusercontent.com/13536348/111074737-c6c5c280-8527-11eb-9275-220103d8d59a.jpg" height="200" title="CullingTargetBehaviour_Invisible" />4. Select the BoundingSphereUpdateMode
.
This is an important value for performance.
BoundingSphereUpdateMode
is set to Dynamic
by default. This means that the transform of bounding sphere will be updated every frame.
However, there are some objects that do not move. In such cases, you can avoid the extra update cost by setting the BoundingSphereUpdateMode
to Static
.
<a id="receive-callback" href="#receive-callback"> 3. Receive a callback </a>
Use CullingTargetBehaviour.OnStateChanged
callback to respond to changes in the visibility and distance state of the bounding sphere.
using UnityEngine;
using MackySoft.Vision;
[RequireComponent(typeof(CullingTargetBehaviour))]
public class ReceiveCallbackExample : MonoBehaviour {
void Awake () {
var cullingTarget = GetComponent<ICullingTarget>();
cullingTarget.OnStateChanged += OnStateChanged;
}
void OnStateChanged (CullingGroupEvent ev) {
if (ev.isVisible) {
Debug.Log("Visible!");
} else {
Debug.Log("Invisible!");
}
}
}
<a id="utilities" href="#utilities"> Utilities </a>
Vision provides utility components that can be used with no coding.
<a id="culling-target-renderers" href="#culling-target-renderers"> Culling Target Renderers </a>
Enable / Disable the specified renderer's depending on the visibility of the bounding sphere.
<a id="help-and-contribute" href="#help-and-contribute"> โ Help & Contribute </a>
Questions and ideas are welcome in discussions.
We welcome contributions such as bug reports and pull requests.
<a id="author-info" href="#author-info"> ๐ Author Info </a>
Hiroya Aramaki is a indie game developer in Japan.
- Blog: https://mackysoft.net/blog
- Twitter: https://twitter.com/makihiro_dev
<a id="license" href="#license"> ๐ License </a>
This library is under the MIT License.