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.

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

Cela est surtout utile pour l'impression directe des nombres.

// Prints "42" using integer-to-string conversion.
print_line(itos(42));

// Prints "123.45" using real-to-string conversion.
print_line(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() : Les traductions à l'exécution seront automatiquement localisées dans les projets s'ils fournissent une traduction pour la chaîne de caractère donnée. Ce type de traduction ne doit pas être utilisé dans du code unique à l'éditeur.
// 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 = 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));

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

Voir core/error_macros.h dans la base de code de Godot pour plus d'informations sur chaque macro d'erreur.

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