Gängige Engine-Methoden und Makros¶

Die C++ Codebasis von Godot verwendet Dutzende von benutzerdefinierten Methoden und Makros, die in fast jeder Datei verwendet werden. Diese Seite richtet sich an Anfänger, kann aber auch für diejenigen nützlich sein, die benutzerdefinierte C++ Module schreiben.

Text drucken¶

// Prints a message to standard output.
print_line("Message");

// Prints a message to standard output, but only when the engine
// is started with the `--verbose` command line argument.
print_verbose("Message");

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

Wenn Sie Ihren Nachrichten Platzhalter hinzufügen müssen, verwenden Sie Formatzeichenfolgen wie unten beschrieben.

Formatieren einer Zeichenfolge¶

Die Funktion vformat () gibt ein formatiertes String zurück. Es verhält sich ähnlich wie Cs 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();

Versuchen Sie in den meisten Fällen, vformat() anstelle der Zeichenfolgenverkettung zu verwenden, da dies zu besser lesbarem Code führt.

Konvertieren Sie eine Ganzzahl oder eine Fliesskommazahl in eine Zeichenfolge¶

Dies ist vor allem bei der direkten Ausgabe von Zahlen hilfreich.

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

// Prints "123.45" using real-to-string conversion.
print_line(rtos(123.45));

Internationalisieren einer Zeichenfolge¶

Es gibt zwei Arten der Internationalisierung in Godots Codebasis:

TTR(): Editor-Übersetzungen ("tools") werden nur im Editor verarbeitet. Wenn ein Benutzer denselben Text in einem seiner Projekte verwendet, wird er nicht übersetzt, wenn er eine Übersetzung dafür bereitstellt. Wenn Sie zur Engine beitragen, ist dies im Allgemeinen das Makro, das Sie für lokalisierbare Zeichenfolgen verwenden sollten.
RTR(): Laufzeitübersetzungen werden in Projekten automatisch lokalisiert, wenn sie eine Übersetzung für die angegebene Zeichenfolge bereitstellen. Diese Art der Übersetzung sollte nicht nur im Editor-Code verwendet werden.

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

Um Platzhalter in lokalisierbare Zeichenfolgen einzufügen, schließen Sie das Lokalisierungsmakro wie folgt in einen vformat() -Aufruf ein:

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

Bemerkung

Wenn Sie vformat() und ein Übersetzungsmakro zusammen verwenden, wickeln Sie das Übersetzungsmakro immer in vformat() ein, nicht umgekehrt. Andernfalls stimmt die Zeichenfolge nie mit der Übersetzung überein, da der Platzhalter bereits ersetzt wurde, wenn er an den TranslationServer übergeben wird.

Einen Wert festlegen¶

Godot bietet Makros zum Festklemmen eines Werts mit einer Untergrenze (MAX), einer Obergrenze (MIN) oder beiden (CLAMP):

int a = 3;
int b = 5;

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

Dies funktioniert mit jedem Typ, der mit anderen Werten verglichen werden kann (wie int und float).

Mikrobenchmarking¶

Wenn Sie einen Code benchmarken möchten, aber nicht wissen wie ein Profiler verwendet wird, verwenden Sie diesen Ausschnitt:

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

Dies gibt die Zeit aus, die zwischen der Deklaration begin und der Deklaration end verbracht wurde.

Bemerkung

Möglicherweise müssen Sie #include "core/os/os.h" nutzen, wenn dies nicht bereits vorhanden ist.

Stellen Sie beim Öffnen einer Pull-Anforderung sicher, dass Sie diesen Abschnitt sowie das Include entfernen, wenn es zuvor nicht vorhanden war.

Projekt-/Editoreinstellungen erhalten¶

Hierfür stehen vier Makros zur Verfügung:

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

Wenn an anderer Stelle ein Standardwert angegeben wurde, geben Sie ihn nicht erneut an, um Wiederholungen zu vermeiden:

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

Es wird empfohlen, GLOBAL_DEF/EDITOR_DEF nur einmal pro Einstellung zu verwenden und GLOBAL_GET/EDITOR_GET an allen anderen Stellen zu verwenden, auf die verwiesen wird.

Fehler Makros¶

Godot bietet viele Fehlermakros, um die Fehlerberichterstattung komfortabler zu gestalten.

Warnung

Bedingungen in Fehlermakros funktionieren in entgegengesetzter Weise wie die in GDScript integrierte Funktion assert(). Ein Fehler wird erreicht, wenn die Bedingung darin wahr und nicht falsch ergibt.

Bemerkung

Hier werden nur Varianten mit benutzerdefinierten Nachrichten dokumentiert, da diese immer in neuen Beiträgen verwendet werden sollten. Stellen Sie sicher, dass die bereitgestellte benutzerdefinierte Nachricht genügend Informationen enthält, damit Benutzer das Problem diagnostizieren können, auch wenn sie C++ nicht kennen. Falls einer Methode ungültige Argumente übergeben wurden, können Sie den betreffenden ungültigen Wert anzeigen, um das Debuggen zu vereinfachen.

Entfernen Sie für interne Fehlerprüfungen, bei denen die Anzeige einer für Menschen lesbaren Nachricht nicht erforderlich ist, _MSG am Ende des Makronamens und geben Sie kein Nachrichtenargument an.

Versuchen Sie außerdem immer, verarbeitbare Daten zurückzugeben, damit die Engine weiterhin einwandfrei laufen kann.

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

Siehe auch

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