Best way to unload a scene and world of entities?

Unity Engine
, ,
1

I’m trying to figure out the best or recommended way to handle scene transitions when using entities, particularly when it comes to cleaning up instantiated entities that don’t belong to a subscene.

Suppose for instance that I have two scenes - a main menu, and the game - and that I want to transition back and forth between them.

In mono-behavior land we’d simply use SceneManager.LoadScene(“Game”) to go from the menu to the game, and vice versa to get back. Then we just have to be wise about when we call it and handling all of the OnDisable and OnDestroy events.

In entities land extra work is involved, as changing scenes doesn’t automatically destroy all entities due to them belonging to Worlds rather than to a scene. Subscenes partly address the issue via SceneSystem.UnloadScene, but this will only destroy the entities which belonged to that subscene - not any additional entities which were instantiated during gameplay.

This means that we need to have a separate process for removing any of these instantiated entities when we unload the scene. EntityManager.DestroyAndResetAllEntities() and World.Dispose() look like they have some potential, but I’m not clear on when and how they should be used, or even if they should be used for this purpose - for instance using them within system updates seems to be a bad idea (or not possible in the case of World.Dispose()).

I guess my questions are:

  • What are the best or at least some good ways of cleaning up instantiated entities when unloading a scene?
  • Is there a particular time in a frame when this should or shouldn’t be done - e.g. should it be within a specific system group, does it matter which command buffer we use, are there times where we can outright call a catch all function like EntityManager.DestroyAndResetAllEntities()?
  • Should this be done with a dedicated system (e.g. a “Delete all entities” system which queries and destroys all entities, perhaps based on a tag or the presence of a singleton), or are there built in functions better suited to the task?
  • What about scenarios where we want to keep some entities around regardless of the scene - aka something akin to DontDestroyOnLoad?

My hope is that there’s a simple and elegant way to handle it that will work for 99% of scenarios. The ideal scenario would be something that can be encapsulated in a single method, a sort of “World.Unload()” for lack of a better term.

I suspect doing it with a system at a certain time in the frame (the end? the beginning?) is the “right way”, but it’s a bit confronting that this will likely mean waiting one or more frames and polling for completion before moving on to the next scene, which adds complexity.

2

Relevant: https://github.com/Dreaming381/Latios-Framework-Documentation/blob/main/Core/Scene Management.md

That’s how the Latios Framework is approaching it, though it’s a little hellish to be honest.

1 Like
3

I was going for a very specific behavior with that implementation. There’s a reason the standard bootstrap templates don’t install it.

As long as you only instantiate entities from prefabs and don’t try to create them fully from scratch, you don’t have to worry about this because they will unload when the subscene unloads, which automatically happens when the real scene unloads. This is good enough for most projects.

4

Ah, good to know - didn’t realize prefabs tie them to the subscene.

5

I think what you want is World.Dispose(). As you said World.Dispose() cannot be called while a system in that world is executing, so you’ll want to have separate worlds for your main menu (or some other orchestrating world) and your core game. Your menu/orchestrator world will get notified in whatever way you like (existence of a component for example) that it ought to dispose the game world and it’ll do so by calling World.Dipose(), neatly destroying everything in there in one call.

Regular scene loads/unloads should handle the rest if you have situations where you don’t want to dispose the whole world but just change scenes. As for entities that should stick around after subscene unloads I’d not place them in the subscenes that get unloaded in the first place if at all possible. You can always create new entities, copy entities between worlds, and so forth if you do need to preserve data from a subscene.

1 Like