Proceso de compilación

El proceso de compilación convierte tu proyecto en una imagen de disco para PS1. La versión instalable incluye un runtime precompilado: el engine valida el proyecto, prepara las escenas y los recursos, y ejecuta mkpsxiso para generar los archivos de salida.

Para obtener la ruta más corta a través del proceso, consulta Inicio rápido.

Comandos de compilación

El menú Build contiene las acciones principales de la siguiente tabla. Los botones Build y Run de la barra de herramientas son accesos directos a los dos primeros comandos; ambos usan Release.

Comando	Qué hace
Build Disc Image (.bin + .cue)	Valida el proyecto, prepara el contenido y genera la imagen de disco. No abre el emulador.
Build & Run in DuckStation	Genera la misma imagen de disco y después abre su .cue en DuckStation. Requiere configurar la ruta de DuckStation.
Build Settings...	Permite elegir Scenes In Build y la escena de inicio.
Validate Project	Revisa el proyecto y muestra los resultados en Problems sin generar un disco.
Open Disc Image Folder	Abre Build/ps1/package/, donde se guardan los archivos generados.

Las operaciones de uso menos frecuente están en Build > Tools & Diagnostics:

Comando	Cuándo usarlo
Tool Paths...	Configura las herramientas de empaquetado y DuckStation, y verifica que estén listas para usarse.
Show PS1 Budget	Revisa el uso estimado de los recursos de hardware de la escena actual.
Show VRAM Inspector	Inspecciona la distribución del framebuffer, las páginas de texturas y las CLUT.
Export PS1 Budget Report	Guarda el informe de la escena actual en Build/ps1/logs/ps1_budget_current_scene.json.
Open Build Report	Abre el último Build/ps1/logs/ps1_build_performance_report.json; primero debes generar un disco.
Build with Readiness Checks	Compila en Release y exige el estado PS1 Ready. Las advertencias de presupuesto pueden hacer que esta comprobación más estricta falle; no sustituye las pruebas de juego.
Repackage Disc (Reuse Runtime)	Prepara el contenido y regenera el disco con un runtime Release disponible. Usa una compilación completa después de cambiar el engine o la configuración de compilación.

Para grabar un CD-R, conserva juntos los archivos .bin y .cue y selecciona el .cue en la opción de grabar imagen de tu programa de grabación. El BIN contiene los datos del disco; el CUE describe sus pistas y hace referencia al BIN. DuckStation utiliza este mismo par de archivos. Si solo necesitas exportarlos, usa Build Disc Image (.bin + .cue); no necesitas un emulador.

Etapas de tubería

Validate Project
  -> comprobar rutas de herramientas, lista de escenas, escena inicial, scripts, recursos, importaciones desactualizadas y presupuestos

Seleccionar el entorno de ejecución
  -> usar la versión precompilada Debug o Release de Polygon Engine
  -> las copias privadas del código fuente pueden compilarlo con PSn00bSDK y Ninja

Preparar disc_root
  -> escribir SYSTEM.CNF, POLYGON.EXE y DATA/MANIFEST.JSN
  -> reimportar texturas/audio desactualizados si cambiaron el origen o la configuración de importación
  -> preparar escenas, scripts, mallas, materiales, texturas y audio
  -> validar y preparar los recursos de animación con skinning rígido referenciados
  -> codificar los archivos WAV habilitados para música por streaming como CD-XA
  -> preprocesar primitivas compatibles con PS1 en fragmentos de malla para ejecución
  -> preprocesar las superficies de navegación habilitadas en grafos deterministas de nodos/enlaces que consideren la altura
  -> rechazar cadenas demasiado largas antes de escribir los datos .BSN
  -> escribir datos BSN con límites definidos y bloques de funciones de escena con su tamaño
  -> escribir un paquete secuencial de dependencias alineado a sectores por cada escena compilada
  -> escribir los informes de presupuesto y rendimiento de PS1 después del preprocesamiento

Empaquetar
  -> escribir el XML de mkpsxiso
  -> generar .bin, .cue e .iso en Build/ps1/package
  -> escribir registros e instrucciones de grabación

Carpetas de salida

Ruta	Descripción
Build/ps1/disc_root/	Contenido de disco escalonado interno
Build/ps1/package/	Salida de paquete orientada al usuario
Build/ps1/logs/	Resumen de compilación, presupuestos de creación, presupuestos de ejecución después del preprocesamiento, informe de rendimiento y registros de compilación y empaquetado
Library/build_history.json	ltimos 20 resúmenes de construcciones locales

La carpeta del paquete es la que la mayoría de los usuarios deben inspeccionar después de una compilación exitosa.

Resumen de finalización

Al terminar, el cuadro de diálogo muestra el resultado, la duración, la ruta del disco y el tamaño de los archivos generados. Open Disc Image Folder abre la carpeta de salida. Repackage & Run prepara el disco de nuevo con las opciones de la última compilación y un runtime disponible, y después abre DuckStation. Copy Summary copia un resumen breve para solicitar soporte.

Build/ps1/logs/build_summary.json almacena el resultado más reciente, incluido el paso que falló y su mensaje si se detiene la compilación. Library/build_history.json conserva los últimos 20 resúmenes. Estos archivos permiten diagnosticar problemas localmente; el paquete y los informes definitivos posteriores al preprocesamiento siguen siendo la evidencia para la publicación.

Datos de tiempo de ejecución por etapas

El tiempo de ejecución de PS1 espera un diseño compacto por etapas. Una construcción típica incluye:

Build/ps1/disc_root/
  SYSTEM.CNF
  POLYGON.EXE
  DATA/
    MANIFEST.JSN
    S/  escenas
    L/  scripts de Lua
    M/  mallas
    K/  recursos de animación con skinning rígido
    R/  materiales
    T/  texturas
    A/  audio VAG residente
    X/  música CD-XA por streaming (si existe)
    B/  paquetes secuenciales por escena

DATA/MANIFEST.JSN mapea los GUIDs en tiempo de ejecución y los nombres de escena a estas rutas de disco en etapas compactas. El editor sigue mostrando categorías de proyectos amigables como Escenas, Scripts, Mallas, Materiales, Texturas y Audio; los nombres de carpetas cortas solo existen para reducir la sobrecarga de texto manifiesto y ruta de CD en PS1.

Cada escena construida también recibe un paquete .PGB local de escena que contiene su escena binaria y dependencias ordenadas. El manifiesto asigna la escena a ese paquete, lo que permite que el tiempo de ejecución realice lecturas de CD secuenciales con menos búsquedas. Los recursos por etapas sueltos permanecen disponibles como un respaldo limitado y como las rutas de manifiesto canónicas; los autores no hacen referencia a los archivos .PGB directamente.

Cada entrada de escena de manifiesto también lleva la configuración de pantalla de carga compacta de la escena de destino. El tiempo de ejecución puede seleccionar esa presentación antes de leer el destino .BSN, lo que hace que la pantalla de carga correcta esté disponible desde el primer cuadro de la transición. El fragmento LOAD BSN sigue siendo la copia residente en la escena de la misma configuración de autoría.

Informes de presupuesto posteriores al preprocesamiento

El proceso de compilación valida tanto los datos de creación como los datos finales de tiempo de ejecución de PS1. La estimación de autoría detecta referencias faltantes temprano. El informe post-preprocesamiento es la fuente de la verdad porque se genera después de que las primitivas se convierten en fragmentos de malla y después de que las escenas se escriben como archivos binarios .BSN.

Archivos generados importantes:

File	Finalidad
ps1_budget_current_scene.json	Presupuesto de la escena actual; se sobrescribe con los datos posteriores al preprocesamiento durante la compilación
ps1_runtime_budget_<scene>_<hash>.json	Un presupuesto definitivo posterior al preprocesamiento por cada escena compilada
ps1_build_performance_report.json	Manifiesto de nivel de compilación, memoria de tiempo de ejecución, recurso global y resumen de escena

El informe de nivel de compilación también registra la región de video seleccionada y la frecuencia de actualización objetivo. La aceptación comprueba que el proyecto, el informe y el MANIFEST.JSN por etapas están de acuerdo.

Las advertencias aparecen cuando una escena se acerca a los límites fijos de PS1, como el recuento de GameObject, la memoria caché de malla, la memoria caché de manifiestos, el búfer de paquetes, el tamaño de carga de la escena binaria o el margen de RAM en tiempo de ejecución. Los datos de escena .BSN se tratan como memoria transitoria del cargador; el informe de tiempo de ejecución separa ese pico de la malla persistente y la memoria Lua. Los problemas difíciles detienen la construcción antes del empaquetado.

El informe de nivel de compilación ahora lleva un campo canónico readiness: PS1 Ready, Needs optimization o Build blocker. La aceptación de la producción requiere PS1 Ready a través de la construcción, no simplemente un éxito ISO / BIN / CUE.

Los objetivos actuales de producción para las plantillas oficiales son:

Presupuesto	Objetivo de producción
RAM en tiempo de ejecución	Al menos 160 KB libres dentro del presupuesto de ejecución compatible con PS1
Texto manifiesto	En o por debajo de 70% del búfer de manifiesto 16 KB
Escena binaria leer tamaño	En o por debajo de 65% del buffer de carga de escena 160 KB
Estimación de paquetes	En o por debajo de 80% del buffer de paquetes 96 KB

Las compilaciones Release y aceptación requieren un informe de memoria en tiempo de ejecución real. Los flujos de solo paquete pueden reutilizar el contenido por etapas, pero no se consideran autoritarios si faltan los datos de memoria en tiempo de ejecución.

Datos de escena binaria

Las compilaciones actuales escriben datos de escena .BSN limitados. El núcleo GameObject y la carga útil de la interfaz de usuario son seguidos por fragmentos de características etiquetados y del tamaño de bytes:

Chunk	Data
RNDR	Niebla a distancia y por-Mesh Renderer color/niebla/política de la Room
LOAD	Presentación y tiempo de carga de pantalla
UIEX	Fuentes de mapa de bits y campos extendidos de UI/ProgressBar
UICV	Definiciones de lienzo con nombre y enlaces de elemento a lienzo
INTR	Botón interactivo, tiempo de reutilización, repetibilidad y campos de lienzo rápido
WRLD	Habitaciones y portales
NAVG	Componentes de navegación más nodos y enlaces preprocesados
TIME	Clips de escena, pistas y cuadros clave
ANIM	Clips, pistas y cuadros clave Animation independientes
SKEL	Encuadernación de Animator de escena

Los trozos desconocidos de tamaño se pueden omitir de forma segura, mientras que los fragmentos conocidos mal formados o truncados fallan con un error explícito de carga de escena. Reconstruir proyectos después de la actualización para que el escritor actual y las reglas de validación comprueban todas las características compatibles.

Cobertura de validación

La validación es parte del producto, no un paso de depuración opcional. Captura cuestiones como:

• Faltan las herramientas de tiempo de ejecución o empaquetado requeridas (SDK/CMake/Ninja solo para compilaciones de origen; DuckStation solo para Ejecutar),
• escena de inicio no incluida en Escenas en construcción,
• escenas referenciadas por configuraciones de construcción que no existen,
• falta de malla, textura, material, audio o recursos de script,
• importaciones de texturas o audio desactualizadas cuando cambian los archivos fuente o la configuración,
• Fallos de codificación XA o más de 8 pistas de música en streaming,
• dependencia de scene-bundle, fallos de ruta o generación de paquetes,
• UI callbacks que hacen referencia a funciones Lua faltantes,
• Montón de Lua, tamaño de script y límites de recuento de scripts,
• Mallas Level Builder sin Colliders,
• La fuente del mapa de bits escala fuera del rango 1..4, atlas importados cuyas dimensiones reales no pueden contener la cuadrícula de glifos declarada, o valores ProgressBar no válidos,
• referencias rotas de Room/Portal, Room de renderizado, superficie NavMesh, o agente NavMesh,
• errores de capacidad de navegación,
• objetivos de escena de cortes no válidos, tiempos, interpolación, eventos o capacidades fijas,
• Animation independiente no válido pistas, objetivos, tiempos, capacidades de seguridad de finalización o tipos de pistas solo de escena de corte no compatibles,
• recursos esqueléticos, clips, enlaces, geometría de skinning rígido, cantidad de materiales o presupuestos de geometría, matrices y búfer temporal de la escena que no sean válidos,
• cadenas .BSN demasiado largas, como nombres GameObject, ID de generación, mensajes, nombres de callback Lua, nombres de acción Input, estados de Animator o texto de interfaz de usuario,
• arriesgada geometría PS1 como grandes primitivas incorporadas no segmentadas,
• materiales transparentes o de doble cara que pueden necesitar un ordenamiento cuidadoso,
• Post-bake escena binaria, manifiesto, malla, script, audio, animación y límites de memoria en tiempo de ejecución.

Los errores duros deben ser corregidos antes de la construcción. Las advertencias deben ser tratadas como riesgos de producción.

Imágenes de disco

El paso de paquete puede generar artefactos .bin, .cue y .iso. Para grabar discos PS1 reales, usa el archivo .cue porque describe el diseño de imagen BIN sin procesar esperado por las herramientas PS1.

Las pruebas DuckStation normalmente utilizan la salida del paquete generado.

Lista de comprobación de solución de problemas

Síntoma	Primeros lugares para comprobar
El tiempo de ejecución no puede cargar una escena	Configuración de compilación, escena de inicio, escenas en compilación, DATA/MANIFEST.JSN
El tiempo de ejecución no puede cargar un script	Ruta de componente de script, DATA/L, validación de compilación
Falta textura o material	Base de datos de recursos, material GUID, DATA/T y DATA/R
Textura o audio cambiados pero la construcción parece vieja	Estado de reimportación en el navegador Project, advertencias de hash de configuración de fuente
La música en streaming no se reproduce	Streaming Music bandera, pista nombre de archivo de la raíz, etapas DATA/X, Music.Play() valor de retorno
El objeto puede ser atravesado	Componente Collider, colocación desde Level Builder y opción Is Trigger del Collider
La construcción falla en el empaquetado	mkpsxiso ruta, registros de paquetes, archivos bloqueados en Build/ps1/package
Build & Run está desactivado o falla	DuckStation ruta y generado .cue

Para obtener información práctica sobre el uso del menú, consulta Flujo de trabajo: compilación y exportación.

Para ver errores comunes de errores de carga en tiempo de ejecución, consulta Solución de problemas.

Probar el paquete

Vuelve a compilar después de actualizar el editor o cambiar los recursos. El menú Build y la exportación por línea de comandos usan Release. Reproduce los errores de scripts en Play Mode para consultar los diagnósticos con líneas de origen y después prueba el disco Release recién compilado. Después de compilar correctamente, prueba el juego empaquetado: controles, interfaz, tasa de cuadros, transiciones de escena, audio y guardado.

Consulta Panel de presupuestos para conocer el significado de PS1 Ready y los próximos pasos de prueba.