Documentación de Polygon Engine
Polygon Engine combina un editor para Windows, un proceso de preparación de recursos, una capa de lógica de juego en Lua y un entorno de ejecución de PlayStation 1 para crear juegos de PS1 mediante un flujo visual. El editor usa conceptos conocidos como GameObjects, Components, Prefabs, Hierarchy, Inspector y Canvas; el entorno de ejecución y el proceso de compilación están diseñados en torno a los límites de la PlayStation original.
La documentación está organizada como un manual de producto: comienza con el flujo de trabajo del editor y continúa con los recursos, los componentes, la programación, los archivos de compilación y las reglas de producción para PS1.
Capas del engine
Editor (Windows, C++ / ImGui)
-> edición de escenas, componentes, UI Canvas, Level Builder y validación
Procesamiento de recursos
-> recursos de origen en Assets/
-> recursos importados para ejecución en Library/
-> audio VAG residente o música CD-XA por streaming
-> referencias basadas en GUID mediante Library/asset_db.json
Proceso de compilación
-> valida escenas, scripts, presupuestos y rutas de herramientas
-> prepara los recursos de DATA/ y los archivos de manifiesto
-> selecciona el entorno de ejecución de PS1 incluido (solo se compila en una versión privada desde el código fuente)
-> empaqueta la imagen de disco en Build/ps1/package
Entorno de ejecución de PS1 (C + PSn00bSDK)
-> carga DATA/MANIFEST.JSN y la escena inicial
-> renderiza mediante GTE/GPU y tablas de ordenamiento
-> ejecuta scripts de Lua, la interfaz creada, el audio, las colisiones y los datos de guardado
Funciones disponibles actualmente
Polygon Engine se enfoca actualmente en estos flujos de trabajo:
- creación visual de escenas con GameObjects, Components, Prefabs y edición de selecciones múltiples,
- importación de modelos, texturas, materiales, audio y scripts Lua,
- recursos de malla de Level Builder guardados en el proyecto y reutilizados en las escenas,
- múltiples lienzos de interfaz con nombre, paneles, textos, imágenes, botones y control de visibilidad y orden mediante scripts,
- interfaces con fuentes de mapa de bits y ProgressBars durante la ejecución,
- pantallas de carga configurables, niebla por distancia, colores de vértice de las mallas e iluminación de vértices mediante GTE,
- conectividad recursiva de Room y Portal y navegación sobre una cuadrícula preprocesada que tiene en cuenta la altura,
- clips independientes y simultáneos de Animation para GameObjects, interfaz, vibración y eventos de animación esquelética,
- líneas de tiempo compactas para cinemáticas, con vista previa en Game View, eventos, pistas de interfaz y niebla y bloqueo opcional del control del jugador,
- animación FBX con skinning rígido y presupuestos limitados de geometría y matrices para PS1,
- un inspector interactivo de distribución de VRAM para framebuffers, páginas de textura, espacio ocupado y CLUT,
- Lua Behaviours con una API estricta en PascalCase, diagnósticos del editor, recarga en caliente, definiciones generadas para el servidor de lenguaje y validación de bytecode de PS1,
- sistemas nativos de jugador, interacción, cámara, colisión, iluminación, audio, animación y guardado,
- validación de PS1, informes de presupuestos, preparación de recursos y empaquetado de discos.
Mapa de la documentación
| Sección | Para qué sirve |
|---|---|
| Inicio rápido | Abrir un proyecto, validarlo y generar la primera compilación de PS1 |
| Estructura del proyecto | Comprender Assets, Library, Scenes y Build |
| Polygon: Last Exit | Conocer el proyecto de referencia básico incluido y el flujo de pruebas iniciales |
| Laboratorio de funciones avanzadas | Validar animación esquelética, líneas de tiempo, portales, navegación, varios lienzos, SaveData y vibración |
| Tutorial del primer proyecto | Crear un juego en primera persona de dos habitaciones con Lua, interfaz, audio, un trigger y guardado en tarjeta de memoria |
| Project Hub | Crear, registrar, buscar, reabrir y reparar entradas de proyectos locales |
| Manual del editor | Conocer los paneles principales y el flujo de trabajo recomendado |
| Level Builder | Crear recursos de malla reutilizables dentro del editor |
| UV Editor | Desplegar, distribuir, inspeccionar y ajustar las coordenadas UV de las mallas para texturas de PS1 |
| Advanced Scene Authoring | Configurar renderizado, carga e interfaz, habitaciones y navegación, cinemáticas y animaciones independientes |
| VRAM Inspector | Inspeccionar la distribución física de VRAM planeada para la escena actual |
| Administración de escenas | Configurar escenas de compilación, transiciones, carga y datos persistentes |
| Visibilidad y descarte de geometría | Comprender el proceso conservador de visibilidad durante la ejecución y sus reglas de creación |
| Habitaciones, portales y navegación | Crear conexiones entre habitaciones y rutas preprocesadas para la ejecución |
| Cinemáticas y líneas de tiempo | Crear y activar secuencias compactas dentro del engine |
| Animaciones independientes | Crear clips simultáneos para GameObjects, interfaz, vibración y eventos de animación esquelética |
| Componentes | Comprender el modelo de GameObjects y componentes |
| Procesamiento de recursos | Importar modelos estáticos, animación esquelética, texturas, materiales y audio |
| Programación en Lua | Implementar la lógica del juego con la API de ejecución actual |
| Flujo de trabajo de programación en Lua | Configurar herramientas, exponer propiedades en el Inspector, diagnosticar scripts y conservar la coherencia con PS1 |
| Recetas prácticas | Copiar patrones comunes de jugabilidad, como objetos recolectables, puertas, botones de interfaz y guardado y carga |
| Proceso de compilación | Validar, preparar recursos, seleccionar el entorno de ejecución y empaquetar los archivos de PS1 |
| Solución de problemas | Diagnosticar fallos comunes de compilación y ejecución |
| Arquitectura de PS1 | Comprender el modelo de hardware que explica las restricciones del engine |
| Referencia de producción para PS1 | Mantenerse dentro de los límites de memoria y renderizado de PlayStation |
Alcance de la documentación
Este manual documenta el flujo de trabajo público y la API actuales. Los nombres de la referencia de Lua son exactos y distinguen entre mayúsculas y minúsculas; los alias no declarados no forman parte del contrato de ejecución. Cuando una función solo admite un flujo limitado compatible con PS1, la documentación indica ese alcance de forma explícita.
Conserva respaldos del proyecto y ejecuta Build > Tools & Diagnostics > Build with Readiness Checks después de abrir un proyecto antiguo. Polygon Engine actualiza de forma transaccional los documentos compatibles de proyectos, escenas y Prefabs antes de guardarlos. Los documentos creados con un formato más reciente no compatible se rechazan en lugar de reescribirse. Los límites de plataformas, mandos, emuladores y hardware se enumeran en Plataformas compatibles y limitaciones.
Cómo orientarte
La API de Lua llama GameObject a los objetos de la escena. En el editor, créalos desde Scene > Create Entity. El campo Target Entity de un botón de interfaz selecciona el GameObject que recibe su callback.
Después de actualizar el editor, regenera el espacio de trabajo Lua del proyecto para que tu editor de código muestre las funciones y los argumentos disponibles. Usa la Referencia de la API de Lua junto con los ejemplos de programación.