Skip to content

t1k:unity:dots-core:bridges

FieldValue
Moduledots-core
Version3.56.1
Effortmedium
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

/t1k:unity:dots-core:bridges

DOTS Bridges — universal ECS↔managed bridges

Section titled “DOTS Bridges — universal ECS↔managed bridges”

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.

LayerSub-asmdefPurpose
CoreDOTSBridges.CoreManagedEventQueue<T>, DOTSBridgeMonoBehaviour<T>, IManagedRequestProcessor<T>, DI seam (IDOTSContainerBuilder, IDOTSResolver, IDOTSFeatureInstaller, IDOTSFeatureStartable)
VContainerDOTSBridges.VContainer (opt-in, autoReferenced: false)SignalBusDOTSBridgeMonoBehaviour<TEvent,TSignal>, registration extensions, DI-seam impl (VContainerBuilderAdapter, VContainerResolverAdapter, DOTSFeatureStartableRunner, DOTSFeatureScope, DOTSFeatureScopeFactory, SignalSubscriberMonoBehaviour<TSignal>)
AudioDOTSBridges.AudioIAudioBridge + AudioBridge + AudioBankSO — layers on DOTSCore.AudioEvent
VFXDOTSBridges.VFXIVFXBridge + VFXBridge + VFXBankSO + VFXEventType (13 categories)
AnalyticsDOTSBridges.AnalyticsIAnalyticsBridge + AnalyticsBridge + NoOpAnalyticsBridge fallback
UI/FloatingTextDOTSBridges.FloatingTextFloatingTextBridge + FloatingTextStyleBank + aggregator (damage / heal / gold / XP)
ScreenShakeDOTSBridges.ScreenShakeIScreenShakeBridge + CameraShakeDOTSBridgeMonoBehaviour (drain) + NoOpScreenShakeBridge + CameraShakeEvent DTO — drains DOTSCore.CameraTrauma
LifecycleDOTSBridges.Core (Runtime/Core/Lifecycle/)AppLifecycleBridge MonoBehaviour + AppResumedTag — publishes OnApplicationPause/OnApplicationFocus as an ECS signal. Not a ManagedEventQueue bridge; see below
  • Burst ISystem needs 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.
BridgeRead side (ECS → managed)Write side / Configuration
AudioAudioEnqueueSystem drains DynamicBuffer<DOTSCore.AudioEvent> → ManagedEventQueue<AudioEvent>.InstanceAudioBridge MonoBehaviour + AudioBankSO (AudioEventType → AudioClip)
VFXVFXEnqueueSystem drains DynamicBuffer<VFXSpawnRequest> → queueVFXBridge + VFXBankSO (VFXEventType → prefab)
AnalyticsAnalyticsEnqueueSystem drains DynamicBuffer<AnalyticsEvent> → queueAnalyticsBridge + IAnalyticsBridge backend (Firebase, AppsFlyer, custom)
FloatingTextFloatingTextEnqueueSystem + 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)
ScreenShakeCameraShakeDOTSBridgeMonoBehaviour 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 MEANS
if (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 only Unity.Mathematics types — 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 polls CameraTrauma.Current, fires Shake only on an upward crossing of FireThreshold (default 0.05), applies ReducedMotionScale when DOTSCore.CameraAccessibility.ReduceMotion is set (falls back to PlayerPrefs["ReduceMotion"] pre-world), and resolves a spatial origin from the CameraTarget singleton (float3.zero if absent).
  • NoOpScreenShakeBridge — null-object default (precedent: NoOpAnalyticsBridge). Returned by the Bridge property when nothing is registered; Verbose=true logs each event for emission verification without dragging in any SDK. This is the graceful-degrade contract — never throw when no backend is wired.
  • CameraShakeEvent — a readonly struct managed DTO (Position, Intensity), stack-created in the drain and passed by value. NOT an IComponentData / 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 feature
public 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 check where T : Component, hitting LifetimeScope (CS0012). Use DOTSFeatureScopeFactory.AttachTo(go): static, void-returning, derives from object, names no vendor type. Do not “simplify” it into a generic AddComponent wrapper — the constraint re-triggers the base-chain walk. Same reason the feature stopped being a scope: inheriting one hop from LifetimeScope still needs the reference.
  • VContainer tolerates duplicate registrations SILENTLY (Registry.AddToBuildBuffer, 1.19) — no throw; Resolve<T>() returns the last, but IEnumerable<T> yields every duplicate, so a double-registered startable runs twice and a broker re-delivers every signal. Hence the explicit idempotence guards in VContainerBuilderAdapter and the nested-scope filter in DOTSFeatureScope.Configure. Never assume a duplicate register throws.
  • Registration order is load-bearing: RegisterDependencyContainer() → RegisterSignalBus() → RegisterMessageBroker<T>(). SignalBus’s constructor injects TheOne.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.

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

Full detail: references/hard-rules.md. Read it before acting on this topic.

Normative rules kept inline:

    1. DOTSCore.AudioEvent is the canonical audio event — do NOT duplicate it. The Audio bridge LAYERS on top: AudioEnqueueSystem reads the existing DynamicBuffer<DOTSCore.AudioEvent> (per-entity, cleaned by DOTSCore.CoreEventCleanupSystem). The 3-pass library search caught this — dots-core/Runtime/Core/Components/AudioEvent.cs already exists. NEVER introduce DOTSBridges.AudioEvent as a new type. → audio-uses-dots-core-audioevent.md (references/audio-uses-dots-core-audioevent.md).
    1. Two ownership modes for ManagedEventQueue<T> — static Instance (sample / headless test fallback) vs DI-registered (production). Mixing both for the same T is anti-pattern #6 in the architecture research doc. Production projects ALWAYS register via builder.RegisterDOTSBridge<TEvent>().
    1. OnDisable MUST nullify the World reference. DOTSBridgeMonoBehaviour<T> already handles this; consumer overrides MUST call base.OnDisable(). Forgetting → first scene reload after Play-mode exit throws ObjectDisposedException.

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.

  • dots-vcontainer-integration (legacy alias of t1k: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) the AudioBridge routes to.
  • t1k:library-decoupling — the engine-agnostic interface+provider seam pattern; IScreenShakeBridge is its Unity Recipe-B reference impl (core event boundary, consumer-side vendor backend).