The Default Transition Controllers are great for performing shader based transitions using a single shader property, or for performing Transform based transitions. To perform other types of transitions, the creation of a custom Cell Visual Transition Controller is required. Fortunately, this section will guide you through the process of creating one.
In order to create a custom Cell Visual Transition Controller, create a new MonoBehaviour script that derives from the CellVisualTransitionController base abstract class. This abstract class defines several abstract methods which need to be overridden in order to implement the logic required by the Streamable Assets Manager to transition World Cells.
You should place your class inside of the DeepSpaceLabs.SAM namespace, which will make the CellVisualTransitionController class available and also help avoid naming conflicts with 3rd party assets or your own code.
--Special Note--
An easy way to start with your custom class is to hover over your custom class name and choose the option Show potential fixes -> Implement abstract class. This will provide default overrides for all abstract class members.
In addition, we recommend adding the following attribute above your class, which will ensure the custom chunk manager is shown with other Cell Visual Transition Controllers in menus:
[AddComponentMenu(GlobalValues.COMPONENT_ROOT_PATH + "Visual Transition Controllers/Custom Transition Controller Name")]
The base CellVisualTransitionController class makes use of Unity's Awake method, so if you'd like to add Awake related logic to your custom class, you will need to override this method. It is called automatically at the end of the base CellVisualTransitionController's Awake method.
This method is queried from Awake to determine whether they each Asset Chunk Type should be allowed to transition using the controller. Note that the only input data about the World Cells is their Chunk Type, so this should be the only determing factor of whether the Cell's can be transitioned.
Using a fixed return value of true can be used if you know that all Asset Chunks Types should be transitionable.
The most useful place for making use of this method is when using World Groupings that have different Asset Chunks. For instance, the default transitioners allow you to specify whether the transitioners should be used with Unity Terrain, which is useful for Streamable Grids that have a mix of LODs containing Terrain and regular Unity Meshes. Without this method, the default transitioners would be required to work for both Unity Terrain and regular Meshes.
The method is queried once for each of the four asset Chunk Types, and the returned values are stored; as such, the first value returned for each asset Chunk Type is used for the lifetime of the Transition Controller.
When performing LOD transitions where the LODs use different asset Chunk Types, the LOD transition is performed using the TransitionBetweenLevelsOfDetail method only if both LOD's asset Chunks are transitionable. If only one group's asset Chunk Type is transitionable, that group is transitioned using the TransitionToVisibleState or TransitionToInvisibleState method instead.
This method should reset the properties/fields on the World Cells' Asset Chunks to whatever values represent the Visible State. It differs from the Transition methods below in that this method may not necessarily transition the Asset Chunks from Invisible to Visible in the eyes of the Player. You should also not ever Activate the World Cells from within this method, nor run secondary logic tied to the visibility of the Asset Chunks.
The method is used in the Editor by the World Designer tool (when Asset Chunks are stored in the Invisible State) and while the application is running before returning Asset Chunks to the Chunk Manager (when Asset Chunks are stored in the Visible State).
The latter is required to ensure Asset Chunks that have just been transitioned to the Invisible state are passed back to the Chunk Manager in the same state as Asset Chunks that might be newly loaded by a Chunk Streamer. This ensures that if those Asset Chunks are pooled for later use, they are in the same state as newly loaded Assets, which allows the World to make assumptions about the Visual State of all Asset Chunks passed to it from Chunk Managers.
For more information, please open the API window via the button at the top of this window.
This method should reset the properties/fields on the World Cells' Asset Chunks to whatever values represent the Invisible State. It differs from the Transition methods below in that this method may not necessarily transition the Asset Chunks from Visible to Invisible in the eyes of the Player. You should also not ever Deactivate the World Cells from within this method, nor run secondary logic tied to the visibility of the Asset Chunks.
The method is used in the Editor by the World Designer tool (when Asset Chunks are stored in the Invisible State) and while the application is running after retrieving Asset Chunks from the Chunk Manager (when Asset Chunks are stored in the Visible State).
The latter is required to ensure Asset Chunks that have just been retrieved from the Chunk Manager are in the proper state expected by the Transition Controller's ImmediatelyTransitionToVisibleState, TransitionToVisibleState, and TransitionBetweenLevelsOfDetail methods.
For more information, please open the API window via the button at the top of this window.
Same as TransitionToVisibleState, except the visible state must be transitioned to in a single frame. True transition effects cannot be achieved as a result of the single frame requirement, but this method is only called in instances where the Player should not see what is going on, so the lack of transition effects is actually beneficial.
Transitions World Cells to a Visible State, optionally over multiple frames. This is used in 2 circumstances:
1) Just after Auto Activating newly loaded World Cells (if option is enabled in inspector).
2) When performing LOD transitions and the Transition From Cells are not able to be transitioned (because the CanWorldCellsBeTransitioned query returned false). In that case, the Transition To cells are transitioned as if they were newly loaded World Cells, just as with option 1.
It is recommended to let the World auto activate World Cells before transitioning them to a Visible State, however you always have the option to disable auto-activation and instead activate the World Cells (and more specifically, their Asset Chunks) manually. In fact, when using non-game object based Asset Chunks, you must activate them manually!
If using manual Activation, the best place to do so is within the Transition Controller, just before beginning the transition process.
Transitions World Cells to an Invisible State, optionally over multiple frames. This is used in 2 circumstances:
1) Just before Auto Deactivating World Cells that are no longer needed (if option is enabled in inspector).
2) When performing LOD transitions and the Transition To Cells are not able to be transitioned (because the CanWorldCellsBeTransitioned query returned false). In that case, the Transition From cells are transitioned as if they were regular World Cells that are being deactivated, just as with option 1.
It is recommended to let the World auto deactivate World Cells after transitioning them to an Invisible State, however you always have the option to disable auto-deactivation and instead deactivate the World Cells (and more specifically, their Asset Chunks) manually. In fact, when using non-game object based Asset Chunks, you must deactivate them manually!
If using manual Deactivation, the best place to do so is within the Transition Controller, just after ending the transition process.
Transitions World Cells between two Levels of Detail. The transitionFrom Cells should be transitioned from Visible to Invisible while the transitionTo Cells are transitioned from Invisible to Visible.
It is recommended to let the World auto activate the transitionTo Cells before TransitionBetweenLevelsOfDetail is called, and also to let the World auto deactivate World Cells after TransitionBetweenLevelsOfDetail is called. However, you always have the option to disable auto activation/deactivation and instead activate/deactivate the World Cells (and more specifically, their Asset Chunks) manually. In fact, when using non-game object based Asset Chunks, you must activate/deactivate them manually!
If using manual Activation/Deactivation, the best place to do so is within the Transition Controller, performing activation at the start of the method just before the transitionTo Cells are transitioned to a Visible State, and performing deactivation at the end of the method just after transitionFrom Cells are transitioned to an Invisible State.
--Special Note--
These three final methods use a return type ofIEnumerator
1) Simply include yield return statements within the method's body where the returned object is either null or an instance of a YieldInstruction.
The compiler will auto generate a state machine class, which will be used to iterate the method's logic. The drawback of this technique is every time the method is called, a new instance of the auto generated class is created, resulting in garbage generation throughout the lifetime of the game.
2) Implement one of the reusable enumerator classes found within the API.
This strategy is harder to implement as you will need to implement the state machine logic yourself, as well as perform some other code related task necessary to use the reusable enumerators. It is recommended for experienced coders only!
If you elect to go with option 2, you can find detailed information on how to use the Reusable Enumerator classes in the Yield Enumerator Section within the Secondary Non Components Chapter.
If you need to create a custom Editor for your custom Transition Controller, make your custom editor derive from CellVisualTransitionControllerEditor rather than Editor.
Then, write the custom editor like you normally would, with one change. If you have code that needs to run in OnEnable, override the OnEnableExtended method instead and put it there.
Doing this will give you access to the default Animation Curves that the other Transition Controllers have.