Administración de escenas

Los proyectos Polygon Engine pueden contener varias escenas, pero el tiempo de ejecución de PS1 carga una escena de autor a la vez. Build Settings define qué escenas se organizan, su orden determinista y qué escena comienza cuando se inicia el juego generado.

Configurar las escenas de la compilación

Abre Build > Build Settings y comprueba:

1. Cada escena que se puede cargar en tiempo de ejecución aparece en Scenes In Build.
2. La escena de arranque prevista se selecciona como la escena de inicio.
3. Las rutas de escena permanecen dentro del directorio Scenes configurado del proyecto.
4. La Production Acceptance no informa de una entrada de compilación faltante o duplicada.

La compilación recopila las dependencias de cada escena incluida y escribe la asignación de escenas en el manifiesto escenificado. Un archivo de escena existente bajo Scenes/ no es suficiente por sí mismo; debe incluirse en la configuración de compilación.

Reutilizar una escena con su HUD y scripts

Usa una escena configurada como punto de partida para otra habitación del mismo proyecto. La copia conserva sus GameObjects, ajustes de componentes, referencias a scripts Lua, canvases de UI y elementos del HUD.

1. Abre la escena original, detén Play Mode y guarda con Ctrl+S.
2. En el Explorador de archivos de Windows, copia su archivo de escena dentro de la carpeta Scenes del proyecto. Por ejemplo, copia Scenes/room_01.json como Scenes/room_02.json. Copia el JSON de origen, no un archivo generado por el build. Conserva la escena original.
3. En el engine, elige Scene > Open Scene... y abre el archivo nuevo desde el Project Browser. Comprueba que estás editando la copia.
4. Cambia la distribución de la habitación y conserva el jugador, la cámara, los objetos que controlan la lógica y el HUD que quieras reutilizar. Revisa las referencias antes de eliminar objetos de la habitación anterior.
5. Ajusta los valores propios de la habitación: posiciones de aparición, destinos de puertas, objetivos de interacción y propiedades Lua expuestas. Conserva los nombres de objetos y elementos de UI que buscan los scripts comunes.
6. Guarda la escena nueva y agrégala a Build > Build Settings > Scenes In Build. Selecciona la escena inicial deseada y actualiza las transiciones con la ruta nueva.
7. Prueba el HUD, los controles y las transiciones en Play Mode. Después genera el build y prueba ambas habitaciones desde el CUE en DuckStation o en una PlayStation.

Haz que ambas escenas usen los mismos archivos Lua cuando compartan comportamiento. No necesitas duplicar scripts, texturas ni materiales para copiar una habitación. Modificar un asset compartido afecta a todas las escenas que lo usan; crea un asset separado si necesitas una variante independiente de una malla o un material.

Los archivos de escena son copias independientes, no plantillas vinculadas. Cambiar después la distribución del HUD de una escena no actualiza la otra automáticamente. Reutilizar la configuración tampoco conserva las variables Lua, los GameObjects ni la UI en ejecución al cambiar de escena. Usa Session para el progreso que deba sobrevivir al cambio.

Cargar una escena de Lua

Usa SceneManager.LoadScene() con un nombre de escena o ruta:

function openHub(gameObjectId)
    SceneManager.LoadScene("hub")
end

La solicitud se aplaza hasta que el tiempo de ejecución alcanza su punto de transición de escena seguro. La escena actual no se reemplaza en medio de la callback Lua. Consulta el API de escenas en Lua para conocer los nombres y las reglas de ruta aceptados.

Comportamiento de carga

La carga de escenas es una operación explícita de CD-ROM. Durante el arranque y los cambios de escena, el tiempo de ejecución presenta su pantalla de carga incorporada y bombea el progreso mientras lee los datos por etapas. La música larga de CD-XA se suspende alrededor de la carga de datos de escena y puede ser reiniciada por el sistema de audio después de la transición. Actualmente, Resume inicia la pista desde su inicio.

El tiempo de ejecución empaquetado extiende las lecturas de escena, la decodificación de recursos, las cargas de textura/SPU y la inicialización final de componentes a través de unidades de trabajo limitadas. Los paquetes secuenciales de escena local reducen las búsquedas físicas; si un paquete válido no está disponible, se pueden leer los mismos archivos lógicos de sus rutas por etapas sueltas. Esta es una optimización de implementación, no un segundo modo de creación.

El cargador conserva la escena anterior mientras comprueba el tamaño del destino y lee sus datos BSN limitados. Una consulta de tamaño fallido no asigna un búfer de reserva de tamaño máximo. Después de que la cabecera de destino pasa la validación, la ruta in situ puede liberar la escena anterior para dejar espacio para la decodificación. Un fallo después de ese punto borra el estado parcial, deja una escena vacía válida e informa de un error. La cancelación y el reemplazo de una solicitud también limpian los datos temporales de carga. Esto es de carga limitada y escalonada; no garantiza el retroceso a la escena jugable anterior después de cada falla.

Solo una transición usa el CD a la vez. La API Lua rechaza otra solicitud mientras hay una pendiente. Comprueba su resultado booleano y no llames a SceneManager.LoadScene() cada cuadro; condiciona la transición al estado del proyecto y envía una sola solicitud. Aceptada significa en cola, no cargada.

No diseñe una transición alrededor del acceso instantáneo. Mantén las escenas de inicio y transición dentro de los presupuestos del cargador y de la escena binaria reportados, y prueba desde el CUE generado para que la prueba usa el diseño del disco empaquetado.

Configura la pantalla de autoría en Advanced Scene Authoring > Loading & UI. Cada escena almacena etiquetas, colores, textura de imagen opcional, fuente de mapa de bits, visibilidad de progreso y porcentaje, tiempo de visualización mínimo y duración de desvanecimiento. El diseño permanece deliberadamente fijo y seguro para PS1; estos ajustes modelan su contenido en lugar de crear una transición arbitraria.

La compilación copia una forma compacta de la configuración de carga al manifiesto. Así selecciona colores, etiqueta, referencias, progreso y tiempos del destino antes de abrir su .BSN. La imagen y la fuente aún necesitan leerse y cargarse: se priorizan antes de la geometría, pero el primer cuadro puede usar solo el fondo y el texto de respaldo.

Ajustes de la pantalla de carga

Ajuste	Comportamiento visible
Enabled	Usa la presentación configurada; deshabilitado, el cargador nativo usa su texto básico
Label	Mensaje breve; PS1 almacena 63 bytes y el ancho fijo puede admitir menos
Image Texture GUID	Referencia de imagen importada, no ruta; cuenta en texturas y VRAM de la escena
Bitmap Font	Scene Default o una fuente bitmap de la escena; su atlas también consume presupuesto
Background / Text / Progress Background / Progress Fill	Colores de la distribución fija de carga
Show Progress	Muestra la lectura de disco actual, no una estimación continua del total de la escena
Show Percent	Agrega el porcentaje de esa lectura si hay progreso; puede reiniciarse entre lecturas
Minimum Display (seconds)	Duración mínima: usa de 0 a 10 segundos para PS1. El editor permite hasta 60, pero la reproducción nativa limita a 10
Fade Out (seconds)	Duración de salida: usa de 0 a 2 segundos para PS1. El editor permite hasta 10, pero la reproducción nativa limita a 2

Para una transición cinematográfica en negro, solicita la presentación Black mediante Sesión y transiciones. Oculta la imagen y barra normales. Lua de escena no se anima durante la lectura; termina la animación de puerta antes de solicitar la transición. Un error de carga sigue mostrando diagnósticos. Prueba desde el disco empaquetado; Play Mode no reproduce los tiempos físicos del CD.

Consulta Advanced Scene Authoring para cada campo.

Estado en todas las escenas

Los GameObjects, elementos de UI, componentes e instancias Lua locales pertenecen a la escena cargada. Usa Session para datos temporales de la partida que deben sobrevivir al cambio de escena sin convertirse en un archivo de guardado:

if Session.Write("game.entry", "warehouse") then
    if not SceneManager.LoadScene("Scenes/warehouse.json") then
        Log.Print("Scene change was not accepted")
    end
end

Session sobrevive a cambios de escena, pero se borra al iniciar otra sesión de Play, cerrar la aplicación o reiniciar la consola. Usa claves estables, no IDs de objetos de escena. Para progreso permanente, usa SaveData o PlayerPrefs. SaveData.Write() modifica su almacén en memoria; SaveData.Flush() lo escribe en la tarjeta. Consulta SaveData para límites y errores.

Ejemplo: restaurar el progreso del HUD en la siguiente habitación

Crea un elemento Text llamado KeyStatus en el HUD y un GameObject habilitado llamado GameProgress con un Lua Behaviour que use Assets/Scripts/GameProgress.lua. Conserva esta configuración en ambas escenas, con referencia al mismo script:

local keyLabel = -1

local function refreshHud()
    if keyLabel < 0 then
        return
    end

    if Session.Read("game.hasKey") == "1" then
        Text.SetText(keyLabel, "KEY: YES")
    else
        Text.SetText(keyLabel, "KEY: NO")
    end
end

function Start(gameObjectId)
    keyLabel = UI.Find("KeyStatus")
    if keyLabel < 0 then
        Log.Print("HUD Text KeyStatus was not found")
    end
    refreshHud()
end

function CollectKey(gameObjectId)
    if not Session.Write("game.hasKey", "1") then
        Log.Print("Could not store key progress")
        return
    end

    refreshHud()
end

function OpenNextRoom(gameObjectId)
    if not SceneManager.LoadScene("Scenes/room_02.json") then
        Log.Print("Scene change was not accepted")
    end
end

Llama a CollectKey en el objeto que controla el progreso desde la interacción de recoger la llave, y a OpenNextRoom desde la salida de la primera habitación. Desde otro Lua Behaviour, usa GameObject.Invoke para llamar a esas funciones en GameProgress. No llames a la salida en cada cuadro. El ejemplo registra la posesión de la llave y actualiza el HUD; tu lógica de recogida sigue controlando la visibilidad del objeto y las reglas del inventario.

Al cargar el destino, la nueva instancia del script ejecuta Start, busca el KeyStatus de esa escena y restaura el HUD a partir de game.hasKey. Una clave inexistente devuelve nil y muestra KEY: NO. No escribas un valor inicial incondicionalmente en el Start de cada escena, porque borrarías el progreso al cambiar de habitación. Lee primero el valor guardado e inicialízalo solo si no existe. Reinícialo únicamente al comenzar una partida nueva de forma intencional, por ejemplo con Session.Delete("game.hasKey").

Usa el mismo patrón para objetos recogidos y puertas abiertas: lee sus claves estables al entrar en la escena y restaura su estado visible. Session no serializa automáticamente el inventario ni la escena. Almacena strings, con un máximo de 32 entradas, de 1 a 31 bytes por clave y de 0 a 63 bytes por valor. Comprueba el resultado de cada escritura y mantén los datos compactos. Consulta Sesión y transiciones para conocer el contrato de almacenamiento.

Para comprobar este ejemplo, recoge la llave en la primera habitación y cambia de escena sin detener Play Mode: el HUD del destino debe seguir mostrando KEY: YES. Al iniciar una sesión nueva de Play debe mostrar KEY: NO. Prueba la misma transición desde el CUE actualizado; Session por sí solo no conserva el progreso después de reiniciar la consola.

Lista de comprobación de validación

• Cada destino SceneManager.LoadScene() está en Build Settings.
• La escena de inicio tiene una cámara jugable habilitada.
• Los scripts locales de escena no suponen que los ID de GameObject de otra escena sigan siendo válidos.
• Las claves de guardado necesarias tienen valores predeterminados adecuados cuando no existen datos de tarjeta de memoria.
• La compilación permanece por debajo del límite de la escena manifiesta y los límites binarios por escena.
• Las transiciones se prueban repetidamente desde el CUE empaquetado en DuckStation.
• Cargar avances sin presentar un juego parcialmente inicializado.
• Un destino fallido produce un error de ejecución procesable y nunca deja una escena parcialmente poblada activa.

Para obtener más información sobre la puesta en escena y la salida, consulta Proceso de compilación.