Loading Content Scenes

Content Scenes provide functionality for loading and tracking content during a session. It utilizes various components and systems to manage the loading process, ensuring that the scene is loaded efficiently and can be tracked.

Content archives

Before content scenes can be loaded, they must be present in the content archive.

Ensure that scenes are added either by including them in the build settings or by downloading and adding them to runtime ahead of time. Use Unity Entities Content Management features to manage this process.

For more information, refer to Unity's Content Management documentation.

Content Scene Metadata

The ContentSceneMetadata struct is used to identify and load content scenes. It contains:

• Name: A FixedString128Bytes representing the name of the entity scene.
• Guid: A Hash128 representing the GUID of the entity scene.

When referencing a content scene, you need to use the entity scene GUID.

Loading Content Scenes

Client-Side

The LoadContentSceneClientSystem handles loading content scenes on the client side:

1. When a client first enters a session, it checks if a content scene has already been loaded.
2. If not, it attempts to load the scene specified in ILocalPlayerInfoService.SelectedContentScene.
3. It then sends a LoadContentSceneCommand to the server to request the scene be loaded on the server.

Server-Side

The LoadContentSceneServerSystem manages content scene loading on the server:

1. It listens for LoadContentSceneCommand requests from clients.
2. When a request is received, it checks if a content scene is already loaded.
3. If no scene is loaded, it loads the requested scene.

Tracking Loaded Scenes

Both client and server use the ContentSceneRef component to track the loaded content scene. This component contains the metadata of the scene and the entity representing the loaded scene.

Streaming Content Scenes

The ContentSceneStreamingSystem is responsible for managing the streaming and activation of the content scene:

1. When a ContentSceneRef is created, it is marked for preloading.
2. The system monitors the preloading progress of each section of the content scene.
3. Once all sections are preloaded, the scene is marked as "Ready to Activate".
4. Unless the WaitForContentActivation app setting is set to false, the system will wait for the application to signal that it is ready to activate the scene (by setting ContentSceneRef.ShouldActivate to true).
5. When the scene is ready to activate, the system will load the scene entity, showing the new content.

Note

Preloading content archives is only supported in builds. In the editor, we load the content during the activation stage. This can lead to longer transitions in the editor.

Important Considerations

1. Only one content scene can be loaded per session.
2. When referencing a content scene, use the entity scene (sub scene) metadata.
3. You can include multiple sub-scenes within your main content scene if you need to load multiple scenes.
4. Ensure that all clients agree on the content scene when entering the server to avoid conflicts.
5. The initial content scene is set through the LocalPlayerInfoService when transitioning to a session.