# Vision - CullingGroup API for everyone **Created by Hiroya Aramaki ([Makihiro](https://twitter.com/makihiro_dev))** [![Release](https://camo.githubusercontent.com/151e14641685d0dbb4880986c1c53adabe80c616bb9cfdae4e194499fd363e84/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6d61636b79736f66742f566973696f6e)](https://github.com/mackysoft/Vision/releases) [![openupm](https://camo.githubusercontent.com/fd5b34aed9b7994e5556c66af071594e9c008b01501935dcd1bbc0a8cb7227d6/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e6d61636b79736f66742e766973696f6e3f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.mackysoft.vision/) ## What is CullingGroup API ? ![TreasureRogue_Culling](https://user-images.githubusercontent.com/13536348/115215242-47d33380-a13e-11eb-816c-c10df930f1aa.gif) 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 ## Table of Contents - [📥 Installation](https://github.com/mackysoft/Vision/raw/main/#installation) - [🔰 Usage](https://github.com/mackysoft/Vision/raw/main/#usage) - [1. Create the CullingGroupProxy](https://github.com/mackysoft/Vision/raw/main/#create-the-culling-group-proxy) - [2. Attach the CullingTargetBehaviour](https://github.com/mackysoft/Vision/raw/main/#attach-the-culling-target-behaviour) - [3. Receive a callback](https://github.com/mackysoft/Vision/raw/main/#receive-callback) - [⚒Utilities](https://github.com/mackysoft/Vision/raw/main/#utilities) - [Culling Target Renderers](https://github.com/mackysoft/Vision/raw/main/#culling-target-renderers) - [✉ Help & Contribute](https://github.com/mackysoft/Vision/raw/main/#help-and-contribute) - [📔 Author Info](https://github.com/mackysoft/Vision/raw/main/#author-info) - [📜 License](https://github.com/mackysoft/Vision/raw/main/#license) # 📥 Installation 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](https://openupm.com/packages/com.mackysoft.vision/) registry. More details [here](https://openupm.com/). ``` openupm add com.mackysoft.vision ``` # 🔰 Usage ## 1. Create the CullingGroupProxy First, create a `CullingGroupProxy`, which is the core of Vision. #### 1. From the `Tools/Vision/Create New CullingGroupProxy` menu, create a `CullingGroupProxy`. ![NewCullingGroupProxy](https://user-images.githubusercontent.com/13536348/111070665-0c798f80-8516-11eb-8ed6-d1f87cc31b61.jpg) #### 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 `` or `Tools/Vision/Open Settings` menu. You can define a new key in the `GroupKeyDefinitions` list. > > ![VisionSettings](https://user-images.githubusercontent.com/13536348/111070868-033cf280-8517-11eb-852c-386f00ad2f45.jpg) #### 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. ![CullingGroupPRoxy_Distances](https://user-images.githubusercontent.com/13536348/111077905-465a8e00-8536-11eb-92c1-657f73c1e7df.jpg) 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 ! ![CullingTargetProxy_Distances_Gizmo](https://user-images.githubusercontent.com/13536348/111077910-4c506f00-8536-11eb-917b-dd35a4bdc6bd.jpg) ## 2. Attach the CullingTargetBehaviour `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. ![CullingTargetBehaviour](https://user-images.githubusercontent.com/13536348/111072032-333ac480-851c-11eb-8821-0b4f766e1e34.jpg) #### 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 ! ![CullingTargetBehaviour_Idle](https://user-images.githubusercontent.com/13536348/111072309-57e36c00-851d-11eb-8196-8c38b2af62c1.jpg) Also, during play mode, the color changes depending on visibility. CullingTargetBehaviour_Visible

#### 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`. ## 3. Receive a callback Use `CullingTargetBehaviour.OnStateChanged` callback to respond to changes in the visibility and distance state of the bounding sphere. ```cs using UnityEngine; using MackySoft.Vision; [RequireComponent(typeof(CullingTargetBehaviour))] public class ReceiveCallbackExample : MonoBehaviour { void Awake () { var cullingTarget = GetComponent(); cullingTarget.OnStateChanged += OnStateChanged; } void OnStateChanged (CullingGroupEvent ev) { if (ev.isVisible) { Debug.Log("Visible!"); } else { Debug.Log("Invisible!"); } } } ``` ## Utilities Vision provides utility components that can be used with no coding. ### Culling Target Renderers Enable / Disable the specified renderer's depending on the visibility of the bounding sphere. ![CullingTargetRenderers](https://user-images.githubusercontent.com/13536348/111073973-5cf7e980-8524-11eb-9b84-ab95c263940c.jpg) # ✉ Help & Contribute Questions and ideas are welcome in [discussions](https://github.com/mackysoft/Vision/discussions). We welcome contributions such as [bug reports](https://github.com/mackysoft/Vision/issues) and [pull requests](https://github.com/mackysoft/Vision/pulls). # 📔 Author Info Hiroya Aramaki is a indie game developer in Japan. - Blog: [https://mackysoft.net/blog](https://mackysoft.net/blog) - Twitter: [https://twitter.com/makihiro_dev](https://twitter.com/makihiro_dev) # 📜 License This library is under the MIT License.