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

您可以使用這個封裝函式，在 Unity C# 中存取 YouTube 遊戲角落 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 遊戲角落 SDK 和 C# 包裝函式，協助將此連結至產品。
    • GoogleYTGameWrapper-with-sample.unitypackage：內含與 GoogleYTGameWrapper 套件中相同的檔案內容，以及說明如何在 C# 中使用 YouTube 遊戲角落 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 遊戲角落 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 遊戲角落 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.
    }
}

requestRewardedAd

以下是 requestRewardedAd 的使用範例。當使用者選擇觀看獎勵廣告，以換取遊戲中的獎勵時，系統就會使用這個方法。如果系統找到可用的廣告，就會向使用者顯示。

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

如何使用 YouTube 的 WebGL 範本範例

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

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

WebGL 範本

  1. 請按照上述 Unity 套件操作說明進行初始設定。 請務必使用 Google-WebGLTemplate-only.unitypackage 或 GoogleYTGameWrapper-with-sample.unitypackage，並匯入 WebGLTemplates/YTGameWrapperTemplate/ 資料夾中的所有檔案。
    • 注意：如果尚未匯入 YTGameWrapper.cs 和 UnityYTGameSDKLib.jslib，也請一併匯入。
  2. 將 WebGL 範本設為使用 YTGameWrapperTemplate。這項設定位於「」->「」->「」->「」分頁標籤 ->「」部分。EditProject settingsPlayerWebGLResolution 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. 提交專案以取得認證時，您需要將步驟 4 中從 Unity 建構的所有檔案傳送至建構位置。如果已完成步驟 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 提供多種資產分割方式，可驗證個別資產群組是否符合大小限制，並確保您載入內容時不會超出時間限制。建議使用 Addressable 或 AssetBundle。

Addressables

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

如要使用 Addressable，您需要透過 Unity 的 Package Manager 匯入 Addressable 套件，然後將資產標記到 Addressable Groups。詳情請參閱 Unity 說明文件。

資產組合

資產包可將專案分割，並即時載入元素，因此非常實用，適用於 DLC、關卡包、新角色等。資產包非常適合自行管理內容載入和組合。如要使用資產包，請將資產標記到特定資產包，然後視需要載入資產包。詳情請參閱 Unity 的資產包說明文件。

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