Traveler
The Traveler
class allows you to easily load and unload scenes (additively or not) and provides UniTasks to manage your call orders in code. It also handles initial logic in scenes.
Scene Handler
Imagine you need some initial preparations in a scene before everything starts working. To do this, you can define your own SceneHandler
for the scene.
public class GameSceneHandler : SceneHandler<GameSceneArgs>
{
protected override void SetupScene(GameSceneArgs args)
{
// Initialization logic here
}
}
public class GameSceneArgs : SceneArgs
{
// Define additional data here
}
What is the GameSceneArgs
Class?
The GameSceneArgs
class allows you to provide additional data to the scene when loading it. For example, you might need to create several levels with different difficulties. Instead of creating a separate scene for each difficulty, you can set up one scene and change its logic based on the data provided to it.
Here's an example:
public class PingPongSceneHandler : SceneHandler<PingPongSceneArgs>
{
[SerializeField] private Enemy m_Enemy;
protected override void SetupScene(PingPongSceneArgs args)
{
m_Enemy.SetSpeed(args.EnemySpeed);
}
}
[Serializable]
public class PingPongSceneArgs : SceneArgs
{
public float EnemySpeed;
}
In this example, we set the enemy's speed defined by PingPongSceneArgs
. The SceneArgs
class is derived from ScriptableObject
, so you can create multiple PingPongSceneArgs
assets for each difficulty and bind them to difficulty buttons in your menu scene.
You can also override the OnUnloadCallback
method to perform some logic before the scene unloads.
Scene Loading
To load a scene, simply call:
This method returns a UniTask, so you can await it to manage your calls if needed:
Scene Unloading
To unload a scene, simply call:
You can also unload all scenes except MAIN
by calling:
These methods also return a UniTask.
The LoadScene
method has an overload that allows you to get the SceneHandler
. If you know the type of SceneHandler
for the scene you are loading, you can use this type as a generic:
If you want to get the SceneHandler
after opening a scene, you can still do that using the following syntax:
or
if you have multiple scenes with this type of handler.
Loading Order
After calling the LoadScene
method of the Traveler
class, it will wait for the current operations (loading/unloading scenes) to finish. Then the scene will be loaded as usual, and a SceneLoadingMessage
will be fired. After the scene finishes loading, a SceneLoadedMessage
fires, and all objects in the scene will be traversed. If any object contains a SceneHandler
, it will be initialized by the Updater
and will start preparing the scene. Then all objects in the scene will be initialized, and a SceneOpenedMessage
will fire.
IMPORTANT! The scene handler must be a root game object in the scene.
On the UnloadScene
call, it will wait until the current operations (loading/unloading scenes) are done. Then a SceneUnloadingMessage
fires. If a SceneHandler
exists on this scene, the OnSceneUnload
method will be invoked, and all objects in the scene will be removed from the Updater
processing. Finally, it unloads the scene as usual, waits for it to finish, and fires a SceneUnloadedMessage
.