ZOA Diagnostics

IDiagnosticProvider

interface

One source of findings. Report a snapshot of current state; leave filtering and presentation to the service.

• string ProviderId { get; }
• IReadOnlyList<DiagnosticEntry> CollectDiagnostics()

IDiagnosticService

service

Owns the provider set, aggregates their output, and filters it. GetBySeverity takes a minimum, so Warning includes errors and criticals.

• event Action DiagnosticsCollected
• void RegisterProvider(IDiagnosticProvider provider)
• void UnregisterProvider(string providerId)
• IReadOnlyList<DiagnosticEntry> CollectAll()
• IReadOnlyList<DiagnosticEntry> GetByPackage(string packageId)
• IReadOnlyList<DiagnosticEntry> GetBySeverity(DiagnosticSeverity severity)

DiagnosticEntry

class

One finding. Immutable, timestamped, tagged, and flagged with whether a quick fix exists.

• DiagnosticId Id { get; }
• DiagnosticSeverity Severity { get; }
• string Title { get; }
• string Message { get; }
• string Source { get; }
• DateTime Timestamp { get; }
• IReadOnlyList<string> Tags { get; }
• bool QuickFixAvailable { get; }

DiagnosticId

struct

Readonly string-backed id with implicit conversions in both directions, so a literal works at any call site.

• string Value { get; }
• bool IsEmpty { get; }

DiagnosticSeverity

enum

Info 0, Warning 1, Error 2, Critical 3. The explicit values make a minimum-severity filter meaningful.

IDependencyAnalyzer

interface

Cycle detection and forbidden-edge validation over explicit edges, so it can be tested with a synthetic graph rather than a real project.

• IReadOnlyList<DependencyEdge> AnalyzeDependencies(IReadOnlyList<DependencyEdge> edges)
• IReadOnlyList<IReadOnlyList<string>> FindCycles()
• IReadOnlyList<DependencyEdge> ValidateForbiddenEdges(IReadOnlyList<(string from, string to)> forbiddenPairs)

DependencyEdge

class

One directed edge, with flags for whether it participates in a cycle and whether it is optional.

• string FromPackage { get; }
• string ToPackage { get; }
• bool IsCyclic { get; }
• bool IsOptional { get; }

DependencyAnalyzer

class

The shipped analyzer. Depth-first search for cycles over an adjacency list built from the supplied edges.

IHealthDashboard

service

Per-package health signals with a refresh that re-evaluates every package and fires an event per package.

• event Action<string> HealthUpdated
• PackageHealthSignal GetPackageHealth(string packageId)
• IReadOnlyList<PackageHealthSignal> GetAllPackageHealth()
• void RefreshAll()

PackageHealthSignal

class

A package's summary: status, test pass and fail counts, validation error count, and when it was last checked.

• string PackageId { get; }
• PackageHealthStatus Status { get; }
• int TestsPassing { get; }
• int TestsFailing { get; }
• int ValidationErrors { get; }
• DateTime LastChecked { get; }

PackageHealthStatus

enum

Healthy, Degraded, Failing, Unknown.

FoundryDiagnosticScanner

class

The static scan entry point. Builds the package inventory once, runs the providers the request implies, and returns a report with severity counts, timing and inspection counts. Synchronous, so a CLI or build step can call it directly.

• static ScanReport Run(ScanRequest request)
• enum ScanScope { FullSystem, PerPackage, DependenciesOnly }
• struct ScanRequest { ScanScope Scope; string TargetPackage; bool IncludePackageAndAsmdef; bool IncludeCanonicalLayout; bool IncludeNamespaceConventions; }
• static ScanRequest ScanRequest.Default()
• class ScanReport { IReadOnlyList<DiagnosticEntry> Entries; IReadOnlyList<string> ProvidersRun; int InfoCount; int WarningCount; int ErrorCount; int CriticalCount; TimeSpan Duration; int PackagesInspected; int AsmdefsInspected; }

FrameBudget

class

Per-system frame-time and allocation budget with violation tracking. Bracket the system's tick and read the rate rather than a single frame.

• FrameBudget(string systemName, double maxFrameMs = 2.0, long maxAllocBytes = 0, ...)
• void BeginFrame()
• void EndFrame(long allocBytes = 0)
• bool IsOverBudget { get; }
• int TotalFrames { get; }
• int ViolationCount { get; }
• double ViolationRate { get; }
• double AverageFrameMs { get; }
• double PeakFrameMs { get; }
• string GetViolationSummary()

PerformanceBenchmark

class

Engine-free hot-path benchmarking. Returns a full distribution rather than one number, so a test can assert on the median or p99.

• static BenchmarkResult Run(string name, Action action, int iterations)
• static BenchmarkResult RunWithAllocations(string name, Action action, int iterations)
• class BenchmarkResult { double MinMs; MaxMs; MedianMs; MeanMs; P95Ms; P99Ms; TotalMs; EstimatedAllocBytesPerIteration; }

ErrorTelemetry

class

Captures, categorises and throttles errors so a repeating failure does not flood the log. Engine-agnostic; feed it from any logging source.

• ErrorTelemetry(int maxRecentErrors = 100, int throttlePerBucketPerMinute = 10)
• bool RecordError(string category, string message, ...)
• IReadOnlyList<ErrorRecord> RecentErrors { get; }
• int TotalErrorCount { get; }
• int ThrottledCount { get; }
• event Action<ErrorRecord> ErrorRecorded
• IReadOnlyDictionary<string, int> GetErrorCountsByCategory()
• IReadOnlyDictionary<ErrorSeverity, int> GetErrorCountsBySeverity()
• string GetSummary()
• void Reset()

StatModifierDiagnosticsRegistry

class

Shared publication point for stat modifier snapshots, so systems that are not Unity objects surface on the same diagnostics path as scene components.

• static IReadOnlyList<StatModifierSnapshot> Snapshots { get; }
• static event Action SnapshotsChanged
• static void Publish(string entityId, IEnumerable<StatModifier> modifiers)
• static void Publish(StatModifierSnapshot snapshot)
• static bool Remove(string entityId)
• static void Clear()

StatModifierSnapshot

class

An entity's modifiers at a moment: stat id, additive and multiplicative contributions, order, and the source that applied each one.

• string EntityId { get; }
• IReadOnlyList<StatModifierEntry> Modifiers { get; }
• class StatModifierEntry { string StatId; float Additive; float Multiplier; int Order; string Source; }

ZOAProductionManager

component

DontDestroyOnLoad singleton that applies the profile to ZOADiagnosticsGate and toggles every IZOADebugComponent. One per project, in the main menu scene.

• static ZOAProductionManager Instance { get; }
• ZOAProductionProfile Profile { get; }
• void ApplyProfile()
• void SetMode(ZOAProductionMode mode)
• void SetCategory(ZOADebugCategory category, bool enabled)
• void RefreshDebugComponents()

DamageFlowDiagnosticHud

component

Renders recent shots as flow diagrams from DamageFlowBus: muzzle node, pellet branches, hit nodes with surface, region and multiplier badges, and penetration chains. An IZOADebugComponent in the Weapon category, so the production gate governs it.

DemoControlsOverlay

component

Controls help overlay listing every keyboard-mapped action grouped by action map. An IZOADebugComponent in the Overlay category.

• bool ShowOnStart { get; set; }
• void SetVisible(bool visible)
• bool IsVisible { get; }

ZOAProductionProfile

asset

The one asset that decides whether the running game is Development or Production and which debug categories are live. Assets > Create > ZOA > Diagnostics > Production Profile; canonical path Assets/Resources/ZOA/ZOAProductionProfile.asset.

• const string ResourcesPath = "ZOA/ZOAProductionProfile"
• ZOAProductionMode Mode { get; }
• ZOADebugCategory EnabledCategories { get; }
• bool ForceDevelopmentInEditor { get; }
• ZOAProductionMode ResolveEffectiveMode()
• ZOADebugCategory ResolveEffectiveCategories()