Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Perfetto

也參考

詳情請參閱 tracing profiler instructions 。

Perfetto 是安卓(Android)系統預設的效能追蹤工具。事實上,它的系統追蹤服務從 Android 9 開始就已經內建在安卓平台里了。

使用官方提供的 Perfetto 範本

從 Godot 4.7 版本開始,官方發佈的每一個穩定版 Godot 都會附帶 Perfetto 匯出範本,你可以直接從 GitHub Releases page 下載。

使用 Gradle 建置範本

  • 請前往(GitHub)的 Release(發佈)頁面,下載名為 Godot_v<godot_version>_android_source.perfetto.zip 的發佈檔案。其中,godot_version 需要替換為你目前正在使用的引擎版本號。

  • 在 專案 > 匯出 對話框中,必須啟用 進階選項 和 使用 Gradle 建置。

  • 請將 Android Source Template(安卓原始碼範本) 這一項,指向你剛剛下載好的匯出範本檔案。

../../../_images/cpp_profiler_perfetto_gradle_build_config.webp

請按照 Configuration section 中的說明,來瞭解如何設定並建立追蹤(trace)。

使用非 Gradle 建置範本

  • 請前往 Release(發佈)頁面,下載以下發佈產物(release artifacts)。注意,其中的 godot_version 需要替換為你目前正在使用的引擎版本號。

    • Godot_v<godot_version>_android_debug.perfetto.apk (用於除錯建置)

    • Godot_v<godot_version>_android_release.perfetto.apk (用於發佈版本)

  • 在 Project > Export (專案 > 匯出)對話框中:

    • 必須啟用 進階選項

    • 必須停用(關閉) Use Gradle Build

  • 請將 Custom Template (自訂範本)指向你下載好的匯出範本檔案。

../../../_images/cpp_profiler_perfetto_non_gradle_build_config.webp

請按照 Configuration section 中的說明,來瞭解如何設定並建立追蹤(trace)。

帶 Perfetto 支援的自訂 Godot 建置

在 godot 根目錄下,執行以下 Python 腳本,即可在 thirdparty/perfetto 路徑下安裝最新版本的 Perfetto SDK:

python misc/scripts/install_perfetto.py

接下來,請參照《安卓平台編譯指南》( Compiling for Android ),使用 scons 為你的目標架構編譯 Android 的 debug 或 release 範本。不過,你需要額外加上 profiler=perfetto 這個參數。

備註

通常來說,建議使用 Release(發佈)範本來進行效能分析,因為這才是你的玩家們最終會玩到的版本,而且它的執行表現會和其他型別的建置版本有所不同。不過,在安卓(Android)這個特定情況下,使用 Debug(除錯)範本有時候也會很有用,因為 Godot 只能對從 Debug 範本匯出的遊戲進行遠端除錯。

例如,要為 arm64 架構編譯發佈範本:

scons platform=android target=template_release arch=arm64 generate_android_binaries=yes profiler=perfetto

配置

Perfetto 需要一個設定檔案來告訴它具體應該追蹤哪些事件。

建立一個名為 godot.config 的檔案,並填入以下內容:

# Trace for 10 seconds.
duration_ms: 10000

buffers {
    size_kb: 32768
    fill_policy: RING_BUFFER
}

# Write to file once every second to prevent overflowing the buffer.
write_into_file: true
file_write_period_ms: 1000

# Track events in the "godot" category.
data_sources {
    config {
        name: "track_event"
        track_event_config {
            enabled_categories: "godot"
        }
    }
}

備註

Godot 會記錄兩類追蹤事件(track events):

  • godot :用於記錄 Godot 引擎事件。主要用於效能分析。事件追蹤的開銷不會顯著影響效能。這應該是大多數開發者常用的追蹤模式。

  • godot_scripting:用於記錄 Godot 腳本相關的事件。這是一個比較慢(開銷較大)的類別,因為它會對整個遊戲的腳本邏輯進行效能分析。它通常用於理解程式碼邏輯、除錯、或者找出到底是甚麼導致了遊戲畫面的瞬間卡頓(frame hitch)。開啟後效能會明顯變慢,但它能幫你揪出那個平時隱藏很深、引發問題的特定函式呼叫。

抓取追蹤記錄

最後,使用你之前自己編譯好的匯出範本,將你的遊戲啟動並執行在安卓裝置上。

當您準備錄制追蹤資訊時(例如,當您已進入遊戲的某個部分併發現效能問題時),你可以使用 Perfetto GitHub倉庫中的此腳本 。

./record_android_trace -c /path/to/godot.config

這會錄制 10 秒鐘(根據設定設定),或者直到你按下 Ctrl + C 為止。

分析追蹤記錄

一旦那個腳本執行完畢退出,它就會自動在網頁瀏覽器中打開 Perfetto 的視覺化介面(UI)。

要查看Godot事件,請通過按一下您的應用的Android 唯一名稱 / 套件名稱 / 應用ID 來展開該應用的行(Perfetto還會在追蹤中包含一些來自系統服務的事件)。

../../../_images/cpp_profiler_perfetto.webp

然後,你就可以用 WASD 這幾個鍵在圖表裡自由瀏覽啦:

  • 按下 A 鍵或 D 鍵,可以在時間軸上向前或向後瀏覽

  • 按下 W 或 S 以放大或縮小

你可能需要稍微放大一下檢視,才能看清 Godot 產生的那些具體事件。

想瞭解更多詳情,可以查閱 Perfetto UI documentation。