Troubleshoot Flow Stats

Goal

Troubleshoot Flow Stats from the owning component outward: Profile, validation, instance overrides, initial preview, then live runtime. Stop at the first boundary that differs from the intended configuration.

When To Use This

Use this workflow when a Flow Stats owner does not initialize, a calculated value or cached boundary differs from authoring, an Effect or event route appears inactive, generated UI is empty, or snapshot restore fails.

Open the troubleshooting workspace

1. Select the GameObject with Flow Stats.
2. Keep its Inspector, Game view, and Console visible.
3. Open the component’s Main, Overrides, and Debug tabs as needed.
4. Use Open Profile to inspect the Profile’s Validation tab.

1. Confirm the runtime can initialize

In Main, check these fields first:

• Profile references the intended Flow Stats Profile;
• Initialize On Awake is enabled when no external code calls Initialize;
• the configuration message reports no validation issues.

In Edit Mode, Debug > Status should read Initial Preview. In Play Mode, an initialized component reads Live Runtime. Runtime Not Initialized means the component has no runtime collections to inspect.

2. Read validation before repairing anything

Open the Profile’s Validation tab and read the listed issue before changing data. Common blockers include missing or duplicate Stable IDs, invalid Formula token order, missing Formula or boundary dependencies, non-finite values, invalid Resource bounds, and incompatible initial Effects.

Use Repair Missing IDs only for empty Profile, Stat, and Resource identities. It does not rewrite duplicates or silently retarget references.

3. Check preserved instance overrides

Open the component’s Overrides tab. Unmatched Overrides appears when a saved component override can no longer map uniquely to the assigned Profile, and those entries block initialization.

Review each entry before selecting Clear Unmatched. That button removes invalid, duplicate, and Profile-unmatched instance overrides; it does not modify matching overrides or the Profile.

Find the visible symptom

Symptom	First check	Smallest matching action
Flow Stats does not initialize	Main > Profile and the validation message	Assign the intended Profile, then correct the first listed validation issue.
Initial Preview is unavailable	Profile Validation and Overrides > Unmatched Overrides	Correct invalid configuration data or explicitly clear obsolete unmatched overrides.
A calculated Stat is unexpectedly high	The Stat asset’s Base Value, Tokens, and Scale	Remember Raw = Base + Formula Contribution; use Base 0 when the Formula supplies the whole Raw value.
A Formula does not update after editing	Debug > Status	Exit and re-enter Play Mode or call RebuildRuntime() so it consumes a new authoring snapshot.
Resource Current uses an old capacity	Debug > Resources > Cached Minimum / Cached Maximum	Run Stats Refresh Resource Bounds or the matching runtime refresh after the source value changes.
A Status Effect is ignored	Profile Effects > Mode, then Allowed Effects or Blocked Effects	Permit the Effect and confirm every targeted Stat and Resource exists in the Profile.
A periodic Effect fires immediately	Effect Main > Tick Phase	Use After Interval; On Apply intentionally performs an immediate periodic operation.
A Manual Effect never advances	Effect Time Mode and tick Step	Use Manual, apply the Effect, then supply a finite Step greater than zero.
An Event Graph stays silent	Component Events > Storage Mode and the Trigger’s Enabled state	Open the active graph and enable the required Stats Trigger; Repair Standards does not enable it.
A generated Stats UI list is empty	List Filter By UI Display Mask, list Display Mask, and definition UI Display Mask	Enable filtering when intended and make the list and definition masks overlap; manually bound UI ignores this mask.
Snapshot restore fails	Runtime initialization and Profile Stable ID	Restore after initialization into the same logical Profile, outside an active Stats mutation or event dispatch.

Distinguish cached and live values

The Debug tab exposes different contracts:

• Stats show Base, Formula Contribution, Raw, cached Scale, and Effective.
• Resources show Current, Cached Minimum, Cached Maximum, and normalized progress.
• Effects show active instances, Stacks, duration, and modifier counts.
• Event Graph reports the enabled standard event types in the active channel.

Do not treat editing a Profile or definition asset during Play Mode as proof that the initialized runtime changed. Rebuild only when you intend to replace the complete runtime snapshot; refresh Resource bounds when only cached boundaries need new source values.

Common Mistakes

• Stable IDs are runtime and persistence identities. Change them only when assigning a different logical identity.
• Resource initial values are normalized zero-to-one positions, not raw Health or Mana units.
• Stats Change Resource in Normalized mode uses the complete cached range, not a percentage of Current.
• Multiply and Divide operations use factors: 1.1 increases a value by ten percent; 0.1 does not mean “plus ten percent.”
• Status Effects are filtered and checked for compatible targets independently.
• Persist controls snapshot eligibility for an Effect; it does not create disk persistence by itself.

Related Capabilities

• Explore Flow Stats in Five Minutes
• Build Your First Flow Stats Profile
• Create a Calculated Stat
• React to Flow Stats Events
• Run Turn-Based Status Effects
• Capture and Restore Flow Stats