افزودن توابع ضبط زمان بار کردن

مهم است که زمان انجام رویدادهای بار کردن بازی را به دو دلیل ثبت کنید:

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

رویداد بارگیری می‌تواند فراداده‌های مرتبط داشته باشد:

public class LoadingTimeMetadata
{
    public enum LoadingState
    {
        Unknown = 0,

        /// <summary>
        ///     The first time the game is run.
        /// </summary>
        FirstRun = 1,

        /// <summary>
        ///     App is not backgrounded.
        /// </summary>
        ColdStart = 2,

        /// <summary>
        ///     App is backgrounded.
        /// </summary>
        WarmStart = 3,

        /// <summary>
        ///     App is backgrounded, least work needed.
        /// </summary>
        HotStart = 4,

        /// <summary>
        ///     Asset loading between levels.
        /// </summary>
        InterLevel = 5
    }

    public LoadingState state;

    public enum LoadingSource
    {
        UnknownSource = 0,

        /// <summary>
        ///     Uncompressing data.
        /// </summary>
        Memory = 1,

        /// <summary>
        ///     Reading assets from APK bundle.
        /// </summary>
        Apk = 2,

        /// <summary>
        ///     Reading assets from device storage.
        /// </summary>
        DeviceStorage = 3,

        /// <summary>
        ///     Reading assets from external storage, e.g. SD card.
        /// </summary>
        ExternalStorage = 4,

        /// <summary>
        ///     Loading assets from the network.
        /// </summary>
        Network = 5,

        /// <summary>
        ///     Shader compilation.
        /// </summary>
        ShaderCompilation = 6,

        /// <summary>
        ///     Time spent between process starting and onCreate.
        /// </summary>
        PreActivity = 7,

        /// <summary>
        ///     Total time spent between process starting and first render frame.
        /// </summary>
        FirstTouchToFirstFrame = 8,

        /// <summary>
        ///     Time from start to end of a group of events.
        /// </summary>
        TotalUserWaitForGroup = 9
    }

    public LoadingSource source;

    /// <summary>
    ///     0 = no compression, 100 = max compression
    /// </summary>
    public int compression_level;

    public enum NetworkConnectivity
    {
        Unknown = 0,
        Wifi = 1,
        CellularNetwork = 2
    }

    public NetworkConnectivity network_connectivity;

    /// <summary>
    ///     Bandwidth in bits per second.
    /// </summary>
    public ulong network_transfer_speed_bps;

    /// <summary>
    ///     Latency in nanoseconds.
    /// </summary>
    public ulong network_latency_ns;
}

هر فیلدی که به نیازهای شما مربوط نیست می‌تواند صفر باشد.

رویداد بار کردن می‌تواند حاشیه‌نویسی مرتبط هم داشته باشد. می‌توانید بااستفاده از یک یا چند فیلد در پیام Annotation، به همان روش حاشیه‌نویسی‌های زمان پردازش فریم تعریف کنید.

Result<ulong> StartRecordingLoadingTime(LoadingTimeMetadata eventMetadata, TAnnotation annotation);

این تابع ضبط رویداد زمان بارگیری مرتبط با فراداده و حاشیه‌نویسی ارائه‌شده را شروع می‌کند و Result<ulong>.value را برای استفاده در تابع StopRecordingLoadingTime() تکمیل می‌کند.

ErrorCode StopRecordingLoadingTime(ulong handle);

این تابع ضبط رویدادی را که قبلاً توسط StartRecordingLoadingTime() شروع شده است متوقف می‌کند. رویداد در پاک‌سازی جلسه بعدی بارگذاری می‌شود.

درحال بار کردن عملکردهای گروهی

در بازی‌تان، ممکن است چندین رویداد بار کردن را برای یک دوره بار کردن که کاربر می‌بیند ثبت کنید. برخی‌از نمونه‌ها عبارت‌اند از بار کردن فایل، بار کردن صحنه، وافشرده‌سازی، و کامپایل کردن سایه‌زن.

مهم است که به Android Performance Tuner اطلاع دهید که رویدادهای بارگیری بخشی از چنین گروهی هستند تا بتواند اطلاعات آماری بهتری ارائه دهد. برای انجام این کار، رویدادهای بارگیری را با توابع شروع و توقف زیر دسته‌بندی کنید.

Result<ulong> StartLoadingGroup(LoadingTimeMetadata eventMetadata, TAnnotation annotation);

این تابع یک گروه بارگیری مرتبط با فراداده و حاشیه‌نویسی داده‌شده را شروع می‌کند و یک Result<ulong>.value را برای استفاده در تابع StopLoadingGroup() پر می‌کند. درحال‌حاضر فراداده و حاشیه‌نویسی توسط Play backend استفاده نمی‌شود، و فقط حاشیه‌نویسی را می‌توان روی null تنظیم کرد. همه رویدادهای بارگیری بعدی با شناسه گروه یکتایی برچسب‌گذاری می‌شوند.

ErrorCode StopLoadingGroup(ulong handle);

این تابع گروه بارگیری را که قبلاً توسط StartLoadingGroup() شروع شده است متوقف می‌کند. رویدادهای بارگیری بعدی تا زمانی که StartLoadingGroup() دوباره فراخوانی نشود، شناسه گروه نخواهند داشت.

روندنمایی که StartLoadingGroup و StopLoadingGroup را نشان می‌دهد که تماس‌های بار کردن دارایی را دربرمی‌گیرد
شکل ۱. نمونه‌ای از گروه بارگیری.

مثال‌ها

در اینجا چند نمونه از نحوه افزودن توابع زمان بارگیری به بازی‌تان آورده شده است.

رویدادهای بار کردن فایل

نمونه کد زیر نحوه ثبت رویدادهای بار کردن فایل را در بازی‌تان نشان می‌دهد.

public RawImage image;

IEnumerator LoadImageFromStreamingAssets(string imageName)
{
    string imagePath = "file://" + Path.Combine(Application.streamingAssetsPath, imageName);
    using (var r = UnityWebRequestTexture.GetTexture(imagePath))
    {
        LoadingTimeMetadata fileLoadingMetadata = new LoadingTimeMetadata()
        {
            state = LoadingTimeMetadata.LoadingState.InterLevel,
            source = LoadingTimeMetadata.LoadingSource.DeviceStorage,
            // Fields are zero by default but they could be set as follows
            compression_level = 0,
            network_connectivity = 0,
            network_transfer_speed_bps = 0,
            network_latency_ns = 0
        };
        Annotation annotation = new Annotation()
        {
            Scene = Scene.MagicalForest
        };
        // Start recording loading time.
        Result<ulong> result = performanceTuner.StartRecordingLoadingTime(fileLoadingMetadata, annotation);
        yield return r.SendWebRequest();
        // Stop recording loading time.
        performanceTuner.StopRecordingLoadingTime(result.value);
        if (r.isNetworkError || r.isHttpError)
        {
            Debug.Log(r.error);
        }
        else
        {
            Texture2D tex = DownloadHandlerTexture.GetContent(r);
            image.texture = tex;
        }
    }
}

رویدادهای بار کردن صحنه

نمونه کد زیر نحوه ضبط رویدادهای بار کردن صحنه را در بازی‌تان نشان می‌دهد.

IEnumerator LoadScene(int sceneIndex)
{
    LoadingTimeMetadata metadata = new LoadingTimeMetadata()
        {state = LoadingTimeMetadata.LoadingState.InterLevel};
    Annotation annotation = new Annotation() {Scene = (Scene) (sceneIndex + 1)};
    Result<ulong> result = performanceTuner.StartRecordingLoadingTime(metadata, annotation);
    AsyncOperation asyncSceneLoad = SceneManager.LoadSceneAsync(sceneIndex, LoadSceneMode.Single);
    while (!asyncSceneLoad.isDone)
    {
        yield return null;
    }

    performanceTuner.StopRecordingLoadingTime(result.value);
}

درحال بار کردن عملکردهای گروهی

نمونه کد زیر نحوه افزودن عملکردهای گروه بارگیری را به بازی‌تان نشان می‌دهد.

IEnumerator LoadImages()
{
    LoadingTimeMetadata groupMetadata = new LoadingTimeMetadata()
    {
        state = LoadingTimeMetadata.LoadingState.InterLevel,
        source = LoadingTimeMetadata.LoadingSource.DeviceStorage,
    };
    Result<ulong> result = performanceTuner.StartLoadingGroup(groupMetadata, null);
    yield return StartCoroutine(LoadImageFromStreamingAssets("image1.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image2.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image3.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image4.jpeg"));
    var stopErrorCode = performanceTuner.StopLoadingGroup(0);
}