Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Macros et méthodes courantes du moteur

La base de code C++ de Godot utilise des dizaines de méthodes et de macros personnalisées qui sont utilisées dans presque tous les fichiers. Cette page est destinée aux contributeurs débutants, mais elle peut également être utile à ceux qui écrivent des modules C++ personnalisés.

Imprimer du texte

// 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 vous devez ajouter des espaces réservés dans vos messages, utilisez des chaînes de caractère de format comme décrit ci-dessous.

Formater une chaîne de caractères(string)

La fonction vformat() renvoie une chaîne formatée String. Elle se comporte d'une manière similaire à la fonction sprintf() du 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();

Dans la plupart des cas, essayez d'utiliser vformat() au lieu de la concaténation de chaînes de caractères car cela rend le code plus lisible.

Convertir un entier ou un flottant en une chaîne de caractère

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

Internationaliser une chaîne de caractère(string)

Il y a deux types d'internationalisation dans la base de code de Godot :

TTR() : Les traductions de l'éditeur ("tools") ne seront traitées que dans l'éditeur. Si un utilisateur utilise le même texte dans un de ses projets, il ne sera pas traduit s'il en fournit une traduction. Lorsque vous contribuez au moteur, c'est généralement la macro que vous devez utiliser pour les chaînes localisables.
RTR(): Runtime 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?");

Pour insérer espaces réservés dans des chaînes localisables, il faut envelopper la macro de localisation dans un appel vformat() comme suit :

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

Note

Lorsque vous utilisez vformat() et une macro de traduction ensemble, enveloppez toujours la macro de traduction dans vformat(), et non l'inverse. Sinon, la chaîne de caractère ne correspondra jamais à la traduction car l'emplacement réservé sera déjà remplacé lorsqu'elle sera transmise au TranslationServer.

Borner une valeur

Godot fournit des macros pour fixer une valeur avec une limite inférieure (MAX), une limite supérieure (MIN) ou les deux (CLAMP) :

int a = 3;
int b = 5;

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

Cela fonctionne avec tout type qui peut être comparé à d'autres valeurs (comme int et float).

Microbenchmarking

Si vous voulez benchmark un morceau de code mais ne savez pas comment utiliser un profileur, utilisez cet extrait :

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

Ceci imprimera le temps passé entre la déclaration begin et la déclaration end.

Note

Vous devrez peut-être inclure #include "core/os/os.h" s'il n'est pas déjà présent.

Lorsque vous ouvrez une pull request, veillez à supprimer cet extrait(snippet) ainsi que l'include si il n'était pas là auparavant.

Obtenir les paramètres du projet/éditeur

Quatre macros sont disponibles pour cela :

// 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 une valeur par défaut a été spécifiée ailleurs, ne la spécifiez pas à nouveau pour éviter les répétitions :

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

Il est recommandé d'utiliser GLOBAL_DEF/EDITOR_DEF une seule fois par paramètre et d'utiliser GLOBAL_GET/EDITOR_GET dans tous les autres endroits où il est référencé.

Macros d'erreur

Godot propose de nombreuses macros d'erreur pour rendre la notification des erreurs plus pratique.

Avertissement

Les conditions dans les macros d'erreur fonctionnent à la manière opposée de la fonction intégrée assert() de GDScript. Une erreur est atteinte si la condition à l'intérieur est évaluée comme étant true et non false.

Note

Seules les variants avec des messages personnalisés sont documentés ici, car ils doivent toujours être utilisés dans les nouvelles contributions. Assurez-vous que le message personnalisé fourni contient suffisamment d'informations pour que les personnes puissent diagnostiquer le problème, même si elles ne connaissent pas le C++. Si une méthode a reçu des arguments invalides, vous pouvez imprimer la valeur invalide en question pour faciliter le débogage.

Pour la vérification interne des erreurs, lorsqu'il n'est pas nécessaire d'afficher un message lisible par l'humain, supprimez _MSG à la fin du nom de la macro et ne fournissez pas d'argument pour le message.

De plus, essayez toujours de renvoyer des données traitables afin que le moteur puisse continuer à bien fonctionner.

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

Voir aussi

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

Certaines fonctions renvoient un code d'erreur (matérialisé par un type de retour Error). Cette valeur peut être renvoyée directement depuis une macro d'erreur. Voir la liste des codes d'erreur disponibles dans core/error/error_list.h.