Custom Content in BSP packen: Texturen, Models, Sounds

Eigene Texturen, Models und Sounds packst du in die BSP, indem du sie nach dem letzten Compile mit einem Werkzeug wie bspzip, CompilePal oder VIDE in das Pakfile der Map schreibst. Die Engine lädt die Dateien dann direkt aus der Map, und Spieler brauchen dafür keinen zusätzlichen Download. Ohne Packen sehen sie pink-schwarze Karos statt Texturen und rote ERROR-Schriftzüge statt Models.

Warum du Inhalte packen solltest

Eine BSP enthält neben Geometrie und Licht einen eigenen Bereich für eingebettete Dateien, das Pakfile. Technisch ist das ein Archiv innerhalb der Map. Beim Laden behandelt die Engine dessen Inhalt so, als lägen die Dateien im Spielordner. Garry's Mod setzt dabei eine Grenze: Seit den Sicherheits-Patches vom Dezember 2023 prüft das Spiel eingebettete Dateien gegen eine Whitelist, und was durchfällt, wird nicht eingebunden. In der Konsole steht dann BSP embedded file failed whitelist check. Wie die BSP insgesamt aufgebaut ist, erklärt Was ist eine BSP-Datei?.

Die Alternative ist, Inhalte getrennt auszuliefern, etwa als Addon. Das funktioniert, hat aber mehr Fehlerquellen: Eine Datei fehlt, ein Addon ist nicht abonniert, ein Pfad stimmt nicht. Eine gepackte Map ist eine einzige Datei, die überall gleich aussieht.

Was in die BSP gehört

Leicht vergessen werden:

• die Materialien eines Models, die in einem anderen Ordner liegen als das Model selbst
• zusätzliche Texturen, auf die eine VMT verweist, etwa Normal Maps
• eigene Skybox-Texturen unter materials/skybox/
• map-spezifische Skripte wie Soundscapes und eigene Partikeldateien

Nicht in die BSP gehören Inhalte, die jeder Spieler mit dem Spiel ohnehin hat, außerdem unbenutzte Dateien und Quelldateien wie VMF, TGA oder PSD.

Die richtige Ordnerstruktur

Im Pakfile gelten dieselben Pfade wie im Spielordner garrysmod/:

materials/deinname/deinemap/wand_beton01.vmt
materials/deinname/deinemap/wand_beton01.vtf
models/deinname/deinemap/laterne.mdl
sound/deinname/deinemap/halle_ambient.wav

Drei Regeln ersparen dir die meisten Probleme:

1. Eigener Unterordner. Mit einem eindeutigen Ordnernamen überschreibst du keine Dateien anderer Addons und wirst selbst nicht überschrieben.
2. Kleinbuchstaben, keine Leerzeichen, keine Umlaute. Linux-Server unterscheiden Groß- und Kleinschreibung. Ein Pfad, der unter Windows funktioniert, kann dort scheitern.
3. Pfade in der VMT prüfen. Eine VMT verweist auf ihre VTF relativ zu materials/ und ohne Dateiendung. Verschiebst du Dateien, musst du die Verweise anpassen.

Werkzeuge im Vergleich

Mit bspzip übergibst du eine Textdatei mit allen Dateien:

bspzip -addlist deinemap.bsp dateiliste.txt deinemap_gepackt.bsp
bspzip -dir deinemap_gepackt.bsp

Die Liste besteht aus Zeilenpaaren: zuerst der Pfad innerhalb der Map, darunter der vollständige Pfad auf deiner Festplatte. Der zweite Befehl zeigt an, was im Pakfile liegt.

Automatische Werkzeuge erkennen, was die Map direkt verwendet. Inhalte, die erst zur Laufzeit angesprochen werden, etwa ein Sound, den nur ein Skript abspielt, können sie übersehen. Sieh dir die Liste deshalb immer an.

Packen in fünf Schritten

1. Final kompilieren. Packe erst, wenn die Map fertig ist. Den Ablauf beschreibt VBSP, VVIS und VRAD erklärt.
2. Inhalte ermitteln. Lass das Werkzeug die Map scannen oder erstelle die Liste von Hand.
3. Packen. Schreibe in eine Kopie der BSP, damit das Original erhalten bleibt.
4. Cubemaps bauen. Auch Cubemaps werden im Pakfile gespeichert. Baue sie in der gepackten Datei.
5. Testen. Siehe unten.

Wichtig: Jeder neue Compile erzeugt eine frische BSP ohne deine gepackten Inhalte. Nach jeder Änderung an der Map packst du also erneut.

Dateigröße und Kompression

Den größten Anteil an den gepackten Inhalten haben meist Texturen. Wähle Auflösungen, die zur Größe der Fläche passen, und speichere VTF-Dateien in einem komprimierten Format statt unkomprimiert. Entferne Inhalte, die du am Ende nicht verwendet hast, und kürze lange Sounds.

Beim Transport wird meist zusätzlich komprimiert: FastDL-Server liefern Maps üblicherweise als komprimierte Datei aus, und auch der Workshop komprimiert beim Hochladen. Die Größe auf der Festplatte ist also nicht die Download-Größe. Der Hilfetext des bspzip von GMod nennt außerdem -repack -compress, das die BSP selbst komprimiert. In unserem Test mit der aktuellen GMod-Version beendete sich der Befehl allerdings ohne jede Ausgabe und ließ die Datei unverändert, und die Valve Developer Community verweist stattdessen auf das bspzip aus Team Fortress 2. Wenn du eine Map komprimierst, dann als allerletzten Schritt, und teste gründlich, ob Spiel und Server sie einwandfrei laden.

Nach dem Packen prüfen

1. Benenne deine losen Inhaltsordner im Spielordner vorübergehend um oder teste auf einer zweiten Installation. Nur so siehst du, was wirklich aus der BSP kommt.
2. Lade die Map und sieh dir alle Bereiche an. Die Konsole meldet fehlende Materialien und Models.
3. Vergleiche die Ausgabe von bspzip -dir mit deiner Liste.
4. Lade die BSP in den Map Scanner. Er listet eingebettete Lua- und Asset-Dateien im Pakfile auf und prüft die Struktur der Datei.

Tauchen trotzdem Karos oder ERROR-Models auf, hilft Fehlende Texturen und Error-Models beheben.

Rechte: nur packen, was du weitergeben darfst

Wer Inhalte in eine BSP packt, verbreitet sie mit der Map weiter. Packe deshalb nur eigene Arbeiten und Inhalte, deren Lizenz die Weitergabe erlaubt. Willst du die Map verkaufen, muss die Lizenz auch die kommerzielle Nutzung abdecken. Dass ein Addon kostenlos im Workshop steht, ist keine Erlaubnis, und eine Namensnennung ersetzt sie nicht. Das Gleiche gilt für Inhalte, die aus anderen Spielen entnommen wurden. Die Grundlagen stehen in Urheberrecht bei GMod-Maps. Dieser Abschnitt ist keine Rechtsberatung.

Häufige Fragen

Muss ich nach jedem Compile neu packen?

Ja. VBSP schreibt bei jedem Durchlauf eine neue BSP, das Pakfile der alten Datei geht dabei verloren. Packe deshalb erst nach dem letzten Compile und baue danach die Cubemaps.

Warum sehe ich trotz Packen pink-schwarze Karos?

Meist stimmt ein Pfad nicht. Entweder liegt die Datei im Pakfile an anderer Stelle, als die Map erwartet, oder die VMT wurde gepackt, ihre VTF aber nicht. Bei Models fehlen oft die Materialien, weil sie in einem anderen Ordner liegen.

Kann man gepackte Inhalte wieder aus der BSP herausholen?

Ja. Das Pakfile ist ein gewöhnliches Archiv, und dieselben Werkzeuge, die packen, können auch entpacken. Packen ist eine Frage der Auslieferung und kein Schutz deiner Inhalte.

Wie groß darf eine gepackte Map werden?

Eine feste Obergrenze für die ganze Datei können wir für GMod nicht belegen. In der Praxis hängt es vom Verbreitungsweg ab. Je größer die Datei, desto länger warten Spieler beim ersten Beitritt. Bei den gepackten Inhalten sind sparsame Texturen deshalb meist der wirksamste Hebel.