Deneysel YouTube Hazır Oyunlar Unity Sarmalayıcı

Bu sarmalayıcıyla Unity C#'ta YouTube Hazır Oyunlar SDK'sına erişebilirsiniz. Sarmalayıcı, geliştirme sürecinizi hızlandırmak için bir .jslib eklentisi ve bir C# dosyası içerir. Ayrıca, bunları projenizde nasıl kullanabileceğinizi gösteren bir örnek proje de vardır.

Unity paketleri, Hazır Oyunlar örnek depomuzdan indirilebilir.

Kullanım

  1. Unity projenizin Platform ayarının WebGL olarak belirlendiğini doğrulayın. Bu ayar Build Settings bölümünde yer alır.
  2. Web için oyununuzu oluşturmak üzere WebGLTemplate aracını kullanın veya Kendi index.html dosyanızı kullanın bölümündeki talimatları uygulayıp index.html dosyanızda web SDK'sını kurup ilk kullanıma hazırladığınızı doğrulayın.
    • WebGLTemplate, Google-WebGLTemplate-only.unitypackage veya GoogleYTGameWrapper-with-sample.unitypackage paketinde bulunabilir. Bu şablonu ayarlamak ve kullanmak için WebGL Şablonu bölümündeki adımları uygulayın.
    • Kendi Web ve index.html dosyanızı kullanmak için index.html Unity oluşturma komut dosyanıza iki satır eklemeniz gerekir. Entegrasyon için Kendi index.html dosyanızı kullanma bölümüne bakın.
  3. Projenizi Unity'de açın, ardından paketlerden birini açıp projenize aktarın.
    • GoogleYTGameWrapper.unitypackage: YouTube Hazır Oyunlar SDK'sını bağlamak için JS eklentisi ve bunu ürününüze bağlamanıza yardımcı olacak bir C# sarmalayıcı içerir.
    • GoogleYTGameWrapper-with-sample.unitypackage: GoogleYTGameWrapper paketinde bulunan dosyalarla aynı dosyaları ve C# dilinde YouTube Hazır Oyunlar SDK'sının nasıl kullanılacağını gösteren bir örneği içerir.
  4. ÖNEMLİ: Ana sahnenizde yeni bir GameObject oluşturun ve bunu YTGameWrapper olarak adlandırın. Bu oyun nesnesi, JS köprüsüyle iletişim kurmak için kullanılır.
  5. ÖNEMLİ: İçe aktarılan YTGameWrapper.cs kodunu, YTGameWrapper GameObject'e bir komut dosyası bileşeni olarak ekleyin.

  6. Projenizde birden fazla sahne varsa DontDestroyOnLoad simgesini YTGameWrapper.cs komut dosyasına eklediğinizden emin olun (Not: Komut dosyasının yeni sürümlerinde varsayılan olarak açık olan bir DontDestroyOnSceneChange açma/kapatma düğmesi bulunur). Bu sayede, komut dosyası ve GameObject'in oyununuz boyunca kalması sağlanır.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. YTGameWrapper.cs bileşeni ve YTGameWrapper GameObject, YouTube Playables SDK'sına bağlanmak için kullanılır. YouTube'a bağlanmak için bunları kullanın. Nesneyi ve bileşeni bulmak için komut dosyası kullanabilir veya bunları Unity Düzenleyici aracılığıyla oyun kodunuza manuel olarak ekleyebilirsiniz.

  8. Projeniz için teknik koşullara uyduğunuzu doğrulayın.

Kendi index.html dosyanızı kullanma

index.html örneğini kullanmıyorsanız index.html Unity oluşturma komut dosyanıza iki kod satırı eklemeniz gerekir.

Öncelikle bu satırı, projenizin Unity kapsayıcısı, tuval vb. için değişkenleri ayarladığı yere ekleyin.

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

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

    ...

İkinci olarak, createUnityInstance işlevinin içine şu satırı ekleyin.

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

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

    ...

Örnekler

Bu bölümde, C# sarmalayıcısının nasıl kullanılacağına dair bazı örnekler verilmiştir. Bu örnekler, mevcut API'lerin tam listesi değildir. Kullanılabilir API'lerin tam listesi için YouTube Playables SDK'sına bakın.

sendScore

Bu örnekte, C# dilinde sendScore(int points) uygulaması gösterilmektedir:

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

Aşağıda, bir oyunun gerektiğinde motorunu duraklatmak için YT Playables'den gelen Pause etkinliklerini nasıl dinleyebileceğine dair bir örnek verilmiştir:

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

Bu, saveData öğesini YT Playables SDK'sına göndermek için nasıl kullanacağınızla ilgili bir örnektir:

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

Bu, loadData öğesini YT Playables SDK'sına göndermek için nasıl kullanacağınızla ilgili bir örnektir:

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

Bu, requestInterstitialAd öğesinin nasıl kullanılacağına dair bir örnektir. Bu öğe, varsa geçiş reklamı göstermek için uygun bir zaman olduğunu belirtir. En iyi sonuçlar için bu aramayı oyun sırasında bir ara verdiğinizde (ör. bir bölümün sonunda) yapın.

...
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'un örnek WebGL şablonunu kullanma

Çok büyük bir Unity projeniz yoksa oluşturduğunuz .wasm ve .data dosyaları, tek tek dosya boyutu sınırımızın altında olmalıdır. Bu durumda, oynanabilir dosyalarınız gönderildiğinde otomatik olarak sıkıştırılacağından, bu dosyalar için sizin tarafınızdan ek sıkıştırma işlemi yapılmamalıdır. Bu otomatik sıkıştırma işlemi, .wasm dosyanızın ilk paket boyutu şartına uygun olup olmadığını da doğrular. Örneğin, ~25 MiB'lik bir .wasm dosya ~7 MiB'a sıkıştırılır.

Dosyalarınız herhangi bir nedenle maksimum dosya boyutu sınırını aşıyorsa bu sınıra uyduklarını doğrulamak için ZIP sıkıştırması kullanmanız önerilir. Oynatılabilir sıkıştırma bu dosyaları yeniden sıkıştırmaz.

WebGL Şablonu

  1. İlk kurulum için yukarıdaki Unity paketi talimatlarını uygulayın. Google-WebGLTemplate-only.unitypackage veya GoogleYTGameWrapper-with-sample.unitypackage kullanıp tüm dosyaları WebGLTemplates/YTGameWrapperTemplate/ klasörüne aktardığınızdan emin olun.
    • Not: YTGameWrapper.cs ve UnityYTGameSDKLib.jslib öğelerini henüz içe aktarmadıysanız bunları da içe aktarmanız gerekir.
  2. WebGL şablonunuzu YTGameWrapperTemplate kullanacak şekilde ayarlayın. Bu ayar, Edit -> Project settings -> Player -> WebGL sekmesi -> Resolution and Presentation bölümünde yer alır.
    • Not: Varsayılan tuval genişliği ve yüksekliği şablonda% 100 olarak ayarlandığından bu Unity ayarları herhangi bir şeyi düzenlemez.
  3. Compression Format ayarının Devre Dışı olarak ayarlandığından emin olun. Bu ayar, Project settings -> Player -> WebGL sekmesi -> Publishing Settings bölümünde yer alır.
  4. Build Settings penceresinde WebGL için derleyin, ardından projelerinizin ihtiyaçlarına bağlı olarak 7. veya 5. adıma gidin.
  5. Yalnızca sıkıştırma kullanılıyorsa 5. ve 6. adımları uygulayın: Projeniz oluşturulduktan sonra derleme klasörünüzün konumuna gidin ve Build klasörünü açın. Tek tek dosya boyutu sınırlarına uymak için sıkıştırılması gereken .wasm veya .data dosyalarınızı bulun ve bu dosyaları sıkıştırın. *.wasm.zip ve *.data.zip dosyalarını göndereceğiniz için sıkıştırılan orijinal .wasm/.data dosyalarını sildiğinizden emin olun.
    • Not: Mac kullanıyorsanız dosyayı sağ tıklayıp "* sıkıştır"ı seçebilirsiniz. PC'de ise dosyayı sağ tıklayıp "ZIP dosyasına sıkıştır"ı seçebilirsiniz.
  6. Yalnızca 5. adımı uyguladıysanız devam edin: Sıkıştırılmış dosyaları yüklemek ve bunları açmak için YTGameWrapperTemplate öğesinden oluşturulan index.html dosyasını güncelleyin.
    • index.html dosyalarının sonuna doğru Path 1 ifadesini bulup aşağıdaki satırda InitUnitySection(); yorum satırı oluşturun.
    • index.html dosyalarının sonuna doğru Path 2 ifadesini bulup aşağıdaki satırda loadResources(InitUnitySection); yorum satırı oluşturun.
  7. Projenizi sertifikalandırma için gönderirken Unity'de oluşturulan tüm dosyaları 4. adımda belirtilen derleme konumunuza göndermeniz gerekir. 5. ve 6. adımlar uygulandıysa bu dosyaları da ekleyin.

Evrensel Oluşturma İşlem Hattı'nı (URP) kullanmak için sağlanan örnekleri yükseltin

Unity'nin yeni sürümlerindeki en son gelişmelerden biri, Universal Render Pipeline (URP) kullanmalarıdır. Her şeyin doğru şekilde oluşturulması için örneği yükseltin.

  1. GoogleYTGameWrapper-with-sample.unitypackage paketini yeni veya mevcut bir projeye aktararak başlayın.
  2. Render Pipeline Converter penceresine gidin: Window -> Rendering -> Render Pipeline Converter.
  3. Rendering Settings, Material Upgrade ve Readonly Material Converter'yi seçin.
  4. Ardından Initialize and Convert seçeneğini belirleyin, bu işlemin tamamlanmasını bekleyin. Örnek, URP için hazır olmalıdır.

Unity projenizdeki öğeleri bölme (Lazy Loading)

Geliştiricilerin Unity'yi kullanırken vurguladığı temel sorunlardan biri, tek tek dosya boyutu şartlarına ve toplam paket boyutu şartlarına uymaktır.

Öğelerin geç yüklenmesi, projeniz için yapabileceğiniz harika bir optimizasyondur. Bu sayede öğeleri, seviyeleri ve verileri gerektiğinde yükleyebilirsiniz. Sertifika ekibimiz, bu işlem doğru şekilde yapıldığı takdirde genel dosya boyutu kısıtlamalarını kaldırabilir. Bunun nedeni, tam oyununuzun önceden değil, kullanıcı ürününüzde gezinirken yüklenmesidir.

Unity, öğelerin düzgün şekilde yüklenmesine yardımcı olmak için öğelerinizi bölmenin çeşitli yollarını sunar. Bu yollar arasında, bağımsız öğe gruplarınızın boyut sınırlarının altında olduğunu doğrulama ve içeriği zaman içinde yükleme yer alır. Addressables veya Asset Bundles'ı kullanmanızı öneririz.

Addressables

Addressables, birlikte yüklenmesi gereken farklı dosyaları tanımlamanıza olanak tanır ve Unity, paketlemenin büyük bir kısmını sizin için halleder. Unity ayrıca dosya boyutlarını yönetmenize ve öğeleri kopyalamadığınızdan emin olmanıza yardımcı olacak bazı araçlar da sunar.

Addressables'ı kullanmak için Addressables paketini Unity'deki Paket Yöneticisi aracılığıyla içe aktarmanız ve ardından öğelerinizi Addressables Grupları'na etiketlemeniz gerekir. Daha fazla bilgi için Unity belgelerine göz atın.

Öğe paketleri

Projenizi bölüp öğeleri anında yükleyebildiğiniz için öğe paketleri faydalıdır. Bu kaynaklar; indirilebilir içerikler, seviye paketleri, yeni karakterler ve daha fazlası için yararlıdır. Öğe paketleri, kendi kendine yönetilen içerik yükleme ve paketleme için idealdir. Öğelerinizi belirli paketlere etiketleyip paketleri gerektiğinde yükleyerek bu özelliklerden yararlanabilirsiniz. Daha fazla bilgiyi Unity'nin Asset Bundle belgelerinde bulabilirsiniz.

YT Playables API referansının tamamına bakın.