t1k:unity:dots-core:vcontainer-integration
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | high |
| Tools | β |
Keywords: BattlePass bridge, DOTS VContainer bootstrap, ECS UI integration, IAsyncStartable
How to invoke
Section titled βHow to invokeβ/t1k:unity:dots-core:vcontainer-integrationDOTS β VContainer Integration
Section titled βDOTS β VContainer IntegrationβHow DOTS (unmanaged, World-scoped, Burst-compiled) and VContainer + SignalBus (managed, LifetimeScope-scoped, GC) coexist without leaking lifetime, fighting over data, or breaking Burst.
Covers:
- DOTS systems publishing events to VContainer-managed UI controllers (Read).
- VContainer-managed UI sending requests into DOTS (Write).
- World β LifetimeScope lifetime ownership and shutdown order.
- Bootstrap order for
TheOneFeaturemodules (TimeService β Inventory β Feature). - Test isolation across the boundary.
Does NOT cover:
- DOTS rendering (
t1k-unity-dots-rendering-graphics), navigation (t1k-unity-dots-nav-agents-navigation), audio (t1k-unity-audio-core). - General MonoBehaviour DI (
t1k-unity-base-monobehaviour) β load that for non-DOTS DI. - Save/load serialization (
t1k-unity-dots-core-memorypack,t1k-unity-base-save-system).
The (Read, Write, Lifetime) Triple
Section titled βThe (Read, Write, Lifetime) TripleβEvery DOTSβmanaged boundary has three orthogonal concerns. Solve them together or you will rediscover footgun #1 or #6 at runtime.
ECS WORLD β MANAGED / VContainer (Burst, struct) β (GC, class)βββββββββββββββββββββββββββββββββββββββββ β βββββββββββββββββββββββββββββββββ DynamicBuffer<XPEvent> singleton β SignalBus.Fire(new XPEvent(...)) β β β² [Read] BridgeSystem (OrderFirst) β β LateUpdate poll βΌ β β ManagedEventQueue<T> βββββββ shared static ref ββββ€ β² β β [Write] ClaimSystem queries β β EntityManager.Add ClaimRewardRequest β βΌ β β UI controller (IStartable) βββ EntityManager.Create βββββ β [Lifetime] World.IsCreated guard ββββββΊ nullable World ref + OnDisable nullify| Direction | Recommended | Anti-pattern |
|---|---|---|
| Read ECS β MB | Bridge ISystem (OrderFirst) drains buffer β enqueues into static ManagedEventQueue<T>; MB polls in LateUpdate and fires to SignalBus via signalBus.Fire(...). | Direct EntityManager.GetBuffer poll in MB Update β wrong frame timing, GC alloc, no Burst. |
| Write MB β ECS | UI calls world.EntityManager.AddComponentData(new ClaimRewardRequest{...}). Poll-system in OrderFirst consumes + destroys the request entity. | BeginSimulationECB from a managed system β boilerplate without benefit for one-off requests. |
| Lifetime | Bridge MB stores World ref (NOT EntityManager); guards every use with world != null && world.IsCreated; nullifies in OnDisable. | Capturing EntityManager in a closure or MB field β struct copy goes stale on chunk move. |
β See bootstrap-order.md (references/bootstrap-order.md) for the World-vs-LifetimeScope timeline.
Bootstrap Order
Section titled βBootstrap OrderβTheOneFeature services have a hard DAG. Register out-of-order and stamina
recharge breaks, BattlePass tier unlocks miss XP, daily streak resets every
launch. The required order:
UserDataManagerβ every feature reads LocalData via this; must be ready first.TimeServiceβ must beIsSyncedbefore any time-driven feature (Lives, BattlePass, DailyReward, Booster).InventoryServiceβ every reward-granting service callsinventoryService.AddRewards(...); register before BattlePass / DailyReward / Gacha / ClaimReward.- Gameplay features β
RegisterLives(),RegisterBattlePass(),RegisterDailyReward(). - Monetization / engagement β
RegisterFeatureIAP(),RegisterBooster(),RegisterGacha(),RegisterNotification(). - DOTS bridge MonoBehaviours β instantiate AFTER step 5; they
[Inject]the services from steps 3β5 and resolveWorld.DefaultGameObjectInjectionWorldinOnEnable.
β See bootstrap-order.md (references/bootstrap-order.md) for the full registration template and shutdown sequence.
ManagedEventQueue<T>
Section titled βManagedEventQueue<T>βA tiny non-allocating wrapper around System.Collections.Generic.Queue<T> that
serves as the DOTSβmanaged marshalling buffer. It lives on the bridge MB, is
referenced by the bridge ISystem via a static field, and is cleared on scope
teardown.
public sealed class ManagedEventQueue<T> where T : unmanaged{ private readonly Queue<T> queue = new(256); public void Enqueue(in T item) => this.queue.Enqueue(item); public bool TryDequeue(out T item) => this.queue.TryDequeue(out item); public void Clear() => this.queue.Clear(); public int Count => this.queue.Count;}Once the com.the1studio.dots-ui-bridge library package ships, prefer the
shared DOTSUIBridge.ManagedEventQueue<T> over a per-demo copy.
β See managed-event-queue.md (references/managed-event-queue.md) for the full bridge-system + bridge-MB pair, including the static field bootstrap pattern and a NativeQueue<T> variant for jobs.
SignalBus Integration
Section titled βSignalBus IntegrationβThe projectβs SignalBus ships with GameFoundation
(Packages/com.gdk.core/Scripts/Signals/SignalBus.cs, namespace
GameFoundation.Signals). Publish API is Fire(in T), NOT
Publish<T>. Three non-negotiable rules:
- Container plumbing order β
builder.RegisterDependencyContainer()MUST run beforebuilder.RegisterSignalBus()(its ctor injectsIDependencyContainer). See signalbus-integration.md (references/signalbus-integration.md) Β§ βRequired Bootstrap Order.β
Then the handler-lifecycle rules from code-conventions-unity.md:
- Subscribe with named methods, not lambdas. Lambdas have no reference
equality β
Unsubscribesilently fails and you leak callbacks across scene reloads. - Always pair
SubscribeinIStartable.Start()(orOnEnable) withUnsubscribeinIDisposable.Dispose()(orOnDisable). Track theIDisposableif your DI container returns one.
public sealed class BattlePassUIController : IStartable, IDisposable{ private readonly SignalBus signalBus; private readonly BattlePassUIPanel panel;
public BattlePassUIController(SignalBus signalBus, BattlePassUIPanel panel) { this.signalBus = signalBus; this.panel = panel; }
public void Start() => this.signalBus.Subscribe<BattlePassXPEvent>(this.OnXPGained); public void Dispose() => this.signalBus.Unsubscribe<BattlePassXPEvent>(this.OnXPGained); private void OnXPGained(BattlePassXPEvent e) => this.panel.AddXP(e.Amount);}
// Bridge MB publishes via Fire β NOT Publish.this.signalBus.Fire(new BattlePassXPEvent { Amount = 10 });β See signalbus-integration.md (references/signalbus-integration.md) for IAsyncStartable, signal-event payload conventions, and Burst-compatibility constraints (signal payloads must be unmanaged to round-trip through ManagedEventQueue<T>).
Anti-patterns
Section titled βAnti-patternsβTwelve footguns from Phase C / Phase D delivery (BackpackCrawler 2026-05).
Each is expanded in hard-rules.md (references/hard-rules.md).
- Captured
EntityManagerin a closure. Struct copy goes stale after chunk move. StoreWorld, callworld.EntityManagerfresh per use. CreateEntityQueryevery frame. Cache inStart(); dispose inOnDestroy().- Cached
DynamicBuffer<T>reference across frames. Re-fetch each frame. - No
World.IsCreatedguard on Play-mode exit. Guard every access. - Bridge
ISysteminLateSimulationSystemGroup. Use[UpdateInGroup(typeof(SimulationSystemGroup), OrderFirst = true)]. - Multiple LifetimeScopes each instantiating their own bridge. One
app-level bridge (
DontDestroyOnLoad) injected into every scene scope. - Lambda
SignalBus.Subscribe(...). No reference equality βUnsubscribesilently does nothing. Use named instance methods. - Calling
signalBus.Publish<T>(...). UsesignalBus.Fire(in T)β GameFoundationβsSignalBushas noPublishmethod. EntityQuery.Dispose()withoutWorld.IsCreatedguard. A Tier-2 bridge caching anEntityQuerymust guardworld.IsCreatedAND checkquery != defaultBEFORE disposing inOnDestroy/OnDisable, else Play-mode exit throwsObjectDisposedExceptionper bridge. Same rule for every cachedNative*collection.RegisterSignalBus()beforeRegisterDependencyContainer().SignalBusβs ctor injectsIDependencyContainer; missing it produces an opaqueVContainerExceptionon first signal resolve.- Calling
Register{Feature}()without registering its ctor deps first. Extensions are NOT self-contained β e.g.BattlePassServiceneeds 5 globally pre-registered deps. - Typoβing
TheOne.Features.Timein usings.TimeServicelives atTheOne.Feature.Time.Core.Servicesβ singularFeature.
β See hard-rules.md (references/hard-rules.md) for the full failure mode + fix per item.
Reference Files
Section titled βReference Filesβ| File | Topic |
|---|---|
bootstrap-order.md (references/bootstrap-order.md) | Frame-by-frame timeline, registration template, shutdown order, time-sync gate |
managed-event-queue.md (references/managed-event-queue.md) | ManagedEventQueue<T> full source, bridge-system + bridge-MB pair, NativeQueue<T> variant |
signalbus-integration.md (references/signalbus-integration.md) | Named-method subscribe/unsubscribe, IAsyncStartable, payload conventions, leak detection |
hard-rules.md (references/hard-rules.md) | The 12 anti-patterns above with full failure modes, repro symptoms, and fixes |
Related Skills
Section titled βRelated Skillsβt1k-unity-dots-core-ecsβ IComponentData, ISystem, EntityManager, query patterns.t1k-unity-dots-core-enableable-componentsβIEnableableComponentpatterns;GetSingletonEntityrejects enableable singletons (useIgnoreComponentEnabledState).t1k-unity-dots-core-entity-command-bufferβ when to prefer ECB over direct EntityManager calls.t1k-unity-base-monobehaviourβ non-DOTS MonoBehaviour DI, lifecycle, lambdas vs named handlers.t1k-unity-dots-testing-unit-testingβDOTSTestBasefixture for the ECS-side unit tests in this skill.