Log-Dateien in der Spieleentwicklung – Ereignisse nachvollziehen

Eine Log-Datei hält fest, was in deinem Spiel oder Entwicklungswerkzeug passiert. Bei der Fehlersuche kann diese Ereignisfolge entscheidend sein. Statt nur festzustellen, dass eine Funktion nicht richtig arbeitet, kannst du untersuchen, welche Schritte zuvor ausgeführt wurden und an welcher Stelle der Ablauf vom erwarteten Verhalten abweicht.

Was ist ein Log?

Ein Log ist eine protokollierte Folge von Meldungen. Dein Spiel kann beispielsweise festhalten, dass ein Level geladen, eine Datei geöffnet, ein Gegner erzeugt oder eine bestimmte Funktion gestartet wurde. Auch Warnungen und Fehlermeldungen lassen sich darin speichern.
Die einzelnen Meldungen heißen Log-Einträge. Häufig enthalten sie einen Zeitstempel, eine Kennzeichnung der Meldungsart und einen beschreibenden Text. Ein Eintrag könnte beispielsweise so aussehen:

[14:32:10] INFO  Level "Wald" geladen
[14:32:12] INFO  Spielerposition gesetzt
[14:32:15] INFO  Türinteraktion gestartet
[14:32:15] ERROR Schlüsselreferenz fehlt

Dieses Beispiel zeigt eine mögliche Struktur. Welche Angaben tatsächlich erscheinen, hängt vom Spiel, der Engine und der jeweiligen Konfiguration ab.

Was bedeutet Logging?

Logging bezeichnet den Vorgang, bei dem ein Programm solche Meldungen erzeugt und protokolliert. Du kannst legst selbst fest, an welchen Stellen deines Programmcodes Informationen ausgegeben werden sollen.
Bei der Entwicklung eines Inventars protokollierst du beispielsweise, wann der Spieler einen Gegenstand aufnimmt, entfernt oder verwendet. Treten später Fehler auf, zeigen die Einträge, welche Aktionen tatsächlich stattfanden.
Nicht jede einzelne Programmoperation muss protokolliert werden. Zu viele Meldungen erschweren die Übersicht erschweren und beanspruchen zusätzliche Ressourcen. Entscheidend ist, dass die Einträge für die Untersuchung eines Problems aussagekräftig sind.

Warum helfen Logs beim Debugging?

Beim Debugging versuchst du, die Ursache eines Fehlers systematisch einzugrenzen. Ein Log kann dir dabei zeigen, welche Ereignisse vor dem sichtbaren Problem stattgefunden haben.
Angenommen, dein Spiel stürzt beim Öffnen einer Tür ab. Ohne weitere Informationen weißt du zunächst nur, dass der Absturz während dieser Interaktion auftrat. Die Datei könnte dagegen zeigen, dass die Türfunktion gestartet, anschließend das Inventar geprüft und danach ein ungültiger Schlüsselwert festgestellt wurde.
Damit entsteht ein konkreter Untersuchungsansatz. Die letzte Meldung vor dem Absturz muss allerdings nicht zwangsläufig die Ursache enthalten. Ein Fehler kann bereits früher entstanden sein und sich erst später bemerkbar machen.

Vom Symptom zur Ereignisfolge

Ein sichtbarer Spielfehler beschreibt zunächst nur das Ergebnis. Ein Gegner bleibt stehen, ein Questziel aktualisiert sich nicht oder ein Gegenstand verschwindet aus dem Inventar. Das Log kann zusätzliche Informationen über den vorherigen Ablauf liefern.
Bei einem Questfehler könnten beispielsweise folgende Ereignisse protokolliert sein:

[15:08:21] INFO  Gegner "Wächter" besiegt
[15:08:21] INFO  Questziel "Wächter besiegen" geprüft
[15:08:21] WARNING Queststatus konnte nicht aktualisiert werden

Die Meldungen zeigen, dass der Gegner besiegt und die Questprüfung gestartet wurde. Weshalb die Aktualisierung scheiterte, musst du anschließend untersuchen. Die Datei grenzt den Ablauf ein, ersetzt aber nicht die Ursachenanalyse.

Unterschiedliche Arten von Log-Meldungen

Viele Systeme unterscheiden Meldungen nach ihrer Bedeutung. Häufig verwendete Kategorien sind Debug, Info, Warning und Error.
Debug-Meldungen enthalten zusätzliche Informationen für die Entwicklung und Fehlersuche. Info-Meldungen dokumentieren normale Programmabläufe. Warning weist auf eine ungewöhnliche Situation hin, bei der das Programm möglicherweise weiterarbeiten kann. Error kennzeichnet einen Fehler, der eine Funktion beeinträchtigt oder verhindert.
Die genaue Bedeutung und Benennung dieser Kategorien kann je nach Engine oder System variieren. Eine Warning führt beispielsweise nicht automatisch zu einem Absturz, während ein Error nicht zwangsläufig das gesamte Spiel beendet.

Was ist ein Zeitstempel?

Ein Zeitstempel gibt an, wann ein Eintrag entstanden ist. Dadurch kannst du die Reihenfolge von Ereignissen nachvollziehen und verschiedene Meldungen miteinander vergleichen.
Bei mehreren gleichzeitig arbeitenden Systemen ist das besonders hilfreich. Während dein Spiel beispielsweise einen Level lädt, können parallel Audiodateien vorbereitet, Netzwerkdaten verarbeitet oder andere Aufgaben ausgeführt werden.
Zeitstempel allein erklären allerdings nicht immer die genaue Reihenfolge aller internen Vorgänge. Bei parallelen Abläufen können zusätzliche Informationen notwendig sein, um Zusammenhänge eindeutig zuzuordnen.

Logs und Stack Traces ergänzen sich

Ein Stack Trace zeigt, welche Funktionen zum Zeitpunkt eines Fehlers aufgerufen wurden. Ein Log dokumentiert dagegen Ereignisse, die dein Programm zuvor oder währenddessen protokolliert hat.
Beide Informationen erfüllen damit unterschiedliche Aufgaben. Der Stack Trace kann dich zu einer betroffenen Programmstelle führen. Die Datei zeigt möglicherweise, welche Aktionen und Zustände zu diesem Zeitpunkt vorlagen.
Bei einem Absturz während einer Türinteraktion könnte der Stack Trace beispielsweise auf eine Inventarfunktion verweisen. Das Log ergänzt dazu, welcher Gegenstand verwendet wurde und welche Prüfung unmittelbar vorher stattfand.
Zusammen entsteht ein genaueres Bild des Ablaufs. Eine eindeutige Ursache ergibt sich daraus jedoch nicht in jedem Fall.

Logs in Unity

In Unity kannst du Meldungen über die Debug-Klasse ausgeben. Dazu gehören beispielsweise Debug.Log, Debug.LogWarning und Debug.LogError.
Ein einfaches Beispiel lautet:

Debug.Log("Türinteraktion gestartet");

Wird diese Zeile ausgeführt, erscheint die Meldung in der Unity Console. Auf diese Weise kannst du überprüfen, ob eine bestimmte Stelle deines Programmcodes erreicht wurde.
Für eine Warnung lässt sich beispielsweise schreiben:

Debug.LogWarning("Kein gültiger Schlüssel gefunden");

Solche Meldungen eignen sich unter anderem dazu, Zustände und Abläufe während der Entwicklung sichtbar zu machen. In veröffentlichten Spielen solltest du allerdings bewusst entscheiden, welche Informationen weiterhin protokolliert werden.

Logs in Unreal Engine

Auch die Unreal Engine besitzt eigene Logging-Funktionen. In C++ kannst du beispielsweise mit UE_LOG Meldungen ausgeben. Die Engine verwendet dafür Kategorien und unterschiedliche Meldungsstufen.
Ein vereinfachtes Beispiel:

UE_LOG(LogTemp, Warning, TEXT("Kein gültiger Schlüssel gefunden"));

Die Meldung erscheint in der entsprechenden Ausgabe der Engine. Für größere Projekte lassen sich eigene Kategorien verwenden, um Informationen aus unterschiedlichen Systemen besser voneinander zu trennen.
Auch hier gilt: Die Ausgabe zeigt nur die Informationen, die tatsächlich protokolliert wurden. Sie zeichnet nicht automatisch jeden internen Programmschritt auf.

Warum aussagekräftige Meldungen wichtig sind

Eine Meldung wie „Fehler aufgetreten“ liefert nur wenig Kontext. Aussagekräftiger ist eine Beschreibung, die den betroffenen Vorgang und den festgestellten Zustand nennt.
Statt lediglich „Inventarfehler“ auszugeben, könntest du beispielsweise protokollieren, dass bei einer Türinteraktion kein gültiger Schlüssel gefunden wurde.
Dabei solltest du darauf achten, keine unnötigen personenbezogenen oder sicherheitsrelevanten Informationen in Logs zu speichern. Passwörter, Zugangstoken oder andere vertrauliche Daten gehören nicht in gewöhnliche Fehlerprotokolle.

Logs aus verschiedenen Spielversionen

Während der Entwicklung entstehen unterschiedliche Builds. Ein Build ist eine aus dem Projekt erzeugte, ausführbare Version des Spiels.
Bei der Untersuchung eines Fehlerberichts ist deshalb wichtig, zu welcher Version die Daten gehören. Ein Problem aus einem älteren Build kann in einer neueren Version bereits verändert oder behoben sein.
Die Zuordnung zur Spielversion erleichtert außerdem den Vergleich mit einer Versionsverwaltung. Dadurch kannst du untersuchen, welche Änderungen zwischen einem funktionierenden und einem fehlerhaften Entwicklungsstand vorgenommen wurden.

Logs aus Testversionen und veröffentlichten Spielen

Während deiner eigenen Entwicklung kannst du Meldungen häufig direkt in der Engine oder einer Entwicklungsumgebung betrachten. Bei externen Testern und veröffentlichten Spielen ist das nicht immer möglich.
Je nach Plattform und Konfiguration können Dateien lokal gespeichert oder über ein Fehlererfassungssystem übermittelt werden. Dadurch lassen sich auch Probleme untersuchen, die nicht auf deinem eigenen Rechner auftreten.
Welche Informationen verfügbar sind, hängt von der jeweiligen Integration ab. Nicht jede Plattform erlaubt dieselben Möglichkeiten, und nicht jeder Fehlerbericht enthält automatisch vollständige Logs.

Grenzen von Log-Dateien

Ein Log ist keine vollständige Aufzeichnung sämtlicher Vorgänge im Spiel. Es enthält nur die Ereignisse, die das Programm oder die verwendeten Werkzeuge tatsächlich protokollieren.
Fehlt eine wichtige Meldung, kann der entscheidende Zusammenhang unsichtbar bleiben. Umgekehrt können sehr umfangreiche Logs die Untersuchung erschweren, wenn relevante Einträge zwischen zahlreichen anderen Meldungen stehen.
Auch die Reihenfolge der Einträge muss sorgfältig interpretiert werden. Besonders bei parallelen Prozessen lässt sich aus zeitlich benachbarten Meldungen nicht automatisch ein ursächlicher Zusammenhang ableiten.

Logs als Teil eines nachvollziehbaren Debugging-Prozesses

Bei der Fehlersuche kannst du zunächst versuchen, das Problem zu reproduzieren. Anschließend untersuchst du die vorhandenen Einträge und vergleichst sie mit dem erwarteten Programmablauf.
Ergeben sich daraus Hinweise auf eine bestimmte Funktion, überprüfst du diese gezielt. Bei Bedarf ergänzt du weitere Meldungen, um zusätzliche Informationen über den Programmzustand zu erhalten.
Nach einer Korrektur testest du erneut, ob der Fehler unter denselben Bedingungen noch auftritt. Logs können dabei helfen, den veränderten Ablauf nachzuvollziehen.

Zentrale Fehlererfassung mit Sentry

Für die Sammlung und Untersuchung technischer Fehler existieren verschiedene Werkzeuge. Sentry ist eine Plattform, die Fehlerereignisse und zusätzliche Informationen aus Anwendungen erfassen kann. Abhängig von SDK und Konfiguration lassen sich auch Daten in die Fehleranalyse einbeziehen.
Damit können Informationen aus unterschiedlichen Testumgebungen oder Spielversionen an einer zentralen Stelle zusammenlaufen. Welche Daten tatsächlich erfasst werden, hängt von der jeweiligen Integration und den gewählten Einstellungen ab.
Weitere Informationen zu den Funktionen findest du auf der offiziellen Website von Sentry.Ein Log hält fest, was in deinem Spiel oder Entwicklungswerkzeug passiert. Bei der Fehlersuche kann diese Ereignisfolge entscheidend sein.Warum helfen Logs beim Debugging?

Weitere Artikel auf Games und Lyrik

Wenn du dich neben der technischen Spieleentwicklung auch für klassische Adventures interessierst, findest du auf Games und Lyrik weitere Beiträge. In Runaway 3: A Twist of Fate begleitest du Brian und Gina durch ein Point-and-Click-Adventure mit Rätseln, ungewöhnlichen Situationen und einer Geschichte voller Wendungen.