常见的引擎方法和宏

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

格式化字符串

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

国际化字符串

Godot的代码库中有两种国际化类型:

  • 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时, 它的占位符已经被替换了.

限制值

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 声明之间的花费时间.

注解

如果还不存在, 则可能需要 #include "core/os/os.h" .

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

获取project/editor设置

有四种宏可供选择:

// 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.

错误宏

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

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