t1k:unity:base:boot-flow
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: boot flow, composition root, GameLifetimeScope, LifetimeScope, LoadingSceneScope, MainSceneScope, scene handoff, scene scope, VContainer root
How to invoke
Section titled “How to invoke”/t1k:unity:base:boot-flowUnity 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.
BaseUnityTemplateboots differently (checked against itsmain@77ad629,UnityBaseUnityTemplate/):GameLifetimeScopeispublic class(notinternal sealed) atAssets/Scripts/GameLifetimeScope.cs:14and registers onlyRegisterGameFoundation,RegisterUITemplate, a blueprint andGameRemoteConfig; the VContainer root asset isAssets/Settings/VContainerSettings.asset→Assets/Settings/GameLifetimeScope.prefab(there is noAssets/VContainer/);MainSceneScope(Assets/Scripts/Scenes/Main/MainSceneScope.cs) has noStart()home/gameplay branch — itsConfigure()callsInitScreenManually<HomeScreenPresenter>(). The two-scene flow,SceneScopeparent fallback and per-scene requirements still apply there. On BaseUnityTemplate, read its own files; do not follow the line numbers below.
The two-scene flow
Section titled “The two-scene flow”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, everyTheOne.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’sVContainerSettings.GetOrCreateRootLifetimeScopeInstance()instantiates that prefab and callsDontDestroyOnLoadon it — it survives every scene load in this flow, including the single-mode swap above. Configure()(line 88) also callsRegisterGameFoundation, which spawns a scene-independentEventSystemfromAssets/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 fromTheOne.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 byRegisterUserExperience().IGameplayActionHandler.Play()— starts/resumes a puzzle session (IGameplayActionHandler.cs:11). Registered byRegisterPuzzleDefaultActionHandlers().
Both handlers come from submodule feature registrations in GameLifetimeScope.Configure
(#region Features), not from anything MainSceneScope itself registers — it only decides, it
never implements.
Per-scene requirements checklist
Section titled “Per-scene requirements checklist”| Requirement | 0.LoadingScene | 1.MainScene | Notes |
|---|---|---|---|
Camera (tag MainCamera) | ✅ own Camera | ✅ own Camera | Does 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 Camera | One listener per active scene; two active at once logs a Unity warning. |
EventSystem | ❌ not needed in-scene | ❌ not needed in-scene | Spawned 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. |
Canvas | n/a | n/a | Neither .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 | ✅ MainSceneScope | Placed directly in the scene, not a prefab. |
New-project boot checklist
Section titled “New-project boot checklist”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 inLibrary/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.
Hard rules
Section titled “Hard rules”- A per-platform scripting define can compile a second
IAnalyticEventFactoryimplementation, andUITemplateThirdPartyVContainer.cs:50resolves it withGetSingleDerivedType(), 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:scriptingDefineSymbolsare stored per build target, so open and compile on the platform you actually ship. 1.MainSceneis not in Build Settings — see the two-scene-flow gotcha above; don’t “fix” its absence there, it’s by design (Addressables-backed load).- A boot guard that sets
EditorSceneManager.playModeStartScene(e.g. to force Play through0.LoadingScene) silently breaks EVERY PlayMode test run — it redirects Play away from the test runner’s own generated bootstrap scene too, andcom.unity.test-frameworkhas zero defence against the override. Full mechanism, fix, and verification recipe:t1k-unity-testing-workflow§ Gotchas.
Related Skills & Agents
Section titled “Related Skills & Agents”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 (IAnalyticEventFactorycollision).t1k-unity-base-project-structure— whereAssets/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— theplayModeStartScenePlayMode-test-breaking gotcha and its fix (Gotcha #4 above points here for full detail).
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
references/new-project-checklist.md | Ordered, verifiable checklist for booting a fresh DOTSTemplate-derived project |
references/lifecycle-pipeline.md | Who drives ILifecycleManager, what never runs, the serial boot shapes and their measured cost |