Class TimeUtil

Provides static utility methods and cached properties for time-related operations in Unity, including per-frame delta time caching, frame-rate-normalized deltas, rolling FPS statistics, time formatting, interpolation helpers, and game-speed control.

Inheritance
object
TimeUtil
Inherited Members
Namespace: Scylla.Core.Util
Assembly: ScyllaCore.dll
Syntax
public static class TimeUtil
Remarks

Frame caching: DeltaTime and UnscaledDeltaTime cache their values once per frame (keyed on UnityEngine.Time.frameCount) so that multiple calls within the same frame avoid repeated UnityEngine API calls. All other time-related properties delegate directly to UnityEngine.Time without caching.

FPS tracking: AverageFPS, MinFPS, and MaxFPS maintain a circular ring buffer of the last FPS_SAMPLE_COUNT (60) frame measurements. The buffer is updated lazily when one of these properties is accessed. Call ResetFPSStats() to clear all accumulated data, or ResetFPSMinMax() to reset only the extremes.

Thread safety: All members of this class are intended for main-thread use only. The internal state (frame cache, FPS ring buffer) is not protected by any synchronization primitive.

Fields

DEFAULT_TARGET_FRAMERATE

The default target framerate used for frame-normalized delta calculations when no explicit value has been set via TargetFramerate. Equal to 60 frames per second.

Declaration
public const int DEFAULT_TARGET_FRAMERATE = 60
Field Value
Type Description
int

Properties

AverageFPS

Gets the average frames per second computed over the most recent FPS_SAMPLE_COUNT (60) frames. The rolling buffer is updated lazily on each access, so this property implicitly records the current frame's FPS when called.

Declaration
public static float AverageFPS { get; }
Property Value
Type Description
float

A float representing the mean FPS over the sample window. Returns 0 during the startup period when no valid samples have been collected yet (e.g., on the very first frame or immediately after ResetFPSStats()).
See Also

CurrentFPS

Gets the instantaneous frames-per-second rate based on the current frame's unscaled delta time. This value fluctuates significantly frame to frame. For a smoother display value, use AverageFPS instead.

Declaration
public static float CurrentFPS { get; }
Property Value
Type Description
float

The reciprocal of UnityEngine.Time.unscaledDeltaTime, or 0 if the delta time is at or below Scylla.Core.Util.TimeUtil.MIN_DELTA_TIME (to prevent division by zero or unrealistically large spikes on the first frame).
See Also

DeltaTime

Gets the time in seconds elapsed since the last frame, equivalent to UnityEngine.Time.deltaTime. The value is cached once per frame to avoid repeated UnityEngine API invocations when multiple systems read delta time in the same frame.

Declaration
public static float DeltaTime { get; }
Property Value
Type Description
float

A non-negative float in seconds. Scales with UnityEngine.Time.timeScale; returns 0 when the game is paused. See UnscaledDeltaTime for the pause-independent alternative.
See Also

FixedDeltaTime

Gets the fixed timestep interval used for physics and FixedUpdate processing. This value is constant within a fixed update cycle and is configurable in Unity's Project Settings under Time.

Declaration
public static float FixedDeltaTime { get; }
Property Value
Type Description
float

Equivalent to UnityEngine.Time.fixedDeltaTime. Commonly 0.02 seconds (50 Hz).
See Also

FrameCount

Gets the total number of frames that have been rendered since the application started. Equivalent to UnityEngine.Time.frameCount. Useful as a per-frame cache key or for frame-based interval checks.

Declaration
public static int FrameCount { get; }
Property Value
Type Description
int

A non-negative integer that increments by one each rendered frame.

FrameNormalizedDelta

Gets the delta time normalized so that a value of 1.0 represents one frame at the configured TargetFramerate. Values above 1.0 indicate the frame took longer than the target, and values below 1.0 indicate it was faster.

Declaration
public static float FrameNormalizedDelta { get; }
Property Value
Type Description
float

Computed as UnityEngine.Time.deltaTime * TargetFramerate. Scales with UnityEngine.Time.timeScale. Use this when porting fixed-rate game logic that assumes a 60 FPS baseline (e.g., retro-style movement speeds expressed as "units per frame at 60 FPS").
See Also

FrameNormalizedDeltaUnscaled

Gets the unscaled delta time normalized against TargetFramerate. Useful when frame-rate-independent logic must continue to run at the correct relative speed while the game is paused (e.g., pause-screen animations).

Declaration
public static float FrameNormalizedDeltaUnscaled { get; }
Property Value
Type Description
float

Computed as UnityEngine.Time.unscaledDeltaTime * TargetFramerate. Unaffected by UnityEngine.Time.timeScale.
See Also

GameTime

Gets the total elapsed time in seconds since the game started, scaled by UnityEngine.Time.timeScale. Equivalent to UnityEngine.Time.time. Use this for time-dependent gameplay effects that should pause with the game.

Declaration
public static float GameTime { get; }
Property Value
Type Description
float

A non-negative float in seconds. Stops advancing while the game is paused (timeScale == 0).
See Also

IsPaused

Gets a value indicating whether the game is currently paused, defined as UnityEngine.Time.timeScale being approximately equal to zero. Uses Approximately(float, float) to avoid floating-point comparison imprecision.

Declaration
public static bool IsPaused { get; }
Property Value
Type Description
bool

true if the time scale is effectively zero; false otherwise.
See Also

MaxFPS

Gets the highest frames-per-second value recorded since the last call to ResetFPSStats() or ResetFPSMinMax(). Updated lazily on each access, implicitly recording the current frame's FPS.

Declaration
public static float MaxFPS { get; }
Property Value
Type Description
float

The maximum FPS observed over the recording period. Returns 0 before the first valid sample is collected.
See Also

MinFPS

Gets the lowest frames-per-second value recorded since the last call to ResetFPSStats() or ResetFPSMinMax(). Updated lazily on each access, implicitly recording the current frame's FPS.

Declaration
public static float MinFPS { get; }
Property Value
Type Description
float

The minimum FPS observed over the recording period. Returns 0 when no valid samples have been collected yet.
See Also

RealtimeSinceStartup

Gets the wall-clock time in seconds since the application started, as measured by the operating system. Equivalent to UnityEngine.Time.realtimeSinceStartup. This value is never affected by pause state or time scale, and advances during loading screens and application suspension on supported platforms.

Declaration
public static float RealtimeSinceStartup { get; }
Property Value
Type Description
float

A non-negative float in seconds. Always monotonically increasing during a single application session.
See Also

ScaledDeltaTime

Gets the delta time multiplied by the current time scale, representing the effective in-game time elapsed since the last frame. For most gameplay logic this is equivalent to DeltaTime because Unity already applies the time scale to Time.deltaTime.

Declaration
public static float ScaledDeltaTime { get; }
Property Value
Type Description
float

Equivalent to UnityEngine.Time.deltaTime * UnityEngine.Time.timeScale. Returns zero when the game is paused.
See Also

SmoothDeltaTime

Gets the smoothed delta time provided by Unity's built-in frame-time averaging. This value is dampened to reduce frame-to-frame jitter and is suitable for visual effects where a momentary frame spike should not cause a visible pop.

Declaration
public static float SmoothDeltaTime { get; }
Property Value
Type Description
float

Equivalent to UnityEngine.Time.smoothDeltaTime. Scales with time scale.
See Also

TargetFramerate

Gets or sets the target framerate used as the baseline for frame-normalized delta calculations (FrameNormalizedDelta and FrameNormalizedDeltaUnscaled). Changing this value does not affect Unity's Application.targetFrameRate - it only changes the normalization baseline in this utility class.

Declaration
public static int TargetFramerate { get; set; }
Property Value
Type Description
int

A positive integer representing the reference frames per second. Defaults to DEFAULT_TARGET_FRAMERATE (60).
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when the assigned value is zero or negative.
See Also

TimeScale

Gets or sets the game time scale, which controls how fast simulated time progresses relative to real time. A value of 1.0 is normal speed; 0.5 is half speed (slow motion); 0.0 pauses the game; values greater than 1.0 accelerate gameplay. Delegates directly to UnityEngine.Time.timeScale.

Declaration
public static float TimeScale { get; set; }
Property Value
Type Description
float

A float in the range [0, 100]. Values outside this range are not clamped here - use SetTimeScale(float) to apply clamping automatically.
See Also

UnscaledDeltaTime

Gets the real-time elapsed since the last frame, unaffected by UnityEngine.Time.timeScale. The value is cached once per frame. Use this for UI animations, menus, and other systems that should continue running while the game is paused.

Declaration
public static float UnscaledDeltaTime { get; }
Property Value
Type Description
float

A non-negative float in seconds. Equivalent to UnityEngine.Time.unscaledDeltaTime.
See Also

UnscaledGameTime

Gets the total elapsed time in seconds since the game started, unaffected by UnityEngine.Time.timeScale. Equivalent to UnityEngine.Time.unscaledTime. Continues advancing during pause, making it suitable for UI timers and real-time animation playback.

Declaration
public static float UnscaledGameTime { get; }
Property Value
Type Description
float

A non-negative float in seconds that is always monotonically increasing.
See Also

Methods

FormatTime(float, bool?, bool)

Converts a duration in seconds to a human-readable time string. The output format adapts based on the magnitude of the input and the supplied options.

Declaration
public static string FormatTime(float totalSeconds, bool? includeHours = null, bool includeMilliseconds = false)
Parameters
Type Name Description
float totalSeconds

The total duration to format, in seconds. Negative values are clamped to zero before formatting.
bool? includeHours

Controls whether an hours component is included in the output.

  • null (default) - includes hours only when the value is 3600 seconds or more (auto-detect).
  • true - always includes hours, producing H:MM:SS format.
  • false - never includes hours, producing M:SS or MM:SS format.
bool includeMilliseconds

When true, appends a .mmm milliseconds component to the output, producing formats such as 1:23.456 or 1:23:45.678. Defaults to false.
Returns
Type Description
string

A formatted time string. Examples:

  • 75.5 seconds -> "1:15" (default)
  • 75.5 seconds, includeMilliseconds: true -> "1:15.500"
  • 3665.0 seconds -> "1:01:05"
Remarks

Uses a shared StringBuilder internally to avoid per-call heap allocations. Not thread-safe.

See Also

FormatTimeShort(float)

Converts a duration in seconds to a compact M:SS time string, omitting hours even for large values and not including milliseconds. Suitable for countdown timers, progress bars, and any display where brevity is more important than precision.

Declaration
public static string FormatTimeShort(float totalSeconds)
Parameters
Type Name Description
float totalSeconds

The total duration in seconds. Negative values are clamped to zero. Values of 3600 or more will show minute values greater than 59 (e.g., "75:00").
Returns
Type Description
string

A string in the format M:SS where M is the total minutes (not zero-padded) and SS is the seconds component zero-padded to two digits. For example, 90.0 -> "1:30" and 9.5 -> "0:09".
See Also

FormatTimeSpan(TimeSpan, bool)

Converts a TimeSpan to a human-readable time string using the same formatting logic as FormatTime(float, bool?, bool). Hours are auto-detected based on the span's magnitude.

Declaration
public static string FormatTimeSpan(TimeSpan timeSpan, bool includeMilliseconds = false)
Parameters
Type Name Description
TimeSpan timeSpan

The TimeSpan to format.
bool includeMilliseconds

When true, a milliseconds component is appended to the output. Defaults to false.
Returns
Type Description
string

A formatted time string equivalent to calling FormatTime((float)timeSpan.TotalSeconds, null, includeMilliseconds).
See Also

GetInterpolationDelta(float, bool)

Calculates a [0, 1] interpolation factor representing how far through a fixed duration the current frame's delta time carries the caller. Useful for driving one-shot transitions (e.g., fades or slides) without maintaining an external timer - each frame the caller advances its t by this amount until it reaches 1.0.

Declaration
public static float GetInterpolationDelta(float duration, bool useUnscaled = false)
Parameters
Type Name Description
float duration

The total target duration in seconds. Values of zero or less cause immediate completion by returning 1.0.
bool useUnscaled

When true, uses UnityEngine.Time.unscaledDeltaTime so the transition continues to run while the game is paused. Defaults to false.
Returns
Type Description
float

A value in the range [0, 1] representing the fraction of duration covered by the current frame's delta time. Returns exactly 1.0 if duration is zero or negative.
See Also

GetSmoothingFactor(float, bool)

Calculates a frame-rate-independent exponential smoothing factor for use with Lerp(float, float, float). Given the current frame's delta time and a conceptual smoothTime, the factor is derived from the formula 1 - exp(-deltaTime / smoothTime), which produces consistent smoothing regardless of frame rate.

Declaration
public static float GetSmoothingFactor(float smoothTime, bool useUnscaled = false)
Parameters
Type Name Description
float smoothTime

The approximate time constant in seconds - a larger value produces slower, more gradual smoothing; a smaller value reaches the target more quickly. Values of zero or less cause immediate snap by returning 1.0.
bool useUnscaled

When true, the calculation uses UnityEngine.Time.unscaledDeltaTime so smoothing continues while the game is paused. Defaults to false.
Returns
Type Description
float

A value in the range (0, 1] appropriate for use as the third argument of Lerp(float, float, float). Typical usage:

value = Mathf.Lerp(value, target, TimeUtil.GetSmoothingFactor(0.2f));
Remarks

Unlike SmoothDamp(float, float, ref float, float, float), this method does not track velocity and is simpler to apply for purely visual dampening effects such as smoothly following a camera target or fading values toward a goal.

See Also

Pause()

Pauses the game by setting UnityEngine.Time.timeScale to zero. All gameplay systems that rely on scaled delta time (physics, animations, gameplay logic) will stop advancing. Systems using UnscaledDeltaTime or UnscaledGameTime remain unaffected.

Declaration
public static void Pause()
See Also

ResetFPSMinMax()

Resets only the minimum and maximum FPS extremes without clearing the rolling average buffer. Useful when you want to start tracking a new min/max window (e.g., after entering a new area) while retaining the existing average data.

Declaration
public static void ResetFPSMinMax()
See Also

ResetFPSStats()

Clears all FPS tracking data, resetting the ring buffer, running sum, valid sample count, minimum, and maximum. The reset takes effect from the next frame onward; the current frame is skipped in the FPS tracker to avoid an off-by-one artefact.

Declaration
public static void ResetFPSStats()
Remarks

Call this after a significant event that would make previously recorded FPS data unrepresentative, such as after a scene load or entering/leaving a graphics-heavy area, to start building a fresh performance baseline.

See Also

Resume()

Resumes normal game speed by setting UnityEngine.Time.timeScale to 1.0. If the game was paused with a different mechanism (e.g., a custom time scale) and must be restored to that custom value, set TimeScale directly instead.

Declaration
public static void Resume()
See Also

SampleFPS()

Records the current frame's FPS into the rolling-average buffer.

Declaration
public static void SampleFPS()
Remarks

The FPS properties (AverageFPS, MinFPS, MaxFPS) record a sample only when they are read, so a consumer that reads them infrequently produces a coarse, slow-to-converge average. Call this once per frame (for example from a per-frame update) to keep the rolling average based on consecutive frames regardless of how often the values are displayed. Recording is capped at one sample per frame, so extra calls are harmless.

SecondsToTimeSpan(float)

Creates a TimeSpan representing the given number of seconds. A thin convenience wrapper around FromSeconds(double).

Declaration
public static TimeSpan SecondsToTimeSpan(float seconds)
Parameters
Type Name Description
float seconds

The duration in seconds. May be fractional. Negative values produce a negative TimeSpan.
Returns
Type Description
TimeSpan

A TimeSpan equal to seconds seconds.
See Also

SetTimeScale(float)

Sets the game time scale, clamping the value to the range [0, 100] before applying it to UnityEngine.Time.timeScale. Prefer this over assigning TimeScale directly when the input may come from untrusted sources such as debug consoles or user-configurable settings.

Declaration
public static void SetTimeScale(float scale)
Parameters
Type Name Description
float scale

The desired time scale. Values below zero are clamped to zero (effectively pausing); values above 100 are clamped to 100 (the practical maximum for stable physics).
See Also

TimeSpanToSeconds(TimeSpan)

Converts a TimeSpan to its total duration expressed as a single-precision floating-point number of seconds. Precision loss may occur for very large or very precise TimeSpan values.

Declaration
public static float TimeSpanToSeconds(TimeSpan timeSpan)
Parameters
Type Name Description
TimeSpan timeSpan

The TimeSpan to convert.
Returns
Type Description
float

The total duration of timeSpan in seconds as a float. Equivalent to (float)timeSpan.TotalSeconds.
See Also