Solución de problemas de compilación y ejecución

Usa esta página cuando el editor valida incorrectamente, la compilación de PS1 falle o el tiempo de ejecución informe de un error de carga.

Triage rápido

1. Ejecuta Build > Validate Project.
2. Abre Problems y corrige los errores duros primero.
3. Abre Build > Tools & Diagnostics > Show PS1 Budget e inspecciona los límites duros.
4. Comprueba Build/ps1/logs/ después de una compilación fallida.
5. Inspecciona Build/ps1/disc_root/DATA/MANIFEST.JSN cuando no se pueda cargar un recurso en tiempo de ejecución.
6. Prueba el .cue generado a partir de Build/ps1/package/.

Problemas comunes de compilación

Síntoma	Causa probable	Arreglar
Herramientas de compilador de tiempo de ejecución faltantes	Construcción privada/de origen seleccionada sin su cadena de herramientas	Usa el tiempo de ejecución binario instalado o abre Build > Tools & Diagnostics > Tool Paths...
Perdida ruta Ninja	Construcción en tiempo de ejecución privada/fuente seleccionada sin su corredor de compilación	Configura Ninja para esa compilación de origen; las versiones binarias usan el tiempo de ejecución incluido
Falta la ruta mkpsxiso	La ruta de la herramienta no está configurada	Establecer ruta ejecutable mkpsxiso
Falla la función Build & Run	Ruta DuckStation no encontrada o no válida	Configurar la ruta DuckStation
Los sticks no mueven al jugador o la cámara	El modo analógico está desactivado o faltan las asignaciones de sticks en Port 1	Configura Port 1 como Analog Controller / DualShock y activa Automatically Enable Analog Mode, o pulsa el botón Analog/Guide asignado. Last Exit también permite usar el D-Pad y L1/R1/L2/R2 en modo digital.
La cámara o el jugador se mueve sin tocar los sticks en una PS1 física	Los valores de reposo superan la zona muerta configurada; el emulador puede devolver un centro más preciso	Prueba PlayerInput > Dead Zone = 0.35. En Last Exit, ajusta deadZone a 0.35 en el LuaBehaviour del jugador. Vuelve a compilar el juego; actualizar el editor no cambia un proyecto ni un disco existente. Consulta Input.
Falta escena de inicio	Configurar puntos a una escena que falta	Abrir Build > Build Settings...
La carga de escena falla en tiempo de ejecución	Escena no incluida en Escenas en construcción	Agregar la escena a la configuración de construcción
Repackage Disc (Reuse Runtime) falla	No hay un entorno de ejecución disponible o los archivos preparados están desactualizados	Ejecutar Build Disc Image (.bin + .cue) completo
La importación del modelo indica collapses at PS1 vertex precision	Algunos detalles pequeños pierden su área al convertir las coordenadas a PS1	Centra o divide la malla original, simplifica los detalles demasiado delgados y vuelve a importar. Consulta Importación de modelos.
La importación de textura indica invalid image size	La imagen original no es válida o es demasiado grande para decodificarla de forma segura	Reduce su tamaño o vuelve a exportarla en un formato compatible; después usa Apply & Import.
Needs optimization o poco margen en la RAM principal	Un presupuesto de producción de PS1 está cerca de su límite; es independiente de la memoria de tu PC	Abre PS1 Budget desde la advertencia. Revisa los bytes libres exactos, reduce los datos de modelos o animaciones residentes, o divide la escena; después vuelve a compilar. Consulta Cómo interpretar las advertencias de Problems.

Errores de carga en tiempo de ejecución

failed to load MANIFEST.JSN

Comprueba:

• Build/ps1/disc_root/DATA/MANIFEST.JSN existe,
• empaquetado completado con éxito,
• el .cue apunta al .bin esperado,
• El tiempo de ejecución se inicia desde la última salida de compilación.

Falta script o error de carga de script

Comprueba:

• el campo Script Lua Behaviour apunta a un archivo .lua existente,
• el script está bajo el proyecto y se organiza en una carpeta de tiempo de ejecución compacta DATA/L,
• el script no excede el límite de tamaño configurado,
• existe la función de callback de destino si un botón de IU o Interactable la llama.

Falta malla, textura, material o audio

Comprueba:

• el recurso existe en Library/asset_db.json,
• el recurso fuente todavía existe bajo Assets/,
• la salida importada existe bajo Library/,
• el archivo por etapas existe bajo las carpetas de tiempo de ejecución Build/ps1/disc_root/DATA compactas (S, L, M, R, T, A o X),
• Validate Project no informa de los GUID o archivos faltantes.

La música en streaming no se reproduce

Comprueba:

• el WAV de origen tiene Streaming Music (CD-XA) habilitado,
• no más de 8 pistas de streaming están habilitadas,
• Build/ps1/disc_root/DATA/X/ contiene la pista codificada,
• el nombre enviado a Music.Play() coincide con el nombre del archivo WAV sin extensión; la comparación no distingue entre mayúsculas y minúsculas,
• el script comprueba el booleano devuelto por Music.Play().

Problemas de juego

Síntoma	Comprobar
El jugador camina a través de un objeto	El objeto tiene Collider, Collider no es un disparador, la colocación de Level Builder creó el Collider
El trigger no se activa	Collider existe, Is Trigger está habilitado y el Lua Behaviour define OnTriggerEnter
Interact no hace nada	El jugador tiene Interacción Ray, el objetivo tiene Interactable y el nombre de la función configurada coincide exactamente con el de la función.
El botón UI no hace nada	Botón Al hacer clic en el destino GameObject/función está establecido y el Lua Behaviour define esa función
SceneManager.LoadScene() no hace nada	La ruta de la escena de destino es correcta e incluida en la configuración de compilación
El audio se distorsiona en PS1, pero suena limpio en Play Mode	Vuelve a compilar con el editor actualizado para regenerar las importaciones antiguas de WAV. Si hace falta, selecciona el WAV original, usa Reimport y genera una nueva imagen de disco. Revisa también Audio Source Volume o Music.SetVolume y evita la saturación en el WAV original.
No se reproduce el audio	GameObject tiene Audio Source, existe el GUID del clip y el clip residente se ajusta al presupuesto de SPU
No se reproduce la música	La bandera de transmisión está habilitada, la pista se organiza en DATA/X, y Music.Play() utiliza el nombre de archivo de origen stem
El guardado falla en DuckStation	Habilita una Memory Card con permiso de escritura en Slot 1 y un bloque libre; consulta SaveData.GetLastError() inmediatamente después del error y vuelve a intentar. Espera a que termine el acceso a la tarjeta; la música CD-XA pausa y reinicia durante la operación.
Guardar/cargar no persiste	Usa PlayerPrefs.Save() para las preferencias escritas o SaveData.Flush() para los valores sin procesar; usa SaveData.Reload() antes de esperar datos de dispositivo nuevos
El juego utiliza la frecuencia de actualización incorrecta	Selecciona NTSC o PAL en Project Settings, guarda y ejecuta una compilación Release completa en lugar de Repackage Disc (Reuse Runtime)
Progress Bar no cambia	Resuelve con UI.Find(), luego comprueba el booleano devuelto por ProgressBar.SetValue()
El destino de navegación devuelve false	GameObject tiene un agente raíz NavMesh habilitado, existe una superficie referenciada, el previsualización tiene una ruta conectada en esa superficie y la ruta completa se ajusta dentro de los 32 puntos
El agente cruza un obstáculo dinámico	La navegación durante la ejecución no evita obstáculos dinámicos; incluye los colliders creados en el preprocesamiento o detén y recalcula la ruta desde un script.
La sala del Portal desaparece	Asignación de la Room de renderizador, cámara dentro de la Room esperada, Portal habilitado/abierto y dirección/estado de dos caras, tamaño de la abertura distinto de cero y transformación de Portal válida
Timeline.Play() devuelve false	El nombre del clip coincide exactamente y el clip existe en la escena activa
El jugador nativo todavía se mueve en una escena de corte	Activar Disable Player Controls en el clip; el movimiento Lua personalizado debe estar cerrado por separado
Rumble no está disponible	Usa Rumble.IsSupported(); comprueba que el mando sea analógico/DualShock, la asignación de vibración de DuckStation y la compatibilidad del manejador activo del BIOS con el parche opcional de salida, que se rechaza si no se cumplen las condiciones esperadas.

Renderización y problemas de rendimiento

Síntoma	Comprobar
Las caras desaparecen o se doblan al girar la cámara	Compila con el runtime actual y compara la misma vista en Game y en el CUE. Revisa orientación, caras duplicadas o intersectadas, colisión de cámara y plano cercano; no inviertas UV ni actives doble cara en todos los materiales. Consulta Importación de modelos.
Los polígonos se superponen incorrectamente	Revisa duplicados coplanarios, decoración incrustada y transparencias. El orden automático de límites y la subdivisión reducen defectos, pero no agregan un buffer de profundidad. Consulta Renderizado y creación de niveles.
Las paredes se ven gruesas y los props pequeños detallados	Compara dimensiones importadas y espacio de atlas por superficie. Corrige proporciones UV y densidad de texeles en el modelo fuente; aumentar solo la paleta no agrega píxeles. Consulta Importación de texturas.
El escenario es lento	Recuento de triángulos, estimación de paquetes, recuento de texturas, clips de audio, scripts activos
La UI se dibuja por encima del escenario de forma inesperada	Revisa el orden de los elementos de UI y la reserva de la tabla de ordenamiento para el primer plano
Objeto Transparent se clasifica mal	Mantén las superficies transparentes pequeñas y aisladas
Conflicto de empaquetado VRAM	Abre VRAM Inspector, selecciona la región roja, revela la textura, cambia de formato/tamaño y vuelve a importarla
Faltan los colores de malla	La malla importada contiene colores de vértice y Mesh Renderer utiliza Mesh Vertex Colors
La iluminación GTE es plana	Mesh contiene normales utilizables, la iluminación de escena está activa y Mesh Renderer utiliza GTE Vertex Lighting
La banda de niebla de distancia parece gruesa	Aumentar la subdivisión de geometría donde un triángulo grande abarca gran parte del rango de niebla; la niebla PS1 se interpola a partir de factores por vértice, no evaluados por píxel

Baja tasa de cuadros en DuckStation

1. Después de actualizar el engine, ejecuta Build Disc Image (.bin + .cue) y abre el .cue recién generado. Repackage Disc (Reuse Runtime) puede reutilizar un runtime preparado anteriormente; no sustituye una compilación completa.
2. Revisa el contador Game de DuckStation. Video: 60 FPS (100%) indica la salida NTSC y la velocidad de emulación, no 60 actualizaciones del juego por segundo. Mide con el overclock de CPU desactivado y a velocidad normal; mejoras como PGXP no sirven para confirmar el rendimiento del hardware original.
3. Mantén presionados L1 + R1 y pulsa Select para mostrar el diagnóstico del runtime. El valor frame cuenta los intervalos de VSync por cuadro del juego: a 60 Hz nominales en NTSC, 1 intervalo equivale aproximadamente a 60 FPS; 2, a 30 FPS; y 3, a 20 FPS. A 50 Hz en PAL, esos mismos intervalos equivalen aproximadamente a 50, 25 y 16.7 FPS. El contador slow registra los cuadros que tardan más de un intervalo; no es un contador de errores ni un objetivo configurable de 30 FPS.
4. Compara distintas vistas mientras recorres el nivel. Si el renderizado consume más tiempo, reduce la geometría visible al mismo tiempo, las subdivisiones excesivas, las superficies transparentes superpuestas y el detalle lejano. Usa Rooms, Portals y navegación para organizar interiores. Si predomina el tiempo de física, simplifica las formas de colisión y elimina Colliders superpuestos que no sean necesarios. Si predomina Lua, evita buscar objetos repetidamente y crear cadenas o tablas en cada cuadro; actualiza el texto del HUD solo cuando cambie su valor.
5. Vuelve a compilar y recorre la misma ruta después de cada cambio. Revisa los paquetes descartados, los fallos de asignación de memoria y los errores de Lua, además del tiempo por cuadro. Mide la carga y las transiciones de escena por separado de la jugabilidad estable, y prueba también con el diagnóstico oculto.

PS1 Ready y los límites de triángulos documentados son comprobaciones de presupuesto, no una garantía de FPS. Un nivel más grande necesita sus propias mediciones; ni el resultado de una demo pequeña ni el rendimiento de Play Mode predicen la velocidad de todos los juegos. Consulta PS1 Budget Dashboard para conocer los contadores y los reportes.

UI, carga y audio de eventos

Síntoma	Qué revisar
La imagen del objeto se superpone a las filas del baúl	Revisa Enabled, padres, Canvas y modo de distribución. La vista de inspección debe empezar deshabilitada y activarse solo donde corresponde; cambiar texto no oculta imágenes.
Una imagen de UI queda negra o falta en PS1	Revisa GUID, importación y dependencia de escena. Un nombre de archivo no es un GUID para Image.SetTexture. Referencia las opciones dinámicas en la UI de escena, incluso en elementos ocultos, para cargarlas en la compilación.
La mira tiene un rectángulo sólido detrás	Usa píxeles transparentes y Mask1Bit; comprueba si un Panel separado aporta el fondo.
El diálogo deja de revelar texto o corta una frase	Revisa Visible Characters, el límite de 127 bytes, los glifos y el rectángulo. Conserva la línea completa para la distribución y cambia solo el número de caracteres visibles.
La animación de UI se detiene al pausar	Activa Unscaled Time en el clip o usa Time.UnscaledDeltaTime en el temporizador Lua. Mantén su Canvas habilitado hasta terminar la salida.
El sonido no se detiene o IsPlaying devuelve false mientras se escucha	La fuente no controla las voces independientes de PlayOneShot. Usa Play/Stop para chirridos y sonidos ligados a una acción. Consulta AudioSource.
La navegación o los pasos suenan demasiado rápido	Usa cambios de selección o movimiento real, no una condición sostenida cada cuadro. Comprueba cada resultado; los sonidos independientes superpuestos pueden agotar voces.
La imagen de carga tarda en aparecer o el porcentaje se reinicia	El arte y la fuente necesitan leerse antes de usarse; el progreso describe la lectura actual. Black oculta deliberadamente la UI normal. Consulta Ajustes de carga.
Reinstalar sigue abriendo un demo anterior	Actualiza la copia editable o crea otra; instalar el engine no sustituye proyectos del usuario. Compila y abre su CUE nuevo. Consulta Actualizar el ejemplo.

Qué guardar al reportar un error

Incluye:

• nombre del proyecto y escena activa,
• comando de construcción exacta,
• Salida del panel Problems,
• Registros de compilación/ejecución de Console,
• Build/ps1/logs/ps1_budget_current_scene.json,
• Build/ps1/logs/build_summary.json,
• archivo de script relevante,
• captura de pantalla o video corto del problema de tiempo de ejecución,
• si el problema ocurre en el editor Play Mode, DuckStation, o hardware.

Problemas de script, memoria y carga

Síntoma	Qué probar
Lua instruction budget exceeded	Revisa si hay ciclos sin límite y reduce el trabajo de los callbacks o repártelo entre varios cuadros. Consulta Project > Project Settings... > Scripting > Lua VM Instructions / Callback. Aumentar Lua Heap (KB) no resuelve un límite de instrucciones. Reproduce el error en Play Mode para obtener diagnósticos con líneas de origen; las exportaciones normales de PS1 usan Release y eliminan esa información.
not enough memory o Lua heap exhausted	Lua agotó la memoria que tiene asignada. Revisa Project > Project Settings... > Scripting > Lua Heap (KB). Si una copia anterior de First Person Example sigue configurada en 64, usa el ajuste actualizado de 104 KiB, pulsa Save, reinicia Play Mode y vuelve a compilar el disco para DuckStation. Consulta la explicación de memoria que aparece abajo.
Script exceeds max script size	Revisa Max Script Size (KB) en la misma sección. Este límite se aplica a cada archivo y es independiente del heap compartido de Lua. Reduce o divide el script si es demasiado grande; el máximo del engine es de 64 KiB por archivo.
El presupuesto de RAM se superó después de una actualización	Compila de nuevo para actualizar el informe y, a continuación, reduce el tamaño de la escena o del recurso utilizando el panel de control de presupuesto. Comprueba las transiciones de escena, así como las escenas individuales.
Music se reinicia después de cargar	La reproducción XA se reanuda desde el principio de la pista. Planifique las transiciones con ese comportamiento en mente.
El texto de diagnóstico desaparece	Comprueba los contadores de entrega de paquetes en la superposición de tiempo de ejecución y reduce la geometría o la carga de la interfaz de usuario.
Falla el guardado o la carga	Abre Save Data Simulator, comprueba el modo de fallo seleccionado e inspecciona SaveData.GetLastError(). Muestra un mensaje de error y una opción de reintento en tu juego.

Cómo ajustar la memoria de Lua

PlayStation tiene 2 MiB de RAM principal para todo el juego. El código ejecutable, los datos de las escenas, las mallas, los buffers de carga y Lua comparten esa memoria. No son 2 MiB disponibles exclusivamente para scripts. La VRAM y la memoria de audio son independientes.

Lua Heap (KB) reserva memoria para la máquina virtual de Lua, sus bibliotecas y todos los scripts activos, incluidas sus tablas, cadenas y asignaciones temporales. Es una reserva compartida, no una cantidad que se asigna a cada script. El editor muestra KB para unidades de 1,024 bytes (KiB). En Windows de 64 bits, Play Mode reserva el doble de memoria física para compensar el mayor tamaño de los punteros y de los encabezados de asignación. Esta compensación de la vista previa no modifica el presupuesto exportado a PS1, y las cifras de Play Mode no son mediciones de la consola.

1. Detén Play Mode y abre Project > Project Settings....
2. En Scripting, revisa Lua Heap (KB). El rango admitido es de 64 a 512 KiB. Conserva el presupuesto que incluye tu ejemplo: First Person Example usa 104 KiB. Otros proyectos pueden necesitar una cantidad distinta; aumentarla también reduce la RAM disponible para el resto del juego.
3. Pulsa Save y vuelve a iniciar Play Mode. Para probar en DuckStation, compila de nuevo el disco; una compilación existente conserva la configuración anterior.
4. Si la memoria sigue siendo insuficiente, revisa las asignaciones y los datos que permanecen en uso. Evita reconstruir tablas o cadenas en cada cuadro y cargar grandes cantidades de datos de scripts al mismo tiempo. Aumenta el heap de forma gradual, siempre que el presupuesto total de RAM lo permita, y revisa Budget Dashboard y los informes del proyecto recompilado. Un ajuste de 256 KiB puede dejar muy poca RAM para una escena que sí cabe con un heap de Lua más pequeño. Si ya está en 512 KiB, reduce el consumo de los scripts en lugar de intentar superar el límite del engine.

El error de memoria puede ocurrir al cargar una escena, antes de que se ejecute cualquier callback Update. Acortar los callbacks no resuelve por sí solo una reserva de memoria insuficiente. En cambio, el límite de instrucciones mide el trabajo de ejecución, no el consumo de memoria.

La Console identifica el script y la entidad que fallaron. Play Mode pausa los reintentos automáticos cuando falla la carga o un callback de cuadro; edita el script, asigna otro o reinicia Play Mode para volver a intentarlo. Los cambios al presupuesto de memoria requieren un reinicio de Play Mode. Prueba las transiciones entre escenas además de la carga inicial, y verifica el juego recompilado en el emulador y en hardware: aprobar un informe de presupuestos no garantiza que todas las asignaciones de los scripts quepan en memoria.