Core Scene Manager

O Core Scene Manager é a peça mais importante do pacote. Ele é responsável por realizar Operações de Cena em coordenação com o Unity Scene Manager.

Interface ISceneManager

A interface ISceneManager expõe alguns métodos e eventos para padronizar as Operações de Cena:

public interface ISceneManager : IDisposable
{
    event Action<Scene, Scene> ActiveSceneChanged;
    event Action<Scene> SceneUnloaded;
    event Action<Scene> SceneLoaded;
    event Action<SceneOperation> OperationStarted;

    int LoadedSceneCount { get; }
    int TotalSceneCount { get; }

    void SetActiveScene(Scene scene);

    SceneOperation TransitionAsync(SceneParameters sceneParameters, LoadingScreen loadingScreen = null);

    SceneOperation ReloadActiveSceneAsync(LoadingScreen loadingScreen = null);

    SceneOperation LoadAsync(SceneParameters sceneParameters);

    SceneOperation UnloadAsync(SceneParameters sceneParameters);

    Scene GetActiveScene();

    bool TryGetLoadedSceneAt(int index, out Scene scene);

    Scene GetLastLoadedScene();

    bool TryGetLoadedSceneByName(string name, out Scene scene);
}

As duas consultas são métodos Try: elas respondem se a cena está lá em vez de lançar exceção quando não está, então TryGetLoadedSceneAt é seguro de chamar enquanto LoadedSceneCount muda por causa de um carregamento ou descarregamento em outro lugar. TryGetLoadedSceneByName só enxerga cenas que terminaram de carregar — uma cena ainda a caminho não é uma delas, então ele não serve de proteção contra iniciar o mesmo carregamento duas vezes. Para isso, guarde a SceneOperation que o primeiro LoadAsync retornou.

info

Quatro métodos async cobrem todos os casos. SceneParameters e LoadingScreen convertem a partir de qualquer tipo de referência, então carregar uma cena pelo nome e cinco por AssetReference é o mesmo método com argumentos diferentes.

Progresso e cancelamento são propriedades do trabalho, não da requisição, então eles vivem no SceneOperation retornado.

Você vai notar muitas semelhanças com a classe SceneManager da Unity, tanto para manter a curva de aprendizado suave quanto porque algumas dessas operações acabam chamando o Unity Scene Manager internamente (como SetActiveScene, por exemplo).

O pacote inclui a implementação CoreSceneManager, capaz de lidar com operações de cena tanto addressable quanto não-addressable. Você pode usar essa implementação como referência para construir seu próprio Scene Manager, se precisar.

O CoreSceneManager foi pensado para ser usado como uma camada sobre o SceneManager da Unity, com funcionalidades adicionais. Ao criar um CoreSceneManager, você decide se ele deve ou não gerenciar as cenas que já estavam carregadas.

A interface ISceneManager define que os métodos LoadAsync, UnloadAsync, TransitionAsync e ReloadActiveSceneAsync retornam um SceneOperation — de forma síncrona, antes de o trabalho começar. Isso significa que você pode dar await nele, ou se inscrever nos eventos SceneLoaded ou SceneUnloaded para receber as mesmas cenas.

info

Você também pode aguardar a conclusão desses métodos em coroutines:

yield return sceneManager.LoadAsync("my-scene").ToCoroutine();

Os quatro métodos também recebem uma struct SceneParameters. Assim, um único método cobre um índice de build, um nome, um caminho, um endereço ou um array de qualquer um deles.

Construtor

Você pode criar um CoreSceneManager usando três construtores:

// Cria um Core Scene Manager incluindo todas as cenas atualmente carregadas. Útil para a maioria dos casos.
// Não deve ser chamado no `Awake()`, já que ele roda antes da cena ser carregada.
new CoreSceneManager(addLoadedScenes: true);

// Cria um Core Scene Manager vazio. Útil se você fizer isso antes de qualquer cena ser carregada ou em uma cena de bootstrap.
new CoreSceneManager();

// Cria um Core Scene Manager incluindo um array de cenas. Útil quando você quer incluir apenas um conjunto específico de cenas.
new CoreSceneManager(initializationScenes: new Scene[]);

nota

Você não precisa criar manualmente uma instância de CoreSceneManager se estiver usando o MySceneManager.

Scene Parameters

SceneParameters é uma struct que simplifica o envio de uma ou várias cenas como parâmetros para as Operações de Cena.

public readonly struct SceneParameters
{
    public readonly int Length;

    public readonly SceneRef GetSceneRef();

    public readonly SceneRef[] GetSceneRefs();

    public readonly bool ShouldSetActive();

    public readonly int GetIndexToActivate();
}

Isso permite definir um único método capaz de realizar operações em uma ou várias cenas. Idealmente, você deve confiar nas conversões implícitas em vez de criar uma instância manualmente a cada chamada. Por exemplo:

// Você não precisa fazer isso:
sceneManager.LoadAsync(new SceneParameters(SceneRef.FromKey("my-scene")));

// A conversão faz isso por você:
sceneManager.LoadAsync("my-scene");

Use o construtor explícito quando precisar indicar qual cena vai ficar ativa:

sceneManager.LoadAsync(new SceneParameters("my-scene", true));
sceneManager.LoadAsync(new SceneParameters(new SceneRef[] { 1, 2, 3 }, 1));

Scene Result

Assim como o SceneParameters, o SceneResult simplifica o retorno de uma ou várias cenas como resultado de uma Operação de Cena.

public readonly struct SceneResult
{
    public readonly Scene GetScene();

    public readonly Scene[] GetScenes();
}