Struct ScyllaSceneLoadOptions

Immutable per-call options for a managed scene load performed by ScyllaSceneManager.

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Scenes

Assembly: ScyllaCore.dll

Syntax

public readonly struct ScyllaSceneLoadOptions

Remarks

A default-constructed instance (or Default) is always valid: it requests a UnityEngine.SceneManagement.LoadSceneMode.Single load with automatic activation and defers every optional setting to the active ScyllaSceneConfiguration. Values that can inherit from the configuration are stored as nullables and remain null until explicitly set.

The type is a readonly struct holding only value-type fields (an enum, a couple of nullable primitives, and three more enums for the hygiene overrides), so passing an instance by value, copying it, or chaining several With* calls allocates no managed heap memory. Each With* method returns a new value built from the current one and leaves the source untouched, which makes options instances safe to share, cache as static readonly presets, or rebuild every frame without generating garbage.

Instances are configured through the fluent With* methods, each of which returns a modified copy and leaves the source untouched:

var options = ScyllaSceneLoadOptions.Default
    .WithAdditive()
    .WithSetActiveScene(true)
    .WithMinDuration(0.5f);

Properties

Default

Gets the default options: a UnityEngine.SceneManagement.LoadSceneMode.Single load with automatic activation, all configuration-inheritable values unset, and every hygiene step set to UseConfig.

Declaration

public static ScyllaSceneLoadOptions Default { get; }

Property Value

Type	Description
ScyllaSceneLoadOptions	A ScyllaSceneLoadOptions equivalent to default(ScyllaSceneLoadOptions), provided as a named, self-documenting starting point for the fluent With* chain.

EventBusHygiene

Gets the per-call override for the event-bus-prune hygiene step, which removes destroyed Unity subscribers from the event bus before a destructive scene change.

Declaration

public HygieneOverride EventBusHygiene { get; }

Property Value

Type	Description
HygieneOverride	One of the HygieneOverride values. Defaults to UseConfig.

ManualActivation

Gets whether the operation starts with a closed activation gate. When true, the load holds in WaitingForActivation until the caller opens the gate on the operation handle by setting AllowActivation to true, which is the hook a loading screen uses to finish its outro before the new scene becomes active.

Declaration

public bool ManualActivation { get; }

Property Value

Type	Description
bool	true to require an explicit activation call; false (default) to activate automatically.

MinDurationSeconds

Gets the minimum duration in seconds the operation takes to complete, regardless of actual load speed. null defers to DefaultMinLoadDurationSeconds.

Declaration

public float? MinDurationSeconds { get; }

Property Value

Type	Description
float?	A non-negative duration in seconds, or null to inherit the configured default.

Mode

Gets the Unity load mode for the operation. Defaults to UnityEngine.SceneManagement.LoadSceneMode.Single.

Declaration

public LoadSceneMode Mode { get; }

Property Value

Type	Description
LoadSceneMode	Either UnityEngine.SceneManagement.LoadSceneMode.Single or UnityEngine.SceneManagement.LoadSceneMode.Additive.

SetActiveScene

Gets whether the loaded scene should become the active scene after an additive load. null defers to SetActiveSceneOnAdditiveLoad.

Declaration

public bool? SetActiveScene { get; }

Property Value

Type	Description
bool?	true to assign the loaded scene as active, false to leave the active scene unchanged, or null to inherit the configured default. Ignored for UnityEngine.SceneManagement.LoadSceneMode.Single loads, which always make the loaded scene active.

TimeModifierHygiene

Gets the per-call override for the timescale-modifier-clear hygiene step, which empties the ScyllaTime timescale-modifier stack before a destructive scene change.

Declaration

public HygieneOverride TimeModifierHygiene { get; }

Property Value

Type	Description
HygieneOverride	One of the HygieneOverride values. Defaults to UseConfig.

TweenHygiene

Gets the per-call override for the tween-kill hygiene step, which stops every active tween (firing completion callbacks) before a destructive scene change.

Declaration

public HygieneOverride TweenHygiene { get; }

Property Value

Type	Description
HygieneOverride	One of the HygieneOverride values. Defaults to UseConfig.

Methods

WithAdditive()

Returns a copy of these options with the load mode set to UnityEngine.SceneManagement.LoadSceneMode.Additive. Convenience for WithMode(LoadSceneMode.Additive).

Declaration

public ScyllaSceneLoadOptions WithAdditive()

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value requesting an additive load.

WithEventBusHygiene(HygieneOverride)

Returns a copy of these options with the event-bus-prune hygiene step override set.

Declaration

public ScyllaSceneLoadOptions WithEventBusHygiene(HygieneOverride hygieneOverride)

Parameters

Type	Name	Description
HygieneOverride	hygieneOverride	The per-call override to apply.

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value with the override applied.

WithManualActivation()

Returns a copy of these options that starts the load with a closed activation gate. The operation holds at WaitingForActivation until the caller opens the gate by setting AllowActivation to true on the operation handle, which is the hook a loading screen uses to finish its outro before the new scene activates.

Declaration

public ScyllaSceneLoadOptions WithManualActivation()

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value requesting manual activation.

WithMinDuration(float)

Returns a copy of these options with an explicit minimum operation duration.

Declaration

public ScyllaSceneLoadOptions WithMinDuration(float minDurationSeconds)

Parameters

Type	Name	Description
float	minDurationSeconds	The minimum duration in seconds. Values below zero are treated as zero.

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value with the minimum duration applied.

WithMode(LoadSceneMode)

Returns a copy of these options with the load mode set to mode.

Declaration

public ScyllaSceneLoadOptions WithMode(LoadSceneMode mode)

Parameters

Type	Name	Description
LoadSceneMode	mode	The Unity load mode to use.

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value with the mode applied.

WithSetActiveScene(bool)

Returns a copy of these options with the active-scene assignment explicitly set.

Declaration

public ScyllaSceneLoadOptions WithSetActiveScene(bool setActiveScene)

Parameters

Type	Name	Description
bool	setActiveScene	true to make the loaded scene the active scene after an additive load; false to leave the active scene unchanged.

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value with the setting applied.

WithTimeModifierHygiene(HygieneOverride)

Returns a copy of these options with the timescale-modifier-clear hygiene step override set.

Declaration

public ScyllaSceneLoadOptions WithTimeModifierHygiene(HygieneOverride hygieneOverride)

Parameters

Type	Name	Description
HygieneOverride	hygieneOverride	The per-call override to apply.

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value with the override applied.

WithTweenHygiene(HygieneOverride)

Returns a copy of these options with the tween-kill hygiene step override set.

Declaration

public ScyllaSceneLoadOptions WithTweenHygiene(HygieneOverride hygieneOverride)

Parameters

Type	Name	Description
HygieneOverride	hygieneOverride	The per-call override to apply.

Returns

Type	Description
ScyllaSceneLoadOptions	A new options value with the override applied.

See Also

ScyllaSceneManager

ScyllaSceneConfiguration

HygieneOverride

SceneLoadOperation