دمج مواد العرض (Unity)

عند دمج عرض المواد في ألعاب Unity الوصول إلى حِزم مواد العرض باستخدام Addressables أو AssetBundles. العناوين هي حلّ حديث ومقترَح لتقديم مواد العرض للألعاب التي صُمِّمت باستخدام Unity 2019.4 أو إصدار أحدث، بينما تتيح AssetBundles استخدام حِزم مواد العرض في Unity 2017.4 و2018.4.

أهداف الانسجام

الألعاب التي تم إنشاؤها باستخدام Unity 2019.4 أو إصدار أحدث يجب أن تستخدم العناوين لتسليم مواد العرض على Android. توفّر Unity واجهة برمجة تطبيقات عرض المواد في Play (PAD) للتعامل مع حِزم مواد العرض في Android باستخدام أداة Addressables. للحصول على معلومات حول استخدام للعناوين، راجع ما يلي:

استخدام ملفات AssetBundle

يمكن للألعاب التي تم إنشاؤها باستخدام Unity 2017.4 و2018.4 استخدام ملفات AssetBundle كمواد عرض. على Android. الانسجام AssetBundle تحتوي الملفات على أصول متسلسلة يمكن تحميلها بواسطة محرك Unity أثناء تطبيقك قيد التشغيل. هذه الملفات خاصة بنظام التشغيل (على سبيل المثال، مصممة Android) ويمكن استخدامها مع حِزم مواد العرض. الأكثر شيوعًا، يتم جمع ملف AssetBundle واحد في حزمة مواد عرض واحدة، مع الحزمة باستخدام نفس اسم AssetBundle. إذا كنت ترغب في مزيد من المرونة في إنشاء Asset pack، اضبط حزمة مواد العرض باستخدام واجهة برمجة التطبيقات.

في وقت التشغيل، استخدِم ميزة عرض المواد في Play for Unity. لاسترداد قيمة AssetBundle المُضمَّنة في حزمة مواد عرض.

المتطلّبات الأساسية

  1. يمكنك تنزيل أحدث إصدار من مكوّن Unity الإضافي لعرض المواد في Play من حِزم Google الانسجام:

  2. أنشِئ AssetBundles في Unity.

إعداد AssetBundles باستخدام واجهة المستخدم

  1. اضبط كل AssetBundle في حزمة مواد عرض على النحو التالي:

    1. حدد Google > مجموعة حزمات تطبيق Android > إعدادات عرض المواد:
    2. لاختيار المجلدات التي تحتوي مباشرةً على ملفات AssetBundle، انقر على إضافة. مجلد.

  2. غيِّر وضع التسليم لكل حزمة إلى وقت التثبيت أو سريع. المتابعة أو المحتوى عند الطلب حل أي أخطاء أو تبعيات وإغلاق نافذة.

  3. حدد Google > يجب إنشاء "مجموعة حزمات تطبيق Android" لإنشاء حِزمة التطبيق.

  4. (اختياري) يمكنك ضبط حِزمة التطبيق للتوافق مع زخارف مختلفة بتنسيقات الضغط

إعداد حِزم مواد العرض باستخدام واجهة برمجة التطبيقات

يمكنك إعداد عرض مواد العرض من خلال النصوص البرمجية للمحرِّر، والتي يمكن تشغيلها كجزء من هذه النصوص. لنظام تصميم آلي

يمكنك استخدام AssetPackConfig لتحديد مواد العرض التي يجب تضمينها في "مجموعة حزمات تطبيق Android" كوضع تسليم الأصول. لا يلزم أن تحتوي حِزم مواد العرض هذه على AssetBundle.

public void ConfigureAssetPacks {
   // Creates an AssetPackConfig with a single asset pack, named
   // examplePackName, containing all the files in path/to/exampleFolder.
   var assetPackConfig = new AssetPackConfig();
   assetPackConfig.AddAssetsFolder("examplePackName",
                                   "path/to/exampleFolder",
                                   AssetPackDeliveryMode.OnDemand);

   // Configures the build system to use the newly created assetPackConfig when
   // calling Google > Build and Run or Google > Build Android App Bundle.
   AssetPackConfigSerializer.SaveConfig(assetPackConfig);

   // Alternatively, use BundleTool.BuildBundle to build an App Bundle from script.
   BuildBundle(new buildPlayerOptions(), assetPackConfig);
}

يمكنك أيضًا استخدام الدالة الثابتة BuildBundle في الفئة Bundletool لإنشاء "مجموعة حزمات تطبيق Android" تحتوي على مادة عرض الحزم، نظرًا BuildPlayerOptions أو AssetPackConfig

للحصول على دليل توجيهي، يُرجى الاطّلاع على استخدام ميزة "عرض المواد في Play" في الدرس التطبيقي حول الترميز الخاص بألعاب Unity:

الدمج مع واجهة برمجة التطبيقات Play Asset Delivery Unity API

تشير رسالة الأشكال البيانية واجهة برمجة التطبيقات في Play Asset Delivery Unity توفير وظائف طلب حِزم مواد العرض وإدارة عمليات التنزيل الوصول إلى الأصول. احرص على إضافة مكوّن Unity الإضافي إلى مشروعك أولاً.

تعتمد الدوال التي تستخدمها في واجهة برمجة التطبيقات على الطريقة التي أنشأت بها حِزم مواد العرض.

إذا كنت أنشأ حِزم مواد العرض باستخدام واجهة مستخدم المكوّن الإضافي اختَر حِزم مواد العرض التي تم ضبطها في المكوّنات الإضافية.

إذا كنت أنشأ حِزم مواد العرض باستخدام واجهة برمجة التطبيقات (أو واجهة مستخدم المكوّن الإضافي)، اختَر حِزم مواد العرض التي تم ضبطها على واجهة برمجة التطبيقات.

يجب تنفيذ واجهة برمجة التطبيقات وفقًا لنوع عرض الإعلانات حزمة مواد العرض التي تريد الوصول إليها. يتم عرض هذه الخطوات في ما يلي مخطط انسيابي.

مخطَّط مسار حزمة مواد العرض للمكوّن الإضافي

الشكل 1. مخطط انسيابي للوصول إلى حِزم مواد العرض

استرداد مجموعات مواد العرض

استيراد مكتبة عرض المواد في Play واستدعاء RetrieveAssetBundleAsync() لاسترداد AssetBundle.

using Google.Play.AssetDelivery;

// Loads the AssetBundle from disk, downloading the asset pack containing it if necessary.
PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(asset-bundle-name);

التسليم في وقت التثبيت

تتوفّر على الفور في التطبيق حِزم مواد العرض التي تم ضبطها لتكون install-time. إطلاقه. يمكنك استخدام ما يلي لتحميل مشهد من AssetBundle:

AssetBundle assetBundle = bundleRequest.AssetBundle;

// You may choose to load scenes from the AssetBundle. For example:
string[] scenePaths = assetBundle.GetAllScenePaths();
SceneManager.LoadScene(scenePaths[path-index]);

متابعة سريعة وتوصيل عند الطلب

تنطبق هذه الأقسام على fast-follow وon-demand حِزم مواد عرض.

فحص الحالة

يتم تخزين كل حزمة مواد عرض في مجلد منفصل على وحدة التخزين الداخلية للتطبيق. يمكنك استخدام isDownloaded() لتحديد ما إذا كان قد سبق تنزيل حزمة مواد عرض.

مراقبة التنزيل

الاستعلام عن PlayAssetBundleRequest لمراقبة حالة الطلب:

// Download progress of request, between 0.0f and 1.0f. The value will always be
// 1.0 for assets delivered as install-time.
// NOTE: A value of 1.0 will only signify the download is complete. It will still need to be loaded.
float progress = bundleRequest.DownloadProgress;

// Returns true if:
//   * it had either completed the download, installing, and loading of the AssetBundle,
//   * OR if it has encountered an error.
bool done = bundleRequest.IsDone;

// Returns status of retrieval request.
AssetDeliveryStatus status = bundleRequest.Status;
switch(status) {
    case AssetDeliveryStatus.Pending:
        // Asset pack download is pending - N/A for install-time assets.
    case AssetDeliveryStatus.Retrieving:
        // Asset pack is being downloaded and transferred to app storage.
        // N/A for install-time assets.
    case AssetDeliveryStatus.Available:
        // Asset pack is downloaded on disk but NOT loaded into memory.
        // For PlayAssetPackRequest(), this indicates that the request is complete.
    case AssetDeliveryStatus.Loading:
        // Asset pack is being loaded.
    case AssetDeliveryStatus.Loaded:
        // Asset pack has finished loading, assets can now be loaded.
        // For PlayAssetBundleRequest(), this indicates that the request is complete.
    case AssetDeliveryStatus.Failed:
        // Asset pack retrieval has failed.
    case AssetDeliveryStatus.WaitingForWifi:
        // Asset pack retrieval paused until either the device connects via Wi-Fi,
        // or the user accepts the PlayAssetDelivery.ShowConfirmationDialog dialog.
    case AssetDeliveryStatus.RequiresUserConfirmation:
        // Asset pack retrieval paused until the user accepts the
        // PlayAssetDelivery.ShowConfirmationDialog dialog.
    default:
        break;
}

عمليات تنزيل كبيرة الحجم

يمكن تنزيل حِزم مواد العرض التي يزيد حجمها عن 200 ميغابايت تلقائيًا، ولكن على شبكة Wi-Fi فقط. في حال حذف المستخدم ليس متصلاً بشبكة Wi-Fi، تم ضبط حالة PlayAssetBundleRequest على AssetDeliveryStatus.WaitingForWifi وتم إيقاف التنزيل مؤقتًا. في هذه الحالة، عليك إما الانتظار حتى يتم توصيل الجهاز إلى Wi-Fi أو استئناف التنزيل أو طلب الموافقة من المستخدم لتنزيل حزمة عبر اتصال خلوي.

تأكيد من المستخدم مطلوب

إذا كانت الحزمة تتضمّن الحالة AssetDeliveryStatus.RequiresUserConfirmation، لن تتم متابعة التنزيل حتى يقبل المستخدم مربع الحوار الذي يظهر مع PlayAssetDelivery.ShowConfirmationDialog() يمكن أن تنشأ هذه الحالة إذا كان التطبيق لا يتعرّف عليه Play. لاحظ أن الاتصال يتسبب PlayAssetDelivery.ShowConfirmationDialog() في هذه الحالة في تحديث التطبيق. بعد التعديل، اطلب مواد العرض مرة أخرى.

if(request.Status == AssetDeliveryStatus.RequiresUserConfirmation
   || request.Status == AssetDeliveryStatus.WaitingForWifi) {
    var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog();
    yield return userConfirmationOperation;

    switch(userConfirmationOperation.GetResult()) {
        case ConfirmationDialogResult.Unknown:
            // userConfirmationOperation finished with an error. Something went
            // wrong when displaying the prompt to the user, and they weren't
            // able to interact with the dialog.
        case ConfirmationDialogResult.Accepted:
            // User accepted the confirmation dialog--an update will start.
        case ConfirmationDialogResult.Declined:
            // User canceled or declined the dialog. It can be shown again.
        default:
            break;
    }
}

إلغاء طلب (عند الطلب فقط)

إذا كنت بحاجة إلى إلغاء الطلب قبل تحميل AssetBundles في الذاكرة، عليك استدعاء AttemptCancel() على PlayAssetBundleRequest الكائن:

// Will only attempt if the status is Pending, Retrieving, or Available - otherwise
// it will be a no-op.
bundleRequest.AttemptCancel();

// Check to see if the request was successful by checking if the error code is Canceled.
if(bundleRequest.Error == AssetDeliveryErrorCode.Canceled) {
    // Request was successfully canceled.
}

طلب حِزم مواد العرض بشكل غير متزامن

في معظم الحالات، يجب عليك استخدام الكوروتين إلى طلب حِزم مواد العرض بشكل غير متزامن ومراقبة مستوى التقدّم، كما هو موضّح في التالي:

private IEnumerator LoadAssetBundleCoroutine(string assetBundleName) {

    PlayAssetBundleRequest bundleRequest =
        PlayAssetDelivery.RetrieveAssetBundleAsync(assetBundleName);

    while (!bundleRequest.IsDone) {
        if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) {
            var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation();

            // Wait for confirmation dialog action.
            yield return userConfirmationOperation;

            if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) ||
               (userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) {
                // The user did not accept the confirmation. Handle as needed.
            }

            // Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on.
            yield return new WaitUntil(() => bundleRequest.Status != AssetDeliveryStatus.WaitingForWifi);
        }

        // Use bundleRequest.DownloadProgress to track download progress.
        // Use bundleRequest.Status to track the status of request.

        yield return null;
    }

    if (bundleRequest.Error != AssetDeliveryErrorCode.NoError) {
        // There was an error retrieving the bundle. For error codes NetworkError
        // and InsufficientStorage, you may prompt the user to check their
        // connection settings or check their storage space, respectively, then
        // try again.
        yield return null;
    }

    // Request was successful. Retrieve AssetBundle from request.AssetBundle.
    AssetBundle assetBundle = bundleRequest.AssetBundle;

لمزيد من المعلومات حول التعامل مع الأخطاء، يمكنك الاطّلاع على قائمة AssetDeliveryErrorCodes

طرق أخرى Play Core API

في ما يلي بعض الطرق الإضافية لواجهة برمجة التطبيقات التي قد تريد استخدامها في تطبيقك.

التحقّق من حجم التنزيل

التحقُّق من حجم AssetBundle من خلال إجراء طلب غير متزامن إلى Google Play وإعداد طريقة معاودة الاتصال عند اكتمال العملية:

public IEnumerator GetDownloadSize() {
   PlayAsyncOperation<long> getSizeOperation =
   PlayAssetDelivery.GetDownloadSize(assetPackName);

   yield return getSizeOperation;
   if(operation.Error != AssetDeliveryErrorCode.NoError) {
       // Error while retrieving download size.
    } else {
        // Download size is given in bytes.
        long downloadSize = operation.GetResult();
    }
}

إزالة مجموعات مواد العرض

يمكنك إزالة مجموعات مواد العرض ذات المتابعة السريعة وعند الطلب غير المتوفرة حاليًا. تم تحميلها في الذاكرة. إجراء المكالمة غير المتزامنة التالية وإعداد معاودة اتصال عند اكتماله:

PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName);

removeOperation.Completed += (operation) =>
            {
                if(operation.Error != AssetDeliveryErrorCode.NoError) {
                    // Error while attempting to remove AssetBundles.
                } else {
                    // Files were deleted OR files did not exist to begin with.
                }
            };

الخطوات التالية

اختبار عرض مواد العرض محليًا ومن Google Play.