Class XRManagerSettings

Class to handle active loader and subsystem management for XR. This class is to be added as a ScriptableObject asset in your project and should only be referenced by the XRGeneralSettings instance for its use.

Given a list of loaders, it will attempt to load each loader in the given order. The first loader that is successful wins and all remaining loaders are ignored. The loader that succeeds is accessible through the activeLoader property on the manager.

Depending on configuration the XRManagerSettings instance will automatically manage the active loader at correct points in the application lifecycle. The user can override certain points in the active loader lifecycle and manually manage them by toggling the automaticLoading and automaticRunning properties. Disabling automaticLoading implies the the user is responsible for the full lifecycle of the XR session normally handled by the XRManagerSettings instance. Toggling this to false also toggles automaticRunning false.

Disabling automaticRunning only implies that the user is responsible for starting and stopping the activeLoader through the StartSubsystems() and StopSubsystems() APIs.

Automatic lifecycle management is executed as follows

• Runtime Initialize -> InitializeLoader(). The loader list will be iterated over and the first successful loader will be set as the active loader.
• Start -> StartSubsystems(). Ask the active loader to start all subsystems.
• OnDisable -> StopSubsystems(). Ask the active loader to stop all subsystems.
• OnDestroy -> DeinitializeLoader(). Deinitialize and remove the active loader.

Inheritance

Object

XRManagerSettings

Namespace: UnityEngine.XR.Management

Syntax

public sealed class XRManagerSettings : ScriptableObject

Properties

activeLoader

Return the current singleton active loader instance.

Declaration

public XRLoader activeLoader { get; }

Property Value

Type	Description
XRLoader

activeLoaders

A shallow copy of the list of loaders currently managed by this XR Manager instance.

Declaration

public IReadOnlyList<XRLoader> activeLoaders { get; }

Property Value

Type	Description
IReadOnlyList<XRLoader>

Remarks

This property returns a read only list. Any changes made to the list itself will not affect the list used by this XR Manager instance. To mutate the list of loaders currently managed by this instance, use TryAddLoader(XRLoader, Int32), TryRemoveLoader(XRLoader), and/or TrySetLoaders(List<XRLoader>).

automaticLoading

Get and set Automatic Loading state for this manager. When this is true, the manager will automatically call InitializeLoader() and DeinitializeLoader() for you. When false automaticRunning is also set to false and remains that way. This means that disabling automatic loading disables all automatic behavior for the manager.

Declaration

public bool automaticLoading { get; set; }

Property Value

Type	Description
Boolean

automaticRunning

Get and set automatic running state for this manager. When set to true the manager will call StartSubsystems() and StopSubsystems() APIs at appropriate times. When set to false, or when automaticLoading is false then it is up to the user of the manager to handle that same functionality.

Declaration

public bool automaticRunning { get; set; }

Property Value

Type	Description
Boolean

isInitializationComplete

Read only boolean letting us know if initialization is completed. Because initialization is handled as a Coroutine, people taking advantage of the auto-lifecycle management of XRManager will need to wait for init to complete before checking for an ActiveLoader and calling StartSubsystems.

Declaration

public bool isInitializationComplete { get; }

Property Value

Type	Description
Boolean

loaders

List of loaders currently managed by this XR Manager instance.

Declaration

public List<XRLoader> loaders { get; }

Property Value

Type	Description
List<XRLoader>

Remarks

Modifying the list of loaders at runtime is undefined behavior and could result in a crash or memory leak. Use activeLoaders to retrieve the currently ordered list of loaders. If you need to mutate the list at runtime, use TryAddLoader(XRLoader, Int32), TryRemoveLoader(XRLoader), and TrySetLoaders(List<XRLoader>).

Methods

ActiveLoaderAs<T>()

Return the current active loader, cast to the requested type. Useful shortcut when you need to get the active loader as something less generic than XRLoader.

Declaration

public T ActiveLoaderAs<T>()
    where T : XRLoader

Returns

Type	Description
T	The active loader as requested type, or null.

Type Parameters

Name	Description
T	Requested type of the loader

DeinitializeLoader()

If there is an active loader, this function will deinitialize it and remove the active loader instance from management. We will automatically call StopSubsystems() prior to deinitialization to make sure that things are cleaned up appropriately.

You must wait for isInitializationComplete to be set to tru prior to calling this API.

Upon return isInitializationComplete will be rest to false;

Declaration

public void DeinitializeLoader()

InitializeLoader()

Iterate over the configured list of loaders and attempt to initialize each one. The first one that succeeds is set as the active loader and initialization immediately terminates.

When complete isInitializationComplete will be set to true. This will mark that it is safe to call other parts of the API. This does not guarantee that init successfully created a loader. For that you need to check that ActiveLoader is not null.

Note that there can only be one active loader. Any attempt to initialize a new active loader with one already set will cause a warning to be logged and immediate exit of this function.

Iteration is done asynchronously and this method must be called within the context of a Coroutine.

If manual initialization of XR is being done, this method can not be called before Start completes as it depends on graphics initialization within Unity completing.

Declaration

public IEnumerator InitializeLoader()

Returns

Type	Description
IEnumerator	Enumerator marking the next spot to continue execution at.

InitializeLoaderSync()

Iterate over the configured list of loaders and attempt to initialize each one. The first one that succeeds is set as the active loader and initialization immediately terminates.

When complete isInitializationComplete will be set to true. This will mark that it is safe to call other parts of the API. This does not guarantee that init successfully created a loader. For that you need to check that ActiveLoader is not null.

Note that there can only be one active loader. Any attempt to initialize a new active loader with one already set will cause a warning to be logged and immediate exit of this function.

This method is synchronous and on return all state should be immediately checkable.

If manual initialization of XR is being done, this method can not be called before Start completes as it depends on graphics initialization within Unity completing.

Declaration

public void InitializeLoaderSync()

StartSubsystems()

If there is an active loader, this will request the loader to start all the subsystems that it is managing.

You must wait for isInitializationComplete to be set to true prior to calling this API.

Declaration

public void StartSubsystems()

StopSubsystems()

If there is an active loader, this will request the loader to stop all the subsystems that it is managing.

You must wait for isInitializationComplete to be set to tru prior to calling this API.

Declaration

public void StopSubsystems()

TryAddLoader(XRLoader, Int32)

Attempts to append the given loader to the list of loaders at the given index.

Declaration

public bool TryAddLoader(XRLoader loader, int index = null)

Parameters

Type	Name	Description
XRLoader	loader	The XRLoader to be added to this manager's instance of loaders.
Int32	index	The index at which the given XRLoader should be added. If you set a negative or otherwise invalid index, the loader will be appended to the end of the list.

Returns

Type	Description
Boolean	true if the loader is not a duplicate and was added to the list successfully, false otherwise.

Remarks

This method behaves differently in the Editor and during runtime/Play mode. While your app runs in the Editor and not in Play mode, attempting to add an XRLoader will always succeed and register that loader's type internally. Attempting to add a loader during runtime/Play mode will trigger a check to see whether a loader of that type was registered. If the check is successful, the loader is added. If not, the loader is not added and the method returns false.

TryRemoveLoader(XRLoader)

Attempts to remove the first instance of a given loader from the list of loaders.

Declaration

public bool TryRemoveLoader(XRLoader loader)

Parameters

Type	Name	Description
XRLoader	loader	The XRLoader to be removed from this manager's instance of loaders.

Returns

Type	Description
Boolean	true if the loader was successfully removed from the list, false otherwise.

Remarks

This method behaves differently in the Editor and during runtime/Play mode. During runtime/Play mode, the loader will be removed with no additional side effects if it is in the list managed by this instance. While in the Editor and not in Play mode, the loader will be removed if it exists and it will be unregistered from this instance and any attempts to add it during runtime/Play mode will fail. You can re-add the loader in the Editor while not in Play mode.

TrySetLoaders(List<XRLoader>)

Attempts to set the given loader list as the list of loaders managed by this instance.

Declaration

public bool TrySetLoaders(List<XRLoader> reorderedLoaders)

Parameters

Type	Name	Description
List<XRLoader>	reorderedLoaders	The list of XRLoaders to be managed by this manager instance.

Returns

Type	Description
Boolean	true if the loader list was set successfully, false otherwise.

Remarks

This method behaves differently in the Editor and during runtime/Play mode. While in the Editor and not in Play mode, any attempts to set the list of loaders will succeed without any additional checks. During runtime/Play mode, the new loader list will be validated against the registered XRLoader types. If any loaders exist in the list that were not registered at startup, the attempt will fail.