Antes de começar, consulte a documentação oficial, que oferece explicações detalhadas e atualizadas.

Instalação via UPM

No Unity, vá até Edit > Project Settings > Package Manager e adicione o seguinte registro:

• Registry URL: https://package.openupm.cn
• Scope(s): com.tuyoogame.yooasset

Em seguida, abra o Package Manager, selecione My Registries e instale o pacote YooAsset. Este guia foi testado com a versão 1.4.17.

Configuração no Editor

Criar arquivo de configuração

Clique com o botão direito no painel Project e escolha YooAsset > Create Setting. O nome do manifesto (MainfestFileName) pode permanecer padrão.

AssetBundle Collector

Habilite as opções Show Package, Use Chinese e Enable Addressable. Crie um novo Package, defina Groups e configure Collectors para definir quais assets pertencem a cada grupo. Os collectors permitem regras personalizadas de inclusão de recursos com base em diretórios ou filtros.

Builder (Construção)

Escolha o modo de construção:

• ForceRebuild: Recria todos os bundles do zero.
• Incremental: Gera apenas bundles novos ou modificados — ideal para atualizações incremenatis em servidores.
• DryRun: Gera apenas manifestos, sem empacotar assets.
• Simulate: Simula o processo de construção (apenas no editor).

Defina compressão como LZ4 (recomendado por desempenho) ou LZMA (maior compressão). A criptograifa requer implementação personalizada de interface. Marque Copy to StreamingAssets se desejar incluir bundles no build final.

Reporter

O diretório Bundles contém os arquivos gerados. O SandBox armazena caches de downloads. Use o Reporter para importar manifestos gerados (pastas com data/hora) e verificar integridade. O depurador integrado detecta referências circulares durante execução.

Inicialização por Código

Passo comum a todos os modos

// Inicializa o sistema
YooAssets.Initialize();

// Cria um pacote com nome correspondente ao definido no Collector
var pkg = YooAssets.CreatePackage("DefaultPackage");

// Define como pacote padrão para carregamento
YooAssets.SetDefaultPackage(pkg);

Seleção do modo de execução

public enum RuntimeMode { EditorSimulate, Offline, Online }

private RuntimeMode _mode = RuntimeMode.EditorSimulate;

// Escolha o modo e inicie a rotina correspondente
switch (_mode)
{
    case RuntimeMode.EditorSimulate:
        StartCoroutine(InitEditorSimulate(pkg));
        break;
    case RuntimeMode.Offline:
        StartCoroutine(InitOffline(pkg));
        break;
    case RuntimeMode.Online:
        StartCoroutine(InitOnline(pkg));
        break;
}

Modo de simulação (Editor)

IEnumerator InitEditorSimulate(ResourcePackage pkg)
{
    var param = new EditorSimulateModeParameters();
    param.SimulateManifestFilePath = EditorSimulateModeHelper.SimulateBuild("DefaultPackage");
    yield return pkg.InitializeAsync(param);
}

Funciona apenas no editor. Não gera bundles reais.

Modo offline (standalone)

IEnumerator InitOffline(ResourcePackage pkg)
{
    var param = new OfflinePlayModeParameters();
    yield return pkg.InitializeAsync(param);
}

Exige que os bundles tenham sido copiados automaticamente para StreamingAssets/buildin durante a construção.

Modo online (com servidor)

Use um servidor HTTP local (ex: HFS) para hospedar os bundles. Arraste a pasta de saída do build para o servidor e anote a URL (ex: http://127.0.0.1:9999/FTP/2023-04-20-1108).

Inicialização

string _serverUrl = "http://127.0.0.1:9999/FTP/2023-04-20-1108";

IEnumerator InitOnline(ResourcePackage pkg)
{
    var param = new HostPlayModeParameters();
    param.QueryServices = new LocalBuiltInChecker();
    param.DefaultHostServer = _serverUrl;
    param.FallbackHostServer = _serverUrl;
    yield return pkg.InitializeAsync(param);
}

class LocalBuiltInChecker : IQueryServices
{
    public bool QueryStreamingAssets(string fileName)
    {
        string builtInDir = YooAssets.GetStreamingAssetBuildinFolderName();
        string fullPath = Path.Combine(Application.streamingAssetsPath, builtInDir, fileName);
        return File.Exists(fullPath);
    }
}

Atualização de versão

string _remoteVersion;

IEnumerator FetchRemoteVersion(ResourcePackage pkg)
{
    var op = pkg.UpdatePackageVersionAsync(timeout: 60);
    yield return op;
    if (op.Status != EOperationStatus.Succeed)
    {
        Debug.LogError("Falha ao obter versão remota.");
        yield break;
    }
    _remoteVersion = op.PackageVersion;
}

Atualização do manifesto

IEnumerator UpdateManifest(ResourcePackage pkg)
{
    var op = pkg.UpdatePackageManifestAsync(_remoteVersion);
    yield return op;
    if (op.Status != EOperationStatus.Succeed)
        Debug.LogError("Falha ao atualizar manifesto.");
}

Download de patches

IEnumerator DownloadPatches()
{
    var pkg = YooAssets.GetPackage("DefaultPackage");
    var downloader = pkg.CreateResourceDownloader(
        downloadingMaxNum: 10,
        failedTryAgain: 3,
        timeout: 60
    );

    if (downloader.TotalDownloadCount == 0) yield break;

    downloader.OnDownloadErrorCallback += OnDownloadError;
    downloader.OnDownloadProgressCallback += OnProgress;
    downloader.BeginDownload();
    yield return downloader;

    if (downloader.Status == EOperationStatus.Succeed)
        Debug.Log("Download concluído com sucesso.");
    else
        Debug.Log("Falha no download.");
}

Estratégias por cenário

Desenvolvimento (Editor)

Use EditorSimulateMode para iterações rápidas sem rebuilds.

Jogo offline completo

Construa com Copy to StreamingAssets ativado e use OfflinePlayMode.

Offline com verificação de atualização

IEnumerator Start()
{
    var pkg = YooAssets.GetPackage("DefaultPackage");
    
    // Tenta obter versão remota
    var versionOp = pkg.UpdatePackageVersionAsync(60);
    yield return versionOp;

    if (versionOp.Status == EOperationStatus.Succeed)
    {
        // Prossegue com atualização online
        yield return UpdateManifest(pkg);
        yield return DownloadPatches();
    }
    else
    {
        // Verifica integridade local
        string localVer = pkg.GetPackageVersion();
        var preCheck = pkg.PreDownloadContentAsync(localVer);
        yield return preCheck;

        if (preCheck.Status != EOperationStatus.Succeed)
        {
            ShowMessage("Erro na verificação local. Conecte-se à internet.");
            yield break;
        }

        var checker = preCheck.CreateResourceDownloader(1, 1, 10);
        if (checker.TotalDownloadCount > 0)
        {
            ShowMessage("Conteúdo local incompleto. Atualize com internet.");
            yield break;
        }
    }

    StartGame();
}

Jogo totalmente online

Siga a sequência completa: inicialização, atualização de versão, manifesto e download. Qualquer falha deve impedir o acesso ao jogo.