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.

Checking the stable version of the documentation...

使用 C++ 效能分析器

要優化 Godot 的效能，首先要知道該優化什麼。這時，效能分析器就是非常有用的工具。

備註

There is a built-in GDScript profiler in the editor, but using a C++ profiler may be useful in cases where the GDScript profiler is not accurate enough or is missing information due to bugs in the profiler.

There are two main types of profilers: sampling profilers and tracing profilers.

Sampling profilers periodically interrupt the running program and take a "sample", which records which functions are running. Using this information, the profiler estimates which functions the program spent the most time in.

Tracing profilers work by recording application-specific events (such as the start and end of a single frame), producing a log called a "trace". The profiler can use the trace to produce a graph showing an accurate high-level timeline of what happened. However, any code that is not explicitly instrumented will not appear in a tracing profiler's timeline!

Godot supports both sampling profilers and tracing profilers, and already includes the logging code for common Godot events for use with a tracing profiler!

Different problems may be easier to debug with one kind of profiler over the other, but it's difficult to provide a set of rules for which to use. Give both a try, and see what you can learn from them!

Sampling profilers

We recommend the following sampling profilers:

這些效能分析器也許不是最強大或最靈活的選擇，但它們獨立運作、功能單純，因此上手更容易。

設定 Godot

若要取得有用的效能分析資訊，務必要 使用包含偵錯符號的 Godot 執行檔。官方釋出的二進位檔並未包含偵錯符號，因為這會大幅增加下載檔案的大小。

若想獲得最貼近生產環境（但又有除錯符號）的效能分析資料，建議用 production=yes debug_symbols=yes 的 SCons 選項編譯執行檔。

你也可以用較少優化的建構（比如 target=template_debug 且未啟用 LTO）來進行效能分析，但這樣得出的結果會和實際運作環境有些偏差。

警告

請勿 在編譯完成後使用 strip 指令移除偵錯符號，否則執行效能分析器時將無法取得有用的分析資訊。

測試啟動／關閉所需時間

If you're looking into optimizing Godot's startup/shutdown performance, you can tell the profiler to use the --quit command line option on the Godot binary. This will exit Godot just after it's done starting. The --quit option works with --editor, --project-manager, and --path <path to project directory> (which runs a project directly).

也參考

更多 Godot 支援的命令列參數，請參閱 命令列教學 。

Tracing profilers

Godot currently supports three tracing profilers:

備註

Perfetto is the default tracing system for Android, so pre-built export templates with Perfetto built-in and enabled are provided from the GitHub Releases page.

In order to use either of them, you'll need to build the engine from source. If you've never done this before, please read these docs for the platform you want to profile on. You'll need to perform the same steps here, but with some additional arguments for scons.

Microbenchmarks

While not technically profiling, microbenchmarks are a related concept: after you've identified your hotspot, you'll want a simple and isolatable way to test whether what you're doing has an impact. While re-profiling can be an option, sometimes a microbenchmark can be simpler.

You can see example benchmark setups in the subsections below. Between C++ and GDScript, GDScript benchmarks are usually the more appropriate choice. Because they involve the GDScript language and its overhead, GDScript benchmarks are truthful to how most people will experience your changes. C++ benchmarks are more versatile and can measure smaller performance differences. However, they are also more difficult to get right. In practice, it can often be good to benchmark both.

備註

To benchmark effectively can be difficult. Benchmarks can easily lead you astray, for example by not representing the situation faithfully, by failing to account for compiler optimizations and other nuances, or by measuring in an unreliable way such that you record noise instead of an actual performance change. Before you start benchmarking, please read up on benchmarking guides and best practices. A good place to start is Gregg's "Active Benchmarking", which provides a high level overview and quick checklist for benchmarking.

GDScript benchmarks

To run a GDScript benchmark, start by creating a benchmark.gd file with the following contents:

extends SceneTree

func _init():
    const N = 1_000_000

    var t0 := Time.get_ticks_usec()
    for i in N:
        pass  # Do the thing you want to benchmark here.
    var t1 := Time.get_ticks_usec()

    var ns_per_op := (t1 - t0) * 1000.0 / N
    print("Benchmark result: %.1f ns/op" % ns_per_op)
    quit()

Edit the file to add your benchmark. You can run the benchmark using godot --headless -s benchmark.gd.

備註

At the time of writing, GDScript performs few code optimization. Dead code elimination, for example, is generally not performed. Therefore, it is easier to write a decently representative benchmark in GDScript than in C++. This might change in the future.

C++ benchmarks

To run a C++ benchmark, create the file tests/core/test_user_bench.cpp with the following contents:

#include "tests/test_macros.h"

TEST_FORCE_LINK(test_user_bench)

#include <chrono>
#include <cstdio>

static void user_bench() {
    const int N = 1'000'000;
    static uintptr_t sink = 0; // Defeats dead-code elimination.

    auto t0 = std::chrono::steady_clock::now();
    for (int i = 0; i < N; i++) {
        // Do the thing you want to benchmark here.
        // sink += (uintptr_t)something; // Update the sink from the result somehow.
    }
    auto t1 = std::chrono::steady_clock::now();

    double ns_per_op = std::chrono::duration<double, std::nano>(t1 - t0).count() / N;
    printf("Benchmark result: %.1f ns/op (sink %zu)\n", ns_per_op, (size_t)sink);
}

REGISTER_TEST_COMMAND("user-bench", &user_bench)

Edit the file to add your benchmark. Compile Godot with tests=yes, and run the benchmark using godot --test user-bench.

備註

C++ benchmarks can be fickle and can easily lead you astray unless you have a strong foundation of knowledge about C++ and compilers. Before you start benchmarking, read up on guides and best practices about how to benchmark C++. You can find free in-depth guides in Bakhvalov's "Performance Analysis and Tuning on Modern CPUs", and Agner Fog's "Software Optimization Resources".