Common engine methods and macros¶
Godot's C++ codebase makes use of dozens of custom methods and macros which are used in almost every file. This page is geared towards beginner contributors, but it can also be useful for those writing custom C++ modules.
Print text¶
// Prints a message to standard output.
print_line("Message");
// Non-String arguments are automatically converted to String for printing.
// If passing several arguments, they will be concatenated together with a
// space between each argument.
print_line("There are", 123, "nodes");
// Prints a message to standard output, but only when the engine
// is started with the `--verbose` command line argument.
print_verbose("Message");
// Prints a rich-formatted message using BBCode to standard output.
// This supports a subset of BBCode tags supported by RichTextLabel
// and will also appear formatted in the editor Output panel.
// On Windows, this requires Windows 10 or later to work in the terminal.
print_line_rich("[b]Bold[/b], [color=red]Red text[/color]")
// Prints a formatted error or warning message with a trace.
ERR_PRINT("Message");
WARN_PRINT("Message");
// Prints an error or warning message only once per session.
// This can be used to avoid spamming the console output.
ERR_PRINT_ONCE("Message");
WARN_PRINT_ONCE("Message");
If you need to add placeholders in your messages, use format strings as described below.
Format a string¶
The vformat()
function returns a formatted String. It behaves
in a way similar to C's 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();
In most cases, try to use vformat()
instead of string concatenation as it
makes for more readable code.
Convert an integer or float to a string¶
This is not needed when printing numbers using print_line()
, but you may
still need to perform manual conversion for some other use cases.
// Stores the string "42" using integer-to-string conversion.
String int_to_string = itos(42);
// Stores the string "123.45" using real-to-string conversion.
String real_to_string = rtos(123.45);
Internationalize a string¶
There are two types of internationalization in Godot's codebase:
TTR()
: Editor ("tools") translations will only be processed in the editor. If a user uses the same text in one of their projects, it won't be translated if they provide a translation for it. When contributing to the engine, this is generally the macro you should use for localizable strings.RTR()
: Run-time translations will be automatically localized in projects if they provide a translation for the given string. This kind of translation shouldn't be used in editor-only code.
// 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?");
To insert placeholders in localizable strings, wrap the localization macro in a
vformat()
call as follows:
String file_path = "example.txt";
vformat(TTR("Couldn't open \"%s\" for reading."), file_path);
Note
When using vformat()
and a translation macro together, always wrap the
translation macro in vformat()
, not the other way around. Otherwise, the
string will never match the translation as it will have the placeholder
already replaced when it's passed to TranslationServer.
Clamp a value¶
Godot provides macros for clamping a value with a lower bound (MAX
), an
upper bound (MIN
) or both (CLAMP
):
int a = 3;
int b = 5;
MAX(b, 6); // 6
MIN(2, a); // 2
CLAMP(a, 10, 30); // 10
This works with any type that can be compared to other values (like int
and
float
).
Microbenchmarking¶
If you want to benchmark a piece of code but don't know how to use a profiler, use this snippet:
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));
This will print the time spent between the begin
declaration and the end
declaration.
Note
You may have to #include "core/os/os.h"
if it's not present already.
When opening a pull request, make sure to remove this snippet as well as the include if it wasn't there previously.
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");
If a default value has been specified elsewhere, don't specify it again to avoid repetition:
// Returns the value of the project setting.
GLOBAL_GET("section/subsection/value");
// Returns the value of the editor setting.
EDITOR_GET("section/subsection/value");
It's recommended to use GLOBAL_DEF
/EDITOR_DEF
only once per setting and
use