Unity Wrapper آزمایشی YouTube Playables

با استفاده از این بسته‌بندی می‌توانید به SDK مربوط به YouTube Playables در Unity C# دسترسی پیدا کنید. این بسته‌بندی دارای یک افزونه .jslib و یک فایل C# است تا به سرعت بخشیدن به توسعه شما کمک کند. همچنین یک پروژه نمونه وجود دارد که نشان می‌دهد چگونه می‌توانید از این موارد در پروژه خود استفاده کنید.

بسته‌های یونیتی را می‌توان از مخزن نمونه Playables ما دانلود کرد.

کاربرد

  1. مطمئن شوید که پلتفرم پروژه Unity شما روی WebGL تنظیم شده است. این تنظیم را می‌توانید در Build Settings پیدا کنید.
  2. یا از WebGLTemplate برای ساخت بازی تحت وب خود استفاده کنید، یا بخش « استفاده از فایل index.html خودتان» را دنبال کنید و تأیید کنید که SDK وب را در فایل index.html خود راه‌اندازی و مقداردهی اولیه کرده‌اید.
    • WebGLTemplate می‌توانید در بسته‌های Google-WebGLTemplate-only.unitypackage یا GoogleYTGameWrapper-with-sample.unitypackage پیدا کنید. برای تنظیم و استفاده از این الگو، مراحل موجود در بخش WebGL Template را دنبال کنید.
    • برای استفاده از فایل وب و index.html خودتان، باید دو خط به اسکریپت ساخت index.html در Unity اضافه کنید، برای ادغام به بخش «استفاده از فایل index.html خودتان» مراجعه کنید.
  3. پروژه خود را در یونیتی باز کنید، سپس هر یک از بسته‌ها را باز کرده و به پروژه خود وارد کنید.
    • GoogleYTGameWrapper.unitypackage : شامل افزونه JS برای اتصال SDK مربوط به YouTube Playables و یک wrapper مربوط به C# برای کمک به اتصال این مورد به محصول شما است.
    • GoogleYTGameWrapper-with-sample.unitypackage : شامل همان فایل‌های موجود در پکیج GoogleYTGameWrapper و نمونه‌ای است که نحوه استفاده از SDK مربوط به YouTube Playables را در C# نشان می‌دهد.
  4. مهم: در صحنه اصلی خود، یک شیء بازی جدید ایجاد کنید و نام آن را YTGameWrapper بگذارید. این شیء بازی برای ارتباط با پل JS استفاده می‌شود.
  5. مهم: کد YTGameWrapper.cs وارد شده را به عنوان یک جزء اسکریپت به شیء بازی YTGameWrapper اضافه کنید.

  6. اگر پروژه شما چندین صحنه دارد، حتماً DontDestroyOnLoad به اسکریپت YTGameWrapper.cs اضافه کنید (نکته: نسخه‌های جدید اسکریپت دارای گزینه DontDestroyOnSceneChange هستند که به طور پیش‌فرض فعال است). این کار باعث می‌شود اسکریپت و GameObject در طول بازی شما باقی بمانند.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. کامپوننت YTGameWrapper.cs و YTGameWrapper GameObject برای اتصال به SDK مربوط به YouTube Playables استفاده می‌شوند. از این‌ها برای اتصال به YouTube استفاده کنید. یا با استفاده از اسکریپت برای یافتن شیء و کامپوننت یا به صورت دستی از طریق ویرایشگر Unity آن‌ها را به کد بازی خود اضافه کنید.

  8. تأیید کنید که الزامات فنی پروژه خود را رعایت می‌کنید.

از فایل index.html خودتان استفاده کنید

اگر از مثال index.html ارائه شده استفاده نمی‌کنید، باید دو خط کد به اسکریپت ساخت index.html در 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های موجود، به SDK مربوط به YouTube Playables مراجعه کنید.

sendScore

این مثال پیاده‌سازی تابع 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

این مثالی از چگونگی گوش دادن یک بازی به رویدادهای Pause ناشی از YT Playables برای مکث موتور خود در صورت نیاز است:

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

نحوه استفاده از الگوی WebGL نمونه یوتیوب

مگر اینکه پروژه Unity بسیار سنگینی داشته باشید، فایل‌های .wasm و .data ساخته شده شما باید کمتر از محدودیت حجم فایل ما باشند. در این صورت، هیچ فشرده‌سازی اضافی از طرف شما برای این فایل‌ها نباید انجام شود، زیرا آنها به طور خودکار هنگام ارسال فایل‌های قابل پخش شما فشرده می‌شوند. این فشرده‌سازی خودکار همچنین تأیید می‌کند که فایل .wasm شما با الزامات اولیه اندازه بسته مطابقت دارد. به عنوان مثال، یک فایل .wasm با حجم تقریبی ۲۵ مگابایت تا حدود ۷ مگابایت فشرده می‌شود.

اگر به هر دلیلی حجم فایل‌های شما از حداکثر حجم مجاز برای هر فایل بیشتر است، بهتر است از فشرده‌سازی ZIP برای تأیید گنجاندن آنها در این محدودیت استفاده کنید. فشرده‌سازی قابل پخش، این فایل‌ها را دوباره فشرده نمی‌کند.

قالب 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 tab -> Resolution and Presentation section قرار دارد.
    • توجه: عرض و ارتفاع پیش‌فرض بوم نقاشی در قالب روی ۱۰۰٪ تنظیم شده‌اند، بنابراین این تنظیمات Unity چیزی را تغییر نمی‌دهند.
  3. مطمئن شوید که Compression Format شما روی غیرفعال تنظیم شده است. این تنظیم در Project settings -> Player -> برگه WebGL -> بخش Publishing Settings قرار دارد.
  4. در پنجره Build Settings گزینه Build for WebGL را انتخاب کنید و سپس بر اساس نیازهای پروژه خود به مرحله ۷ یا ۵ بروید.
  5. فقط در صورت استفاده از فشرده‌سازی، مراحل ۵ و ۶ را دنبال کنید : پس از ساخت پروژه، به محل پوشه build خود بروید و پوشه Build را باز کنید. فایل‌های .wasm یا .data پروژه‌های خود را که برای قرار گرفتن در محدودیت‌های اندازه فایل، نیاز به فشرده‌سازی دارند، پیدا کنید و این فایل‌ها را فشرده کنید. مطمئن شوید که فایل‌های .wasm / .data اصلی که فشرده شده‌اند را حذف کرده‌اید، زیرا به جای آنها فایل‌های *.wasm.zip و *.data.zip را ارسال خواهید کرد.
    • توجه: اگر از مک استفاده می‌کنید، می‌توانید روی فایل کلیک راست کرده و گزینه "Compress *" را انتخاب کنید. در کامپیوتر شخصی می‌توانید روی فایل کلیک راست کرده و گزینه "Compress to ZIP file" را انتخاب کنید.
  6. فقط در صورتی که مرحله ۵ را انجام داده‌اید، این کار را انجام دهید : فایل index.html ساخته شده از YTGameWrapperTemplate را به‌روزرسانی کنید تا فایل‌های زیپ شده را بارگذاری کرده و آنها را از حالت فشرده خارج کند.
    • نزدیک به انتهای فایل‌های index.html Path 1 پیدا خواهید کرد و خط زیر را با استفاده InitUnitySection(); از حالت کامنت خارج کنید.
    • نزدیک به انتهای فایل‌های index.html Path 2 پیدا خواهید کرد و خط زیر را به صورت کامنت درآورید: loadResources(InitUnitySection);
  7. هنگام ارسال پروژه خود برای صدور گواهینامه، باید تمام فایل‌های ساخته شده از Unity را به محل ساخت خود از مرحله ۴ ارسال کنید. اگر مراحل ۵ + ۶ دنبال شده است، این فایل‌ها را نیز اضافه کنید.

نمونه‌های ارائه شده را برای استفاده از Universal Render Pipeline (URP) ارتقا دهید.

یکی از آخرین پیشرفت‌ها در نسخه‌های جدیدتر یونیتی این است که از Universal Render Pipeline (URP) برای ارتقاء نمونه استفاده می‌کنند تا همه چیز به درستی رندر شود.

  1. با وارد کردن پکیج GoogleYTGameWrapper-with-sample.unitypackage به یک پروژه جدید یا موجود شروع کنید.
  2. به پنجره Render Pipeline Converter بروید: Window -> Rendering -> Render Pipeline Converter .
  3. Rendering Settings ، Material Upgrade و Readonly Material Converter را انتخاب کنید.
  4. سپس گزینه Initialize and Convert را انتخاب کنید، صبر کنید تا این کار تمام شود و نمونه برای URP آماده شود.

نحوه تقسیم‌بندی دارایی‌ها در پروژه یونیتی (بارگذاری تنبل)

یکی از مشکلات اصلی که توسعه‌دهندگان هنگام استفاده از یونیتی به آن اشاره کرده‌اند، رعایت نکردن الزامات اندازه فایل تکی و الزامات اندازه کل بسته نرم‌افزاری است.

بارگذاری تنبلِ دارایی‌ها، بهینه‌سازی بسیار خوبی است که می‌توانید برای پروژه خود انجام دهید، زیرا می‌توانید دارایی‌ها، مراحل و داده‌ها را در صورت نیاز بارگذاری کنید. اگر این کار به درستی انجام شود، تیم صدور گواهینامه ما ممکن است از محدودیت‌های کلی اندازه فایل صرف نظر کند، زیرا بازی کامل شما از ابتدا بارگذاری نمی‌شود، بلکه همزمان با پیمایش کاربر در محصول شما بارگذاری می‌شود.

برای کمک به بارگذاری مناسب، یونیتی روش‌های مختلفی برای تقسیم‌بندی دارایی‌های شما دارد تا تأیید کند که گروه‌های دارایی‌های شما زیر محدودیت اندازه هستند و محتوا را به مرور زمان بارگذاری می‌کنید. پیشنهاد می‌کنیم از Addressables یا Asset Bundles استفاده کنید.

آدرس‌پذیرها

آدرس‌پذیرها به شما امکان می‌دهند فایل‌های مختلفی را که باید با هم بارگذاری شوند شناسایی کنید و یونیتی بیشتر مراحل بسته‌بندی را برای شما انجام می‌دهد. یونیتی همچنین ابزارهایی برای مدیریت اندازه فایل‌ها ارائه می‌دهد و به شما کمک می‌کند تا مطمئن شوید که فایل‌های تکراری ندارید.

برای استفاده از Addressables باید پکیج Addressables را از طریق Package Manager در Unity وارد کنید، سپس فایل‌های خود را در گروه‌های Addressable تگ‌گذاری کنید. جزئیات بیشتر را می‌توانید در مستندات Unity بیابید.

بسته‌های دارایی

بسته‌های دارایی مفید هستند زیرا می‌توانید پروژه خود را تقسیم کرده و عناصر را در لحظه بارگذاری کنید. این بسته‌ها برای DLC، بسته‌های مراحل، شخصیت‌های جدید و موارد دیگر مفید هستند. بسته‌های دارایی برای بارگذاری و بسته‌بندی محتوای خودمدیریت‌شده عالی هستند. می‌توان از این بسته‌ها با برچسب‌گذاری دارایی‌های خود در بسته‌های خاص و سپس بارگذاری بسته‌ها در صورت نیاز استفاده کرد. جزئیات بیشتر را می‌توانید در مستندات بسته‌های دارایی یونیتی بیابید.

مرجع کامل YT Playables API را ببینید.