常见的引擎方法和宏

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

打印文本

  1. // Prints a message to standard output.
  2. print_line("Message");
  4. // Prints a message to standard output, but only when the engine
  5. // is started with the `--verbose` command line argument.
  6. print_verbose("Message");
  8. // Prints a formatted error or warning message with a trace.
  9. ERR_PRINT("Message");
  10. WARN_PRINT("Message");
  12. // Prints an error or warning message only once per session.
  13. // This can be used to avoid spamming the console output.
  14. ERR_PRINT_ONCE("Message");
  15. WARN_PRINT_ONCE("Message");

如果你需要在信息中添加占位符,请使用下面描述的格式字符串.

格式化字符串

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

  1. vformat("My name is %s.", "Godette");
  2. vformat("%d bugs on the wall!", 1234);
  3. vformat("Pi is approximately %f.", 3.1416);
  5. // Converts the resulting String into a `const char *`.
  6. // You may need to do this if passing the result as an argument
  7. // to a method that expects a `const char *` instead of a String.
  8. vformat("My name is %s.", "Godette").c_str();

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

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

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

  1. // Prints "42" using integer-to-string conversion.
  2. print_line(itos(42));
  4. // Prints "123.45" using real-to-string conversion.
  5. print_line(rtos(123.45));

国际化字符串

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

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

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

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

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

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

注解

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

限制值

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

  1. int a = 3;
  2. int b = 5;
  4. MAX(b, 6); // 6
  5. MIN(2, a); // 2
  6. CLAMP(a, 10, 30); // 10

这适用于任何可以与其他值进行比较的类型(如 int 和 float ).

微型基准测试

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

  1. uint64_t begin = OS::get_singleton()->get_ticks_usec();
  3. // Your code here...
  5. uint64_t end = OS::get_singleton()->get_ticks_usec();
  6. print_line(vformat("Snippet took %d microseconds", end - begin));

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

注解

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

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

获取project/editor设置

有四种宏可供选择:

  1. // Returns the specified project setting's value,
  2. // defaulting to `false` if it doesn't exist.
  3. GLOBAL_DEF("section/subsection/value", false);
  5. // Returns the specified editor setting's value,
  6. // defaulting to "Untitled" if it doesn't exist.
  7. EDITOR_DEF("section/subsection/value", "Untitled");

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

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

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

错误宏

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

警告

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

注解

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

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

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

  1. // Conditionally prints an error message and returns from the function.
  2. // Use this in methods which don't return a value.
  3. ERR_FAIL_COND_MSG(!mesh.is_valid(), vformat("Couldn't load mesh at: %s", path));
  5. // Conditionally prints an error message and returns `0` from the function.
  6. // Use this in methods which must return a value.
  7. ERR_FAIL_COND_V_MSG(rect.x < 0 || rect.y < 0, 0,
  8.         "Couldn't calculate the rectangle's area.");
  10. // Prints an error message if `index` is < 0 or >= `SomeEnum::QUALITY_MAX`,
  11. // then returns from the function.
  12. ERR_FAIL_INDEX_MSG(index, SomeEnum::QUALITY_MAX,
  13.         vformat("Invalid quality: %d. See SomeEnum for allowed values.", index));
  15. // Prints an error message if `index` is < 0 >= `some_array.size()`,
  16. // then returns `-1` from the function.
  17. ERR_FAIL_INDEX_V_MSG(index, some_array.size(), -1,
  18.         vformat("Item %d is out of bounds.", index));
  20. // Unconditionally prints an error message and returns from the function.
  21. // Only use this if you need to perform complex error checking.
  22. if (!complex_error_checking_routine()) {
  23.     ERR_FAIL_MSG("Couldn't reload the filesystem cache.");
  24. }
  26. // Unconditionally prints an error message and returns `false` from the function.
  27. // Only use this if you need to perform complex error checking.
  28. if (!complex_error_checking_routine()) {
  29.     ERR_FAIL_V_MSG(false, "Couldn't parse the input arguments.");
  30. }
  32. // Crashes the engine. This should generally never be used
  33. // except for testing crash handling code. Godot's philosophy
  34. // is to never crash, both in the editor and in exported projects.
  35. CRASH_NOW_MSG("Can't predict the future! Aborting.");

参见

See core/error_macros.h in Godot’s codebase for more information about each error macro.

Some functions return an error code (materialized by a return type of Error). This value can be returned directly from an error macro. See the list of available error codes in core/error_list.h.