World Designer Grouping Listeners offer a simple but powerful mechanism for listening to the World Designer Tool in order to receive notification after Asset Chunks are added to the scene and before they are removed from the scene.
Their primary purpose is to allow you to notify third party tools or your own custom scripts about the existence of specific Asset Chunks in the scene. For instance, some third party tools that work on Unity Terrain may need to know which Terrain are currently loaded into the editor.
There are no default Listeners included with SAM, so to use them you must create your own custom class that derives from the base abstract WorldDesignerGroupingListener class.
In order to interface with the WorldDesignerGroupingListener class, you must create the script in a folder called Editor and you should place the class definition inside of the DeepSpaceLabs.EditorSAM namespace.
In your custom class, you must provide overrides for the OnAfterAssetChunksAdded and OnBeforeAssetChunksRemoved methods (let your IDE complete the method signatures to make things easier).
Creating logic inside of these methods should be fairly straightfoward, however one thing to note is that if you wish to use both the assetChunks and World Cells (each is represented by a separate list), you should use a for statement rather than a foreach statement. This will allow you to access both list with the same index (for every asset chunk, the corresponding World Cell that asset chunk belongs to is stored at the same index).
World Designer Grouping Listeners are Scriptable Assets, so in order to use them, you must create the physical scriptable object asset in your project hierarchy. To do this, you can place the following line of code above your class definition (Replacing SampleDesignerGroupingListener and Sample Listener with your own names):
[CreateAssetMenu(fileName = "SampleDesignerGroupingListener", menuName = "Deep Space Labs/SAM/Designer Grouping Listeners/Sample Listener")]
Once you add this line of code, you will be able to create the phsyical asset by right clicking a folder in your project hierarchy and using the Create asset menu.
Designer Grouping Listeners can be assigned to specific World Groupings via the Editing Controls tab of the Main Controls window of the World Designer Tool. You can find the Listener section under the Auto Disable and Auto Destroy options.
By default, no Listener fields will be available. You need to use the Add Listener button first! If using more than one Listener, the ordering matters, as Listeners are called in the order they appear (1, 2, 3, and so on).
If you no longer wish to use a Listener, use the X button next to the Listener to remove it. Do note, however, that you can temporarily disable Listeners by unchecking the toggle to the left of the listener. This allows you to disable the listener for a period of time, for example during an Assignment or other advanced operation. This can be very useful, as in some situations the assets may only be loaded temporarily and executing the listener code may just slow down the current operation without adding any real benefit.
It's important to take note of the following limitations when using World Designer Grouping Listeners:
1) References to the objects passed to the Listeners may become nulled out under different situations, such as unloading the scene the assets are in or performing an assembly reload. This, in combination with item 2 below, may cause issues.
2) Only newly loaded assets are passed to the OnAfterAssetChunksAdded method. You will need to account for this and in some cases (when references become "lost"), you may need to manually unload and re-load the Asset Chunks for the Grouping in order for the asset chunks to be detected as "new" and for them to trigger the OnAfterAssetChunksAdded method.
If storing the assets in a list, you may also need to check before using the assets to make sure they are not null (if they are null, they should be pruned from the list).
3) The World Cells passed into the OnAfterAssetChunksAdded method are fully configured and settings can be relied upon to be accurate, including the neighbors; however, there is no guarantee that the World Cells will remain valid after you return execution to calling code (for instance, they will be destroyed if you change which World Grouping is being edited by the World Designer Tool). As such, you should only use the World Cells in your method bodies and should not store references to them to be used later.
In addition to this, neighbors will not be set on World Cells when they are passed to the OnBeforeAssetChunksRemoved method, due to the nature of how the World Designer works. All values will be null!
4) It does not make much sense to make edits to the assets using this class, as the edits will be performed every time the asset is loaded and/or unloaded. Instead, this class is primarily intended to allow you to interface with other scripts that may need to know when an asset is loaded and unloaded, or to perform secondary logic.
If more than one listener is assigned to a Grouping, each listener is called in the order they appear in the World Designer Tool.
Each batch of assets/World Cells passed to the Listeners method are guaranteed to come from the same World Grouping and LOD Group. Therefore, you can check the first World Cell in the list (at index 0) to see which World Grouping and LOD Group the assets are from, and either exit early or perform custom logic depending on the World Grouping and/or LOD Group.