Lire un compile log : VBSP, VVIS et VRAD dans Hammer

Q: Où trouver le compile log une fois la fenêtre fermée ?

Les outils de compilation écrivent le log dans .log, à côté de ton VMF. Tu peux ouvrir le fichier dans n’importe quel éditeur de texte. Les outils de GMod ajoutent chaque nouvelle compilation à la fin du fichier.

Lire un compile log de Hammer : les sections VBSP, VVIS et VRAD, les messages qui comptent et comment trouver la première vraie cause d’une erreur.

Publié le 8 octobre 20266 min de lecture

Un compile log se lit de haut en bas, en cherchant le premier message qui signale une erreur. Le log comporte trois sections, une pour VBSP, une pour VVIS et une pour VRAD, et la plupart des messages suivants ne sont que des conséquences du premier problème. Une fois que tu sais distinguer les trois sections et que tu connais une poignée de messages typiques, tu trouves généralement la cause en quelques minutes.

Où se trouve le log et comment il est structuré

Hammer affiche le log dans la fenêtre de compilation pendant qu’elle tourne, et les outils de compilation l’écrivent aussi dans <mapname>.log, dans le même dossier que ton VMF. Les outils de GMod ne remplacent pas ce fichier, ils écrivent à la suite : la compilation la plus récente se trouve donc à la fin. Dans le fichier, commence ta lecture là où débute la dernière compilation.

Dans la fenêtre de compilation du Hammer fourni, chacun des trois outils commence par le bloc ci-dessous ; Hammer++ écrit à la place une ligne qui commence par Running command:. Le fichier .log ne contient pas cet en-tête : là, tu reconnais les sections aux lignes typiques du tableau :

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

Section	Rôle	Lignes typiques quand tout va bien
VBSP	Construit la géométrie, les entités et les portals à partir du VMF	`ProcessBlock_Thread`, `Building Faces`, `WriteBSP`
VVIS	Calcule quelles zones sont visibles depuis où	`BasePortalVis`, `PortalFlow`, `Average clusters visible`
VRAD	Calcule les lightmaps et l’éclairage des props	`BuildFacelights`, `GatherLight`, `FinalLightFace`

Ce que font les trois outils en détail est expliqué dans VBSP, VVIS et VRAD expliqués. Pour lire le log, une règle suffit : chaque outil travaille avec le résultat du précédent. Si VBSP échoue, VVIS et VRAD n’ont rien d’exploitable sous la main.

Erreur, avertissement ou sans importance

Toutes les lignes qui attirent l’œil ne sont pas des problèmes. Il y a trois niveaux.

Erreur : L’outil s’arrête ou n’écrit aucun résultat exploitable. Si VBSP s’arrête, aucun nouveau BSP n’est créé. Hammer signale alors souvent The command failed lors de l’étape de copie finale, ou bien le jeu démarre avec l’ancien fichier et tes modifications manquent.
Avertissement : L’outil continue, mais le résultat est défectueux à un endroit. Exemple : WARNING: Too many light styles on a face de VRAD. La map fonctionne, mais l’éclairage est faux à la position indiquée.
Sans importance : Une ligne comme Memory leak: mempool blocks left in memory, connue des logs des outils de compilation Source, n’a rien à voir avec un leak dans ta map. Elle concerne l’outil lui-même et peut être ignorée.

Les messages les plus importants et ce qu’ils signifient

Message	Section	Signification	Ce que tu fais
`** leaked **`	VBSP	La map n’est pas étanche. Une entité est en contact avec le vide extérieur. La ligne suivante donne l’entité et ses coordonnées.	Charge la ligne rouge dans Hammer via Map > Load Pointfile et suis-la jusqu’au trou.
`areaportal brush doesn't touch two areas`	VBSP	Un areaportal ne sépare pas deux zones, parce qu’elles restent reliées ailleurs. La ligne commence par le numéro du brush.	Charge la ligne via Map > Load Pointfile et ferme la liaison restée ouverte entre les zones.
`material ... not found`	VBSP	Un matériau utilisé dans le VMF est introuvable dans les chemins de recherche du jeu.	Vérifie le chemin et l’orthographe, et assure-toi que le contenu se trouve dans le bon dossier du jeu.
`MAX_MAP_...` ou `Too many ...`	VBSP, VRAD	Une limite du moteur a été dépassée, par exemple les brush sides ou les planes.	Simplifie la géométrie et déplace les détails dans des modèles.
`LoadPortals: couldn't read`	VVIS	VBSP n’a pas écrit de fichier de portals. C’est presque toujours la conséquence d’un leak.	Ne cherche pas ici. Corrige le leak dans la section VBSP.
`The map overflows the max portal count`	VVIS	La map contient plus de portals que VVIS ne peut en traiter, et l’outil s’arrête.	Transforme les petits éléments en `func_detail` et simplifie la géométrie de monde.
`No vis information, direct lighting only`	VRAD	VRAD n’a reçu aucune donnée de visibilité et calcule sans lumière rebondie.	Cherche la cause plus haut, en général un leak ou un passage de VVIS sauté.

Les cas les plus fréquents ont leurs propres guides : corriger un leak de map et les limites des maps Source.

Le tableau à la fin de VRAD

Tout à la fin, VRAD affiche un récapitulatif du taux de remplissage des différentes zones de données du BSP, comme les brushes, les planes ou les entités. Si une ligne est marquée VERY FULL!, tu es proche d’une limite. Sur les grandes maps, vérifie ce tableau après chaque compilation complète pour repérer tôt les goulots d’étranglement.

La méthode : la première erreur d’abord

Vérifie que les trois outils ont bien tourné. Dans la fenêtre de compilation, cherche vbsp.exe, vvis.exe et vrad.exe ; dans le fichier .log, cherche les lignes typiques du tableau plus haut.
Cherche en partant du haut leaked, Error, WARNING, failed et not found.
Ne corrige que la première vraie erreur. Tout ce qui suit peut en être une conséquence.
Recompile et relis le log depuis le début. Ce n’est qu’une fois la première erreur disparue que les messages restants veulent dire quelque chose.
Traite ensuite les avertissements. Beaucoup de messages donnent des coordonnées ou un numéro de brush. Dans Hammer, le menu View permet de sauter directement à des coordonnées ou à un numéro de brush.
Pour finir, regarde le tableau de VRAD pour garder un œil sur les limites.

Faire analyser le log par un outil

Les longs logs sont pénibles quand on ne connaît pas encore les messages. Le Map Scanner a un mode compile log pour ça : tu colles un log de Hammer, VBSP, VVIS ou VRAD, ou tu l’envoies en .txt ou .log. Le résultat est trié en causes racines probables, autres erreurs, conséquences et avertissements, avec à chaque fois une cause et des étapes pour corriger. Les messages que le scanner ne connaît pas encore peuvent être signalés. Le scanner est indiqué comme étant en beta et il est gratuit.

Si tu veux rechercher un message précis, utilise la base d’erreurs. Elle contient des messages d’erreur vérifiés de Hammer et des outils de compilation, avec leur cause et leur solution.

Questions fréquentes

Où trouver le compile log une fois la fenêtre fermée ?

Les outils de compilation écrivent le log dans <mapname>.log, à côté de ton VMF. Tu peux ouvrir le fichier dans n’importe quel éditeur de texte. Les outils de GMod ajoutent chaque nouvelle compilation à la fin du fichier.

Dois-je corriger tous les avertissements ?

Non. Les avertissements n’arrêtent pas la compilation, et certains n’ont aucun effet visible. Corrige ceux qui donnent des coordonnées dans des zones jouables, car l’éclairage ou la visibilité y sont en général visiblement faussés.

Pourquoi mes modifications manquent-elles en jeu alors que la compilation est terminée ?

Très probablement, VBSP s’est arrêté et aucun nouveau BSP n’a été écrit. Le jeu charge alors l’ancien fichier. Cherche le premier message d’erreur dans la section VBSP.

Que signifie « Memory leak: mempool blocks left in memory » ?

La ligne vient des outils de compilation Source et décrit de la mémoire que l’outil n’a pas libérée en se fermant. Elle n’a rien à voir avec un leak dans la map, et tu n’as rien à faire. Dans nos compilations de test avec les outils actuels de GMod, elle n’est pas apparue.