實驗性 YouTube 遊戲角落 Unity 包裝函式

您可以使用這個封裝函式，在 Unity C# 中存取 YouTube Playables SDK。包裝函式包含 .jslib 外掛程式和 C# 檔案，可加快開發速度。此外，我們也提供範例專案，說明如何在專案中使用這些項目。

您可以從 Playable 範例存放區下載 Unity 套件。

用量

1. 確認 Unity 專案平台已設為 WebGL。這項設定位於 Build Settings。
2. 您可以透過 WebGLTemplate 為網頁建構遊戲，也可以按照「使用您自己的 index.html 檔案」一節的說明操作，並確認您已在 index.html 檔案中設定及初始化網頁 SDK。
   • WebGLTemplate 位於 Google-WebGLTemplate-only.unitypackage 或 GoogleYTGameWrapper-with-sample.unitypackage 套件中。如要設定及使用此範本，請按照「WebGL 範本」一節中的步驟操作。
   • 如要使用自己的 Web 和 index.html 檔案，您需要在 index.html Unity 建立指令碼中新增兩行，請參閱「使用自己的 index.html 檔案」一節瞭解整合方式。
3. 在 Unity 中開啟專案，然後開啟並匯入任一套件至專案。
   • GoogleYTGameWrapper.unitypackage：包含 JS 外掛程式，可連結 YouTube Playables SDK 和 C# 包裝函式，協助將此外掛程式連結至產品。
   • GoogleYTGameWrapper-with-sample.unitypackage：內含與 GoogleYTGameWrapper 套件中相同的檔案內容，以及說明如何在 C# 中使用 YouTube Playables SDK 的範例。
4. 重要事項：在主要場景中建立新的遊戲物件，並將其命名為 YTGameWrapper。這個遊戲物件用於與 JS 橋接器通訊。
5. 重要事項：將匯入的 YTGameWrapper.cs 程式碼新增為 YTGameWrapper GameObject 的指令碼元件。

6. 如果專案有多個場景，請務必將 DontDestroyOnLoad 新增至 YTGameWrapper.cs 指令碼 (注意：新版指令碼預設會開啟 DontDestroyOnSceneChange 切換鈕)。這樣一來，指令碼和 GameObject 就能在整個遊戲中保留下來。

   GameObject.DontDestroyOnLoad(this.gameObject);
   

7. YTGameWrapper.cs 元件和 YTGameWrapper GameObject 用於連結至 YouTube Playables SDK。並使用這些資訊連線至 YouTube。 您可以使用指令碼尋找物件和元件，也可以透過 Unity 編輯器手動將這些項目新增至遊戲程式碼。

8. 確認你符合專案的技術規定。

使用自己的 index.html 檔案

如果未使用提供的 index.html 範例，您需要在 index.html Unity 建立指令碼中加入兩行程式碼。

首先，請在專案設定 Unity 容器、畫布等變數的相同位置，新增這行程式碼。

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

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

    ...

其次，在 createUnityInstance 函式中新增這行程式碼。

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

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

    ...

範例

本節提供 C# 包裝函式的使用範例，但並非所有可用 API 的完整清單。如需可用 API 的完整清單，請參閱 YouTube Playables SDK。

sendScore

以下範例顯示 C# 中的 sendScore(int points) 實作方式：

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

以下範例說明遊戲如何監聽 YT Playables 傳來的 Pause 事件，以便在需要時暫停引擎：

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

以下範例說明如何使用 saveData，並將其傳送至 YT Playables SDK：

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

以下範例說明如何使用 loadData，並將其傳送至 YT Playables SDK：

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

以下範例說明如何使用 requestInterstitialAd，指出目前是顯示插頁式廣告的好時機 (如有)。為獲得最佳效果，請在遊戲中場休息時撥打電話，例如關卡結束時。

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

如何使用 YouTube 的 WebGL 範本範例

除非 Unity 專案非常龐大，否則建構的 .wasm 和 .data 檔案應該不會超過個別檔案大小限制。如果是這種情況，您不必對這些檔案進行額外壓縮，因為系統會在您提交可玩檔案時自動壓縮。自動壓縮作業也會驗證 .wasm 檔案是否符合初始套件大小規定。舉例來說，大約 25 MiB 的 .wasm 檔案會壓縮至約 7 MiB。

如果檔案因故超過個別檔案大小上限，建議使用 ZIP 壓縮功能，確認檔案符合限制。可播放壓縮不會重新壓縮這些檔案。

注意： 目前不支援使用 Unity 的 gzip 或 brotli 壓縮功能建構的 Unity 專案。所有專案都應在不壓縮的情況下建構，如果需要壓縮，則應在初始建構後進行。

WebGL 範本

1. 按照上述 Unity 套件操作說明進行初始設定。 請務必使用 Google-WebGLTemplate-only.unitypackage 或 GoogleYTGameWrapper-with-sample.unitypackage，並匯入 WebGLTemplates/YTGameWrapperTemplate/ 資料夾中的所有檔案。
   • 注意：如果尚未匯入 YTGameWrapper.cs 和 UnityYTGameSDKLib.jslib，請一併匯入。
2. 將 WebGL 範本設為使用 YTGameWrapperTemplate。這項設定位於「Edit」->「Project settings」->「Player」->「WebGL」分頁標籤 ->「Resolution and Presentation」部分。
   • 注意：範本中的預設畫布寬度和高度設為 100%，因此這些 Unity 設定不會調整任何項目。
3. 確認 Compression Format 已設為「已停用」。這項設定位於「Project settings」->「Player」->「WebGL」分頁標籤 ->「Publishing Settings」部分。
4. 在「Build Settings」視窗中建構 WebGL，然後根據專案需求前往步驟 7 或 5。
5. 只有在使用壓縮功能時，才需要按照步驟 5 和 6 操作：專案建構完成後，請前往建構資料夾位置，然後開啟 Build 資料夾。找出需要壓縮的專案 .wasm 或 .data 檔案，確保檔案符合個別檔案大小限制，然後將這些檔案壓縮成 ZIP 檔案。請務必刪除壓縮後的原始 .wasm/.data 檔案，因為您要改為提交 *.wasm.zip 和 *.data.zip 檔案。
   • 注意：如果你使用 Mac，可以對檔案按一下滑鼠右鍵，然後選取「壓縮『*』」。如果你使用 PC，可以對檔案按一下滑鼠右鍵，然後選取「壓縮成 ZIP 檔案」。
6. 只有在完成步驟 5 時才需要執行下列操作：更新從 YTGameWrapperTemplate 建構的 index.html 檔案，載入並解壓縮 ZIP 檔案。
   • 在 index.html 檔案結尾附近，您會找到 Path 1，並註解掉下列程式碼行 InitUnitySection();。
   • 在 index.html 檔案結尾附近，您會找到 Path 2，並註解掉下列程式碼行 loadResources(InitUnitySection);。
7. 提交專案以進行認證時，您需要將從 Unity 建構的所有檔案傳送至步驟 4 的建構位置。如果已按照步驟 5 和 6 操作，請一併加入這些檔案。

升級提供的範例，以使用 Universal Render Pipeline (URP)

Unity 新版本的一項最新進展是使用 Universal Render Pipeline (URP)。升級範例，確保所有項目都能正確算繪。

1. 首先，請將 GoogleYTGameWrapper-with-sample.unitypackage 套件匯入新專案或現有專案。
2. 依序點選「Window」>「Rendering」>「Render Pipeline Converter」，前往「Render Pipeline Converter」視窗。
3. 選取 Rendering Settings、Material Upgrade 和 Readonly Material Converter。
4. 接著選取 Initialize and Convert，等待完成後，範例應該就能用於 URP。

如何在 Unity 專案中分割資產 (延遲載入)

開發人員在使用 Unity 時，主要問題之一是必須符合個別檔案大小規定，以及總套件大小規定。

延遲載入資產是專案的絕佳最佳化方式，因為您可以視需要載入資產、層級和資料。如果做法正確，認證團隊可能會免除整體檔案大小限制，因為系統不會預先載入完整遊戲，而是在使用者瀏覽產品時載入。

為確保正確載入，Unity 提供多種分割資產的方式，可驗證個別資產群組是否符合大小限制，以及您是否隨時間載入內容。建議使用 Addressables 或 Asset Bundles。

Addressables

您可以使用 Addressables 識別應一併載入的不同檔案，Unity 會為您處理大部分的封裝作業。Unity 也提供一些工具來管理檔案大小，並確保您不會重複使用資產。

如要使用 Addressable，您必須透過 Unity 的套件管理工具匯入 Addressable 套件，然後將資產標記到 Addressable 群組。詳情請參閱 Unity 說明文件。

資產組合

資產組合很有幫助，因為您可以分割專案並即時載入元素。這些資源有助於 DLC、關卡包、新角色等。 素材資源組合非常適合自行管理內容載入和組合。方法是將資產標記到特定組合中，然後視需要載入組合。詳情請參閱 Unity 的資產套件說明文件。

請參閱完整的 YT Playables API 參考資料。