Class ScyllaSceneConfiguration

Configuration asset for the ScyllaSceneManager scene management service. Defines whether the framework hierarchy persists across scene loads, the default loading behavior, and which transition hygiene steps run on managed scene changes.

Inheritance
object
Object
ScriptableObject
ScyllaConfiguration
ScyllaSceneConfiguration
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.Scenes
Assembly: ScyllaCore.dll
Syntax
[CreateAssetMenu(fileName = "Scylla Scene Configuration", menuName = "Scylla/Configuration/Scene Configuration")]
public sealed class ScyllaSceneConfiguration : ScyllaConfiguration
Remarks

This asset is a UnityEngine.ScriptableObject that can be created via the Unity asset menu at Scylla/Configuration/Scene 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() and otherwise falls back to built-in defaults (which match this asset's field initializers).

The configurable fields are organized into three 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. The bootstrap applies these overrides BEFORE initializing ScyllaSceneManager so that PersistFrameworkAcrossScenes can be toggled per environment.

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 Scene Configuration for auto-loading to succeed.

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

DEFAULT_PROGRESS_EPSILON

The default value for ProgressEventEpsilon: publish a progress event whenever the reported progress advances by at least one percent.

Declaration
public const float DEFAULT_PROGRESS_EPSILON = 0.01
Field Value
Type Description
float

GROUP_GENERAL

The JSON config file group holding the general scene management settings.

Declaration
public const string GROUP_GENERAL = "General"
Field Value
Type Description
string

GROUP_HYGIENE

The JSON config file group holding the transition hygiene settings.

Declaration
public const string GROUP_HYGIENE = "Hygiene"
Field Value
Type Description
string

GROUP_LOADING

The JSON config file group holding the loading behavior settings.

Declaration
public const string GROUP_LOADING = "Loading"
Field Value
Type Description
string

KEY_CLEAR_TIME_MODIFIERS

The JSON config file key for ClearTimeModifiersOnSceneChange.

Declaration
public const string KEY_CLEAR_TIME_MODIFIERS = "ClearTimeModifiersOnSceneChange"
Field Value
Type Description
string

KEY_DEFAULT_MIN_LOAD_DURATION

The JSON config file key for DefaultMinLoadDurationSeconds.

Declaration
public const string KEY_DEFAULT_MIN_LOAD_DURATION = "DefaultMinLoadDurationSeconds"
Field Value
Type Description
string

KEY_KILL_TWEENS

The JSON config file key for KillTweensOnSceneChange.

Declaration
public const string KEY_KILL_TWEENS = "KillTweensOnSceneChange"
Field Value
Type Description
string

KEY_PERSIST_FRAMEWORK

The JSON config file key for PersistFrameworkAcrossScenes.

Declaration
public const string KEY_PERSIST_FRAMEWORK = "PersistFrameworkAcrossScenes"
Field Value
Type Description
string

KEY_PROGRESS_EVENT_EPSILON

The JSON config file key for ProgressEventEpsilon.

Declaration
public const string KEY_PROGRESS_EVENT_EPSILON = "ProgressEventEpsilon"
Field Value
Type Description
string

KEY_PRUNE_EVENT_SUBSCRIBERS

The JSON config file key for PruneEventSubscribersOnSceneChange.

Declaration
public const string KEY_PRUNE_EVENT_SUBSCRIBERS = "PruneEventSubscribersOnSceneChange"
Field Value
Type Description
string

KEY_SET_ACTIVE_SCENE_ON_ADDITIVE

The JSON config file key for SetActiveSceneOnAdditiveLoad.

Declaration
public const string KEY_SET_ACTIVE_SCENE_ON_ADDITIVE = "SetActiveSceneOnAdditiveLoad"
Field Value
Type Description
string

MAX_MIN_LOAD_DURATION

The maximum accepted value for DefaultMinLoadDurationSeconds. A minimum load duration above one minute is almost certainly a configuration mistake; used as the Inspector slider upper bound and in Validate().

Declaration
public const float MAX_MIN_LOAD_DURATION = 60
Field Value
Type Description
float

MAX_PROGRESS_EPSILON

The maximum accepted value for ProgressEventEpsilon. Larger values would suppress progress events almost entirely.

Declaration
public const float MAX_PROGRESS_EPSILON = 0.5
Field Value
Type Description
float

MIN_MIN_LOAD_DURATION

The minimum accepted value for DefaultMinLoadDurationSeconds. Used as the lower bound of the Inspector slider and in Validate().

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

MIN_PROGRESS_EPSILON

The minimum accepted value for ProgressEventEpsilon. Smaller values would publish a progress event on nearly every frame of a load.

Declaration
public const float MIN_PROGRESS_EPSILON = 0.001
Field Value
Type Description
float

Properties

ClearTimeModifiersOnSceneChange

Gets whether the ScyllaTime timescale-modifier stack is cleared before a managed scene change that destroys scene objects. Prevents a slow-motion or pause effect from the outgoing scene leaking into the next one.

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

true (default) to run the modifier-clear hygiene step.
Remarks

This is only the default. An individual call can override it via WithTimeModifierHygiene(HygieneOverride) and the HygieneOverride tri-state, which takes precedence over this configured value for that one operation.

DefaultMinLoadDurationSeconds

Gets the default minimum duration in seconds for managed scene loads. A managed operation completes no earlier than this many seconds after it starts, even if the underlying Unity load finishes sooner, which prevents a loading screen from flashing on very fast loads.

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

A duration in the range [MIN_MIN_LOAD_DURATION, MAX_MIN_LOAD_DURATION]. 0 disables the minimum.
Remarks

This is only the default. An individual call can override it via WithMinDuration(float), which takes precedence over this configured value for that one operation.

KillTweensOnSceneChange

Gets whether all active tweens are killed (firing their completion callbacks) before a managed scene change that destroys scene objects. Prevents tweens whose setters captured a destroyed scene object from throwing after the load completes.

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

true (default) to run the tween-kill hygiene step.
Remarks

This is only the default. An individual call can override it via WithTweenHygiene(HygieneOverride) and the HygieneOverride tri-state, which takes precedence over this configured value for that one operation.

PersistFrameworkAcrossScenes

Gets whether the bootstrap hierarchy (framework plus module children) is moved to DontDestroyOnLoad during initialization so it survives every scene load.

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

true to persist the framework hierarchy (default); false for the per-scene bootstrap model.

ProgressEventEpsilon

Gets the minimum progress change required before another progress event is published during a managed load. Prevents flooding subscribers with a ScyllaSceneLoadProgressEvent on every frame of the operation.

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

A threshold in the range [MIN_PROGRESS_EPSILON, MAX_PROGRESS_EPSILON], on a 0 to 1 progress scale.

PruneEventSubscribersOnSceneChange

Gets whether destroyed Unity subscribers are pruned from the event bus before a managed scene change. Removes stale subscriptions belonging to objects the scene change destroys instead of leaving them registered until the next publish call.

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

true (default) to run the event-bus-prune hygiene step.
Remarks

This is only the default. An individual call can override it via WithEventBusHygiene(HygieneOverride) and the HygieneOverride tri-state, which takes precedence over this configured value for that one operation.

SetActiveSceneOnAdditiveLoad

Gets whether additively loaded scenes become the active scene by default. The active scene owns the ambient lighting and skybox settings, so this determines which loaded scene those settings are read from after an additive load.

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

true to assign the loaded scene as active after additive loads; false (default) to leave the active scene unchanged.
Remarks

This is only the default. An individual call can override it via WithSetActiveScene(bool), which takes precedence over this configured value for that one operation.

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 parsed JSON configuration to read from. May be null, in which case no overrides are applied.
Returns
Type Description
int

The number of configuration values that were successfully applied.
Overrides
Remarks

Group and key names must match those written by ExportToConfigFile(); both methods share the GROUP_* and KEY_* constants on this class. 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 seven configuration values organized into three groups:
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 Scene Configuration".
Overrides

LoadDefault()

Loads the default ScyllaSceneConfiguration 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 ScyllaSceneConfiguration LoadDefault()
Returns
Type Description
ScyllaSceneConfiguration

The ScyllaSceneConfiguration 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:

Extension Methods

See Also