Wrapper experimental do Unity para a Sala de jogos do YouTube

Com esse wrapper, você pode acessar o SDK do Sala de jogos do YouTube no Unity C#. O wrapper tem um plug-in .jslib e um arquivo C# para ajudar a acelerar o desenvolvimento. Há também um projeto de amostra que mostra como usar esses recursos no seu projeto.

Os pacotes do Unity podem ser baixados no nosso repositório de amostras do Playables sample repo.

Uso

  1. Verifique se a plataforma do seu projeto do Unity está definida como WebGL. Essa configuração pode ser encontrada em Build Settings.
  2. Use o WebGLTemplate para criar seu jogo para a Web ou siga a seção Usar seu próprio arquivo index.html e verifique se você configurou e inicializou o SDK da Web no arquivo index.html.
    • WebGLTemplate pode ser encontrado no pacote Google-WebGLTemplate-only.unitypackage ou GoogleYTGameWrapper-with-sample.unitypackage. Para definir e usar esse modelo, siga as etapas na seção Modelo WebGL.
    • Para usar seu próprio arquivo da Web e index.html, adicione duas linhas ao script de criação do index.html do Unity. Consulte a seção Usar seu próprio arquivo index.html para integração.
  3. Abra seu projeto no Unity e importe um dos pacotes para ele.
    • GoogleYTGameWrapper.unitypackage: contém o plug-in JS para conectar o SDK da Sala de jogos do YouTube e um wrapper C# para ajudar a conectar isso ao seu produto.
    • GoogleYTGameWrapper-with-sample.unitypackage: contém o mesmo conteúdo de arquivos do pacote GoogleYTGameWrapper e um exemplo de como usar o SDK da Sala de jogos do YouTube em C#.
  4. IMPORTANTE:na cena principal, crie um novo gameobject e nomeie-o como YTGameWrapper. Esse objeto de jogo é usado para se comunicar com a ponte JS.
  5. IMPORTANTE: adicione o código importado YTGameWrapper.cs como um componente de script ao GameObject YTGameWrapper.

  6. Se o projeto tiver várias cenas, adicione DontDestroyOnLoad ao script YTGameWrapper.cs. Observação: as novas versões do script têm uma opção DontDestroyOnSceneChange ativada por padrão. Isso garante que o script e o GameObject permaneçam no jogo.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. O componente YTGameWrapper.cs e o GameObject YTGameWrapper são usados para se conectar ao SDK da Sala de jogos do YouTube. Use-os para se conectar ao YouTube. Você pode usar o script para encontrar o objeto e o componente ou adicioná-los manualmente ao código do jogo pelo Unity Editor.

  8. Verifique se você está seguindo os requisitos técnicos para o seu projeto.

Usar seu próprio arquivo index.html

Se você não usar o exemplo index.html fornecido, adicione duas linhas de código ao script de criação do index.html do Unity.

Primeiro, adicione essa linha no mesmo lugar em que o projeto configura variáveis para o contêiner do Unity, a tela etc.

    var container = document.querySelector("#unity-container");
    var canvas = document.querySelector("#unity-canvas");

    var unityGameInstance = null; // <-- Add this line >

    ...

Em segundo lugar, dentro da função createUnityInstance, adicione esta linha.

    createUnityInstance(canvas, config, (progress) => {
        progressBarFull.style.width = 100 * progress + "%";
    }).then((unityInstance) => {

        unityGameInstance = unityInstance; // <-- Add this line >

    ...

Exemplos

Esta seção tem alguns exemplos de como usar o wrapper C#. Não é a lista completa de APIs disponíveis. Para conferir a lista completa de APIs disponíveis, consulte o SDK da Sala de jogos do YouTube.

sendScore

Este exemplo mostra uma implementação de sendScore(int points) em C#:

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;
public int battleScore = 0;

...

// Update the total score and send this to the YouTube Game Wrapper.
public void UpdateScores(int scoreAmt)
{
    battleScore += scoreAmt;
    // ytGameWrapper should be a reference to your YTGameWrapper component.
    ytGameWrapper.SendGameScore(battleScore);
}

onPause

Este é um exemplo de como um jogo pode ouvir eventos Pause do YT Playables para pausar o mecanismo quando necessário:

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;
public bool gameIsPaused = false;

...
void Start()
{
    // Sets the OnPause callback with the YT Playables SDK
    ytGameWrapper.SetOnPauseCallback(PauseTheGameCallback);
}

// Pause game callback, will pause the game when called.
public void PauseTheGameCallback()
{
    gameIsPaused = true;
}

saveData

Este é um exemplo de como usar saveData, enviando-o para o SDK do YT Playables:

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;

...

// Saves the current score of the game and converts it to a JSON format.
public void SaveScore(int scoreAmt)
{
    SaveGameData("{\"BestScore\": \"" + scoreAmt.ToString() + "\"}");
}

public void SaveGameData(string saveString)
{
    if (string.IsNullOrEmpty(saveString)) return;

    // Sends save data to the YT Playables SDK
    ytGameWrapper.SendGameSaveData(saveString);
}

loadData

Este é um exemplo de como usar loadData, enviando-o para o SDK do YT Playables:

...
using UnityEngine;
using YTGameSDK;
...

[Serializable]
public class LoadedScores
{
    public int BestScore;
    public float BestTime;
}

public YTGameWrapper ytGameWrapper;

...

void Start()
{
    ytGameWrapper.LoadGameSaveData(LoadSaveGameDataReturned);
}

public void LoadSaveGameDataReturned(string data)
{
    if (!string.IsNullOrEmpty(data))
    {
        LoadedScores loadedScores = JsonUtility.FromJson<LoadedScores>(data);
        Debug.Log("LoadSaveGameDataReturned > Score <" + loadedScores.BestScore.ToString()
                  +   "> Time <" + loadedScores.BestTime.ToString("0.00"));
    }
}

requestInterstitialAd

Este é um exemplo de como usar requestInterstitialAd, indicando que é um bom momento para mostrar um anúncio intersticial, se disponível. Para melhores resultados, faça essa chamada durante um intervalo no jogo, por exemplo, no final de um nível.

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;

...

// At the end of a round send a request to show an interstitial Ad, if one is
//  available an Ad will be shown and Pause Game Callback should be called.

// EXAMPLE: send and forget
public void RequestInterstitialAd()
{
    ytGameWrapper.RequestInterstitialAd();
}

// EXAMPLE: send and react to if an Ad was shown
public void RequestInterstitialAd()
{
    int status = ytGameWrapper.RequestInterstitialAd();
    if (status == 0)
    {
        // Ad request was successful, do some action.
    }
}

requestRewardedAd

Este é um exemplo de como usar requestRewardedAd. Ele é usado quando um usuário seleciona um anúncio premiado em troca de uma recompensa no jogo. Se um anúncio estiver disponível, ele será apresentado ao usuário.

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;

...

public void RequestRewardedAd()
{
    // Register callback for Rewarded Ads. If an Ad is available one will be
    //  shown. Pause Game Callback should be called. Any ID is fine as long as
    //  its identifyable for your game.
    ytGameWrapper.RequestRewardedAd("my-reward-ad-id-123", (rewardEarned) => {
        if (rewardEarned) {
            // Rewarded Ad is earned, reward the user.
        } else {
            // Rewarded Ad not earned, take the appropriate action
        }
    });
}

Como usar o modelo WebGL de exemplo do YouTube

A menos que você tenha um projeto do Unity muito pesado, os arquivos .wasm e .data criados precisam estar abaixo do limite de tamanho de arquivo individual. Se for esse o caso, não faça nenhuma compressão extra desses arquivos, porque eles serão compactados automaticamente no envio dos arquivos do Playables. Essa compressão automática também verifica se o arquivo .wasm atende ao requisito de tamanho do pacote inicial. Por exemplo, um arquivo .wasm de ~25 MiB será compactado para ~7 MiB.

Se, por algum motivo, os arquivos excederem o limite máximo de tamanho de arquivo individual, é melhor usar a compressão ZIP para verificar se eles se encaixam nesse limite. A compressão do Playables não vai compactar esses arquivos novamente.

Modelo WebGL

  1. Siga as instruções do pacote do Unity acima para a configuração inicial. Use Google-WebGLTemplate-only.unitypackage ou GoogleYTGameWrapper-with-sample.unitypackage e importe todos os arquivos na pasta WebGLTemplates/YTGameWrapperTemplate/.
    • Observação: se você ainda não importou YTGameWrapper.cs e UnityYTGameSDKLib.jslib, importe-os também.
  2. Defina o modelo WebGL para usar YTGameWrapperTemplate. Essa configuração está em Edit -> Project settings -> Player -> guia WebGL -> seção Resolution and Presentation.
    • Observação: a largura e a altura padrão da tela são definidas como 100% no modelo. Portanto, essas configurações do Unity não vão ajustar nada.
  3. Verifique se o Compression Format está definido como "Disabled". Essa configuração está em Project settings -> Player -> guia WebGL -> seção Publishing Settings.
  4. Crie para WebGL na janela Build Settings e siga para a etapa 7 ou 5 com base nas necessidades do seu projeto.
  5. Siga apenas as etapas 5 e 6 se a compressão for usada: depois que o projeto for criado, navegue até o local da pasta de build e abra a pasta Build. Encontre os arquivos .wasm ou .data dos projetos que precisam de compressão para se ajustar aos limites de tamanho de arquivo individual e compacte estes arquivos. Exclua os arquivos .wasm/.data originais que foram compactados, porque você vai enviar os arquivos *.wasm.zip e *.data.zip em vez disso.
    • Observação: se você estiver usando um Mac, clique com o botão direito do mouse no arquivo e selecione "Compress *". No PC, clique com o botão direito do mouse no arquivo e selecione "Compress to ZIP file".
  6. Siga apenas se você fez a etapa 5: atualize o arquivo index.html criado no YTGameWrapperTemplate para carregar arquivos compactados e descompactá-los.
    • Perto do final dos arquivos index.html, você vai encontrar Path 1 e comentar a seguinte linha: InitUnitySection();.
    • Perto do final dos arquivos index.html, você vai encontrar Path 2 e comentar a seguinte linha: loadResources(InitUnitySection);.
  7. Ao enviar seu projeto para certificação, envie todos os arquivos criados no Unity para o local de build da etapa 4. Se as etapas 5 e 6 foram seguidas, inclua esses arquivos também.

Fazer upgrade dos exemplos fornecidos para usar o Pipeline de Renderização Universal (URP)

Um dos avanços mais recentes das versões mais recentes do Unity é que elas usam o Pipeline de Renderização Universal (URP, na sigla em inglês). Para fazer upgrade da amostra, tudo é renderizado corretamente.

  1. Comece importando o pacote GoogleYTGameWrapper-with-sample.unitypackage para um projeto novo ou atual.
  2. Navegue até a janela Render Pipeline Converter: Window -> Rendering -> Render Pipeline Converter.
  3. Selecione Rendering Settings, Material Upgrade e Readonly Material Converter.
  4. Em seguida, selecione Initialize and Convert, aguarde a conclusão e a amostra estará pronta para o URP.

Como dividir recursos no projeto do Unity (carregamento lento)

Um dos principais problemas que os desenvolvedores destacaram ao usar o Unity é manter os requisitos de tamanho de arquivo individual e os requisitos de tamanho total do pacote .

O carregamento lento de recursos é uma ótima otimização que você pode fazer para seu projeto, já que é possível carregar recursos, níveis e dados conforme necessário. Nossa equipe de certificação pode dispensar as restrições gerais de tamanho de arquivo se isso for feito corretamente, já que o jogo completo não será carregado antecipadamente, mas conforme o usuário navega pelo produto.

Para ajudar no carregamento adequado, o Unity tem várias maneiras de dividir os recursos, verificando se os grupos de recursos individuais estão abaixo dos limites de tamanho e se você carrega o conteúdo ao longo do tempo. Sugerimos usar Addressables ou Asset Bundles.

Addressables

Os Addressables permitem identificar diferentes arquivos que precisam ser carregados juntos, e o Unity vai processar a maior parte da embalagem para você. O Unity também oferece algumas ferramentas para gerenciar tamanhos de arquivos e ajudar a garantir que você não esteja duplicando recursos.

Para usar os Addressables, importe o pacote Addressables pelo Package Manager no Unity e marque os recursos em grupos de Addressables. Mais detalhes podem ser encontrados na documentação do Unity.

Asset Bundles

Os Asset Bundles são úteis porque você pode dividir seu projeto e carregar elementos em tempo real. Eles são úteis para DLCs, pacotes de níveis, novos personagens e muito mais. Os Asset Bundles são ótimos para carregamento e agrupamento de conteúdo autogerenciado. Eles podem ser usados marcando os recursos em pacotes específicos e carregando pacotes conforme necessário. Mais detalhes podem ser encontrados na documentação do Asset Bundle do Unity.

Consulte a referência completa da API YT Playables.