Skip to content

t1k:unity:base:boot-flow

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: boot flow, composition root, GameLifetimeScope, LifetimeScope, LoadingSceneScope, MainSceneScope, scene handoff, scene scope, VContainer root

/t1k:unity:base:boot-flow

Unity Boot Flow — Composition Root, Scene Scopes & Scene Handoff

Section titled “Unity Boot Flow — Composition Root, Scene Scopes & Scene Handoff”

Owns the two-scene boot flow of a DOTSTemplate-derived project end-to-end: 0.LoadingScene → 1.MainScene, the VContainer scope hierarchy that wires them, and the per-scene requirements a new scene needs to boot at all. For DOTS SubScenes, see t1k-unity-dots-core-subscene.

Scope — DOTSTemplate only. Every path, line number and code excerpt below describes DOTSTemplate. BaseUnityTemplate boots differently (checked against its main @ 77ad629, UnityBaseUnityTemplate/): GameLifetimeScope is public class (not internal sealed) at Assets/Scripts/GameLifetimeScope.cs:14 and registers only RegisterGameFoundation, RegisterUITemplate, a blueprint and GameRemoteConfig; the VContainer root asset is Assets/Settings/VContainerSettings.asset → Assets/Settings/GameLifetimeScope.prefab (there is no Assets/VContainer/); MainSceneScope (Assets/Scripts/Scenes/Main/MainSceneScope.cs) has no Start() home/gameplay branch — its Configure() calls InitScreenManually<HomeScreenPresenter>(). The two-scene flow, SceneScope parent fallback and per-scene requirements still apply there. On BaseUnityTemplate, read its own files; do not follow the line numbers below.

0.LoadingScene (Build Settings index 0 — the ONLY entry there; boots the app)
├─ GameLifetimeScope ← VContainer ROOT scope, DontDestroyOnLoad, instantiated once
└─ LoadingSceneScope ← per-scene CHILD scope
Start() publishes ManualInitScreenSignal → opens UITemplateLoadingScreenPresenter
→ awaits blueprint load (ILifecycleManager) → LoadAsync("1.MainScene", Single, activateOnLoad:false)
→ ActivateAsync("1.MainScene")
1.MainScene (Addressable, address "1.MainScene" — NOT in Build Settings; LoadSceneMode.Single UNLOADS 0.LoadingScene)
└─ MainSceneScope ← per-scene CHILD scope
Start(): CanGoHomeCondition ? EnterHomeAsync() : Play()

Consequence of the single-mode load: ISceneManager.LoadAsync defaults to LoadSceneMode.Single and LoadNextScene() never overrides it (UITemplateLoadingScreenView.cs:162) — loading 1.MainScene unloads 0.LoadingScene entirely. Anything the loading scene owns and does not reparent under the DontDestroyOnLoad root (its own Camera, its own AudioListener) is destroyed with it. GameLifetimeScope survives because VContainerSettings instantiates it once via DontDestroyOnLoad and every SceneScope resolves it as parent (see below) — it is not part of either scene.

Gotcha (verified): 1.MainScene is registered as an Addressable (Assets/AddressableAssetsData/AssetGroups/Scenes.asset:19, address 1.MainScene) and is absent from ProjectSettings/EditorBuildSettings.asset — only 0.LoadingScene is listed there. It loads through TheOne.ResourceManagement.AddressablesSceneManager (Addressables.LoadSceneAsync), not classic SceneManager.LoadScene. Adding a new scene to this flow means adding it to the Addressable Scenes group with a matching address — adding it to Build Settings alone does nothing for this pipeline.

The composition root — GameLifetimeScope

Section titled “The composition root — GameLifetimeScope”
  • Assets/Scripts/GameLifetimeScope.cs:58 — internal sealed class GameLifetimeScope : LifetimeScope, the ONE VContainer root for the whole game. Configure() registers GameFoundation, UITemplate, every TheOne.Features.* module, and project-local services (AudioManagerAdapter, LevelConfigService, UpcomingFeaturesCollector).
  • Wired as the VContainer root via Assets/VContainer/VContainerSettings.asset → RootLifetimeScope: {guid: fb7b0339be2a9dd4387825acfe4a1ecf} → Assets/VContainer/GameLifetimeScope.prefab. On first access, VContainer’s VContainerSettings.GetOrCreateRootLifetimeScopeInstance() instantiates that prefab and calls DontDestroyOnLoad on it — it survives every scene load in this flow, including the single-mode swap above.
  • Configure() (line 88) also calls RegisterGameFoundation, which spawns a scene-independent EventSystem from Assets/Resources/EventSystem.prefab, parented under the root’s transform — see “Per-scene requirements” below.

SceneScope — a named pattern, not a second root

Section titled “SceneScope — a named pattern, not a second root”

SceneScope (Packages/com.gdk.core/Scripts/DI/VContainer/SceneScope.cs:7) is an empty abstract class SceneScope : LifetimeScope — a marker type, not extra behaviour. LoadingSceneScope and MainSceneScope both derive from it and place ONE MonoBehaviour instance directly in their scene (verified: both carry m_PrefabInstance: {fileID: 0} in the scene YAML — not a prefab instance).

Neither overrides FindParent() nor sets a parentReference. Every SceneScope therefore resolves its parent through VContainer’s own fallback chain (LifetimeScope.GetRuntimeParent()): not root → no explicit parent → falls through to VContainerSettings.Instance.GetOrCreateRootLifetimeScopeInstance() — i.e. GameLifetimeScope. This is what makes a SceneScope a CHILD scope automatically, with zero per-scene wiring: Container.CreateScope(...) builds it as a child of the root’s IObjectResolver, so it can Resolve<T>() anything the root registered plus whatever it adds itself.

What breaks if a scene builds its own root instead: a plain LifetimeScope that is IsRoot (or one that Configure()s an unrelated container) cannot resolve anything GameLifetimeScope registered — every feature interface (IUserExperienceService, IHomeFlowHandler, IGameplayActionHandler, …) throws “No such registration” at Resolve<T>(). SceneScope exists specifically so a new scene never has to remember this — inherit it, don’t reinvent LifetimeScope per scene.

LoadingSceneScope — Assets/Scripts/Scenes/LoadingSceneScope.cs

Section titled “LoadingSceneScope — Assets/Scripts/Scenes/LoadingSceneScope.cs”

Start() resolves IPublisher<ManualInitScreenSignal> and publishes it with a freshly Instantiated UITemplateLoadingScreenPresenter (lines 14-19). That presenter (Assets/UITemplate/.../UITemplateLoadingScreenView.cs:94) drives the actual transition: BindData() awaits AOA + ILifecycleManager.LoadAsync (blueprints), then LoadNextScene() runs scenesManager.LoadAsync(NextSceneName, activateOnLoad:false, progress) → View.CompleteLoading() → scenesManager.ActivateAsync(NextSceneName) (lines 157-164). NextSceneName defaults to "1.MainScene" (line 33) and is a serialized field on the prefab — change it there, not in code, to retarget the loading screen.

MainSceneScope.Start() — the entry branch

Section titled “MainSceneScope.Start() — the entry branch”

Assets/Scripts/Scenes/MainSceneScope.cs:12-22, verbatim:

if (this.Container.Resolve<IUserExperienceService>().CanGoHomeCondition)
{
this.Container.Resolve<IHomeFlowHandler>().EnterHomeAsync().Forget();
}
else
{
this.Container.Resolve<IGameplayActionHandler>().Play();
}
  • IUserExperienceService.CanGoHomeCondition — remote-config-backed flag from TheOne.Features.UserExperience.* (Assets/TheOneFeature/.../IUserExperienceService.cs:8).
  • IHomeFlowHandler.EnterHomeAsync() — “Executes the full home-entry sequence: stops gameplay, plays animations, then opens the home screen” (IHomeFlowHandler.cs:10). Registered by RegisterUserExperience().
  • IGameplayActionHandler.Play() — starts/resumes a puzzle session (IGameplayActionHandler.cs:11). Registered by RegisterPuzzleDefaultActionHandlers().

Both handlers come from submodule feature registrations in GameLifetimeScope.Configure (#region Features), not from anything MainSceneScope itself registers — it only decides, it never implements.

Requirement0.LoadingScene1.MainSceneNotes
Camera (tag MainCamera)✅ own Camera✅ own CameraDoes NOT survive the single-mode load — each scene needs its own; the loading scene’s camera is destroyed when 1.MainScene loads Single. Anything reading Camera.main needs the current scene’s camera present first.
AudioListener✅ on the Camera✅ on the CameraOne listener per active scene; two active at once logs a Unity warning.
EventSystem❌ not needed in-scene❌ not needed in-sceneSpawned ONCE by RegisterGameFoundation from Assets/Resources/EventSystem.prefab, parented under the root’s transform (GameFoundationVContainer.cs:76-78) — lives on the DontDestroyOnLoad root, survives every scene swap. Don’t add a second one.
Canvasn/an/aNeither .unity file contains an in-scene Canvas GameObject (verified). UI is spawned per-screen via UITemplate’s screen-flow system; each screen prefab owns its own CanvasGroup (BaseView.cs:9), not the scene.
A SceneScope-derived MonoBehaviour✅ LoadingSceneScope✅ MainSceneScopePlaced directly in the scene, not a prefab.

Full step-by-step with verification commands: references/new-project-checklist.md.

The lifecycle pipeline can be registered and still never run

Section titled “The lifecycle pipeline can be registered and still never run”

LoadingSceneScope is the only thing that instantiates UITemplateLoadingScreenPresenter, and that presenter is the only caller of ILifecycleManager.LoadAsync. A project that replaces 0.LoadingScene with its own boot scene registers ILoadable / IAsyncEarlyLoadable services that never execute — a measured path had BlueprintManager, AssetsLoader, UserDataManager, LocalizationService and LevelConfigService all idle while AssetsLoader’s preload labels looked live.

  • Do not budget their work (measured 0 bytes at boot) and do not call them dead — re-entering the flow adds all of it at once.
  • Do not assume “no caller” from an Assets/ grep — the caller lives in Library/PackageCache/com.theone.lifecycle@* (rules/negative-result-scope.md).
  • The cost a real boot does pay is usually serial awaits: one request per table in a loop (measured 51 files / 848 KB ≈ 2 s over loopback) and a foreach (var type in types) user-data loop (≈964 ms). Count those before optimizing the parse.

Mechanism, the never-executed service table, ordering semantics: references/lifecycle-pipeline.md.

  1. A per-platform scripting define can compile a second IAnalyticEventFactory implementation, and UITemplateThirdPartyVContainer.cs:50 resolves it with GetSingleDerivedType(), which throws unless exactly one candidate exists — Configure() never finishes, so boot dies on the container’s first resolve, Android/iOS only (Standalone’s define set differs). Full write-up: t1k-unity-base-game-patterns/references/vcontainer-registration-override.md. Background: scriptingDefineSymbols are stored per build target, so open and compile on the platform you actually ship.
  2. 1.MainScene is not in Build Settings — see the two-scene-flow gotcha above; don’t “fix” its absence there, it’s by design (Addressables-backed load).
  3. A boot guard that sets EditorSceneManager.playModeStartScene (e.g. to force Play through 0.LoadingScene) silently breaks EVERY PlayMode test run — it redirects Play away from the test runner’s own generated bootstrap scene too, and com.unity.test-framework has zero defence against the override. Full mechanism, fix, and verification recipe: t1k-unity-testing-workflow § Gotchas.
  • t1k-unity-base-scene-management — generic Unity scene loading/transition patterns; the camera dangling-GUID gotcha lives there in full.
  • t1k-unity-base-game-patterns — VContainer registration-override gotcha (IAnalyticEventFactory collision).
  • t1k-unity-base-project-structure — where Assets/Scripts/ (composition root) sits in the folder layout.
  • t1k-unity-dots-core-subscene — DOTS SubScene loading (out of scope here — this skill covers the Mono/VContainer boot flow only).
  • t1k-unity-testing-workflow — the playModeStartScene PlayMode-test-breaking gotcha and its fix (Gotcha #4 above points here for full detail).
FileContents
references/new-project-checklist.mdOrdered, verifiable checklist for booting a fresh DOTSTemplate-derived project
references/lifecycle-pipeline.mdWho drives ILifecycleManager, what never runs, the serial boot shapes and their measured cost