Common engine methods and macros

If you need to add placeholders in your messages, use format strings as described below.

Format a string

The 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 *`.
// 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.

This is mainly useful when printing numbers directly.

// 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(): 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.

To insert placeholders in localizable strings, wrap the localization macro in a vformat() call as follows:


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

Note

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:

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.

There are four macros available for this:

// Returns the specified project setting's value,
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.

Error macros

Godot features many error macros to make error reporting more convenient.

Warning

Conditions in error macros work in the opposite way of GDScript’s built-in assert() function. An error is reached if the condition inside evaluates to true, not false.

Note

Only variants with custom messages are documented here, as these should always be used in new contributions. Make sure the custom message provided includes enough information for people to diagnose the issue, even if they don’t know C++. In case a method was passed invalid arguments, you can print the invalid value in question to ease debugging.

For internal error checking where displaying a human-readable message isn’t necessary, remove _MSG at the end of the macro name and don’t supply a message argument.

Also, always try to return processable data so the engine can keep running well.