Up to date

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

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 ausgeben¶

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

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

Formatieren eines Strings¶

Die Funktion vformat () gibt einen formatierten String zurück. Sie verhält sich ähnlich wie sprintf() in 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();

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

Konvertiert eine Integer- oder eine Float-Zahl in einen String¶

Dies ist nicht notwendig, wenn man Zahlen mit print_line() ausgibt, aber für einige andere Anwendungsfälle kann es notwendig sein, eine manuelle Konvertierung durchzuführen.

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

Internationalisieren eines Strings¶

Es gibt zwei Arten der Internationalisierung in Godots Codebasis:

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

// 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 Strings 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, sollten Sie das Übersetzungsmakro immer in vformat() wrappen, nicht umgekehrt. Andernfalls wird der String niemals mit der Übersetzung übereinstimmen, da der Platzhalter bereits ersetzt ist, wenn er an TranslationServer übergeben wird.

Einen Wert begrenzen¶

Godot bietet Makros zum Begrenzen 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 man einen Profiler verwendet, benutzen Sie diesen Schnipsel:

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

Dies gibt die Zeit zwischen der begin und end-Deklaration aus.

Bemerkung

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

Stellen Sie beim Öffnen eines Pull-Requests sicher, dass Sie dieses Snippet sowie das Include entfernen, falls es vorher nicht vorhanden war.

Zugriff auf Projekt-/Editoreinstellungen¶

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 Default-Wert 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.

Fehlermakros¶

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 ausgelöst, 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

Siehe core/error/error_macros.h in der Codebasis von Godot für weitere Informationen über jedes Fehlermakro.

Einige Funktionen geben einen Fehlercode zurück (der sich durch einen Rückgabetyp von Error zeigt). Dieser Wert kann direkt von einem Fehlermakro zurückgegeben werden. Siehe die Liste der verfügbaren Fehlercodes in core/error/error_list.h.