Wrapper sperimentale Unity della Sala giochi di YouTube

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

I pacchetti Unity possono essere scaricati dal nostro repository di esempio di Playables.

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 tuo 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 file index.html.
   • WebGLTemplate si trova 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 index.html Unity. Per l'integrazione, consulta la sezione Utilizzare il proprio file index.html.
3. Apri il tuo progetto in Unity, quindi apri e importa uno dei due pacchetti nel tuo progetto.
   • GoogleYTGameWrapper.unitypackage: Contiene il plug-in JS per la connessione dell'SDK YouTube Playables e un wrapper C# per facilitare la connessione al tuo prodotto.
   • GoogleYTGameWrapper-with-sample.unitypackage: contiene gli stessi file contenuti di quelli presenti nel pacchetto GoogleYTGameWrapper e un esempio che mostra come utilizzare l'SDK YouTube Playables in C#.
4. IMPORTANTE:nella scena principale crea un nuovo gameobject e chiamalo YTGameWrapper. Questo oggetto di gioco viene utilizzato per comunicare con il bridge JS.
5. IMPORTANTE: aggiungi il codice YTGameWrapper.cs importato come componente script all'oggetto GameObject YTGameWrapper.

6. Se il tuo progetto ha più scene, assicurati di aggiungere DontDestroyOnLoad allo script YTGameWrapper.cs (nota: le nuove versioni dello script hanno un pulsante di attivazione/disattivazione DontDestroyOnSceneChange attivo per impostazione predefinita). In questo modo, lo script e GameObject rimarranno presenti per tutta la durata del gioco.

   GameObject.DontDestroyOnLoad(this.gameObject);
   

7. Il componente YTGameWrapper.cs e l'oggetto GameObject YTGameWrapper vengono utilizzati per connettersi all'SDK YouTube Playables. Utilizza questi dati per connetterti a YouTube. Utilizzando Script per trovare l'oggetto e il componente o aggiungendoli manualmente al codice del gioco tramite Unity Editor.

8. Verifica di rispettare i requisiti tecnici per il tuo progetto.

Utilizzare il proprio file index.html

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

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

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

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

    ...

Secondo, 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 è l'elenco completo delle API disponibili. Per l'elenco completo delle API disponibili, consulta l'SDK YouTube Playables.

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 YT 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, inviandolo all'SDK 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

Questo è un esempio di come utilizzare loadData, inviandolo all'SDK 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

Questo è un esempio di come utilizzare requestInterstitialAd, che indica che è un buon momento per mostrare un annuncio interstitial, se disponibile. Per ottenere risultati ottimali, effettua questa chiamata durante una pausa del gioco, 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.
    }
}

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 dovrebbero rientrare nel nostro limite di dimensioni dei file individuali. In questo caso, non devi comprimere ulteriormente questi file, in quanto verranno compressi automaticamente al momento dell'invio dei file riproducibili. Questa compressione automatica verificherà anche che il file .wasm rientri nel requisito relativo alle dimensioni iniziali del bundle. Ad esempio, un file .wasm di circa 25 MiB verrà compresso a circa 7 MiB.

Se per qualche motivo i tuoi file superano il limite di dimensione massima individuale, è consigliabile utilizzare la compressione ZIP per verificare che rientrino in questo limite. La compressione riproducibile non comprimerà nuovamente questi file.

Nota: al momento non è disponibile il supporto per i progetti Unity creati con la compressione gzip o brotli di Unity. Tutti i progetti devono essere creati senza compressione, poi, se è necessaria, deve essere eseguita dopo la build iniziale.

Modello WebGL

1. Segui le istruzioni riportate sopra per il pacchetto Unity 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 importare anche questi.
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 del canvas sono impostate al 100% nel modello, quindi queste impostazioni di Unity non modificheranno nulla.
3. Assicurati che Compression Format sia impostato su Disattivato. Questa impostazione si trova in Project settings -> Player -> scheda WebGL -> sezione Publishing Settings.
4. Crea per WebGL nella finestra Build Settings, poi vai al passaggio 7 o 5 in base alle esigenze dei tuoi progetti.
5. Segui i passaggi 5 e 6 solo se viene utilizzata la compressione: dopo aver creato il progetto, vai alla posizione della cartella di build e apri la cartella Build. Trova i file .wasm o .data dei tuoi progetti che devono essere compressi per rientrare nei limiti di dimensione dei file individuali e comprimili. Assicurati di eliminare i file .wasm/.data originali compressi, in quanto invierai i file *.wasm.zip e *.data.zip.
   • Nota: se utilizzi un Mac, puoi fare clic con il tasto destro del mouse sul file e selezionare "Comprimi *". Su PC, puoi fare clic con il tasto destro del mouse sul file e selezionare "Comprimi in file ZIP".
6. Segui questo passaggio solo se hai completato 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 commenta la riga seguente InitUnitySection();.
   • Verso la fine dei file index.html troverai Path 2 e commenta la riga seguente loadResources(InitUnitySection);.
7. Quando invii il progetto per la certificazione, devi inviare tutti i file creati da Unity alla posizione di build del passaggio 4. Se hai seguito i passaggi 5 e 6, includi anche questi file.

Esegui l'upgrade dei campioni forniti per utilizzare la pipeline di rendering universale (URP)

Uno degli ultimi progressi delle versioni più recenti di Unity è l'utilizzo della Universal Render Pipeline (URP). Per eseguire l'upgrade del campione 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 e il campione dovrebbe essere pronto per URP.

Come suddividere gli asset nel progetto Unity (caricamento differito)

Uno dei principali problemi evidenziati dagli sviluppatori durante l'utilizzo di Unity è il rispetto dei requisiti relativi alle dimensioni dei file individuali e alle dimensioni totali del bundle.

Il caricamento differito degli asset è un'ottima ottimizzazione che puoi apportare al tuo progetto, in quanto puoi caricare asset, livelli e dati in base alle necessità. Il nostro team di certificazione potrebbe rinunciare alle limitazioni generali delle dimensioni dei file se questa operazione viene eseguita correttamente, in quanto il gioco completo non verrà caricato in anticipo, ma man mano che l'utente naviga nel tuo prodotto.

Per facilitare il caricamento corretto, Unity offre diversi modi per dividere gli asset, verificando che i singoli gruppi di asset rispettino i limiti di dimensione e che i contenuti vengano caricati nel tempo. Ti consigliamo di utilizzare Addressables o Asset Bundles.

Addressables

Gli asset indirizzabili ti consentono di identificare diversi file da caricare insieme e Unity gestirà la maggior parte del packaging per te. Unity fornisce anche alcuni strumenti per gestire le dimensioni dei file e assicurarsi di non duplicare le risorse.

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

Bundle di asset

I bundle di asset sono utili perché puoi dividere il progetto e caricare gli elementi al volo. Sono utili per DLC, pacchetti di livelli, nuovi personaggi e altro ancora. I bundle di asset sono ideali per il caricamento e il raggruppamento dei contenuti autogestiti. Questi possono essere utilizzati taggando le risorse in bundle specifici, quindi caricando i bundle in base alle tue esigenze. Per ulteriori dettagli, consulta la documentazione di Unity su Asset Bundle.

Consulta la documentazione di riferimento completa dell'API YT Playables.