# Concepts

Core concepts behind AP Timer Suite's design.

# Timer Identity: Gameplay Tags

Each timer is keyed by a Gameplay Tag (example: Timer.Cooldown.Dodge).

Why Gameplay Tags?

Tags provide a human-readable, collision-safe identity system that works across the entire project. Use the Project Settings Gameplay Tags editor to register your timer tag namespace. Tags are used for lookup, replication diffing, and debug display.

# Thresholds

Thresholds are ratios in the range [0..1] representing elapsed progress.

Example: 0.75 fires when 75% of duration has elapsed.

Threshold ratios are treated as data — they are clamped, sorted, and deduplicated automatically. Configure multiple thresholds per timer for granular callbacks (e.g., at 25%, 50%, 75%, and 100% elapsed).

Ratio	Meaning
`0.0`	Timer just started
`0.5`	Half the duration has elapsed
`1.0`	Timer has finished

# Replication Model (FastArray)

Timer state replicates via FastArraySerializer delta replication — only changed timers replicate each network update, keeping bandwidth usage minimal regardless of total timer count.

# Server-Authoritative Model

Authority Rules

The server mutates timer state and schedules expiration/threshold callbacks.
Clients react to replicated state transitions and use queries/snapshots for UI.
Clients should not run expiration logic locally.

Server                    Client
  |                         |
  |-- StartTimer ---------->|  (replicates via FastArray)
  |                         |
  |-- OnTimerStarted ------>|  (fires on both)
  |                         |
  |-- OnTimerFinished ----->|  (fires on both)

# Late Join (No Replay)

On initial replication, late-joining clients compute which thresholds have already elapsed and set a baseline — prior thresholds are not replayed.

Late-Join Behavior

Future thresholds still fire correctly for late joiners. Client UI should use snapshot/query functions to display current state rather than relying on event history.

AfterPrime Systems — Building the Gameplay Foundation