Packer du contenu custom dans un BSP : textures, modèles, sons

Tu packes tes propres textures, modèles et sons dans le BSP en les écrivant dans le pakfile de la map après la dernière compilation, avec un outil comme bspzip, CompilePal ou VIDE. Le moteur charge alors les fichiers directement depuis la map, et les joueurs n’ont rien d’autre à télécharger pour ça. Sans packing, ils voient des damiers rose et noir à la place des textures et des ERROR rouges à la place des modèles.

Pourquoi packer ton contenu

En plus de la géométrie et de l’éclairage, un BSP contient une section réservée aux fichiers embarqués : le pakfile. Techniquement, c’est une archive à l’intérieur de la map. Au chargement de la map, le moteur traite son contenu comme si les fichiers se trouvaient dans le dossier du jeu. Garry’s Mod y met une limite : depuis les patchs de sécurité de décembre 2023, le jeu contrôle les fichiers embarqués par rapport à une whitelist, et ce qui échoue n’est pas monté. La console affiche alors BSP embedded file failed whitelist check. La structure d’ensemble d’un BSP est expliquée dans Qu’est-ce qu’un fichier BSP ?.

L’autre solution consiste à livrer le contenu à part, par exemple sous forme d’addon. Ça marche, mais les sources d’erreur sont plus nombreuses : un fichier manque, le joueur n’est pas abonné à un addon, un chemin est faux. Une map packée, c’est un seul fichier qui a le même rendu partout.

Ce qui va dans le BSP

Ce qu’on oublie facilement :

• les matériaux d’un modèle, qui se trouvent dans un autre dossier que le modèle lui-même
• les textures supplémentaires référencées par un VMT, comme les normal maps
• les textures de skybox custom dans materials/skybox/
• les scripts propres à la map, comme les soundscapes, et les fichiers de particules custom

Ce qui n’a rien à faire dans le BSP : le contenu que chaque joueur possède déjà avec le jeu, les fichiers inutilisés et les fichiers sources comme les VMF, TGA ou PSD.

La bonne structure de dossiers

Dans le pakfile, les chemins sont les mêmes que dans le dossier du jeu garrysmod/ :

materials/yourname/yourmap/wall_concrete01.vmt
materials/yourname/yourmap/wall_concrete01.vtf
models/yourname/yourmap/lantern.mdl
sound/yourname/yourmap/hall_ambient.wav

Trois règles t’évitent la plupart des problèmes :

1. Ton propre sous-dossier. Avec un nom de dossier unique, tu n’écrases pas les fichiers d’autres addons et les tiens ne se font pas écraser non plus.
2. Minuscules, pas d’espaces, pas de caractères spéciaux. Les serveurs Linux sont sensibles à la casse. Un chemin qui fonctionne sous Windows peut échouer là-bas.
3. Vérifie les chemins dans le VMT. Un VMT référence son VTF par un chemin relatif à materials/ et sans extension. Si tu déplaces des fichiers, tu dois adapter les références.

Comparatif des outils

Avec bspzip, tu passes un fichier texte qui liste tous les fichiers :

bspzip -addlist yourmap.bsp filelist.txt yourmap_packed.bsp
bspzip -dir yourmap_packed.bsp

La liste se compose de paires de lignes : d’abord le chemin à l’intérieur de la map, en dessous le chemin complet sur ton disque. La seconde commande affiche le contenu du pakfile.

Les outils automatiques détectent ce que la map utilise directement. Ils peuvent passer à côté d’un contenu qui n’est appelé qu’à l’exécution, par exemple un son joué uniquement par un script. Regarde donc toujours la liste.

Packer en cinq étapes

1. Fais la compilation finale. Ne packe qu’une fois la map terminée. Le déroulement est décrit dans VBSP, VVIS et VRAD expliqués.
2. Détermine le contenu. Laisse l’outil analyser la map ou écris la liste à la main.
3. Packe. Écris dans une copie du BSP pour conserver l’original.
4. Génère les cubemaps. Les cubemaps sont elles aussi stockées dans le pakfile. Génère-les dans le fichier packé.
5. Teste. Voir plus bas.

Important : chaque nouvelle compilation produit un BSP tout neuf, sans ton contenu packé. Après chaque modification de la map, tu packes à nouveau.

Taille du fichier et compression

Dans le contenu packé, les textures représentent le plus souvent la plus grosse part. Choisis des résolutions adaptées à la taille de la surface et enregistre tes VTF dans un format compressé plutôt que non compressé. Retire le contenu que tu n’as finalement pas utilisé et raccourcis les sons trop longs.

Le transport ajoute en général une compression par-dessus : les serveurs FastDL livrent le plus souvent les maps sous forme de fichier compressé, et le Workshop compresse lui aussi à l’upload. La taille sur le disque n’est donc pas la taille du téléchargement. Le texte d’aide du bspzip de GMod mentionne aussi -repack -compress, qui compresse le BSP lui-même. Dans notre test avec la version actuelle de GMod, la commande s’est toutefois terminée sans aucune sortie et a laissé le fichier inchangé, et la Valve Developer Community renvoie plutôt au bspzip de Team Fortress 2. Si tu compresses une map, fais-le en toute dernière étape et teste soigneusement que le jeu et le serveur la chargent sans problème.

Vérifier après le packing

1. Renomme temporairement tes dossiers de contenu non packé dans le dossier du jeu, ou teste sur une seconde installation. C’est le seul moyen de voir ce qui vient réellement du BSP.
2. Charge la map et parcours chaque zone. La console signale les matériaux et les modèles manquants.
3. Compare la sortie de bspzip -dir avec ta liste.
4. Envoie le BSP au Map Scanner. Il liste les fichiers Lua et les assets embarqués dans le pakfile et vérifie la structure du fichier.

Si des damiers ou des modèles ERROR apparaissent encore, consulte Corriger les textures manquantes et les modèles ERROR.

Droits : ne packe que ce que tu peux redistribuer

Packer du contenu dans un BSP, c’est le redistribuer avec la map. Ne packe que ton propre travail et du contenu dont la licence autorise la redistribution. Si tu veux vendre la map, la licence doit aussi couvrir l’usage commercial. Qu’un addon soit gratuit sur le Workshop ne vaut pas autorisation, et créditer l’auteur ne la remplace pas. Il en va de même pour le contenu tiré d’autres jeux. Les bases sont expliquées dans Droit d’auteur et maps GMod : les bases. Cette section ne constitue pas un conseil juridique.

Questions fréquentes

Dois-je repacker après chaque compilation ?

Oui. VBSP écrit un nouveau BSP à chaque passage, et le pakfile de l’ancien fichier est perdu. Ne packe qu’après la dernière compilation et génère les cubemaps ensuite.

Pourquoi est-ce que je vois encore des damiers rose et noir après le packing ?

Le plus souvent, un chemin est faux. Soit le fichier ne se trouve pas dans le pakfile à l’endroit où la map l’attend, soit le VMT a été packé mais pas son VTF. Pour les modèles, ce sont souvent les matériaux qui manquent, parce qu’ils se trouvent dans un autre dossier.

Peut-on extraire à nouveau le contenu packé d’un BSP ?

Oui. Le pakfile est une archive ordinaire, et les outils qui servent à packer savent aussi extraire. Le packing sert à la distribution, pas à protéger ton contenu.

Quelle taille peut faire une map packée ?

Nous ne pouvons pas confirmer de limite fixe pour le fichier entier dans GMod. En pratique, tout dépend de la façon dont la map est distribuée. Plus le fichier est gros, plus les joueurs attendent à leur première connexion. Pour le contenu packé, des textures légères sont donc le plus souvent le levier le plus efficace.