Wrapper experimental do Unity para a Sala de jogos do YouTube

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

Os pacotes do Unity podem ser baixados no repositório de amostras da Sala de jogos.

Uso

1. Verifique se a plataforma do projeto 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 configurar e usar esse modelo, siga as etapas na seção Modelo do WebGL.
   • Para usar seu próprio arquivo da Web e index.html, adicione duas linhas ao script de criação do index.html Unity. Consulte a seção Usar seu próprio arquivo index.html para integração.
3. Abra o projeto no Unity e importe um dos pacotes para ele.
   • GoogleYTGameWrapper.unitypackage: contém um 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 objeto de jogo e nomeie-o como YTGameWrapper. Esse objeto de jogo é usado para se comunicar com a ponte JS.
5. IMPORTANTE:adicione o código YTGameWrapper.cs importado 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 alternância DontDestroyOnSceneChange ativada por padrão. Isso garante que o script e o GameObject permaneçam durante todo o jogo.

   GameObject.DontDestroyOnLoad(this.gameObject);
   

7. O componente YTGameWrapper.cs e o GameObject YTGameWrapper são usados para se conectar ao SDK do YouTube Playables. Use essas informações para se conectar ao YouTube. Usando o script para encontrar o objeto e o componente ou adicionando manualmente ao código do jogo pelo Unity Editor.

8. Verifique se você está seguindo os requisitos técnicos do 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 Unity.

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

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

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

    ...

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

    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#, mas não é a lista completa de APIs disponíveis. Para conferir a lista completa de APIs disponíveis, consulte o SDK do YouTube Playables.

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 detectar 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 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 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 ter os melhores resultados, faça essa chamada durante uma pausa no jogo, por exemplo, no final de uma fase.

...
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.
    }
}

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 devem estar abaixo do nosso limite individual de tamanho de arquivo. Se for esse o caso, não faça compactação extra nos arquivos, porque eles serão compactados automaticamente quando você os enviar. Essa compactaçã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, seus arquivos excederem o limite máximo de tamanho individual, é melhor usar a compactação ZIP para verificar se eles se encaixam nesse limite. A compactação reproduzível não vai compactar esses arquivos novamente.

Observação: no momento, não há suporte para projetos do Unity criados com a compressão gzip ou brotli do Unity. Todos os projetos precisam ser criados sem compactação. Se a compactação for necessária, ela deverá ser feita após o build inicial.

Modelo do 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, faça isso também.
2. Defina seu modelo WebGL para usar YTGameWrapperTemplate. Essa configuração está na guia Edit -> Project settings -> Player -> 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 ajustam nada.
3. Verifique se o Compression Format está definido como "Desativado". 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 de acordo com as necessidades do seu projeto.
5. Siga apenas as etapas 5 e 6 se a compactaçã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 seus projetos que precisam ser compactados para se adequar aos limites de tamanho de arquivo individuais e compacte esses arquivos. Exclua os arquivos originais .wasm/.data que foram compactados, já que você vai enviar os arquivos *.wasm.zip e *.data.zip em vez deles.
   • Observação: se você estiver usando um Mac, clique com o botão direito do mouse no arquivo e selecione "Compactar *". No PC, clique com o botão direito do mouse no arquivo e selecione "Compactar para arquivo ZIP".
6. Siga apenas se você fez a etapa 5: atualize o arquivo index.html criado em YTGameWrapperTemplate para carregar e descompactar os arquivos.
   • Perto do final dos arquivos index.html, encontre Path 1 e adicione um comentário à seguinte linha InitUnitySection();.
   • Perto do final dos arquivos index.html, encontre Path 2 e adicione um comentário à seguinte linha loadResources(InitUnitySection);.
7. Ao enviar seu projeto para certificação, você precisará enviar 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 das amostras fornecidas para usar o Pipeline de Renderização Universal (URP)

Um dos avanços mais recentes das versões mais novas do Unity é o uso do Pipeline de Renderização Universal (URP). Para fazer upgrade da amostra e garantir que tudo seja 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 seu projeto do Unity (carregamento lento)

Um dos principais problemas destacados pelos desenvolvedores ao usar o Unity é ficar abaixo dos requisitos individuais de tamanho do arquivo e dos requisitos totais de tamanho do pacote.

O carregamento lento de recursos é uma ótima otimização que você pode fazer no 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 do arquivo se isso for feito corretamente, já que o jogo completo não será carregado de imediato, mas conforme o usuário navega pelo produto.

Para ajudar no carregamento adequado, o Unity tem várias maneiras de dividir seus 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

Com os endereçáveis, é possível identificar diferentes arquivos que precisam ser carregados juntos, e o Unity processa a maior parte do empacotamento para você. O Unity também oferece algumas ferramentas para gerenciar tamanhos de arquivo e ajudar a garantir que você não esteja duplicando recursos.

Para usar o Addressables, importe o pacote pelo Package Manager no Unity e marque seus recursos em grupos de Addressables. Para mais detalhes, consulte a documentação do Unity (link em inglês).

Pacotes de recursos

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

Consulte a referência completa da API YT Playables.