Cómo leer un compile log: VBSP, VVIS y VRAD en Hammer

Q: ¿Dónde encuentro el compile log después de cerrar la ventana?

Las herramientas de compilación escriben el log en .log, junto a tu VMF. Puedes abrir el archivo con cualquier editor de texto. Las herramientas de GMod añaden cada compilación nueva al final del archivo.

Cómo leer un compile log de Hammer: las secciones de VBSP, VVIS y VRAD, los mensajes que importan y cómo dar con la primera causa real de un error.

Publicado el 8 de octubre de 20266 min de lectura

Un compile log se lee de arriba abajo, buscando el primer mensaje que avisa de un error. El log tiene tres secciones, una para VBSP, otra para VVIS y otra para VRAD, y la mayoría de los mensajes posteriores son solo consecuencias del primer problema. En cuanto sabes distinguir las tres secciones y conoces un puñado de mensajes típicos, sueles dar con la causa en pocos minutos.

Dónde está el log y cómo se estructura

Hammer muestra el log en la ventana de compilación mientras trabaja, y las herramientas de compilación lo escriben además en <mapname>.log, en la misma carpeta que tu VMF. Las herramientas de GMod no sustituyen ese archivo, sino que van añadiendo texto, así que la compilación más reciente está al final. En el archivo, empieza a leer donde comienza la última compilación.

En la ventana de compilación del Hammer incluido, cada una de las tres herramientas empieza con el bloque de abajo; Hammer++ escribe en su lugar una línea que empieza por Running command:. El archivo .log no tiene esa cabecera, así que ahí distingues las secciones por las líneas típicas de la tabla:

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

Sección	Tarea	Líneas típicas cuando todo va bien
VBSP	Construye la geometría, las entities y los portales a partir del VMF	`ProcessBlock_Thread`, `Building Faces`, `WriteBSP`
VVIS	Calcula qué zonas son visibles desde dónde	`BasePortalVis`, `PortalFlow`, `Average clusters visible`
VRAD	Calcula los lightmaps y la iluminación de los props	`BuildFacelights`, `GatherLight`, `FinalLightFace`

Lo que hacen las tres herramientas en detalle está en VBSP, VVIS y VRAD explicados. Para leer el log basta una regla: cada herramienta trabaja con el resultado de la anterior. Si VBSP falla, VVIS y VRAD no tienen nada aprovechable con lo que trabajar.

Error, advertencia o inofensivo

No toda línea llamativa es un problema. Hay tres niveles.

Error: La herramienta se detiene o no escribe un resultado aprovechable. Si VBSP se detiene, no se crea un BSP nuevo. Hammer suele avisar entonces con The command failed en el paso final de copia, o el juego arranca con el archivo antiguo y faltan tus cambios.
Advertencia: La herramienta sigue adelante, pero el resultado tiene un fallo en algún punto. Un ejemplo es WARNING: Too many light styles on a face de VRAD. El mapa funciona, pero la iluminación está mal en la posición indicada.
Inofensivo: Una línea como Memory leak: mempool blocks left in memory, conocida de los logs de las herramientas de compilación de Source, no tiene nada que ver con un leak en tu mapa. Se refiere a la propia herramienta y puedes ignorarla.

Los mensajes más importantes y qué significan

Mensaje	Sección	Significado	Qué haces
`** leaked **`	VBSP	El mapa no está sellado. Una entity tiene conexión con el vacío exterior. La línea siguiente indica la entity y sus coordenadas.	Carga la línea roja en Hammer con Map > Load Pointfile y síguela hasta el agujero.
`areaportal brush doesn't touch two areas`	VBSP	Un areaportal no separa dos áreas porque siguen conectadas por otro sitio. La línea empieza por el número del brush.	Carga la línea con Map > Load Pointfile y cierra la conexión que sigue abierta entre las áreas.
`material ... not found`	VBSP	Un material usado en el VMF no se ha encontrado en las rutas de búsqueda del juego.	Revisa la ruta y que el nombre esté bien escrito, y asegúrate de que el contenido está en la carpeta de juego correcta.
`MAX_MAP_...` o `Too many ...`	VBSP, VRAD	Se ha superado un límite del motor, por ejemplo de brush sides o de planos.	Simplifica la geometría y pasa el detalle a modelos.
`LoadPortals: couldn't read`	VVIS	VBSP no ha escrito el archivo de portales. Casi siempre es consecuencia de un leak.	No busques aquí. Arregla el leak en la sección de VBSP.
`The map overflows the max portal count`	VVIS	El mapa tiene más portales de los que VVIS puede procesar, y la herramienta se detiene.	Convierte las piezas pequeñas en `func_detail` y simplifica la geometría del mundo.
`No vis information, direct lighting only`	VRAD	VRAD no ha recibido datos de visibilidad y calcula sin luz rebotada.	Busca la causa más arriba, normalmente un leak o que se omitió VVIS.

Los casos más frecuentes tienen su propia guía: solucionar un leak en el mapa y límites de mapas en Source Engine.

La tabla del final de VRAD

Justo al final, VRAD imprime un resumen de lo llenas que están las distintas áreas de datos del BSP, como brushes, planos o entities. Si una línea está marcada con VERY FULL!, estás cerca de un límite. En mapas grandes, revisa esta tabla después de cada compilación completa para detectar los cuellos de botella a tiempo.

Cómo proceder: primero el primer error

Comprueba que se han ejecutado las tres herramientas. En la ventana de compilación, busca vbsp.exe, vvis.exe y vrad.exe; en el archivo .log, busca las líneas típicas de la tabla de arriba.
Busca desde arriba leaked, Error, WARNING, failed y not found.
Arregla solo el primer error real. Todo lo que viene después puede ser una consecuencia.
Compila otra vez y vuelve a leer el log desde arriba. Solo cuando el primer error ha desaparecido significan algo los mensajes restantes.
Después, ve repasando las advertencias. Muchos mensajes indican coordenadas o un número de brush. En Hammer, el menú View te permite saltar directamente a unas coordenadas o a un número de brush.
Por último, echa un vistazo a la tabla de VRAD para no perder de vista los límites.

Deja que una herramienta analice el log

Los logs largos son pesados cuando todavía no conoces los mensajes. El Map Scanner tiene para eso un modo de compile log: pegas un log de Hammer, VBSP, VVIS o VRAD, o lo subes como .txt o .log. El resultado se ordena en causas raíz probables, otros errores, errores derivados y advertencias, cada uno con su causa y los pasos para solucionarlo. Los mensajes que el scanner todavía no conoce se pueden reportar. El scanner está marcado como beta y es gratuito.

Si quieres consultar un mensaje concreto, usa la base de datos de errores. Contiene mensajes de error revisados de Hammer y de las herramientas de compilación, con causa y solución.

Preguntas frecuentes

¿Dónde encuentro el compile log después de cerrar la ventana?

Las herramientas de compilación escriben el log en <mapname>.log, junto a tu VMF. Puedes abrir el archivo con cualquier editor de texto. Las herramientas de GMod añaden cada compilación nueva al final del archivo.

¿Tengo que arreglar todas las advertencias?

No. Las advertencias no detienen la compilación, y algunas no tienen ningún efecto visible. Sí conviene arreglar las que indican coordenadas en zonas jugables, porque ahí la iluminación o la visibilidad suelen estar mal a simple vista.

¿Por qué no aparecen mis cambios en el juego si la compilación ha terminado?

Lo más probable es que VBSP se haya detenido y no se haya escrito un BSP nuevo. El juego carga entonces el archivo anterior. Busca el primer mensaje de error en la sección de VBSP.

¿Qué significa "Memory leak: mempool blocks left in memory"?

La línea procede de las herramientas de compilación de Source y describe memoria que la herramienta no liberó al cerrarse. No tiene nada que ver con un leak en el mapa y no tienes que hacer nada. En nuestras compilaciones de prueba con las herramientas actuales de GMod no apareció.