bspviz/README.md

BSPViz

BSPViz ist ein kompaktes Go-Tool zum Analysieren von Doom-WAD-Dateien. Es lädt Maps, inspiziert Geometriedaten und baut daraus BSP-Bäume samt Statistiken oder Visualisierungen. Das Projekt entstand im Rahmen einer Seminararbeit und dient als Baukasten, um verschiedene BSP-Build-Heuristiken auszuprobieren.

Features

• Lädt klassische Doom-WADs und listet die enthaltenen Lumps
• Extrahiert einzelne Lumps als Dateien zum Debuggen
• Führt Geometrie-Diagnosen (Segment-Splits, Bounding Boxes) durch
• Baut BSP-Bäume mit konfigurierbaren Parametern und misst resultierende Metriken
• Exportiert BSP-Strukturen als DOT, optional weiterverarbeitbar zu PNG

Voraussetzungen

• Go >= 1.25 (siehe go.mod)
• Graphviz (nur nötig, wenn DOT-Dateien gerendert werden sollen)
• Eine Doom-kompatible WAD-Datei als Eingabe

Graphviz installieren

• Linux (Debian/Ubuntu): sudo apt install graphviz
• macOS (Homebrew): brew install graphviz
• Windows (Chocolatey): choco install graphviz

Alternativ stehen aktuelle Pakete und Installationshinweise auch auf der offiziellen Seite: https://graphviz.org/download/

Installation

git clone https://git.protron.dev/Seminar/bspviz.git
cd bspviz
go build ./...

Alternativ lässt sich das Tool ohne vorherigen Build direkt ausführen:

go run ./main.go -wad MYMAP.wad -map MAP01 -info

Verwendung

Wichtige Flags (vollständige Übersicht mit -h):

• -wad <pfad> (Pflicht): Pfad zur WAD-Datei.
• -map <name>: Map-Marker wie MAP01, E1M1 oder benutzerdefinierte Namen.
• -list: WAD-Verzeichnis anzeigen und beenden.
• -info: Basisstatistiken zu Vertices und Linedefs ausgeben.
• -extract <L1,L2>: Angegebene Lumps (z. B. VERTEXES,LINEDEFS) nach -out speichern.
• -geomtest: Segment- und Split-Diagnose für die gewählte Map ausgeben.
• -buildbsp: BSP-Baum erzeugen; Parameter wie -alpha, -beta, -leafmax, -maxdepth, -cands und -seed steuern das Verhalten.
• -dot <datei.dot>: Gebauten BSP als DOT exportieren (setzt -buildbsp voraus; benötigt ein installiertes Graphviz für die weitere Verarbeitung).

Beispiel: BSP bauen und als PNG visualisieren (Graphviz vorausgesetzt):

go run ./main.go -wad MYMAP.wad -map MAP01 -buildbsp -dot tree.dot
dot -Tpng tree.dot -o tree.png

Entwicklung

• Code formatieren: gofmt -w .
• Tests ausführen: go test ./... (Top-Level-Paket bspviz enthält bewusst keine eigenen Tests; der Aufruf über ./... zieht die Test-Suites der internal/*-Pakete automatisch nach.)
• Abhängig vom Fokus können Teilbereiche separat geprüft werden, z. B. go test ./internal/geom oder go test ./internal/bsp.
• Die vorhandenen Tests decken u. a. Geometrie-Primitive, BSP-Build-Heuristiken, Map-/WAD-Parsing sowie DOT-/PNG-Export ab.
• Temporäre Artefakte (DOT/PNG) sind über .gitignore bereits ausgeschlossen.