CONTENU

Usage de Bspzip pour intégrer du contenu au BSP

Ce tutorial porte sur "comment insérer du contenu personnel dans un fichier BSP"
Cette page dispose d'une feuille de style pour l'impression (afin de supprimer la mise en page du site).
Dernière mise à jour le 24/08/2013.

Ce cours a été entièrement écrit par moi, c'est à dire NykO18.
Pour me contacter, plusieurs moyens :

Plan

Bspzip.exe

les maps au format BSP du moteur Source peuvent contenir des fichiers personnalisés comme des textures ou des models qui sont uniques à chaque map et qui ne sont pas livrés avec les jeux Source par défaut. Bspzip est un programme de VALVe en ligne de commande qui vous permet d'inclure, d'extraire et de lister des fichiers dans les BSP. Ceci permet une distribution plus facile des maps en évitant de demanderà l'utilisateur d'extraire la map dans /maps, les models dans /models, les textures dans /materials et ainsi de suite...

bspzip.exe peut être utilisé selon 4 modes d'action différents avec les syntaxes suivantes :

bspzip -dir fichierbsp
bspzip -addfile fichierbsp cheminrelatif chemincomplet newfichierbsp
bspzip -addlist fichierbsp listfile newfichierbsp
bspzip -extract fichierbsp fichiers.zip

Utilisation

La variable d'environnement Windows %sourcesdk% peut être utilisée pour cibler bspzip.exe plus facilement dans une ligne de commande. Cette variable contient l'emplacement du repertoire d'installation du SDK Source et peut donc être utilisée directement comme un chemin plutôt que de taper le chemin complet jusqu'à l'executable bspzip.exe. Par exemple, pour faire la liste de tous les fichiers contenus dans la map HL²DM dm_lockdown.bsp, ouvrez simplement un prompt de commande (Démarrer > Executer > cmd), changez le répertoire (en utilisant la commande cd nomdudossier) pour C:\Program Files\Steam\SteamApps\<utilisateur>\half-life 2\hl2\maps (par exemple) et entrez ces commandes :

"%sourcesdk%\bin\bspzip" -dir dm_lockdown.bsp

Ceci va générer la liste des fichiers contenus dans le fichier BSP comme ceci :

materials/maps/dm_lockdown/tile/tilewall009b_-3792_3120_72.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-3488_2752_80.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-3488_3104_72.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-3192_3120_72.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-2944_3136_72.vmt
...

Dans le cas présent, ce sont tous les cubemaps utilisés dans dm_lockdown.bsp qui sont listés.

Note: Il est très important que vous choisissiez le bon Current Game dans le Launcher du SDK pour obtenir le bon chemin vers le jeu avant d'ouvrir le prompt de commande. Changer le jeu courrant dans le launcher n'affectera pas les prompts déjà ouverts. C'est à cause de la façon dont Windows gère ses variables. Il faut donc, ouvrir le SDK, changer le jeu ou mod pour lequel vous mappez, puis ouvrir le prompt de commande et taper les commandes.

Inclure des fichiers individuels

Par exemple, si vous avez un fichier VMT (une texture) exemple.vmt que vous souhaitez inclure dans une map appelée dm_mymap.bsp. En admettant que la texture se trouve dans le dossier C:\Program Files\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch\hl2mp\materials\metal\, vous devrez ouvrir une invite de commande (cmd), changer de dossier pour celui contenant la map (cmd "%vproject%/maps") et entrer ceci dans l'invite de commande (les couleurs sont là pour faire beau..) :

"%sourcesdk%\bin\bspzip" -addfile dm_mymap.bsp "materials/metal/exemple.vmt" "%vproject%/materials/metal/exemple.vmt" dm_mymap_bspzip.bsp

Ceci va lire la map dm_mymap.bsp située dans le répertoire courant, ajouter materials/metal/exemple.vmt à l'intérieur et réécrire le BSP original sous le nom dm_mymap_bspzip.bsp. La variable d'environnement %vproject% est utilisée pour situer automatiquement le répertoire du jeu.

Attention : Ne faites pas la même erreur que moi à mes débuts. N'utilisez pas cette commande pour ajouter toute une liste de fichiers à un BSP. Cela va fonctionner, mais cela va également prendre très longtemps à cause du fait qu'après chaque fichier ajouté, le BSP va être intégralement réécrit. Donc si vous incluez 50 fichiers, le BSP va être réécrit 50 fois.. D'où une lenteur extrême.

Inclure une liste de fichiers

L'argument -addlist de bspzip permet d'ajouter plusieurs fichiers contenus dans une liste au format texte à un BSP :

bspzip -addlist dm_mymap.bsp dm_mymap_liste.txt dm_mymap_bspzip.bsp

La liste utilise un format similaire à la commande -addfile -- un chemin relatif vers le répertoire du jeu suivit du chemin absolu du fichier que vous voulez ajouter. La liste doit contenir les chemins relatifs ET complets (absolus) pour chaque fichier, comme ceci :

cheminrelatif/file1
cheminabsolu/file1
cheminrelatif/file2
cheminabsolu/file2

...

Par exemple, si vous avez plusieurs fichiers VMT dans C:\Program Files\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch\hl2mp\materials\metal\ que vous souhaitez insérer dans une map, vous devrez créer un fichier comme celui-ci avec un éditeur de texte basique :

materials/metal/exemple.vmt
C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple.vmt
materials/metal/exemple.vtf
C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple.vtf
materials/metal/exemple2.vmt
C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple2.vmt
materials/metal/exemple2.vtf
C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple2.vtf

Sauvegardez ensuite cette liste dans le répertoire des maps (là où le BSP se trouve). En fait, elle peut être placée n'importe où, mais c'est plus facile de s'y retrouver ainsi. Par la suite, si vous souhaitez ajouter les fichiers listés dans un fichier nommé dm_mymap_liste.txt à un BSP nommé dm_mymap.bsp, vous devrez taper dans l'invite de commande :

"%sourcesdk%\bin\bspzip" -addlist dm_mymap.bsp dm_mymap_liste.txt dm_mymap_bspzip.bsp

Ceci va alors lire la map dm_mymap.bsp, ajouter tous les fichiers référencés dans dm_mymap_liste.txt et réécrire le fichier BSP au même endroit et sous le nom dm_mymap_bspzip.bsp. Bspzip devrait générer les messages suivants quand la commande est éxecutée :

Opening bsp file: C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/maps/dm_mymap.bsp
Adding file: C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple.vmt
Adding file: C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple.vtf
Adding file: C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple2.vmt
Adding file: C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/materials/metal/exemple2.vtf
Writing new bsp file: C:\Program Files\Valve\Steam\SteamApps\<utilisateur>\half-life 2 deathmatch/hl2mp/maps/dm_mymap_bspzip.bsp

Attention : Suite à mes nombreux déboires avec bspzip, j'ai remarqué certains petits détails qui font planter le logiciel si on n'y prend pas garde. Premièrement, il est interdit de passer des lignes dans le fichier-listing. Chaque fichier doit suivre directement son précédent. Le fichier devient ainsi très "bordélique" mais on n'a pas le choix. Deuxièmement, il faut impérativement laisser une ligne vide tout en bas de la liste.. Pour une raison qui m'est inconnue, si ceci n'est pas effectué, le dernier fichier de la liste ne sera pas ajouté.

Extraire des fichiers

Vous pouvez extraire les fichiers contenus dans un BSP en utilisant la syntaxe suivante :

"%sourcesdk%\bin\bspzip" -extract dm_mymap.bsp dm_mymap.zip

Ceci va créer un fichier nommé dm_mymap.zip contenant tous les fichiers inclus dans le BSP dm_mymap.bsp. Le fichier ZIP peut alors être ouvert et décompressé librement pour examiner le contenu du BSP.

Pakrat : attention

Depuis quelques temps, un logiciel spécial nommé pakrat permet de s'affranchir de toutes ces manipulations rébarbatives de lignes de commandes. Malheureusement, son utilisation est à vos risques et périls car il ne fait pas son travail correctement. Je vous explique rapidement pourquoi.

Pour déterminer si un fichier a besoin d'être inclu ou pas dans une map, pakrat devrait lister dans votre BSP toutes les références vers des sons, textures, models ou autres fichiers qu'il ne trouve dans les fichiers GCF des jeux puis proposer de les inclure. Or, il se trouve qu'au lieu de faire cela, pakrat recherche les fichiers sur le disque dur, et s'ils s'y trouvent, il les inclue. Concrètement, cela signifie que si vous avez un model situé dans un fichier GCF et que vous avez également le même model extrait sur votre disque dur, pakrat va penser que le model est un model personnel (vu qu'il est sur le disque) et va l'inclure dans votre BSP sans regarder s'il ne serait pas déjà présent dans le GCF (et donc inutile à inclure).

Par exemple: avec la sortie de Half-Life 2 Episode 1, j'ai eu des tas de problèmes car ce jeu est un standalone. Cela signifie qu'il ne nécessite pas Half-Life 2 pour fonctionner, et cela signifie également qu'il doit donc contenir la plupart des fichiers de HL² au cas où la personne qui souhaite y jouer ne possède pas Half-Life 2. On se retrouve donc avec des fichiers redondants (par exemple des textures dans Half-Life 2 utilisées dans Episode 1 sont dans chacun des deux GCF des deux jeux). Ce qui signifie que si vous souhaitez utiliser le contenu personnalisé d'Episode 1 et que vous sortez tous les models et texture de son GCF sans avoir envie de faire le tri entre les nouveaux et les anciens, vous allez vous retrouver avec des models et textures de Half-Life 2 sur votre disque et pakrat va les considérer comme personnels et donc les inclure au BSP.

En pratique, cela donne des maps qui contiennent des tas de fichiers inutiles et qui peuvent grossir exponentiellement de plusieurs dizaines de méga-octets pour rien. J'ai constaté que beaucoup de mappeurs ne savaient pas cela et que leurs maps contenaient des tas de fichiers inutiles, j'ai moi même réalisé une map, dm_mine_enhanced, qui pèse 53MB avec tout le contenu additionnel ajouté via bspzip (en ligne de commande) alors qu'avec pakrat, elle pesait 98MB... Alors faites bien attention à ce que vous incluez dans vos maps.

Ceci est au moins valable jusqu'à la version actuelle de pakrat (0.95).
J'ai développé un outil, PHPZip, afin d'aider à cette étape d'inclusion de contenu.

Tests & conclusion

Notez que vous pouvez aussi bien ajouter des models en utilisant la même méthode. Veillez juste à ne pas oublier d'inclure tous les fichiers necessaires aux models (.mdl, .vtx, phy, .dx80.vtx, .dx90.vtx et .sw.vtx) ainsi que toutes les textures qui leurs servent.

Une fois que vous aurez terminé d'ajouter vos fichier à votre BSP, vérifiez alors que tout a fonctionné et que vous n'avez rien oublié en renommant les dossiers materials, models et sound du jeu en materials2, models2 et sound2 avant de lancer votre nouveau BSP. Si vous avez fait les choses correctement, le contenu personnalisé devrait tout de même apparaître même s'il n'est pas trouvé dans les dossier materials et models car il est désormais contenu dans le BSP. C'est exactement ce que verrai quelqu'un qui teste votre map.

Si des fichiers sont manquants, vous aurez des messages d'erreur dans la console expliquant quels fichiers sont manquants. Utilisez alors la commande -dir avec bspzip pour voir quels sont les fichiers inclus dans le BSP et comprendre lesquels manquent et ajoutez-les simplement de la même manière que précédemment.