Class TimeScaleModifierStack

A deterministic, priority-ordered stack of TimeScaleModifier entries that compose into a single effective time-scale multiplier. Used by ScyllaTime to layer effects such as hit-stop, bullet-time, or slow-motion windows on top of the base time scale.

Inheritance
object
TimeScaleModifierStack
Inherited Members
Namespace: Scylla.Core.Time
Assembly: ScyllaCore.dll
Syntax
public sealed class TimeScaleModifierStack
Remarks

Modifiers are evaluated each time GetEffectiveMultiplier() is called by iterating in ascending priority order, starting with a running accumulator of 1.0:

Within the same priority, ties are broken by insertion order (deterministic). Calling Update(float) each tick decrements RemainingDuration on duration-bound modifiers and removes those that have expired.

The stack is backed by a List<T> kept sorted by (Priority, InsertionSeq); insertion is O(n) but n is typically small (1-10 modifiers in flight). Removal by handle is O(n). GetEffectiveMultiplier() is O(n) and allocation-free in steady state.

Properties

Count

Number of currently active modifiers in the stack.

Declaration
public int Count { get; }
Property Value
Type Description
int

Methods

Clear()

Removes all modifiers from the stack regardless of priority, source, or remaining duration.

Declaration
public void Clear()

GetActiveModifiers()

Read-only view of the active modifiers in priority order. Intended for debug overlays and tests; does not allocate when the underlying list grows past initial capacity.

Declaration
public IReadOnlyList<TimeScaleModifier> GetActiveModifiers()
Returns
Type Description
IReadOnlyList<TimeScaleModifier>

GetEffectiveMultiplier()

Folds all active modifiers into a single multiplier by walking the stack in ascending priority order. Returns 1.0 when the stack is empty.

Declaration
public float GetEffectiveMultiplier()
Returns
Type Description
float

Pop(TimeScaleModifierHandle)

Removes the modifier identified by handle, if present.

Declaration
public bool Pop(TimeScaleModifierHandle handle)
Parameters
Type Name Description
TimeScaleModifierHandle handle
Returns
Type Description
bool

true if a modifier with the matching ID was found and removed; otherwise false.

Push(TimeScaleModifier)

Adds a modifier to the stack and returns a handle the caller can use to remove it later. The returned handle remains valid until either the modifier auto-expires (RemainingDuration reaches 0 via Update(float)) or it is removed via Pop(TimeScaleModifierHandle) or RemoveBySourceID(string).

Declaration
public TimeScaleModifierHandle Push(TimeScaleModifier modifier)
Parameters
Type Name Description
TimeScaleModifier modifier

The modifier to add. Its ID field is overwritten.
Returns
Type Description
TimeScaleModifierHandle

The newly assigned handle.

RemoveBySourceID(string)

Removes every modifier whose SourceID equals the supplied identifier (using ordinal string comparison).

Declaration
public int RemoveBySourceID(string sourceID)
Parameters
Type Name Description
string sourceID

The source identifier to match. null matches no modifiers.
Returns
Type Description
int

The number of modifiers removed.

Update(float)

Decrements the RemainingDuration of every duration-bound modifier by unscaledDeltaTime. Modifiers whose remaining duration drops to 0 or below are removed from the stack.

Declaration
public void Update(float unscaledDeltaTime)
Parameters
Type Name Description
float unscaledDeltaTime
Remarks

This method is intended to be called once per real-world frame from Tick(float). Negative deltas are treated as zero (the stack does not extend modifier durations even if the wall clock somehow runs backwards).

Extension Methods