t1k:unity:dots-core:bridges
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| Tools | — |
Keywords: AnalyticsBridge, app lifecycle, app resume, AppLifecycleBridge, AppResumedSignalHolder, AppResumedTag, AudioBridge, background foreground, bridge, camera shake, CameraTrauma, cue hub, cue notify, DI seam, DOTS bridge, dots-bridges, DOTSFeatureScope, DOTSFeatureScopeFactory, ECS to managed, EnsureCueHub, feature scope, FloatingText, GameplayCueRequest, IDOTSContainerBuilder, IDOTSFeatureInstaller, IDOTSFeatureStartable, IDOTSResolver, IGameplayUiGateway, input-ack from UI, IScreenShakeBridge, LifetimeScope, ManagedEventQueue, Mono to ECS write, NotifyDraftCardTapped, OnApplicationFocus, OnApplicationPause, RegisterSignalInfrastructure, screen shake, ScreenShake, SignalBus, SignalBusBridge, SignalSubscriberMonoBehaviour, UI gateway, VContainerBuilderAdapter, VFXBridge
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:bridgesDOTS Bridges — universal ECS↔managed bridges
Section titled “DOTS Bridges — universal ECS↔managed bridges”Overview
Section titled “Overview”com.the1studio.dots-bridges (v1.0.0, renamed from com.the1studio.dots-ui-bridge) ships six production-ready bridges built on one shared primitive — ManagedEventQueue<T>. Each bridge follows the (Read, Write, Lifetime) triple so the hand-off from Burst-compiled ISystem to Unity-managed MonoBehaviour is leak-free, frame-accurate, and Play-mode-exit safe.
| Layer | Sub-asmdef | Purpose |
|---|---|---|
| Core | DOTSBridges.Core | ManagedEventQueue<T>, DOTSBridgeMonoBehaviour<T>, IManagedRequestProcessor<T>, DI seam (IDOTSContainerBuilder, IDOTSResolver, IDOTSFeatureInstaller, IDOTSFeatureStartable) |
| VContainer | DOTSBridges.VContainer (opt-in, autoReferenced: false) | SignalBusDOTSBridgeMonoBehaviour<TEvent,TSignal>, registration extensions, DI-seam impl (VContainerBuilderAdapter, VContainerResolverAdapter, DOTSFeatureStartableRunner, DOTSFeatureScope, DOTSFeatureScopeFactory, SignalSubscriberMonoBehaviour<TSignal>) |
| Audio | DOTSBridges.Audio | IAudioBridge + AudioBridge + AudioBankSO — layers on DOTSCore.AudioEvent |
| VFX | DOTSBridges.VFX | IVFXBridge + VFXBridge + VFXBankSO + VFXEventType (13 categories) |
| Analytics | DOTSBridges.Analytics | IAnalyticsBridge + AnalyticsBridge + NoOpAnalyticsBridge fallback |
| UI/FloatingText | DOTSBridges.FloatingText | FloatingTextBridge + FloatingTextStyleBank + aggregator (damage / heal / gold / XP) |
| ScreenShake | DOTSBridges.ScreenShake | IScreenShakeBridge + CameraShakeDOTSBridgeMonoBehaviour (drain) + NoOpScreenShakeBridge + CameraShakeEvent DTO — drains DOTSCore.CameraTrauma |
| Lifecycle | DOTSBridges.Core (Runtime/Core/Lifecycle/) | AppLifecycleBridge MonoBehaviour + AppResumedTag — publishes OnApplicationPause/OnApplicationFocus as an ECS signal. Not a ManagedEventQueue bridge; see below |
When to use
Section titled “When to use”- Burst
ISystemneeds to talk to managed UI / audio / VFX / analytics → use the matching bridge. - VContainer scope needs
SignalBus.Fire(...)from ECS events →SignalBusDOTSBridgeMonoBehaviour. - UI controllers must enqueue requests back into ECS (claim reward, sell item) →
IManagedRequestProcessor<TRequest>(the Write side). - A managed UI gateway needs to raise a DOTS gameplay cue (
input-ack,valid-action, …) at the moment of touch, without a request/response round trip → ui-to-ecs-cue-notify-pattern.md (references/ui-to-ecs-cue-notify-pattern.md) (the Write side’s fire-and-forget sibling). - Do NOT put a bridge in a Burst job. Bridges are managed by design — see Gotchas.
Core API (6 bridges)
Section titled “Core API (6 bridges)”| Bridge | Read side (ECS → managed) | Write side / Configuration |
|---|---|---|
| Audio | AudioEnqueueSystem drains DynamicBuffer<DOTSCore.AudioEvent> → ManagedEventQueue<AudioEvent>.Instance | AudioBridge MonoBehaviour + AudioBankSO (AudioEventType → AudioClip) |
| VFX | VFXEnqueueSystem drains DynamicBuffer<VFXSpawnRequest> → queue | VFXBridge + VFXBankSO (VFXEventType → prefab) |
| Analytics | AnalyticsEnqueueSystem drains DynamicBuffer<AnalyticsEvent> → queue | AnalyticsBridge + IAnalyticsBridge backend (Firebase, AppsFlyer, custom) |
| FloatingText | FloatingTextEnqueueSystem + FloatingTextAggregatorSystem (coalesces damage by target) | FloatingTextBridge + FloatingTextStyleBank (color → style SO) + IObjectPoolManager |
| SignalBus | (inherits from DOTSBridgeMonoBehaviour<TEvent>) | SignalBusDOTSBridgeMonoBehaviour<TEvent,TSignal> — override Map(in TEvent) → TSignal, calls signalBus.Fire(in signal) |
| ScreenShake | CameraShakeDOTSBridgeMonoBehaviour polls the DOTSCore.CameraTrauma decaying scalar in LateUpdate, edge-detects upward threshold crossings → IScreenShakeBridge.Shake(pos, intensity) | RegisterBridge(IScreenShakeBridge) from a bootstrapper; defaults to NoOpScreenShakeBridge |
→ See managed-event-queue-pattern.md (references/managed-event-queue-pattern.md) for the (Read, Write, Lifetime) triple + bootstrap order.
App-lifecycle seam (AppLifecycleBridge → AppResumedTag)
Section titled “App-lifecycle seam (AppLifecycleBridge → AppResumedTag)”The one Mono→ECS bridge in this package that is not a ManagedEventQueue<T> bridge. It publishes native lifecycle callbacks as a stateless enableable tag:
// dots-bridges (library) — genre-neutral, says only "the app came back"public struct AppResumedTag : IComponentData, IEnableableComponent { }
// consumer side (your game) — decides what a resume MEANSif (SystemAPI.IsComponentEnabled<AppResumedTag>(signalEntity)) { /* act */ ; disable it }Drop AppLifecycleBridge onto any always-loaded GameObject. No DI registration, no VContainer reference — it binds World.DefaultGameObjectInjectionWorld in OnEnable and creates its singleton entity once.
Scope — it is the mid-process resume signal, not “session start”
Section titled “Scope — it is the mid-process resume signal, not “session start””A full process restart is already a valid first-initialization for any consumer: a freshly-constructed world starts in its own “never seen a session” state, no signal needed. What this bridge covers is the case a restart does not — the OS backgrounds and later foregrounds the app without killing the process (lock the screen, switch apps, come back), where process-lifetime state a consumer set up earlier is still live and would otherwise never learn that time passed. Do not treat it as the general session-start hook.
Consumer-cleared, deliberately — do NOT add an OrderFirst auto-clearer
Section titled “Consumer-cleared, deliberately — do NOT add an OrderFirst auto-clearer”This is the *DirtyTag half of Pattern 1, not the auto-cleared *Event half. The usual OrderFirst cleanup choreography assumes the producer is an ECS system at a known position relative to the cleanup slot. OnApplicationPause/OnApplicationFocus are native engine callbacks with no defined ordering relative to any SystemGroup tick — an auto-clearer could legitimately clear the flag in the same frame it was set, before any consumer saw it, and a dropped resume is silent. Whoever reads the tag disables it.
Both callbacks are wired to the same signal on purpose (Android is reliable on OnApplicationPause, desktop on OnApplicationFocus). Firing twice for one physical resume is harmless — enabling an already-enabled IEnableableComponent is a no-op.
ScreenShake seam (camera-shake third-party decoupling)
Section titled “ScreenShake seam (camera-shake third-party decoupling)”The ScreenShake bridge is the library’s Recipe B managed-effect seam (see the library-decoupling skill): it decouples ECS combat trauma from any concrete shake backend (Cinemachine impulse, Feel MMF_Player, custom). Unlike the queue-based bridges, it drains the DOTSCore.CameraTrauma decaying scalar directly — no ManagedEventQueue, no DynamicBuffer.
IScreenShakeBridge— library-owned interface:void Shake(float3 position, float intensity). Carries onlyUnity.Mathematicstypes — no vendor type in the signature (decoupling rule objective test #4). Impls just play a shake; they MUST NOT re-apply edge-detection or ReduceMotion scaling.CameraShakeDOTSBridgeMonoBehaviour— the drain. A[DisallowMultipleComponent]singleton (Instance) placed in the main scene (not SubScene). All policy lives HERE so every impl stays dumb: it pollsCameraTrauma.Current, firesShakeonly on an upward crossing ofFireThreshold(default 0.05), appliesReducedMotionScalewhenDOTSCore.CameraAccessibility.ReduceMotionis set (falls back toPlayerPrefs["ReduceMotion"]pre-world), and resolves a spatial origin from theCameraTargetsingleton (float3.zeroif absent).NoOpScreenShakeBridge— null-object default (precedent:NoOpAnalyticsBridge). Returned by theBridgeproperty when nothing is registered;Verbose=truelogs each event for emission verification without dragging in any SDK. This is the graceful-degrade contract — never throw when no backend is wired.CameraShakeEvent— areadonly structmanaged DTO (Position,Intensity), stack-created in the drain and passed by value. NOT anIComponentData/IBufferElementData— do not bake it.
Registration (VContainer / bootstrapper):
// Place CameraShakeDOTSBridgeMonoBehaviour on a main-scene GameObject, then:var drain = CameraShakeDOTSBridgeMonoBehaviour.Instance;drain.RegisterBridge(new FeelScreenShakeBridge(myMMFPlayer)); // consumer-side impl// or Cinemachine-only consumers self-register from CinemachineCameraBridge.// No registration → drain falls back to NoOpScreenShakeBridge (logs only).Double-consumer guard: when CameraShakeDOTSBridgeMonoBehaviour is present, DOTSCore.Camera.CinemachineCameraBridge detects it on its first LateUpdate (one-time Instance != null check) and suppresses its own ReadTraumaShake poll to prevent double-shake. Scenes without the drain MonoBehaviour (e.g. BattleDemo*) keep the legacy self-poll unchanged. The single registered impl IS the natural one-consumer guard — it replaces the old runtime FindFirstObjectByType double-consumer guard from the removed FeelCombatBridge.
DI-agnostic feature-scope seam (wire a feature with ZERO VContainer references)
Section titled “DI-agnostic feature-scope seam (wire a feature with ZERO VContainer references)”DOTSBridges.Core owns four interfaces — IDOTSContainerBuilder, IDOTSResolver,
IDOTSFeatureInstaller, IDOTSFeatureStartable — and gained no new asmdef references to carry them. The concrete impl lives in the opt-in DOTSBridges.VContainer assembly. A consumer feature declares WHAT it needs and never names a DI container:
using DOTSBridges; // Core only — no `using VContainer;` anywhere in the featurepublic sealed class BattlePassInstaller : MonoBehaviour, IDOTSFeatureInstaller{ public void Install(IDOTSContainerBuilder builder) => builder .RegisterSignalInfrastructure<BattlePassXPSignal>() .RegisterDOTSBridge<BattlePassXPEvent>() .RegisterComponentInHierarchy<BattlePassDOTSBridge>() .RegisterFeatureStartable<BattlePassBootstrap>();}Drop DOTSFeatureScope on the same GameObject; it discovers every IDOTSFeatureInstaller in its hierarchy at Awake and installs them in Inspector order. No LifetimeScope subclass per feature. Post-build work goes in an IDOTSFeatureStartable (gets an IDOTSResolver whose TryResolve never throws — probe optional services and degrade); signal subscribers extend SignalSubscriberMonoBehaviour<TSignal> (named-method subscribe/unsubscribe — a lambda breaks Unsubscribe).
Three traps that make or break this seam:
AddComponent<DOTSFeatureScope>()does NOT compile from a VContainer-free assembly — C# walks the whole base chain to checkwhere T : Component, hittingLifetimeScope(CS0012). UseDOTSFeatureScopeFactory.AttachTo(go):static,void-returning, derives fromobject, names no vendor type. Do not “simplify” it into a genericAddComponentwrapper — the constraint re-triggers the base-chain walk. Same reason the feature stopped being a scope: inheriting one hop fromLifetimeScopestill needs the reference.- VContainer tolerates duplicate registrations SILENTLY (
Registry.AddToBuildBuffer, 1.19) — no throw;Resolve<T>()returns the last, butIEnumerable<T>yields every duplicate, so a double-registered startable runs twice and a broker re-delivers every signal. Hence the explicit idempotence guards inVContainerBuilderAdapterand the nested-scope filter inDOTSFeatureScope.Configure. Never assume a duplicate register throws. - Registration order is load-bearing:
RegisterDependencyContainer()→RegisterSignalBus()→RegisterMessageBroker<T>().SignalBus’s constructor injectsTheOne.DI.IDependencyContainer; out of order it throws at scope-build.RegisterSignalInfrastructure<TSignal>()encapsulates the order so consumers stop hand-rolling it.
→ See di-feature-scope-seam.md (references/di-feature-scope-seam.md) for the full pattern, the com.theone.di 5.x RegisterDependencyContainer assembly move (CS1061 that looks like a deleted API), and the decoupling-rule mapping.
Examples
Section titled “Examples”One paste-and-adapt example per bridge (Audio via a Burst combat system, VFX spawn request,
FloatingText aggregated damage number, Analytics event, SignalBus custom-event bridge):
references/worked-examples.md. Per-bridge wiring, bank authoring, override seams, and pool
integration: audio-uses-dots-core-audioevent.md (references/audio-uses-dots-core-audioevent.md), vfx-bridge.md (references/vfx-bridge.md), analytics-bridge.md (references/analytics-bridge.md), floating-text-hoist.md (references/floating-text-hoist.md).
Hard rules
Section titled “Hard rules”Full detail: references/hard-rules.md. Read it before acting on this topic.
Normative rules kept inline:
-
DOTSCore.AudioEventis the canonical audio event — do NOT duplicate it. The Audio bridge LAYERS on top:AudioEnqueueSystemreads the existingDynamicBuffer<DOTSCore.AudioEvent>(per-entity, cleaned byDOTSCore.CoreEventCleanupSystem). The 3-pass library search caught this —dots-core/Runtime/Core/Components/AudioEvent.csalready exists. NEVER introduceDOTSBridges.AudioEventas a new type. → audio-uses-dots-core-audioevent.md (references/audio-uses-dots-core-audioevent.md).
-
- Two ownership modes for
ManagedEventQueue<T>— staticInstance(sample / headless test fallback) vs DI-registered (production). Mixing both for the sameTis anti-pattern #6 in the architecture research doc. Production projects ALWAYS register viabuilder.RegisterDOTSBridge<TEvent>().
- Two ownership modes for
-
OnDisableMUST nullify the World reference.DOTSBridgeMonoBehaviour<T>already handles this; consumer overrides MUST callbase.OnDisable(). Forgetting → first scene reload after Play-mode exit throwsObjectDisposedException.
Security
Section titled “Security”Bridges marshal ECS data to managed Unity APIs (AudioSource.Play, Object.Instantiate, Debug.Log, SignalBus.Fire). Standard guard: never enqueue user-controlled strings without length-clamping — AnalyticsEvent already enforces this via FixedString64Bytes/FixedString512Bytes.
Related skills
Section titled “Related skills”dots-vcontainer-integration(legacy alias oft1k:unity:dots-core:vcontainer-integration) — the 12-anti-pattern playbook this package supersedes.t1k:unity:dots-core:ecs—DynamicBuffer<T>patterns the bridges drain.t1k:unity:dots-core:enableable-components— alternative for stateless intra-ECS signals.t1k:unity:audio:core— managed-side audio (FMOD/Wwise) theAudioBridgeroutes to.t1k:library-decoupling— the engine-agnostic interface+provider seam pattern;IScreenShakeBridgeis its Unity Recipe-B reference impl (core event boundary, consumer-side vendor backend).