Discussing implementation and ideas for AdvancedSceneManager

[VirtualMaestro]

Hey Joao and everyone interested in the Advanced scene manager!
Let's discuss the current version, possible improvements and features.
I'm not deep into the code base, so please correct me if something has no sense or just insane))

I think, first of all there should be a vision "how do I see using of the scene manager". (all the questions just to think about)

1. Currently, a user must create an instance for the manager to use.
   Is there really a necessity for this? Or in another word, do I really need to have an instance?
   If I have an instance I can have multinstances. For what?
   If I have an instance (or instances) means I can remove the instance.
   In this case what should happen?
   What does it mean that instance was removed? Could it be that some scenes were related only to some instance and when this instance was removed these scenes also should be unloaded? Will it be easy to use such manager?
   Currently, there is a "Dispose" method that only clears up internal lists.
   So, should it be by the RAII principle (Resource Acquisition Is Initialization)?
   Probably not, since a scene is a resource like a prefab or texture that should be handled a ResourceManager that is higher level of manager that is out of the scope of a SceneManager. Or probably, this is not a bad idea. Need to think more))

2. Is there a sense of not having all the active scenes in the manager?
   I'm referring to the constructor with the bool param and with the array of scenes.
   I see such lib as a full "replacement" of the Unity's SceneManager, so no need to use the standard one anymore. (quotes, because under the hood the lib uses the standard one).

3. Simplicity-of-use is the most value for me. Plug and go. Without thinking "in which MonoBehaviour phase I have to use it? Does my manager know about all the loaded scenes?" Or, like we discussed in another thread this kind of hack could be implemented inside the manager: _sceneManager.UnloadAsync(SceneManager.GetSceneByPath(LoaderSceneInfo));
   Ideally, you can stupidly plug in and go without thinking about possible caveats.
   Probably, some of these simplicity could be solved by directly hooked into the Unity's player loop.
   (I did such in my kind of coroutine manager https://pastebin.com/HBhUeuf2 or here you can also find such solution https://youtu.be/ilvmOQtl57c)

4. Continue the simplicity topic, can we say that all the manager's API (like loading/unloading) is asynchronous? Or in another word will be there synchronous API?
   Let's say we see that there are no sense to have a synchronous API, then we can simplify the API even more : AdvancedSceneManager.Load(), AdvancedSceneManager.Transition.
   Also, currently the API uses ValueTask everywhere, it implies that we have more situations when the methods (Load/Unload) return instant result. We need to figure out if this is not the case then better to use Task instead.
   E.g. I did a simple test where the manager on 'Scene_A' loads a 'Scene_B' by clicking UI button and unloads 'Scene_A' and then on "Scene_B" a user click another UI button to return back to Scene_A and unloads Scene_B. Everytime when by loading or unloading it takes 4 frames it means that it is loaded/unloaded asynchronous and in this case it is better to use Task instead of ValueTask.

5. Hide if it is possible all the interfaces, structs, class that are not meant to be used by the users, so internal.

6. One of the possible feature is a scenario or configurations for loading/unloading scenes. So, you have a configuration for loading of multiple scenes and unloading some other scenes. You could set this scenario and everything happens.
   I did something like this (I used it in a game), but it was tightly coupled to my framework. Here is an example how it looks like https://pastebin.com/WzmfpeG9.
   Not the best implementation, but to bring my idea https://github.com/VirtualMaestro/StubbUnity/blob/master/StubbUnity/StubbUnity/Src/StubbFramework/Scenes/Configurations/ScenesLoadingConfiguration.cs.

Again, these the brief thoughts, probably there are no sense or simply is wrong, probably some of them sparkle an idea to move on.

[joaoborks]

Hey @VirtualMaestro, thanks for taking the time to share your feedback and sorry for taking long to respond.

I totally agree with your simplicity and usability vision. I've released a new version with a Static API to interact with the Advanced Scene Manager, that works just like the Unity Scene Manager. It does not require you to manually initialize the scene manager nor store a reference to it.

In short, this is my proposed usability for v4 (using your code from #48 as example):

// This namespace lies in a separate Assembly Definition file with the same name.
using MyGameDevTools.SceneLoading.Api;

// [...]

private static readonly string MainScenePath = "Assets/Client/Scenes/Main.unity";

private void _OnConfigFileLoaded()
{
    AdvancedSceneManager.TransitionAsync(MainScenePath);
}

That's it, no more ILoadSceneInfo or anything else. I think that probably covers the topics mentioned in 1, 2 and 3.

Topic 4

There will probably never be any synchronous API, since it's all relying on the Unity Scene Manager internally. However, since all calls can be awaited and be given a CancellationToken, I'd maintain the Async suffix to indicate that. About your ValueTask argument, I didn't dig too much into it since originally I was looking for a replacement for UniTask. It seemed natural to switch from a struct to a struct instead of a class, but as far as I've just read that might have been a mistake. It would be helpful if you could share more about this, as I'm not so experienced with that. I'd happily use Unity's Awaitables if that were the best choice, but that's only Unity 6+.

Topic 5

Most users won't ever need to touch an ILoadSceneInfo or SceneParameters, but my experience suggests that I should allow them to customize and expand over the package to their own needs if they want. I'm reluctant to internalize all access, so what I've done instead is put the public static API in its own Assembly Definition (MyGameDevTools.SceneLoading.Api), so none of the complexity is exposed to the users. However, if you have a complex initialization process or any other non-conventional environment, you can still tailor the package to your project by accessing all of its internal structures.

Topic 6

Loading, unloading and transitioning to multiple scenes is supported, the only detail is that the transition only unloads the active scene (if any). You could save the multiple scenes as a template (which would inevitably become a complex usage) by using a SceneParameters struct. But for simple multiple scene operations you can just pass in an array of scene references directly (names, paths, indexes or addressable references).

Conclusion

My vision for this package is that it's as simple to use as the standard Unity Scene Manager, while very efficiently handling the complexity to offer scene transitions and allow the usage of Addressables within the same API.

[VirtualMaestro]

Hey Joao,
Great work! I'll update and test again to see how to use it.
I haven't used 'SceneParameters' yet, so I need to figure out how to use it.

About ValueTask. Yes, the ValueTask is a struct and will be efficient only if during the whole app life-cycle most of the api of a library return synchronous result. Let's take a look at an example.
Let's say you have a resource manager. It has an asynchronous method, 'CreateAsync' that creates and returns ValueTask with a prefab instance by its name. For first time when you request a specific Prefab it has to make a request to the server, download a bundle, then create a prefab and return it.
In this case the ValueTask will cost more because we need an async operation and internally it creates the Task instance and do the async operation.
But the next time you request the same Prefab. In this case the Prefab was cached from the last request and the instance can be returned immediately within the same frame, so no async is needed.
In this case the ValueTask will cost less because internally it will not create the Task instance and the result will be immediately returned with the ValueTask.
So, it is only about how often in the real cases the async operation will used during the app lifetime:

• more sync - use ValueTask
• more async - use Task

So, ValueTask is a wrapper for a Task, but internally the Task instance will not be created if a result is ready immediately, and no async is needed.

In terms of SceneManager if we load scene we need an async operation then we unload scene and load again and we need again async operation, so I presume we will never have a case when we load a scene instantly without async operation.
You can test and see results.

[joaoborks]

Thank you for the explanation! I've done some additional research around this as well and it seems it would be more beneficial to replace all return types to Task. The scene manager operations are all async by design, aligning with your description of the Task usage.

I'm going to implement this with the other change I mentioned in #48, to unload any matching scene, in the next prerelease version (4.0.0-pre.3).

[joaoborks]

I've just released version 4.0.0-pre.3 replacing all ValueTask return types to Task. The scene manager continues to work as expected. I've also included that change mentioned in #48, check here for more details about it.