ZOA Feedback

IFeedbackService

interface

The dispatch surface. Fire an event, register and unregister channel handlers, load a graph, and mute channels wholesale.

• void Fire(FeedbackContext context)
• void RegisterHandler(IFeedbackChannelHandler handler)
• bool UnregisterHandler(IFeedbackChannelHandler handler)
• IReadOnlyList<IFeedbackChannelHandler> GetHandlers(FeedbackChannelId channelId)
• void LoadGraph(IFeedbackGraph graph)
• IFeedbackGraph ActiveGraph { get; }
• void StopAll()
• void SetChannelActive(FeedbackChannelId channelId, bool active)

FeedbackRouter

service

The default IFeedbackService. Pure C# with no Unity dependency; delayed mappings queue internally and need ProcessDelayed pumped from a MonoBehaviour.

• void ProcessDelayed(float deltaTime)
• int PendingDelayedCount { get; }

IFeedbackChannelHandler

interface

One output modality. Implement it once per channel your project actually renders, and register it with the service. IsActive is settable so a channel can be muted without being torn down.

• FeedbackChannelId ChannelId { get; }
• bool IsActive { get; set; }
• void HandleFeedback(FeedbackContext context)
• void StopAll()

IFeedbackGraph

interface

The routing table. Named, and queryable by event id; GetMappingsForEvent returns an empty list rather than null for an unmapped event.

• string GraphId { get; }
• string DisplayName { get; }
• IReadOnlyList<FeedbackMapping> Mappings { get; }
• IReadOnlyList<FeedbackMapping> GetMappingsForEvent(FeedbackEventId eventId)

FeedbackMapping

class

One routing edge with its tuning: which event, which channel, an intensity scale, a delay in seconds, an optional asset reference, and a mutable enabled flag.

• FeedbackEventId EventId { get; }
• FeedbackChannelId ChannelId { get; }
• float IntensityScale { get; }
• float Delay { get; }
• bool IsEnabled { get; set; }
• string AssetReference { get; }

FeedbackContext

class

What accompanies a fired event: position and normal as float triples, an intensity scalar, a source id, a surface tag, and the distance to the player for attenuation and level-of-detail decisions.

• FeedbackEventId EventId { get; }
• float PositionX, PositionY, PositionZ
• float NormalX, NormalY, NormalZ
• float Intensity { get; set; }
• string SourceId { get; set; } string SurfaceTag { get; set; }
• float DistanceToPlayer { get; set; }

FeedbackGraphBuilder

class

Fluent construction of an immutable graph. Build indexes the mappings by event id up front so runtime lookups do not scan.

• FeedbackGraphBuilder Map(FeedbackEventId eventId, FeedbackChannelId channelId, float intensityScale = 1f, float delay = 0f, string assetReference = null)
• FeedbackGraphBuilder AddMapping(FeedbackMapping mapping)
• IFeedbackGraph Build()

DefaultChannels

class

The ten built-in channel ids: SFX, VFX, Decal, Tracer, Haptics, CameraShake, CameraRecoil, HitMarker, ScreenEffect, and UIFlash.

DefaultFeedbackEvents

class

The built-in event ids, grouped by weapon, impact, player, interaction, and hit confirmation. WeaponFired, BulletImpact, PlayerDamaged, EnemyKilled, and HeadshotHit are among them.

IGameNotificationService

interface

The publish hub for player-facing notifications. Publication never throws into the caller, and a non-empty dedupe key suppresses a duplicate while the first is active.

• event Action<GameNotification> Published
• event Action<NotificationScope> Cleared
• void Publish(GameNotification notification)
• void Clear(NotificationScope scope)

GameNotification

class

One notification: scope, severity, localization ids for title and body with optional args, an icon and action id, a duration, and a dedupe key. Title and body are localization ids so the presentation layer resolves the active language.

• string Id; string DedupeKey;
• NotificationScope Scope; NotificationSeverity Severity;
• string TitleLocalizationId; string BodyLocalizationId; List<string> BodyArgs;
• string IconId; float DurationSeconds; string ActionId;

GameNotificationService

service

The default hub. Dedupes by active key, keeps a sixty-four entry rolling history, raises events outside its lock, and takes an injectable clock defaulting to Time.unscaledTime.

• const int HistoryCapacity = 64
• GameNotification[] History { get; }
• int ActiveCount { get; }
• void Reset()

NotificationFeedbackChannelHandler

class

Bridges the two systems. Subscribes to Published and fires a ui_notification FeedbackContext, mapping severity to intensity and swallowing any exception so feedback never bubbles back into the publisher.

• static readonly FeedbackEventId NotificationEvent = new("ui_notification")
• void Dispose()

FeedbackGraphAsset

asset

The authoring asset for a graph. Holds a stable graph slug and a list of serialized mappings, each naming an event id, a channel id, an intensity scale, and a delay. The same event id may appear on several rows to fan out.

• Tools/ZOA/Feedback/Feedback Graph
• string GraphId { get; }
• IReadOnlyList<SerializedFeedbackMapping> Mappings { get; }

FeedbackSceneInstaller

component

Registers IFeedbackService and IGameNotificationService and wires the notification bridge between them. Idempotent, reuses anything already registered, and unregisters only what it created. Execution order -9400.

• ZOA/Feedback/Feedback Scene Installer
• IFeedbackService Feedback { get; }
• IGameNotificationService Notifications { get; }
• void EnsureRegistered()
• void HandleDestroy()