إضافة دوال تسجيل مدة التحميل

من المهم تسجيل الحالات التي تنفِّذ فيها لعبتك أحداث تحميل لسببَين:

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 حاليًا البيانات الوصفية والتعليقات التوضيحية، ولكن يمكن ضبط التعليق التوضيحي فقط على null. ويتم وضع علامة على جميع أحداث التحميل اللاحقة برقم تعريف مجموعة فريد.

ErrorCode StopLoadingGroup(ulong handle);

تُوقف هذه الدالة مجموعة تحميل سبق أن بدأت من خلال StartLoadingGroup(). ولن تتضمّن أحداث التحميل اللاحقة رقم تعريف مجموعة إلى أن يتم استدعاء StartLoadingGroup() مرة أخرى.

الشكل 1. مثال على مجموعة التحميل

أمثلة

في ما يلي بعض الأمثلة حول كيفية إضافة دوال وقت التحميل إلى لعبتك.

أحداث تحميل الملفات

يعرض مثال الرمز التالي كيفية تسجيل أحداث تحميل الملفات في لعبتك.

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