LoadSceneAsync, AsyncOperation, and allowSceneActivation

[nocturne oxide]

I find the documentation to be very lacking on this topic.

I am trying to pre-load scenes additively for performance-related issues (I am building an XR app, and don't want hiccups to happen when transitioning scenes).

The documentation states that Unity 'Stops Progress at Unity stops progress at 0.9'

But what does that even mean?
Have all assets fully finished loading? Is the 0.9 just an arbitrary number? What happens in the last 10%?

Furthermore, the docs state:

//Begin to load the Scene you specify
AsyncOperation asyncOperation = SceneManager.LoadSceneAsync("Scene3");
//Don't let the Scene activate until you allow it to
asyncOperation.allowSceneActivation = false;

So now I have to store this AsyncOperation, which seems to be a very generic name. Why does it 'magically' have a allowSceneActivation property?
Why is there nothing other in the docs that describes that this has to do with Scene loading?

The way I'm currently doing things feels needleslly complicated:

private void LoadModule(GameplayModuleData startingModule, UnityEvent sceneReadyEvent = null, UnityEvent sceneActivatedEvent = null)
{
    Logger.Log($"Loading Module: '{startingModule.name}'");
    SceneLoadState sceneLoadState = ModuleLoader.Instance.LoadModule(
        startingModule,
        additive: true,
        preload: true,
        sceneReadyEvent,
        sceneActivatedEvent);

    _loadedModules[startingModule] = sceneLoadState;
    Logger.Log($"Tuple stored for module '{startingModule.name}'");
}

void Update()
{
    if (Keyboard.current.spaceKey.wasPressedThisFrame)
    {
        Logger.Log($"Activating scene for Starting Module: '{StartingModule.name}'");
        _loadedModules[StartingModule].SceneLoadOperation.allowSceneActivation = true;
    }
}

[nocturne cipher]

Yes, 0.9 is arbitrary and just used as an indicator that the scene has been fully loaded and the only thing that remains is "activating" it. Which just means calling Awake/OnEnable on all scripts and components. You don't have to use allowSceneActivation for async loading, it doesn't avoid hitches, it's only there if you want to delay scene activation for whatever reason.

The thing is, Unity can do all the scene loading on a background thread fully asynchronously and avoid stalling the main thread. But it has to activate scripts and components on the main thread (and deactivate, call OnDisable/OnDestroy when unloading the previous scene). So there is always still a chance of a hitch when using LoadSceneAsync during this step, depending on how many components you have and how heavy their initialization logic is. That's why Unity lets you delay this part, so you can control the circumstances before that hitch happens.

As for why AsyncOperation is a mess, it's a type that Unity decided to reuse for both async scene loading and async web requests. Which was fine, until they wanted to add this allowSceneActivation flag, so instead of refactoring the whole thing, they just slapped it on.

Sorry, no, it isn't used for web request, but for other asset loading APIs. But still, they wrote it to be reusable elsewhere.

[nocturne oxide]

yeah reason I want to use it is pretty much exactly that - i don't want to need a custom awake/start lifecycle hook, so loading in the scene and then disabling everything wouldn't work.

[arctic flicker]

I'm not sure it's only the Awake/Start functions that are called after scene activation (last 10%). I think it is impossible to load a scene without frame skip in Unity... async included, additive or not.

Having made a VR-game myself, ended up fading to black during async scene transitions so the freezes would not get noticed. Have almost nothing in Awake/Start. Don't know how it would be additively loading though.

[wheat ivy]

As far as i know its something to do with the physics...