t1k:unity:dots-core:subscene
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | high |
| Tools | — |
Keywords: baking, DOTS, scene management, subscene
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:subsceneDOTS SubScene Baking
Section titled “DOTS SubScene Baking”Handles SubScene authoring → baking → runtime entity loading patterns.
Does NOT handle general ECS patterns (→ t1k-unity-dots-core-ecs) or architecture decisions (→ t1k-unity-dots-core-architecture).
SubScene Lifecycle
Section titled “SubScene Lifecycle”Authoring (MonoBehaviour) → Baker → BlobAsset/Entity → EntityScene (.entities file)- Add
SubScenecomponent to a GameObject in the Editor scene - Unity bakes GameObjects inside to entities on save / domain reload
- At runtime,
SceneSystem.LoadSceneAsyncloads the.entitiesbinary
Baker Patterns
Section titled “Baker Patterns”class MyBaker : Baker<MyAuthoring>{ public override void Bake(MyAuthoring authoring) { var entity = GetEntity(TransformUsageFlags.Dynamic); AddComponent(entity, new MyComponent { Value = authoring.value }); // Declare dependency so baker re-runs when referenced asset changes: DependsOn(authoring.referencedAsset); }}GetEntity flags:
TransformUsageFlags.Dynamic— entity has LocalTransform, needs per-frame updatesTransformUsageFlags.Renderable— entity renders but doesn’t moveTransformUsageFlags.None— pure data entity, no transform overhead
DependsOn(obj) — re-bake when obj changes (prefabs, ScriptableObjects, textures).
LiveConversion vs Full Bake
Section titled “LiveConversion vs Full Bake”| Mode | When | Tradeoff |
|---|---|---|
| LiveConversion | Editor Play Mode | Fast iteration; some fidelity gaps |
| Full bake | Build / asset import | Accurate; slower |
LiveConversion only processes dirty objects — don’t assume full re-bake on every change.
Hybrid Objects (Non-Baking)
Section titled “Hybrid Objects (Non-Baking)”MonoBehaviours that must stay managed (physics callbacks, third-party SDKs):
- Add a
CompanionLinkcomponent via baker - Unity keeps the GameObject alive and syncs its transform from entity
- Never add both an ECS component and a managed component for the same data
Entity Scene Loading
Section titled “Entity Scene Loading”// Async loadvar sceneEntity = SceneSystem.LoadSceneAsync(state.WorldUnmanaged, new Unity.Entities.Hash128(sceneGUID));
// Check loadedbool ready = SceneSystem.IsSceneLoaded(state.WorldUnmanaged, sceneEntity);
// Section loading (large worlds)SceneSystem.LoadSceneAsync(state.WorldUnmanaged, guid, new SceneSystem.LoadParameters { AutoLoad = false });// Then manually load sections by indexHard rules
Section titled “Hard rules”-
Stale cache: after changing a Baker, rename
Library/EntityScenesaside (Editor closed) and reimport to force full rebake -
Baking order: Bakers run in undefined order — never read another entity’s component inside a Baker; use
GetEntityreferences only -
Shared components during baking:
ISharedComponentDatavalues affect chunk assignment at bake time; changing them post-bake causes chunk moves -
Transform flattening: deep GameObject hierarchies become flat entity lists — parent-child transform relationships are baked into
LocalTransformoffsets, not preserved as ECS hierarchy unlessTransformUsageFlags.Dynamicis set withWithDynamicUsage -
BlobAssetReference: must be created via
BlobBuilderinside Baker; not valid to create at runtime outside a Baker -
A baker that only calls
CreateAdditionalEntitycan lose every entity it made (Entities 6.5.0). If aBakernever puts a component on its own primary, that primary is unreferenced and — when the baker also never requests a transform usage on itself — carriesRuntimeTransformUsage == None. Entities tags exactly that pair withRemoveUnusedEntityInBake(Unity.Entities.Hybrid/Baking/BakedEntityData.cs:964) andRemoveEntityInBakeDestroyEntitiesSystemdestroys it duringEntitySceneOptimizations; separately, entity-scene serialization moves only entities matchingAll<SceneSection>filtered to{sceneGUID, Section = 0}(Unity.Scenes.Editor/EditorEntityScenes.cs:305-323, moved at:512). Bake reports success, Console is clean, entities are absent at runtime. Fix the shape: put spawn-critical data on the primary — aDynamicBuffer<T>when it is a list — so no additional entities exist to be dropped. ⚠️ Do not conclude that stripping the primary cascades to its additional entities: that claim was tested and disproven (primary kept alive → additional entities still0). Full mechanism, the surviving baker shape, the disproven claim, and how to tell “root absent” from “configs absent”:references/unreferenced-primary-stripping.md. -
A plain asset import (for example
t1k unity refresh) on a.unityfile does NOT rebuild the entity scene. A plain import refreshes the scene asset without re-running the SubScene bake, so a source change you just made is not in the entity scene you then measure — and every conclusion drawn from that Play session is about the old bake. Forcing a real rebake needs anImportAssetOptions.ForceUpdatereimport (in this project:Tools/DOTS RPG/Force SubScene Rebake,dots-core/Editor/Utilities/ForceSubSceneRebake.cs). Rule of thumb: if you did not see freshStart importing Assets/SceneDependencyCache/<guid>…→-> (artifact id: …)lines in the worker log, no bake happened, whatever the import call returned. -
Never hand-write a
#comment into a baked.unitySubScene file — the bake path and the editor serializer disagree, and BOTH failures are silent. (1) The additive scene open that feeds the bake rejects the comment and truncates the entity buffer at that line:Unable to parse file ...: [Parser Failure at line N: Expect ':' between key and value within mapping], every element after the comment silently dropped — until the parser recovers at the next--- !u!114document boundary, so other components in the same scene still bake and the damage looks local and unrelated. (2) Merely opening the SubScene (any PlayMode run) makes Unity rewrite the file without the comment — so an unexplained diff (“corruption”) that yougit checkout --away actually restores the broken state; the strip is Unity repairing the file. Guidance: keep rationale in the authoring.cs, never in the baked.unity; regenerate via the scene builder over hand-patching YAML; cheap class-wide guardgrep -rn '^[[:space:]]*#' --include='*.unity' --include='*.prefab' --include='*.asset'. A test asserting the baked buffer’s expected length catches this in seconds where the runtime symptom costs hours. Concrete case + symptom→diagnosis mapping:references/comment-in-baked-unity.md.
Reference Files
Section titled “Reference Files”| Reference | Content |
|---|---|
references/stale-authoring-guid.md | Stale authoring-MonoBehaviour GUIDs after a type move: why the Console stays clean, which logs carry the evidence, [MovedFrom]’s limits, recovery chain, GUID verification |
references/unreferenced-primary-stripping.md | Why a CreateAdditionalEntity-only baker loses its entities; RemoveUnusedEntityInBake + SceneSection serialization filter with source refs; the surviving buffer-on-primary shape; the disproven cascade claim |
references/comment-in-baked-unity.md | Why a hand-written # comment in a baked .unity truncates the entity buffer at that line and why PlayMode then strips the comment; the timeline-truncation incident; guards and the buffer-length test |
| Cross-Reference | Content |
|---|---|
→ See t1k-unity-dots-core-ecs | General baking pipeline, IComponentData, SystemAPI |
→ See t1k-unity-dots-core-ecs/references/blobconfig-migration.md § “Lazy-Resolve Variant” | A system’s SubScene-streaming-latency race with its own lazy BlobConfigRegistry resolve — latch the flag only on success |
→ See t1k-unity-dots-core-architecture | When to use SubScene vs runtime spawning |