Skip to content

t1k:unity:dots-core:subscene

FieldValue
Moduledots-core
Version3.56.1
Efforthigh
Tools—

Keywords: baking, DOTS, scene management, subscene

/t1k:unity:dots-core:subscene

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).

Authoring (MonoBehaviour) → Baker → BlobAsset/Entity → EntityScene (.entities file)
  1. Add SubScene component to a GameObject in the Editor scene
  2. Unity bakes GameObjects inside to entities on save / domain reload
  3. At runtime, SceneSystem.LoadSceneAsync loads the .entities binary
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 updates
  • TransformUsageFlags.Renderable — entity renders but doesn’t move
  • TransformUsageFlags.None — pure data entity, no transform overhead

DependsOn(obj) — re-bake when obj changes (prefabs, ScriptableObjects, textures).

ModeWhenTradeoff
LiveConversionEditor Play ModeFast iteration; some fidelity gaps
Full bakeBuild / asset importAccurate; slower

LiveConversion only processes dirty objects — don’t assume full re-bake on every change.

MonoBehaviours that must stay managed (physics callbacks, third-party SDKs):

  • Add a CompanionLink component 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
// Async load
var sceneEntity = SceneSystem.LoadSceneAsync(state.WorldUnmanaged,
new Unity.Entities.Hash128(sceneGUID));
// Check loaded
bool 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 index
  • Stale cache: after changing a Baker, rename Library/EntityScenes aside (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 GetEntity references only

  • Shared components during baking: ISharedComponentData values 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 LocalTransform offsets, not preserved as ECS hierarchy unless TransformUsageFlags.Dynamic is set with WithDynamicUsage

  • BlobAssetReference: must be created via BlobBuilder inside Baker; not valid to create at runtime outside a Baker

  • A baker that only calls CreateAdditionalEntity can lose every entity it made (Entities 6.5.0). If a Baker never puts a component on its own primary, that primary is unreferenced and — when the baker also never requests a transform usage on itself — carries RuntimeTransformUsage == None. Entities tags exactly that pair with RemoveUnusedEntityInBake (Unity.Entities.Hybrid/Baking/BakedEntityData.cs:964) and RemoveEntityInBakeDestroyEntitiesSystem destroys it during EntitySceneOptimizations; separately, entity-scene serialization moves only entities matching All<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 — a DynamicBuffer<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 still 0). 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 .unity file 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 an ImportAssetOptions.ForceUpdate reimport (in this project: Tools/DOTS RPG/Force SubScene Rebake, dots-core/Editor/Utilities/ForceSubSceneRebake.cs). Rule of thumb: if you did not see fresh Start 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 .unity SubScene 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!114 document 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 you git 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 guard grep -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.

ReferenceContent
references/stale-authoring-guid.mdStale 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.mdWhy 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.mdWhy 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-ReferenceContent
→ See t1k-unity-dots-core-ecsGeneral 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-architectureWhen to use SubScene vs runtime spawning