Uninomicon

Documenting the dark corners of the Unity Engine.

User Tools

Site Tools


entities.scenes

Entities.Scenes

SerializeUtility

SerializeUtility is responsible for writing entire Worlds to disk. It is written specifically for serializing Subscene Sections to disk in the editor, and then for streaming1) them in efficiently during runtime. It can support other use cases, but it is not designed to.

SerializeUtility supports two modes for deserialization:

  • Blocking (DeserializeWorld)
  • Async (BeginDeserializeWorld/EndDeserializeWorld).

But only a blocking mode for serialization (SerializeWorld). This is reasonable because it's edit-time functionality, and runs via a background ScriptedImporter.2)

Baking

There are two types of baking:

  1. Full Rebakes
  2. Incremental Bakes (EntityDiffer) 3)

A full rebake is triggered when:

  • A subscene is opened.
  • An assembly containing Baker classes is modified. 4)

Incremental bakes are triggered when:

  • Open subscenes are modified.

Serialization

Subscenes are serialized to the binary format in several spots:

  1. When closing an opened, dirty SubScene.
  2. After modifying an assembly with bakers, triggering a full rebake.
  3. When making a player build5).

Serialization uses a ScriptedImporter called SubSceneImporter. This importer is injected into the AssetDatabase directly, rather than using the normal attribute. The subscene unity files (ie. my_subscene.unity) do not get imported by this importer, rather, it operates on an in-memory “asset” representing the baked scene.

SubScene serialization can be debugged by placing breakpoints within SerializeUtility.SerializeWorld, and attaching to the Unity Import Worker process via the Rider “Attach to Unity Process…” dialogue.

SceneSectionStreamingSystem

AsyncLoadSceneOperation

These systems stream Sections of entities scenes6) into a World. It's intended for use at runtime, but will also be used in the editor when Entity Subscenes are “Closed for Edit” in the Hierarchy.

The AsyncLoadSceneOperation and associated jobs use the Async Mode of SerializeUtility (see above).

1)
see SceneSectionStreamingSystem
2)
ScriptedImporters run on separate Worker processes due to 2020.1's “Parallel Import” feature.
3)
Incremental bakes rely on a diffing + patching system known as EntityDiffer. This adds EntityGuid components to your entities. This system is also used to patch in changes from the authoring scene while the game is running.
4)
Important! Separate your bakers into separate classes if you want to avoid a full re-import of all baked scenes whenever you modify a gameplay assembly!
5)
Can be incremental
6)
subscenes
entities.scenes.txt · Last modified: 2023/06/24 03:51 by 97.126.63.199