Menambahkan fungsi perekaman waktu pemuatan

Merekam saat game Anda melakukan peristiwa pemuatan sangat penting karena dua alasan, yaitu:

1. Untuk menghindari pencemaran data waktu render frame saat memuat.
2. Untuk menganalisis waktu pemuatan guna mengetahui saat dan tempat waktu pemuatan lebih lama dari yang dapat diterima.

Peristiwa pemuatan dapat memiliki metadata terkait:

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

Setiap kolom yang tidak relevan dengan kebutuhan Anda dapat bernilai nol.

Peristiwa pemuatan juga dapat memiliki anotasi terkait. Anda dapat menentukan dengan cara yang sama seperti anotasi waktu render frame, dengan menggunakan satu atau beberapa kolom dalam pesan Annotation.

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

Fungsi ini mulai merekam peristiwa waktu pemuatan yang terkait dengan metadata dan anotasi yang ditentukan, dan mengisi Result<ulong>.value untuk digunakan dalam fungsi StopRecordingLoadingTime().

ErrorCode StopRecordingLoadingTime(ulong handle);

Fungsi ini berhenti merekam peristiwa yang sebelumnya dimulai oleh StartRecordingLoadingTime(). Peristiwa diupload pada flush sesi berikutnya.

Fungsi grup pemuatan

Peringatan: Semua peristiwa pemuatan harus menjadi bagian dari grup pemuatan. Lihat contoh kode untuk fungsi grup pemuatan.

Di game, Anda dapat merekam beberapa peristiwa pemuatan untuk satu periode pemuatan yang dilihat oleh pengguna. Beberapa contoh menyertakan pemuatan file, pemuatan adegan, dekompresi, dan kompilasi shader.

Penting untuk memberi tahu Android Performance Tuner bahwa peristiwa pemuatan adalah bagian dari grup tersebut agar dapat memberikan insight yang lebih baik. Kumpulkan peristiwa pemuatan dengan fungsi mulai dan berhenti berikut untuk melakukannya.

Catatan: Hanya satu grup pemuatan yang dapat aktif pada satu waktu.

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

Fungsi ini memulai grup pemuatan yang terkait dengan metadata dan anotasi yang ditentukan, dan mengisi Result<ulong>.value untuk digunakan dalam fungsi StopLoadingGroup(). Metadata dan anotasi saat ini tidak digunakan oleh backend Play, tetapi hanya anotasi yang dapat disetel ke null. Semua peristiwa pemuatan berikutnya diberi tag oleh ID grup unik.

ErrorCode StopLoadingGroup(ulong handle);

Fungsi ini menghentikan grup pemuatan yang sebelumnya dimulai oleh StartLoadingGroup(). Peristiwa pemuatan berikutnya tidak akan memiliki ID grup hingga StartLoadingGroup() dipanggil lagi.

Gambar 1. Contoh grup pemuatan.

Contoh

Berikut beberapa contoh cara menambahkan fungsi waktu pemuatan ke game Anda.

Peristiwa pemuatan file

Contoh kode berikut menunjukkan cara merekam peristiwa pemuatan file dalam game Anda.

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

Peristiwa pemuatan adegan

Contoh kode berikut menunjukkan cara merekam peristiwa pemuatan adegan dalam game Anda.

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

Fungsi grup pemuatan

Contoh kode berikut menunjukkan cara menambahkan fungsi grup pemuatan ke game Anda.

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