Compile-Log lesen: VBSP, VVIS und VRAD in Hammer verstehen

Q: Wo finde ich das Compile-Log, wenn das Fenster schon geschlossen ist?

Die Compile-Werkzeuge schreiben das Log als .log neben deine VMF. Du kannst die Datei mit jedem Texteditor öffnen. Die Werkzeuge von GMod hängen jeden neuen Compile am Ende der Datei an.

Compile-Log in Hammer lesen: Aufbau aus VBSP, VVIS und VRAD, die wichtigsten Meldungen und wie du die erste echte Fehlerursache findest.

Veröffentlicht am 7. Oktober 20266 Min. Lesezeit

Ein Compile-Log liest du von oben nach unten und suchst die erste Meldung, die einen Fehler anzeigt. Das Log besteht aus drei Abschnitten, je einem für VBSP, VVIS und VRAD, und die meisten späteren Meldungen sind nur Folgen des ersten Problems. Wenn du die drei Abschnitte auseinanderhalten kannst und eine Handvoll typischer Meldungen kennst, findest du die Ursache meist in wenigen Minuten.

Wo das Log steht und wie es aufgebaut ist

Hammer zeigt das Log während des Kompilierens im Compile-Fenster an, und die Compile-Werkzeuge schreiben es zusätzlich als <mapname>.log in denselben Ordner wie deine VMF. Die Werkzeuge von GMod ersetzen diese Datei nicht, sondern hängen an sie an, der neueste Compile steht also am Ende. Lies in der Datei ab der Stelle, an der der letzte Compile beginnt.

Im Compile-Fenster des mitgelieferten Hammer beginnt jedes der drei Werkzeuge mit dem folgenden Block; Hammer++ schreibt stattdessen eine Zeile, die mit Running command: beginnt. In der .log-Datei fehlt dieser Kopf, dort erkennst du die Abschnitte an den typischen Zeilen aus der Tabelle:

** Executing...
** Command: "...\bin\vbsp.exe"
** Parameters: -game "...\garrysmod" "...\rp_beispiel"

Abschnitt	Aufgabe	Typische Zeilen bei Erfolg
VBSP	Baut aus der VMF die Geometrie, die Entities und die Portale	`ProcessBlock_Thread`, `Building Faces`, `WriteBSP`
VVIS	Berechnet, welche Bereiche von wo aus sichtbar sind	`BasePortalVis`, `PortalFlow`, `Average clusters visible`
VRAD	Berechnet Lightmaps und die Beleuchtung von Props	`BuildFacelights`, `GatherLight`, `FinalLightFace`

Was die drei Werkzeuge im Detail tun, steht im Artikel VBSP, VVIS und VRAD erklärt. Für das Lesen des Logs reicht eine Regel: Jedes Werkzeug arbeitet mit dem Ergebnis des vorherigen. Scheitert VBSP, haben VVIS und VRAD nichts Brauchbares in der Hand.

Fehler, Warnung oder harmlos

Nicht jede auffällige Zeile ist ein Problem. Es hilft, drei Stufen zu unterscheiden.

Fehler: Das Werkzeug bricht ab oder schreibt keine brauchbare Ausgabe. Bricht VBSP ab, entsteht keine neue BSP. Hammer meldet dann am Ende beim Kopieren oft The command failed, oder das Spiel startet mit der alten Datei und deine Änderungen fehlen.
Warnung: Das Werkzeug läuft weiter, das Ergebnis ist an einer Stelle unsauber. Ein Beispiel ist WARNING: Too many light styles on a face aus VRAD. Die Map funktioniert, an der genannten Stelle stimmt das Licht aber nicht.
Harmlos: Eine Zeile wie Memory leak: mempool blocks left in memory, bekannt aus Logs der Source-Compile-Werkzeuge, hat nichts mit einem Leak in deiner Map zu tun. Sie betrifft das Werkzeug selbst und kann ignoriert werden.

Die wichtigsten Meldungen und was sie bedeuten

Meldung	Abschnitt	Bedeutung	Was du tust
`** leaked **`	VBSP	Die Map ist nicht dicht. Eine Entity hat eine Verbindung zum leeren Raum außerhalb. Die Zeile danach nennt die Entity und ihre Koordinaten.	In Hammer über Map > Load Pointfile die rote Linie laden und ihr bis zum Loch folgen.
`areaportal brush doesn't touch two areas`	VBSP	Ein Areaportal trennt keine zwei Bereiche, weil sie an anderer Stelle noch verbunden sind. Die Zeile beginnt mit der Nummer des Brushes.	Die Linie über Map > Load Pointfile laden und die noch offene Verbindung zwischen den Bereichen schließen.
`material ... not found`	VBSP	Ein Material aus der VMF wurde in den Suchpfaden des Spiels nicht gefunden.	Pfad und Schreibweise prüfen und kontrollieren, ob der Content im richtigen Spielordner liegt.
`MAX_MAP_...` oder `Too many ...`	VBSP, VRAD	Ein Engine-Limit ist überschritten, etwa bei Brush-Seiten oder Planes.	Geometrie vereinfachen, Details in Models auslagern.
`LoadPortals: couldn't read`	VVIS	VBSP hat keine Portaldatei geschrieben. Das ist fast immer die Folge eines Leaks.	Nicht hier suchen, sondern den Leak im VBSP-Abschnitt beheben.
`The map overflows the max portal count`	VVIS	Die Map hat mehr Portale, als VVIS verarbeiten kann, und das Werkzeug bricht ab.	Kleinteile zu `func_detail` machen und die Welt-Geometrie vereinfachen.
`No vis information, direct lighting only`	VRAD	VRAD hat keine Sichtbarkeitsdaten bekommen und rechnet ohne indirektes Licht.	Ursache weiter oben suchen, meist ein Leak oder ein übersprungenes VVIS.

Zu den häufigsten Fällen gibt es eigene Anleitungen: Leak-Fehler beheben und Map-Limits der Source Engine.

Die Tabelle am Ende von VRAD

Ganz am Schluss gibt VRAD eine Übersicht aus, wie stark die einzelnen Datenbereiche der BSP gefüllt sind, zum Beispiel Brushes, Planes oder Entities. Steht neben einer Zeile VERY FULL!, bist du nahe an einem Limit. Diese Tabelle lohnt sich bei großen Maps nach jedem vollständigen Compile, weil du Engpässe siehst, bevor der Compile daran scheitert.

So gehst du vor: erste Fehlermeldung zuerst

Prüfe, ob alle drei Werkzeuge gelaufen sind. Suche im Compile-Fenster nach vbsp.exe, vvis.exe und vrad.exe, in der .log-Datei nach den typischen Zeilen aus der Tabelle oben.
Suche von oben nach den Begriffen leaked, Error, WARNING, failed und not found.
Behebe nur die erste echte Fehlermeldung. Alles, was danach kommt, kann eine Folge davon sein.
Kompiliere neu und lies das Log wieder von oben. Erst wenn der erste Fehler verschwunden ist, sind die übrigen Meldungen aussagekräftig.
Arbeite danach die Warnungen ab. Viele Meldungen nennen Koordinaten oder eine Brush-Nummer. In Hammer springst du über das Menü View direkt zu Koordinaten oder zu einer Brush-Nummer.
Wirf am Ende einen Blick auf die Tabelle von VRAD, um Limits im Auge zu behalten.

Log automatisch auswerten lassen

Lange Logs sind mühsam, wenn du die Meldungen noch nicht kennst. Der Map Scanner hat dafür einen Modus für Compile-Logs: Du fügst ein Hammer-, VBSP-, VVIS- oder VRAD-Log ein oder lädst es als .txt oder .log hoch. Das Ergebnis ist nach wahrscheinlichen Hauptursachen, weiteren Fehlern, Folgefehlern und Warnungen sortiert, jeweils mit Ursache und Lösungsschritten. Meldungen, die der Scanner noch nicht kennt, kannst du melden. Der Scanner ist als Beta gekennzeichnet und kostet nichts.

Wenn du eine einzelne Meldung nachschlagen willst, hilft die Fehlerdatenbank. Dort stehen geprüfte Fehlermeldungen von Hammer und den Compile-Werkzeugen mit Ursache und Lösung.

Häufige Fragen

Wo finde ich das Compile-Log, wenn das Fenster schon geschlossen ist?

Die Compile-Werkzeuge schreiben das Log als <mapname>.log neben deine VMF. Du kannst die Datei mit jedem Texteditor öffnen. Die Werkzeuge von GMod hängen jeden neuen Compile am Ende der Datei an.

Muss ich jede Warnung beheben?

Nein. Warnungen stoppen den Compile nicht, und einige haben keine sichtbare Auswirkung. Beheben solltest du Warnungen, die Koordinaten in spielbaren Bereichen nennen, weil dort meist Licht oder Sichtbarkeit sichtbar fehlerhaft sind.

Warum sehe ich meine Änderungen im Spiel nicht, obwohl der Compile durchlief?

Sehr wahrscheinlich ist VBSP abgebrochen und es wurde keine neue BSP geschrieben. Das Spiel lädt dann die ältere Datei. Suche im VBSP-Abschnitt nach der ersten Fehlermeldung.

Was bedeutet „Memory leak: mempool blocks left in memory“?

Die Zeile stammt aus den Source-Compile-Werkzeugen und beschreibt Arbeitsspeicher, den das Werkzeug beim Beenden nicht freigegeben hat. Mit einem Leak in der Map hat sie nichts zu tun, und du musst nichts unternehmen. In unseren Test-Compiles mit den aktuellen Werkzeugen von GMod kam sie nicht vor.