Funktionen zur Aufzeichnung der Ladezeit hinzufügen

Es ist aus zwei Gründen wichtig, zu erfassen, wann in Ihrem Spiel Ladeereignisse ausgeführt werden:

1. Damit deine Frame Time-Daten während des Ladevorgangs nicht verschmutzt werden.
2. Analysieren der Ladezeiten, um zu sehen, wann und wo sie länger als akzeptabel sind

Einem Ladeereignis können zugehörige Metadaten zugeordnet sein:

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

Alle Felder, die für Ihre Anforderungen nicht relevant sind, können null sein.

Einem Ladeereignis kann auch eine Annotation zugeordnet sein. Sie können die Definition auf dieselbe Weise wie Frame Time-Annotationen definieren, indem Sie ein oder mehrere Felder in der Annotation-Nachricht verwenden.

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

Diese Funktion beginnt mit der Aufzeichnung eines Ladezeitereignisses, das mit den angegebenen Metadaten und Annotationen verknüpft ist, und fügt eine Result<ulong>.value ein, die in der Funktion StopRecordingLoadingTime() verwendet werden soll.

ErrorCode StopRecordingLoadingTime(ulong handle);

Diese Funktion beendet die Aufzeichnung eines Ereignisses, das zuvor von StartRecordingLoadingTime() gestartet wurde. Das Ereignis wird bei der nächsten Sitzungslöschung hochgeladen.

Gruppenfunktionen werden geladen

In Ihrem Spiel können Sie mehrere Ladeereignisse für einen einzelnen Ladezeitraum aufzeichnen, die der Nutzer sieht. Beispiele hierfür sind das Laden von Dateien, das Laden von Szenen, die Dekomprimierung und die Shader-Kompilierung.

Es ist wichtig, dem Android Performance Tuner mitzuteilen, dass Ladeereignisse zu einer solchen Gruppe gehören, damit er bessere Statistiken liefern kann. Fügen Sie dazu die folgenden Start- und Stoppfunktionen in Ihre Ladeereignisse ein.

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

Diese Funktion startet eine Ladegruppe, die den angegebenen Metadaten und Anmerkungen zugeordnet ist, und füllt eine Result<ulong>.value aus, die in der Funktion StopLoadingGroup() verwendet werden soll. Die Metadaten und die Annotation werden derzeit nicht vom Play-Back-End verwendet, aber nur die Annotation kann auf null gesetzt werden. Alle nachfolgenden Ladeereignisse werden mit einer eindeutigen Gruppen-ID gekennzeichnet.

ErrorCode StopLoadingGroup(ulong handle);

Diese Funktion stoppt eine Ladegruppe, die zuvor von StartLoadingGroup() gestartet wurde. Nachfolgende Ladeereignisse haben erst dann eine Gruppen-ID, wenn StartLoadingGroup() noch einmal aufgerufen wird.

Abbildung 1: Beispiel für die Ladegruppe.

Beispiele

Hier sind einige Beispiele dafür, wie Sie Funktionen für die Ladezeit zu Ihrem Spiel hinzufügen können.

Ladeereignisse für Dateien

Das folgende Codebeispiel zeigt, wie Sie Ladeereignisse von Dateien in Ihrem Spiel aufzeichnen.

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

Szenenladeereignisse

Das folgende Codebeispiel zeigt, wie Sie Szenenladeereignisse in Ihrem Spiel aufzeichnen.

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

Gruppenfunktionen werden geladen

Das folgende Codebeispiel zeigt, wie Sie Ihrem Spiel Ladegruppenfunktionen hinzufügen.

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