Common engine methods and macros

Godot的C++代码库使用了几十种自定义方法和宏,这些方法和宏几乎在每个文件中都会用到。本页面向初学者,但对那些编写自定义C++模块的人也很有用。

Format a string

vformat() 函数返回一个格式化的 String 。它的行为方式类似于C语言的 sprintf():

vformat("My name is %s.", "Godette");
vformat("%d bugs on the wall!", 1234);
vformat("Pi is approximately %f.", 3.1416);

// Converts the resulting String into a `const char *`.
// You may need to do this if passing the result as an argument
// to a method that expects a `const char *` instead of a String.
vformat("My name is %s.", "Godette").c_str();

在大多数情况下,尽量使用 vformat() 而不是字符串连接,因为这样可以使代码更易读。

将整数或浮点数转换为字符串

在直接打印数字时,这主要是有用的。

// Prints "42" using integer-to-string conversion.
print_line(itos(42));

// Prints "123.45" using real-to-string conversion.
print_line(rtos(123.45));

Internationalize a string

There are two types of internationalization in Godot's codebase:

  • TTR()编辑器("工具")的翻译 只在编辑器中处理。如果用户在他们的一个项目中使用相同的文本,如果他们提供了翻译,但不会被翻译。在为引擎做贡献时,一般来说,这是你应该为可本地化字符串使用的宏。

  • RTR()运行时翻译 如果提供给定字符串的翻译,将在项目中自动本地化,这种翻译不应该用在纯编辑器的代码中。

// Returns the translated string that matches the user's locale settings.
// Translations are located in `editor/translations`.
// The localization template is generated automatically; don't modify it.
TTR("Exit the editor?");

要在可本地化字符串中插入占位符,请将本地化宏包裹在 vformat() 的调用中,如下所示:

String file_path = "example.txt";
vformat(TTR("Couldn't open \"%s\" for reading."), file_path);

注解

当同时使用 vformat() 和翻译宏时,总是将翻译宏包裹在 vformat() 中,而不是相反。否则,字符串永远不会与翻译匹配,因为当它传递给TranslationServer时,它的占位符已经被替换了。

Clamp a value

Godot提供了宏,用于用下限(MAX)、上限(MIN)或两者都有(CLAMP)的值进行限定:

int a = 3;
int b = 5;

MAX(b, 6); // 6
MIN(2, a); // 2
CLAMP(a, 10, 30); // 10

这适用于任何可以与其他值进行比较的类型(如 intfloat )。

微型基准测试

如果你想对一段代码进行基准测试,但不知道如何使用分析器,可以使用这个代码段:

uint64_t begin = OS::get_singleton()->get_ticks_usec();

// Your code here...

uint64_t end = OS::get_singleton()->get_ticks_usec();
print_line(vformat("Snippet took %d microseconds", end - begin));

这将打印从 begin 执行到 end 声明之间的花费时间。

注解

You may have to #include "core/os/os.h" if it's not present already.

当打开一个pull request时,如果之前没有这个代码,请确保删除这个代码段以及include。

Get project/editor settings

There are four macros available for this:

// Returns the specified project setting's value,
// defaulting to `false` if it doesn't exist.
GLOBAL_DEF("section/subsection/value", false);

// Returns the specified editor setting's value,
// defaulting to "Untitled" if it doesn't exist.
EDITOR_DEF("section/subsection/value", "Untitled");

如果在其他地方已经指定了默认值,就不要再指定了,以免重复:

// Returns the value of the project setting.
GLOBAL_GET("section/subsection/value");
// Returns the value of the editor setting.
EDITOR_GET("section/subsection/value");

建议每个设置只使用一次``GLOBAL_DEF``/EDITOR_DEF``并在引用它的所有其他位置使用``GLOBAL_GET/EDITOR_GET

Error macros

Godot提供了许多错误宏,以便更方便地报告错误。

警告

错误宏中的条件以GDScript内置的``assert()``函数的**opposite**方式工作。如果内部条件的计算结果为“true”,而不是“false”,则会出现错误。

注解

此处仅记录具有自定义消息的变体,因为这些变体应始终用于新的贡献中。 确保提供的自定义消息包括足够的信息,即使人们不了解C ++,也可以使人们诊断问题。 如果方法传递了无效的参数,则可以打印有问题的无效值以简化调试。

对于不需要显示可读性信息的内部错误检查,请删除宏名末尾的 _MSG ,并且不要提供信息参数。

另外,总是尽量返回可处理的数据,这样引擎才能保持良好的运行。

// Conditionally prints an error message and returns from the function.
// Use this in methods which don't return a value.
ERR_FAIL_COND_MSG(!mesh.is_valid(), vformat("Couldn't load mesh at: %s", path));

// Conditionally prints an error message and returns `0` from the function.
// Use this in methods which must return a value.
ERR_FAIL_COND_V_MSG(rect.x < 0 || rect.y < 0, 0,
        "Couldn't calculate the rectangle's area.");

// Prints an error message if `index` is < 0 or >= `SomeEnum::QUALITY_MAX`,
// then returns from the function.
ERR_FAIL_INDEX_MSG(index, SomeEnum::QUALITY_MAX,
        vformat("Invalid quality: %d. See SomeEnum for allowed values.", index));

// Prints an error message if `index` is < 0 >= `some_array.size()`,
// then returns `-1` from the function.
ERR_FAIL_INDEX_V_MSG(index, some_array.size(), -1,
        vformat("Item %d is out of bounds.", index));

// Unconditionally prints an error message and returns from the function.
// Only use this if you need to perform complex error checking.
if (!complex_error_checking_routine()) {
    ERR_FAIL_MSG("Couldn't reload the filesystem cache.");
}

// Unconditionally prints an error message and returns `false` from the function.
// Only use this if you need to perform complex error checking.
if (!complex_error_checking_routine()) {
    ERR_FAIL_V_MSG(false, "Couldn't parse the input arguments.");
}

// Crashes the engine. This should generally never be used
// except for testing crash handling code. Godot's philosophy
// is to never crash, both in the editor and in exported projects.
CRASH_NOW_MSG("Can't predict the future! Aborting.");

参见

有关每个错误宏的更多信息,请参见Godot代码库中的`core/error_macros.h <https://github.com/godotengine/godot/blob/master/core/error_macros.h>`__。

有些函数会返回一个错误代码(具体化为返回类型 Error )。这个值可以直接从错误宏返回。参见 core/error_list.h 中的可用错误代码列表。