Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Métodos y macros comunes del motor¶

El código base de Godot en C++ utiliza docenas de métodos y macros personalizados que se utilizan en casi todos los archivos. Esta página está dirigida a colaboradores principiantes, pero también puede ser útil para aquellos que escriben módulos C++ personalizados.

Imprimir texto¶

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

Si necesitas agregar marcadores de posición en tus mensajes, utiliza cadenas de formato como se describe a continuación.

Formateando una cadena¶

La función vformat() devuelve una cadena de texto formateada de la clase String. Se comporta de manera similar a la función sprintf() de C:

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

En la mayoría de los casos, intenta utilizar vformat() en lugar de la concatenación de cadenas, ya que hace que el código sea más legible.

Convertir un intero o flotante 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);

Internacionalizando una cadena¶

Existen dos tipos de internacionalización en el código de Godot:

TTR(): Las traducciones del Editor ("tools") solo se procesarán en el editor. Si un usuario utiliza el mismo texto en uno de sus proyectos, no se traducirá si proporcionan una traducción para él. Cuando contribuyas al motor, esta es generalmente la macro que debes usar para las cadenas localizables.
RTR(): Las traducciones en tiempo de ejecución ("Run-time translations") se localizarán automáticamente en proyectos si proporcionan una traducción para la cadena dada. Este tipo de traducción no debe usarse en código exclusivo del editor.

// 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?");

Para insertar marcadores en cadenas localizables, envuelve la macro de localización en una llamada a vformat() de la siguiente manera:

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

Nota

Cuando uses vformat() y una macro de traducción juntas, siempre envuelve la macro de traducción en vformat(), no al revés. De lo contrario, la cadena nunca coincidirá con la traducción, ya que el marcador ya estará reemplazado cuando se pase a TranslationServer.

Restringir un valor¶

Godot proporciona macros para limitar un valor con un límite inferior (MAX), un límite superior (MIN) o ambos (CLAMP):

int a = 3;
int b = 5;

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

Esto funciona con cualquier tipo que se pueda comparar con otros valores (como int y float).

Microbenchmarking¶

Si deseas evaluar el rendimiento de un fragmento de código pero no sabes cómo usar un perfilador, puedes usar este fragmento de código:

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

// Your code here...

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

Esto imprimirá el tiempo transcurrido entre la declaración begin y la declaración end.

Nota

Es posible que debas incluir #include "core/os/os.h" si aún no está presente.

Cuando abras una solicitud de extracción, asegúrate de eliminar este fragmento de código y también la inclusión del archivo si no estaba presente anteriormente.

Obtener configuración del proyecto/editor¶

Hay cuatro macros disponibles para esto:

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

Si ya se ha especificado un valor predeterminado en otro lugar, no lo especifiques nuevamente para evitar repeticiones:

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

Se recomienda usar GLOBAL_DEF / EDITOR_DEF solo una vez por ajuste y usar GLOBAL_GET / EDITOR_GET en todos los demás lugares donde se hace referencia a él.

Macros de error¶

Godot cuenta con muchos macros de error para facilitar la notificación de errores de manera más conveniente.

Advertencia

Las condiciones en los macros de error funcionan de manera opuesta a la función integrada assert() de GDScript. Se alcanzará un error si la condición evaluada dentro es true, no false.

Nota

Aquí solo se documentan las variantes con mensajes personalizados, ya que siempre se deben usar en nuevas contribuciones. Asegúrate de que el mensaje personalizado proporcionado incluya suficiente información para que las personas puedan diagnosticar el problema, incluso si no saben C++. En caso de que se hayan pasado argumentos no válidos a un método, puedes imprimir el valor no válido en cuestión para facilitar la depuración.

Para la comprobación interna de errores donde no es necesario mostrar un mensaje legible para los humanos, elimina _MSG al final del nombre de la macro y no proporciones un argumento de mensaje.

Además, siempre intenta devolver datos procesables para que el motor pueda seguir funcionando correctamente.

// 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.");

Ver también

See core/error/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/error_list.h.