wrapper ניסיוני של YouTube במשחקייה

באמצעות העטיפה הזו אפשר לגשת אל YouTube Playables SDK ב-Unity C#. ה-wrapper כולל תוסף ‎ .jslib וקובץ C# ‎ כדי לעזור לכם לפתח מהר יותר. יש גם פרויקט לדוגמה שמראה איך אפשר להשתמש בהם בפרויקט שלכם.

אפשר להוריד חבילות Unity ממאגר הדוגמאות של Playables.

שימוש

  1. מוודאים שהפלטפורמה של פרויקט Unity מוגדרת ל-WebGL. ההגדרה הזו נמצאת בBuild Settings.
  2. אפשר להשתמש ב-WebGLTemplate כדי ליצור את המשחק לאינטרנט, או לפעול לפי ההוראות שבקטע שימוש בקובץ index.html משלכם ולוודא שהגדרתם והפעלתם את Web SDK בקובץ index.html.
    • אפשר למצוא את WebGLTemplate בחבילה Google-WebGLTemplate-only.unitypackage או GoogleYTGameWrapper-with-sample.unitypackage. כדי להגדיר את התבנית הזו ולהשתמש בה, צריך לפעול לפי השלבים שבקטע תבנית WebGL.
    • כדי להשתמש בקובץ index.html משלכם, תצטרכו להוסיף שתי שורות לסקריפט היצירה של index.html Unity. פרטים נוספים זמינים בקטע שימוש בקובץ index.html משלכם.
  3. פותחים את הפרויקט ב-Unity, ואז פותחים ומייבאים את אחד מהחבילות לפרויקט.
    • ‫GoogleYTGameWrapper.unitypackage: מכיל פלאגין JS לחיבור של YouTube Playables SDK ועטיפת C# ‎ כדי לעזור לכם לחבר את זה למוצר שלכם.
    • ‫GoogleYTGameWrapper-with-sample.unitypackage: מכיל את אותם קבצים ותוכן כמו אלה שנמצאים בחבילה GoogleYTGameWrapper, ודוגמה שמראה איך להשתמש ב-YouTube Playables SDK ב-C#.
  4. חשוב: בסצנה הראשית, יוצרים אובייקט משחק חדש ונותנים לו את השם YTGameWrapper. אובייקט המשחק הזה משמש לתקשורת עם גשר ה-JS.
  5. חשוב: מוסיפים את קוד YTGameWrapper.cs המיובא כרכיב סקריפט לאובייקט YTGameWrapper GameObject.

  6. אם הפרויקט כולל כמה סצנות, צריך להוסיף DontDestroyOnLoad לתסריט YTGameWrapper.cs (הערה: בגרסאות חדשות של התסריט יש מתג DontDestroyOnSceneChange שמופעל כברירת מחדל). כך תוכלו לוודא שהסקריפט וה-GameObject יישארו לאורך כל המשחק.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. רכיב YTGameWrapper.cs ואובייקט המשחק YTGameWrapper משמשים לחיבור אל YouTube Playables SDK. משתמשים בהם כדי להתחבר ל-YouTube. אפשר להשתמש בסקריפט כדי למצוא את האובייקט והרכיב, או להוסיף אותם ידנית לקוד המשחק באמצעות Unity Editor.

  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 >

    ...

דוגמאות

בקטע הזה מופיעות כמה דוגמאות לשימוש ב-wrapper של C#, אבל זו לא רשימה מלאה של ממשקי ה-API הזמינים. רשימה מלאה של ממשקי ה-API הזמינים מופיעה ב-YouTube Playables SDK.

sendScore

בדוגמה הזו מוצגת הטמעה של sendScore(int points) ב-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

זו דוגמה לאופן שבו משחק יכול להאזין לאירועים מסוג 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.
    }
}

איך משתמשים בתבנית WebGL לדוגמה של YouTube

אלא אם יש לכם פרויקט Unity כבד מאוד, הקבצים .wasm ו-.data שנוצרו צריכים להיות קטנים ממגבלת גודל הקובץ האישי שלנו. אם זה המצב, לא צריך לבצע דחיסה נוספת בקבצים האלה, כי הם יידחסו אוטומטית כששולחים אותם. בנוסף, הדחיסה האוטומטית תאפשר לוודא שקובץ ה-‎ .wasm עומד בדרישה של גודל החבילה הראשוני. לדוגמה, קובץ .wasm בגודל של כ-25MB יידחס לגודל של כ-7MB.

אם מסיבה כלשהי הקבצים שלכם חורגים ממגבלת הגודל המקסימלית של קובץ בודד, מומלץ להשתמש בדחיסת 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 -> הקטע Resolution and Presentation.
    • הערה: רוחב וגובה ברירת המחדל של Canvas מוגדרים ל-100% בתבנית, כך שההגדרות האלה ב-Unity לא ישנו שום דבר.
  3. מוודאים שההגדרה Compression Format מושבתת. ההגדרה הזו נמצאת בקטע Publishing Settings בכרטיסייה WebGL ב-Project settings -> Player.
  4. בונים עבור WebGL בחלון Build Settings ואז עוברים לשלב 7 או 5 בהתאם לצרכים של הפרויקט.
  5. אם משתמשים בדחיסה, צריך לבצע רק את שלבים 5 ו-6: אחרי שהפרויקט נוצר, עוברים למיקום של תיקיית ה-build ופותחים את התיקייה Build. מאתרים את הקבצים של הפרויקטים .wasm או .data שצריך לדחוס כדי שהם יעמדו במגבלות גודל הקובץ, ודוחסים אותם לקובץ ZIP. חשוב למחוק את הקבצים המקוריים .wasm/.data שנדחסו, כי אתם תשלחו במקומם את הקבצים *.wasm.zip ו-*.data.zip.
    • הערה: אם אתם משתמשים ב-Mac, אתם יכולים ללחוץ לחיצה ימנית על הקובץ ולבחור באפשרות 'דחיסה *'. במחשב, אתם יכולים ללחוץ לחיצה ימנית על הקובץ ולבחור באפשרות 'דחיסה לקובץ ZIP'.
  6. רק אם ביצעתם את שלב 5: מעדכנים את קובץ index.html שנבנה מ-YTGameWrapperTemplate כדי לטעון קובצי 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. עוברים לחלון Render Pipeline Converter: Window -> Rendering -> Render Pipeline Converter.
  3. בוחרים באפשרות Rendering Settings, Material Upgrade ו-Readonly Material Converter.
  4. לאחר מכן בוחרים באפשרות Initialize and Convert, מחכים לסיום הפעולה והדוגמה אמורה להיות מוכנה ל-URP.

איך מפצלים נכסים בפרויקט Unity (טעינה עצלה)

אחת הבעיות העיקריות שמפתחים ציינו לגבי השימוש ב-Unity היא שמירה על דרישות גודל הקובץ הבודד ועל דרישות גודל חבילת האפליקציה הכולל.

טעינה עצלה של נכסים היא אופטימיזציה מצוינת שאפשר לבצע בפרויקט, כי אפשר לטעון נכסים, רמות ונתונים לפי הצורך. צוות האישורים שלנו עשוי לוותר על ההגבלות על הגודל הכולל של הקובץ אם הפעולה הזו מתבצעת בצורה נכונה, כי המשחק המלא לא ייטען מראש, אלא בזמן שהמשתמש עובר בין חלקי המוצר.

כדי לעזור לכם לטעון את הנכסים בצורה נכונה, ב-Unity יש כמה דרכים לפצל את הנכסים. כך תוכלו לוודא שקבוצות הנכסים האישיות שלכם לא חורגות ממגבלות הגודל, ושהתוכן נטען לאורך זמן. מומלץ להשתמש ב-Addressables או ב-Asset Bundles.

כתובות שאפשר לשלוח אליהן

הנכסים הניתנים להגדרה מאפשרים לכם לזהות קבצים שונים שצריך לטעון יחד, ו-Unity תטפל ברוב תהליך האריזה בשבילכם. ב-Unity יש גם כלים לניהול גודל הקבצים, שעוזרים לוודא שלא משכפלים נכסים.

כדי להשתמש ב-Addressables, צריך לייבא את חבילת Addressables דרך Package Manager ב-Unity, ואז לתייג את הנכסים ב-Addressable Groups. פרטים נוספים זמינים במסמכי Unity.

חבילות App Bundle של נכסים

חבילות נכסים שימושיות כי אפשר לפצל את הפרויקט ולטעון רכיבים תוך כדי תנועה. הם שימושיים לתוכן להורדה (DLC), לחבילות של רמות, לדמויות חדשות ועוד. חבילות נכסים הן פתרון מצוין לטעינה ולאריזה של תוכן בניהול עצמי. אפשר להשתמש בהם על ידי תיוג הנכסים בחבילות ספציפיות, ואז טעינת החבילות לפי הצורך. פרטים נוספים זמינים במסמכי Asset Bundle של Unity.

הפניית YT Playables API