Class ScyllaTimeConfiguration

Configuration asset for the ScyllaTime time management service. Defines default values for time scale behavior, pause handling, and fixed-timestep adjustment that govern how ScyllaTime initializes and operates at runtime.

Inheritance
object
Object
ScriptableObject
ScyllaConfiguration
ScyllaTimeConfiguration
Inherited Members
ScriptableObject.CreateInstance<T>()
Object.GetEntityId()
Object.GetHashCode()
Object.InstantiateAsync<T>(T)
Object.InstantiateAsync<T>(T, Transform)
Object.InstantiateAsync<T>(T, Vector3, Quaternion)
Object.InstantiateAsync<T>(T, Transform, Vector3, Quaternion)
Object.Instantiate(Object, Vector3, Quaternion)
Object.Instantiate(Object, Vector3, Quaternion, Transform)
Object.Instantiate(Object)
Object.Instantiate(Object, Scene)
Object.Instantiate<T>(T, InstantiateParameters)
Object.Instantiate<T>(T, Vector3, Quaternion, InstantiateParameters)
Object.Instantiate(Object, Transform)
Object.Instantiate<T>(T)
Object.Instantiate<T>(T, Vector3, Quaternion)
Object.Instantiate<T>(T, Vector3, Quaternion, Transform)
Object.Instantiate<T>(T, Transform)
Object.Destroy(Object)
Object.DestroyImmediate(Object)
Object.DontDestroyOnLoad(Object)
Object.FindAnyObjectByType<T>()
Object.FindAnyObjectByType<T>(FindObjectsInactive)
Object.FindObjectsByType<T>()
Object.FindObjectsByType<T>(FindObjectsInactive)
Object.ToString()
Object.name
Object.hideFlags
Namespace: Scylla.Core.Time
Assembly: ScyllaCore.dll
Syntax
[CreateAssetMenu(fileName = "Scylla Time Configuration", menuName = "Scylla/Configuration/Time Configuration")]
public sealed class ScyllaTimeConfiguration : ScyllaConfiguration
Remarks

This asset is a UnityEngine.ScriptableObject that can be created via the Unity asset menu at Scylla/Configuration/Time Configuration and assigned to ScyllaBootstrap in the Inspector. When no asset is assigned, ScyllaBootstrap attempts to load the default asset from Resources/Config/ via LoadDefault().

The configurable fields are organized into four logical groups that correspond directly to the JSON config file section names used by the ConfigFileManager override system:

JSON config file override system: When the global config file gate on ScyllaCoreConfiguration is open and the per-configuration gate on this asset is also enabled, ConfigFileManager loads an external JSON file and calls ApplyConfigFileOverrides(ConfigFile) to overwrite the serialized field values at runtime. This allows teams to ship per-environment or per-platform overrides without rebuilding the project. The JSON structure produced by ExportToConfigFile() serves as the canonical template for these override files.

Every configuration property is actively consumed by the ScyllaTime runtime: InitialTimeScale sets the starting scale, MaxTimeScale clamps all scale changes, AllowPause guards pause calls, RestoreTimeScaleOnResume controls resume behavior, DefaultSlowMotionScale and DefaultFastForwardScale provide defaults for their respective methods, AdjustFixedTimestep with BaseFixedTimestep synchronize physics updates with time scale changes, and the four focus / OS-pause flags drive auto-pause behavior on application focus loss and OS-reported pause events.

Fields

CONFIG_FILENAME

The filename used when creating this asset from the Unity menu and when loading the default instance at runtime via LoadDefault(). The asset must reside at Resources/Config/Scylla Time Configuration for auto-loading to succeed.

Declaration
public const string CONFIG_FILENAME = "Scylla Time Configuration"
Field Value
Type Description
string

DEFAULT_TIME_SCALE

The default time scale value representing normal real-time speed. Applied during ResetToDefaults() and used as the initial value for InitialTimeScale on newly created assets.

Declaration
public const float DEFAULT_TIME_SCALE = 1
Field Value
Type Description
float

GROUP_FIXED_TIMESTEP

The JSON config file group name for all fixed-timestep related settings. Used as the group key when reading overrides via ApplyConfigFileOverrides(ConfigFile) and when writing values via ExportToConfigFile(). Corresponds to the settings: KEY_ADJUST_FIXED_TIMESTEP and KEY_BASE_FIXED_TIMESTEP.

Declaration
public const string GROUP_FIXED_TIMESTEP = "Fixed Timestep"
Field Value
Type Description
string

GROUP_FOCUS

The JSON config file group name for application focus / OS-pause auto-trigger settings. Corresponds to KEY_PAUSE_ON_APPLICATION_FOCUS_LOSS, KEY_RESUME_ON_FOCUS_GAIN, KEY_PAUSE_ON_APPLICATION_PAUSE, and KEY_RESUME_ON_APPLICATION_RESUME.

Declaration
public const string GROUP_FOCUS = "Focus"
Field Value
Type Description
string

GROUP_PAUSE

The JSON config file group name for all pause-behavior related settings. Used as the group key when reading overrides via ApplyConfigFileOverrides(ConfigFile) and when writing values via ExportToConfigFile(). Corresponds to the settings: KEY_ALLOW_PAUSE and KEY_RESTORE_TIME_SCALE_ON_RESUME.

Declaration
public const string GROUP_PAUSE = "Pause"
Field Value
Type Description
string

GROUP_TIME_SCALE

The JSON config file group name for all time-scale related settings. Used as the group key when reading overrides via ApplyConfigFileOverrides(ConfigFile) and when writing values via ExportToConfigFile(). Corresponds to the settings: KEY_INITIAL_TIME_SCALE, KEY_MAX_TIME_SCALE, KEY_DEFAULT_SLOW_MOTION_SCALE, and KEY_DEFAULT_FAST_FORWARD_SCALE.

Declaration
public const string GROUP_TIME_SCALE = "Time Scale"
Field Value
Type Description
string

KEY_ADJUST_FIXED_TIMESTEP

The JSON config file property key for AdjustFixedTimestep within the GROUP_FIXED_TIMESTEP group.

Declaration
public const string KEY_ADJUST_FIXED_TIMESTEP = "AdjustFixedTimestep"
Field Value
Type Description
string

KEY_ALLOW_PAUSE

The JSON config file property key for AllowPause within the GROUP_PAUSE group.

Declaration
public const string KEY_ALLOW_PAUSE = "AllowPause"
Field Value
Type Description
string

KEY_BASE_FIXED_TIMESTEP

The JSON config file property key for BaseFixedTimestep within the GROUP_FIXED_TIMESTEP group.

Declaration
public const string KEY_BASE_FIXED_TIMESTEP = "BaseFixedTimestep"
Field Value
Type Description
string

KEY_DEFAULT_FAST_FORWARD_SCALE

The JSON config file property key for DefaultFastForwardScale within the GROUP_TIME_SCALE group.

Declaration
public const string KEY_DEFAULT_FAST_FORWARD_SCALE = "DefaultFastForwardScale"
Field Value
Type Description
string

KEY_DEFAULT_SLOW_MOTION_SCALE

The JSON config file property key for DefaultSlowMotionScale within the GROUP_TIME_SCALE group.

Declaration
public const string KEY_DEFAULT_SLOW_MOTION_SCALE = "DefaultSlowMotionScale"
Field Value
Type Description
string

KEY_INITIAL_TIME_SCALE

The JSON config file property key for InitialTimeScale within the GROUP_TIME_SCALE group.

Declaration
public const string KEY_INITIAL_TIME_SCALE = "InitialTimeScale"
Field Value
Type Description
string

KEY_MAX_TIME_SCALE

The JSON config file property key for MaxTimeScale within the GROUP_TIME_SCALE group.

Declaration
public const string KEY_MAX_TIME_SCALE = "MaxTimeScale"
Field Value
Type Description
string

KEY_PAUSE_ON_APPLICATION_FOCUS_LOSS

JSON key for PauseOnApplicationFocusLoss in GROUP_FOCUS.

Declaration
public const string KEY_PAUSE_ON_APPLICATION_FOCUS_LOSS = "PauseOnApplicationFocusLoss"
Field Value
Type Description
string

KEY_PAUSE_ON_APPLICATION_PAUSE

JSON key for PauseOnApplicationPause in GROUP_FOCUS.

Declaration
public const string KEY_PAUSE_ON_APPLICATION_PAUSE = "PauseOnApplicationPause"
Field Value
Type Description
string

KEY_RESTORE_TIME_SCALE_ON_RESUME

The JSON config file property key for RestoreTimeScaleOnResume within the GROUP_PAUSE group.

Declaration
public const string KEY_RESTORE_TIME_SCALE_ON_RESUME = "RestoreTimeScaleOnResume"
Field Value
Type Description
string

KEY_RESUME_ON_APPLICATION_RESUME

JSON key for ResumeOnApplicationResume in GROUP_FOCUS.

Declaration
public const string KEY_RESUME_ON_APPLICATION_RESUME = "ResumeOnApplicationResume"
Field Value
Type Description
string

KEY_RESUME_ON_FOCUS_GAIN

JSON key for ResumeOnFocusGain in GROUP_FOCUS.

Declaration
public const string KEY_RESUME_ON_FOCUS_GAIN = "ResumeOnFocusGain"
Field Value
Type Description
string

MAX_TIME_SCALE

The absolute maximum value accepted for any time scale field. This constant serves as the upper bound of the Inspector sliders for InitialTimeScale, MaxTimeScale, and DefaultFastForwardScale, and is used in Validate() to ensure that per-asset limits stay within the hard architectural ceiling.

Declaration
public const float MAX_TIME_SCALE = 10
Field Value
Type Description
float

MIN_TIME_SCALE

The absolute minimum value accepted for any time scale field. A value of 0 represents a fully frozen simulation (time does not advance). This constant is used as the lower bound of the InitialTimeScale Inspector slider and in Validate().

Declaration
public const float MIN_TIME_SCALE = 0
Field Value
Type Description
float

Properties

AdjustFixedTimestep

Gets whether ScyllaTime should proportionally scale Time.fixedDeltaTime whenever the time scale changes, keeping the number of physics steps per real-time second constant.

Declaration
public bool AdjustFixedTimestep { get; }
Property Value
Type Description
bool

true to synchronize the fixed timestep with the current time scale; false to leave Time.fixedDeltaTime unmodified. Defaults to false. When true, BaseFixedTimestep is used as the reference interval at a time scale of 1.0.
Remarks

Enforced by ScyllaTime at runtime: when true, Time.fixedDeltaTime is set to BaseFixedTimestep multiplied by the current time scale on every time scale change.

AllowPause

Gets whether the ScyllaTime service is permitted to pause the simulation by setting Time.timeScale to 0.

Declaration
public bool AllowPause { get; }
Property Value
Type Description
bool

true if pausing is allowed; false to prohibit pause calls entirely. Defaults to true.
Remarks

Enforced by Pause() at runtime: when false, pause requests are silently ignored with a debug log message.

BaseFixedTimestep

Gets the reference fixed-update interval in seconds, corresponding to a time scale of 1.0, used when AdjustFixedTimestep is enabled.

Declaration
public float BaseFixedTimestep { get; }
Property Value
Type Description
float

A float in the range [0.001, 0.1] seconds. The default value of 0.02 equates to 50 physics updates per second - Unity's built-in default. At other time scales the actual Time.fixedDeltaTime is computed as BaseFixedTimestep * timeScale. Validate() produces a warning if AdjustFixedTimestep is true and this value falls outside the recommended range of 0.001 to 0.1.

Clocks

Read-only view of the optional list of ClockDefinition assets that ScyllaTime auto-registers during initialization. Empty by default; designers populate this list to ship per-project clocks (master, UI, world, etc.).

Declaration
public IReadOnlyList<ClockDefinition> Clocks { get; }
Property Value
Type Description
IReadOnlyList<ClockDefinition>

DefaultFastForwardScale

Gets the preset time scale applied when fast-forward mode is activated via ScyllaTime.

Declaration
public float DefaultFastForwardScale { get; }
Property Value
Type Description
float

A float in the range [1.0, MaxTimeScale]. Values above 1.0 accelerate the simulation - for example, 2.0 means the simulation runs at double speed. Defaults to 2.0. Validate() produces a warning if this value is less than 1.0 or exceeds MaxTimeScale.
Remarks

Used by SetFastForward(float) as the default scale when no explicit value is provided.

DefaultSlowMotionScale

Gets the preset time scale applied when slow-motion mode is activated via ScyllaTime.

Declaration
public float DefaultSlowMotionScale { get; }
Property Value
Type Description
float

A float in the range (0.0, 1.0]. Values represent a fraction of real-time speed - for example, 0.5 means the simulation runs at half speed. Defaults to 0.5. Validate() produces a warning if this value is outside the recommended range of 0.1 to 1.0.
Remarks

Used by SetSlowMotion(float) as the default scale when no explicit value is provided.

InitialTimeScale

Gets the time scale that ScyllaTime applies to Time.timeScale immediately after the service initializes.

Declaration
public float InitialTimeScale { get; }
Property Value
Type Description
float

A float in the range [MIN_TIME_SCALE, MaxTimeScale]. 1.0 represents real-time speed. Values below 1.0 slow the simulation; values above 1.0 accelerate it. Defaults to DEFAULT_TIME_SCALE (1.0). Validate() produces an error if this value falls outside the valid range.

MaxTimeScale

Gets the maximum time scale value that ScyllaTime will allow to be set at runtime.

Declaration
public float MaxTimeScale { get; }
Property Value
Type Description
float

A float in the range [1.0, MAX_TIME_SCALE]. Must be at least 1.0 to ensure the service can always reach normal speed. Defaults to MAX_TIME_SCALE (10.0). Validate() produces an error if this value is less than 1.0.
Remarks

Enforced by ScyllaTime at runtime: all time scale changes via SetTimeScale(float), SetSlowMotion(float), and SetFastForward(float) are clamped to this maximum.

PauseOnApplicationFocusLoss

Whether ScyllaTime auto-pauses on application focus loss.

Declaration
public bool PauseOnApplicationFocusLoss { get; }
Property Value
Type Description
bool
Remarks

Platform note: Android fires OnApplicationPause(true) before OnApplicationFocus(false) when backgrounding the app; iOS fires them in the opposite order. With both PauseOnApplicationFocusLoss and PauseOnApplicationPause enabled, the iOS ordering means a backgrounded app reaches a Soft pause via the focus-loss path before the OS pause path can install a Hard pause. If a Hard pause across the entire backgrounded period is required, prefer enabling only PauseOnApplicationPause on iOS-targeted builds.

PauseOnApplicationPause

Whether ScyllaTime auto-pauses when the OS reports the application is paused.

Declaration
public bool PauseOnApplicationPause { get; }
Property Value
Type Description
bool
Remarks

See platform-ordering note on PauseOnApplicationFocusLoss.

RestoreTimeScaleOnResume

Gets whether ScyllaTime should restore the time scale that was active before a pause when Resume is called.

Declaration
public bool RestoreTimeScaleOnResume { get; }
Property Value
Type Description
bool

true to re-apply the pre-pause time scale on resume; false to resume at the default scale instead. Defaults to true.
Remarks

Enforced by Resume() at runtime: when true, the time scale active before the pause is restored; when false, time scale is reset to 1.0 on resume.

ResumeOnApplicationResume

Whether ScyllaTime auto-resumes when the OS reports the application has resumed (only after an OS-triggered hard pause).

Declaration
public bool ResumeOnApplicationResume { get; }
Property Value
Type Description
bool

ResumeOnFocusGain

Whether ScyllaTime auto-resumes when focus returns (only after a focus-loss-triggered soft pause).

Declaration
public bool ResumeOnFocusGain { get; }
Property Value
Type Description
bool

Methods

ApplyConfigFileOverrides(ConfigFile)

Reads configuration values from the supplied ConfigFile and overwrites the corresponding serialized fields on this asset. Only keys that are present in the file are applied; missing keys leave the current field values unchanged.

Declaration
public override int ApplyConfigFileOverrides(ConfigFile configFile)
Parameters
Type Name Description
ConfigFile configFile

The ConfigFile instance loaded by ConfigFileManager. If null, the method returns immediately with no changes applied.
Returns
Type Description
int

The number of individual field values that were successfully read from configFile and applied to this asset. Returns 0 if configFile is null or contains no keys that match the expected group/key pairs.
Overrides
Remarks

The method reads from the following group/key pairs in configFile. All group names and keys are case-insensitive (as defined by ConfigFile):

GroupKeyFieldType
GROUP_TIME_SCALEKEY_INITIAL_TIME_SCALEInitialTimeScalefloat
GROUP_TIME_SCALEKEY_MAX_TIME_SCALEMaxTimeScalefloat
GROUP_TIME_SCALEKEY_DEFAULT_SLOW_MOTION_SCALEDefaultSlowMotionScalefloat
GROUP_TIME_SCALEKEY_DEFAULT_FAST_FORWARD_SCALEDefaultFastForwardScalefloat
GROUP_PAUSEKEY_ALLOW_PAUSEAllowPausebool
GROUP_PAUSEKEY_RESTORE_TIME_SCALE_ON_RESUMERestoreTimeScaleOnResumebool
GROUP_FIXED_TIMESTEPKEY_ADJUST_FIXED_TIMESTEPAdjustFixedTimestepbool
GROUP_FIXED_TIMESTEPKEY_BASE_FIXED_TIMESTEPBaseFixedTimestepfloat

This method does not call Validate() after applying overrides. The caller is responsible for re-validating the configuration if needed.

ExportToConfigFile()

Serializes the current configuration field values into a new ConfigFile instance that captures the full structure expected by ApplyConfigFileOverrides(ConfigFile). The returned object can be passed to ToJSON() to produce a human-readable JSON override file.

Declaration
public override ConfigFile ExportToConfigFile()
Returns
Type Description
ConfigFile

A new ConfigFile containing all twelve configuration values organized into four groups:

Note: the Clocks list is intentionally NOT round-tripped through JSON because ClockDefinition entries are ScriptableObject asset references; clock auto-registration is Inspector-only.
Overrides
Remarks

The exported ConfigFile reflects the values currently held by this asset at the moment of the call, including any overrides previously applied by ApplyConfigFileOverrides(ConfigFile). It does not perform validation; export the file only after confirming the configuration is valid via Validate(). In the Unity Editor, the "Export Config File" button on the Inspector invokes this method automatically.

GetConfigFileName()

Returns the filename used to identify this configuration's JSON override file within the ConfigFileManager override system.

Declaration
public override string GetConfigFileName()
Returns
Type Description
string

The string value of CONFIG_FILENAME, which equals "Scylla Time Configuration".
Overrides

LoadDefault()

Loads the default ScyllaTimeConfiguration asset from the Resources/Config/ folder using Unity's Resources.Load API. Called by ScyllaBootstrap when no configuration asset is explicitly assigned in the Inspector.

Declaration
public static ScyllaTimeConfiguration LoadDefault()
Returns
Type Description
ScyllaTimeConfiguration

The ScyllaTimeConfiguration asset found at Resources/Config/CONFIG_FILENAME, or null if no such asset exists in the project's Resources folders.
Remarks

The asset must be named exactly CONFIG_FILENAME and placed under a Resources/Config/ directory that is included in the build. If the asset is not found, the caller is responsible for falling back to built-in defaults.

ResetToDefaults()

Resets all configuration fields to their built-in default values, discarding any Inspector-authored or config-file-applied overrides.

Declaration
public override void ResetToDefaults()
Overrides
Remarks

After calling this method the asset will have the following field values:

Validate()

Validates all configuration fields and returns an array of ConfigurationValidationResult diagnostics describing any detected problems. This method never throws; all issues are reported as results.

Declaration
public override ConfigurationValidationResult[] Validate()
Returns
Type Description
ConfigurationValidationResult[]

An array of ConfigurationValidationResult instances. An empty array indicates a fully valid configuration. Results with Error severity cause IsValid() to return false.
Overrides
Remarks

The following conditions produce an error result:

  • InitialTimeScale is less than MIN_TIME_SCALE or greater than MaxTimeScale. The error message includes the offending value and the valid range. Field: "_initialTimeScale".
  • MaxTimeScale is less than 1.0, which would prevent the service from ever reaching real-time speed. Field: "_maxTimeScale".

The following conditions produce a warning result:

Extension Methods

See Also