Wrapper sperimentale Unity della Sala giochi di YouTube

Con questo wrapper puoi accedere all'SDK Sala giochi di YouTube in Unity C#. Il wrapper include un plug-in .jslib e un file C# per velocizzare lo sviluppo. È disponibile anche un progetto di esempio che mostra come utilizzarli nel tuo progetto.

I pacchetti Unity possono essere scaricati dal nostro repository di esempi di Playables sample repo.

Utilizzo

  1. Verifica che la piattaforma del progetto Unity sia impostata su WebGL. Questa impostazione si trova in Build Settings.
  2. Utilizza WebGLTemplate per creare il gioco per il web oppure segui la sezione Utilizzare il proprio file index.html e verifica di aver configurato e inizializzato l'SDK web nel tuo file index.html.
    • WebGLTemplate è disponibile nel pacchetto Google-WebGLTemplate-only.unitypackage o GoogleYTGameWrapper-with-sample.unitypackage. Per configurare e utilizzare questo modello, segui i passaggi descritti nella sezione Modello WebGL.
    • Per utilizzare il tuo file web e index.html, devi aggiungere due righe allo script di creazione di index.html di Unity. Per l'integrazione, consulta la sezione Utilizzare il proprio file index.html.
  3. Apri il progetto in Unity, quindi apri e importa uno dei due pacchetti nel progetto.
    • GoogleYTGameWrapper.unitypackage: contiene il plug-in JS per la connessione all'SDK Sala giochi di YouTube e un wrapper C# per facilitare la connessione al tuo prodotto.
    • GoogleYTGameWrapper-with-sample.unitypackage: contiene gli stessi file di GoogleYTGameWrapper e un esempio di come utilizzare l'SDK Sala giochi di YouTube in C#.
  4. IMPORTANTE: nella scena principale, crea un nuovo oggetto di gioco e chiamalo YTGameWrapper. Questo oggetto di gioco viene utilizzato per comunicare con il bridge JS.
  5. IMPORTANTE: aggiungi il codice importato YTGameWrapper.cs come componente di script all'oggetto di gioco YTGameWrapper.

  6. Se il progetto ha più scene, assicurati di aggiungere DontDestroyOnLoad allo script YTGameWrapper.cs (nota: le nuove versioni dello script hanno un'opzione DontDestroyOnSceneChange attiva per impostazione predefinita). In questo modo, lo script e l'oggetto di gioco rimarranno attivi durante il gioco.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. Il componente YTGameWrapper.cs e l'oggetto di gioco YTGameWrapper vengono utilizzati per connettersi all'SDK Sala giochi di YouTube. Utilizzali per connetterti a YouTube. Puoi utilizzare lo script per trovare l'oggetto e il componente oppure aggiungerli manualmente al codice del gioco tramite l'editor di Unity.

  8. Verifica di rispettare i requisiti tecnici del tuo progetto.

Utilizzare il proprio file index.html

Se non utilizzi l'esempio di index.html fornito, devi aggiungere due righe di codice allo script di creazione di index.html di Unity.

Innanzitutto, aggiungi questa riga nello stesso punto in cui il progetto configura le variabili per il contenitore Unity, la tela e così via.

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

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

    ...

Poi, aggiungi questa riga all'interno della funzione createUnityInstance.

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

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

    ...

Esempi

Questa sezione contiene alcuni esempi di come utilizzare il wrapper C#, ma non include l'elenco completo delle API disponibili. Per l'elenco completo delle API disponibili, consulta l' SDK Sala giochi di YouTube.

sendScore

Questo esempio mostra un'implementazione di sendScore(int points) in 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

Questo è un esempio di come un gioco può ascoltare gli eventi Pause provenienti da YouTube Playables per mettere in pausa il motore quando necessario:

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

Questo è un esempio di come utilizzare saveData e inviarlo all'SDK YouTube 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

Questo è un esempio di come utilizzare loadData e inviarlo all'SDK YouTube 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

Questo è un esempio di come utilizzare requestInterstitialAd per indicare che è un buon momento per mostrare un annuncio interstitial, se disponibile. Per risultati ottimali, effettua questa chiamata durante una pausa del gameplay, ad esempio alla fine di un livello.

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

Questo è un esempio di come utilizzare requestRewardedAd. Viene utilizzato quando un utente ha selezionato di visualizzare un annuncio con premio in cambio di un premio nel gioco. Se è disponibile un annuncio, verrà mostrato all'utente.

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

Come utilizzare il modello WebGL di esempio di YouTube

A meno che tu non abbia un progetto Unity molto pesante, i file .wasm e .data creati dovrebbero rientrare nel limite di dimensioni dei singoli file. In questo caso, non è necessario comprimere ulteriormente questi file, perché verranno compressi automaticamente al momento dell'invio dei file Playable. Questa compressione automatica verificherà anche che il file .wasm rientri nel requisito di dimensioni del bundle iniziale. Ad esempio, un file .wasm di circa 25 MiB verrà compresso a circa 7 MiB.

Se per qualche motivo i file superano il limite massimo di dimensioni dei singoli file, è consigliabile utilizzare la compressione ZIP per verificare che rientrino in questo limite. La compressione di Playable non comprimerà di nuovo questi file.

Modello WebGL

  1. Segui le istruzioni del pacchetto Unity riportate sopra per la configurazione iniziale. Assicurati di utilizzare Google-WebGLTemplate-only.unitypackage o GoogleYTGameWrapper-with-sample.unitypackage e di importare tutti i file nella cartella WebGLTemplates/YTGameWrapperTemplate/.
    • Nota: se non hai ancora importato YTGameWrapper.cs e UnityYTGameSDKLib.jslib, devi importarli.
  2. Imposta il modello WebGL in modo che utilizzi YTGameWrapperTemplate. Questa impostazione si trova in Edit -> Project settings -> Player -> scheda WebGL -> sezione Resolution and Presentation.
    • Nota: la larghezza e l'altezza predefinite della tela sono impostate al 100% nel modello, quindi queste impostazioni di Unity non modificheranno nulla.
  3. Assicurati che Compression Format sia impostato su Disabled. Questa impostazione si trova in Project settings -> Player -> scheda WebGL -> sezione Publishing Settings.
  4. Crea il progetto per WebGL nella finestra Build Settings, quindi vai al passaggio 7 o 5 in base alle esigenze del progetto.
  5. Segui i passaggi 5 e 6 solo se utilizzi la compressione: dopo aver creato il progetto, vai alla posizione della cartella di creazione e apri la cartella Build. Trova i file .wasm o .data del progetto che devono essere compressi per rientrare nei limiti di dimensioni dei singolifile e comprimili in un file ZIP. Assicurati di eliminare i file .wasm/.data originali compressi, perché invierai i file *.wasm.zip e *.data.zip invece.
    • Nota: se utilizzi un Mac, puoi fare clic con il tasto destro del mouse sul file e selezionare "Compress *". Su PC, puoi fare clic con il tasto destro del mouse sul file e selezionare "Compress to ZIP file".
  6. Segui questo passaggio solo se hai eseguito il passaggio 5: aggiorna il file index.html creato da YTGameWrapperTemplate per caricare i file compressi e decomprimerli.
    • Verso la fine dei file index.html, troverai Path 1 e dovrai aggiungere un commento alla riga InitUnitySection();.
    • Verso la fine dei file index.html, troverai Path 2 e dovrai aggiungere un commento alla riga loadResources(InitUnitySection);.
  7. Quando invii il progetto per la certificazione, devi inviare tutti i file creati da Unity alla posizione di creazione del passaggio 4. Se hai seguito i passaggi 5 e 6, includi anche questi file.

Eseguire l'upgrade degli esempi forniti per utilizzare Universal Render Pipeline (URP)

Uno degli ultimi progressi delle versioni più recenti di Unity è l'utilizzo di Universal Render Pipeline (URP). Per eseguire l'upgrade dell'esempio in modo che tutto venga visualizzato correttamente:

  1. Inizia importando il pacchetto GoogleYTGameWrapper-with-sample.unitypackage in un progetto nuovo o esistente.
  2. Vai alla finestra Render Pipeline Converter: Window -> Rendering -> Render Pipeline Converter.
  3. Seleziona Rendering Settings, Material Upgrade e Readonly Material Converter.
  4. Poi seleziona Initialize and Convert, attendi il completamento dell'operazione e l'esempio dovrebbe essere pronto per URP.

Come suddividere gli asset nel progetto Unity (caricamento lazy)

Uno dei principali problemi evidenziati dagli sviluppatori quando utilizzano Unity è il rispetto dei requisiti di dimensioni dei singoli file e delle dimensioni totali del bundle.

Il caricamento lazy degli asset è un'ottima ottimizzazione che puoi apportare al tuo progetto, perché ti consente di caricare asset, livelli e dati in base alle esigenze. Il nostro team di certificazione può rinunciare alle restrizioni sulle dimensioni complessive dei file se questa operazione viene eseguita correttamente, perché il gioco completo non verrà caricato in anticipo, ma man mano che l'utente naviga nel prodotto.

Per facilitare il caricamento corretto, Unity offre diversi modi per suddividere gli asset, verificare che i singoli gruppi di asset rientrino nei limiti di dimensioni e caricare i contenuti nel tempo. Ti consigliamo di utilizzare Addressables o Asset Bundle.

Addressables

Addressables ti consente di identificare i diversi file da caricare insieme e Unity gestirà la maggior parte del packaging. Unity fornisce anche alcuni strumenti per gestire le dimensioni dei file e assicurarsi di non duplicare gli asset.

Per utilizzare Addressables, devi importare il pacchetto Addressables tramite Package Manager in Unity, quindi taggare gli asset nei gruppi Addressable. Per maggiori dettagli, consulta la documentazione di Unity.

Asset Bundle

Gli Asset Bundle sono utili perché ti consentono di suddividere il progetto e caricare gli elementi al volo. Sono utili per i DLC, i pacchetti di livelli, i nuovi personaggi e altro ancora. Gli Asset Bundle sono ideali per il caricamento e il raggruppamento di contenuti autogestiti. Puoi utilizzarli taggando gli asset in bundle specifici e poi caricando i bundle in base alle esigenze. Per maggiori dettagli, consulta la documentazione di Unity relativa agli Asset Bundle.

Consulta il riferimento completo dell'API YouTube Playables.