typedefstructTuningFork_LoadingTimeMetadata{enumLoadingState{UNKNOWN_STATE=0,// The first time the game is runFIRST_RUN=1,// App is not backgroundedCOLD_START=2,// App is backgroundedWARM_START=3,// App is backgrounded, least work neededHOT_START=4,// Asset loading between levelsINTER_LEVEL=5}state;enumLoadingSource{UNKNOWN_SOURCE=0,// Uncompressing data.MEMORY=1,// Reading assets from APK bundle.APK=2,// Reading assets from device storage.DEVICE_STORAGE=3,// Reading assets from external storage, e.g. SD card.EXTERNAL_STORAGE=4,// Loading assets from the network.NETWORK=5,// Shader compilation.SHADER_COMPILATION=6,// Time spent between process starting and onCreate.PRE_ACTIVITY=7,// Total time spent between process starting and first render frame.FIRST_TOUCH_TO_FIRST_FRAME=8}source;int32_tcompression_level;// 0 = no compression, 100 = max compressionenumNetworkConnectivity{UNKNOWN=0,WIFI=1,CELLULAR_NETWORK=2}network_connectivity;uint64_tnetwork_transfer_speed_bps;// bandwidth in bits per seconduint64_tnetwork_latency_ns;// latency in nanoseconds}TuningFork_LoadingTimeMetadata;
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-08-26 (世界標準時間)。"],[],[],null,["It is important to record when your game is performing loading events for two reasons:\n\n1. To avoid polluting your frame time data while loading.\n2. To analyze load times to see when and where load times are longer than acceptable.\n\nA loading event can have associated metadata: \n\n typedef struct TuningFork_LoadingTimeMetadata {\n enum LoadingState {\n UNKNOWN_STATE = 0,\n // The first time the game is run\n FIRST_RUN = 1,\n // App is not backgrounded\n COLD_START = 2,\n // App is backgrounded\n WARM_START = 3,\n // App is backgrounded, least work needed\n HOT_START = 4,\n // Asset loading between levels\n INTER_LEVEL = 5\n } state;\n enum LoadingSource {\n UNKNOWN_SOURCE = 0,\n // Uncompressing data.\n MEMORY = 1,\n // Reading assets from APK bundle.\n APK = 2,\n // Reading assets from device storage.\n DEVICE_STORAGE = 3,\n // Reading assets from external storage, e.g. SD card.\n EXTERNAL_STORAGE = 4,\n // Loading assets from the network.\n NETWORK = 5,\n // Shader compilation.\n SHADER_COMPILATION = 6,\n // Time spent between process starting and onCreate.\n PRE_ACTIVITY = 7,\n // Total time spent between process starting and first render frame.\n FIRST_TOUCH_TO_FIRST_FRAME = 8\n } source;\n int32_t compression_level; // 0 = no compression, 100 = max compression\n enum NetworkConnectivity {\n UNKNOWN = 0,\n WIFI = 1,\n CELLULAR_NETWORK = 2\n } network_connectivity;\n uint64_t network_transfer_speed_bps; // bandwidth in bits per second\n uint64_t network_latency_ns; // latency in nanoseconds\n } TuningFork_LoadingTimeMetadata;\n\nAny fields that aren't relevant to your needs can be zero.\n\nA loading event can also have an associated annotation. This is defined in the\nsame way as frame time annotations, using one or more fields in the `Annotation`\nmessage in the `dev_tuningfork.proto` file.\n\n[`TuningFork_ErrorCode TuningFork_startRecordingLoadingTime(\nconst TuningFork_LoadingTimeMetadata* eventMetadata,\nuint32_t eventMetadataSize,\nconst TuningFork_CProtobufSerialization* annotation,\nTuningFork_LoadingEventHandle* handle);`](/games/sdk/reference/performance-tuner/custom-engine/group/tuningfork#tuningfork_startrecordingloadingtime)\n\nThis function starts recording a loading time event associated with the\ngiven metadata and annotation, and fills in a `handle` to be used in the\n`TuningFork_stopRecordingLoadingTime()` function.\n\n[`TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime(\nTuningFork_LoadingEventHandle handle);`](/games/sdk/reference/performance-tuner/custom-engine/group/tuningfork#tuningfork_stoprecordingloadingtime)\n\nThis function stops recording an event previously started by\n`TuningFork_startRecordingLoadingTime()`. The event is uploaded at the next\nsession flush.\n\n[`TuningFork_ErrorCode TuningFork_recordLoadingTime(\nuint64_t time_ns, const TuningFork_LoadingTimeMetadata* eventMetadata,\nuint32_t eventMetadataSize,\nconst TuningFork_CProtobufSerialization* annotation);`](/games/sdk/reference/performance-tuner/custom-engine/group/tuningfork#tuningfork_recordLoadingtime)\n\nWe strongly recommend directly using the start and stop functions\ndescribed previously. If you can't do this, however, you can call this function\nto record a duration and its associated metadata and annotation.\n\nLoading group functions **Warning:** All loading events must be part of a loading group.\n\nIn your game, you may record several loading events for a single loading period\nseen by the user. Some examples include (but aren't limited to) file loading,\ndecompression, and shader compilation.\n\nIt is important to inform Tuning Fork that loading events\nare part of such a group so that it can provide better insights. Bracket your\nloading events with the following start and stop functions in order to do this.\n| **Note:** Only one loading group can be active at a time.\n\n[`TuningFork_ErrorCode TuningFork_startLoadingGroup(\nconst TuningFork_LoadingTimeMetadata* eventMetadata,\nuint32_t eventMetadataSize,\nconst TuningFork_CProtobufSerialization* annotation,\nTuningFork_LoadingEventHandle* handle);`](/games/sdk/reference/performance-tuner/custom-engine/group/tuningfork#tuningfork_startloadinggroup)\n\nThis function starts a loading group associated with the\ngiven metadata and annotation, and fills in a `handle` to be used in the\n`TuningFork_stopLoadingGroup()` function. The metadata and annotation are\ncurrently not used by the Play backend and can be set to `nullptr`. All subsequent\nloading events will be tagged by a unique group ID.\n\n[`TuningFork_ErrorCode TuningFork_stopLoadingGroup(\nTuningFork_LoadingEventHandle handle);`](/games/sdk/reference/performance-tuner/custom-engine/group/tuningfork#tuningfork_stoploadingGroup)\n\nThis function stops a loading group previously started by\n`TuningFork_startLoadingGroup()`. Subsequent loading events will not have a\ngroup ID until `TuningFork_startLoadingGroup()` is called again.\n\n\n**Figure 1.** Example of the loading group."]]