UI Canvas

Las escenas Polygon Engine pueden contener hasta ocho Canvas de UI con nombre. Esta es la ruta preferida para menús, HUD, indicaciones, texto de progreso y botones que se pueden pulsar en el juego.

Usa UI.DrawText() para el texto temporal de script/debug. Utiliza lienzos de interfaz de usuario de autor para la interfaz de usuario de juego real.

Modelo de lienzo

Cada escena contiene un lienzo Main requerido con ID 0 y un tamaño de referencia predeterminado de 320 x 240. Agrega y configura lienzos en View > Advanced Scene Authoring > Loading & UI.

Campo	Significado
Name	Nombre de lienzo local de escena utilizado por el editor, Interactable y Lua
Enabled	Si el lienzo está activo
Sort Order	Ordenación de dibujo de tiempo de ejecución a nivel de lienzo, sujeta a -1024..1024
Reference Width	Ancho de diseño de lienzo, 1..4096
Reference Height	Altura de diseño de lienzo, 1..4096
Elements	Panel, Button, Text, Image y ProgressBar
Bitmap Fonts	Hasta tres definiciones de fuente de atlas de textura y una escena predeterminada

El lienzo Main no se puede eliminar. La eliminación de otro lienzo mueve sus elementos a Main, elimina sus relaciones de jerarquía y borra las referencias de Canvas de aviso interactivo que nombran el lienzo eliminado. Cambiar el nombre de un lienzo actualiza esas referencias.

Los identificadores de elementos de la interfaz de usuario siguen siendo globales y estables en todos los lienzos. Asigna un elemento a través del campo Canvas en su Inspector. Mover un padre mueve su subárbol a ese lienzo; las relaciones padre-hijo no pueden cruzar los límites del lienzo.

El tiempo de ejecución de PS1 resuelve cada elemento frente a su resolución de referencia de lienzo. La interfaz de usuario visible se dibuja determinísticamente utilizando el orden de clasificación de lienzo, el orden de clasificación de elementos, la profundidad de jerarquía y el orden de origen. La visibilidad de Canvas combina la bandera habilitada para la interfaz de usuario de escena, la bandera habilitada para el canvas y cualquier visibilidad temporal del aviso de Interactable.

Tipos de elementos

Elemento	Uso típico
Panel	Fondos sólidos, barras HUD, agrupar contenedores
Text	Etiquetas, indicaciones, progreso, texto del menú
Image	Logos, iconos, elementos de textura creados
Button	Acciones de menú seleccionables con navegación y callbacks de script
ProgressBar	Valor de HUD 0.0..1.0 delimitado horizontal o vertical

Los elementos pueden ser padres de otros elementos de la interfaz de usuario. La visibilidad de los padres afecta la visibilidad del elemento hijo en tiempo de ejecución.

Propiedades comunes

Propiedad	Aplica a	Descripción
Name	Todos	Nombre estable utilizado por Lua lookup
Enabled	Todos	Visibilidad en tiempo de ejecución
Rect Transform	Todos	Posición y tamaño en relación con el padre/lienzo
Local Scale	Todos	Escala visual X/Y alrededor del pivote, 0..4, heredada por los hijos
Sort Order	Todos	Orden de dibujo
Color	Panel, Button, Image	Color de relleno o tinte
Texture GUID	Image, elementos con textura	Referencia de textura importada
Text	Text, Button	Cadena mostrada
Text Color	Text, Button	Color del texto
Text Align	Text, Button	Izquierda, centro o derecha
Visible Characters (-1 = all)	Text, Button	Prefijo visible en bytes, -1..127; los renglones usan el texto completo
Interactable	Button	Permite el enfoque y la activación
Navigation	Button	Movimiento de enfoque explícito o automático
On Click	Button	Nombre de la función Lua que se invoca
Bitmap Font	Text, Button	Nombre de la fuente de escena, escala de enteros 1..4, espaciado de letras y ajuste de línea por palabras
Progress Value	ProgressBar	Fracción rellena, sujeta a 0.0..1.0
Progress Fill Color	ProgressBar	Color de la región rellena
Vertical	ProgressBar	Llenar de abajo a arriba en lugar de izquierda a derecha

Paneles y botones con textura

Asigna una textura importada a un Panel, Button o Image. Usa Color blanco para su brillo original y Text Color para su etiqueta; son tintes independientes. Con Preserve Aspect deshabilitado, el arte se estira sobre el rectángulo; habilítalo para ajustar un icono sin deformarlo. Asignar una textura a un Button desactiva inicialmente Preserve Aspect: revísalo después de asignarla. No existe un ajuste de bordes nine-slice; prepara marcos distintos para proporciones muy diferentes. El foco del botón conserva el resaltado nativo.

Para una mira o un icono recortado, importa un PNG con píxeles transparentes y elige Alpha Mode: Mask1Bit. Evita colocar un Panel opaco detrás si el diseño no lo necesita. Da contraste al texto claro con un panel o fondo oscuro y pruébalo sobre zonas claras y oscuras del juego a la resolución de destino.

Usa Rect Transform > Animate UI... para animar posición, escala y tinte. Consulta Animaciones independientes para previsualizar, capturar valores y usar tiempo sin escalar. Lua controla Visible Characters para la escritura progresiva; consulta Scripting: UI.

Bitmap Fonts

Definir fuentes de mapa de bits en Advanced Scene Authoring > Loading & UI. Una fuente hace referencia a un atlas de textura importado y declara ancho/altura de glifo, carácter de primer byte, recuento de glifos, columnas de atlas, espaciado de letras y espaciado de líneas. La cuadrícula declarada requiere glyphWidth * columns por píxeles glyphHeight * ceil(glyphCount / columns). Debe permanecer dentro de la dimensión de textura PS1 256 x 256 y caber dentro de las dimensiones de salida importadas reales del atlas.

La validación de compilación comprueba este ancho y alto importados para cada escena en Build Settings, no solo la escena activa. Vuelva a importar un atlas cuando faltan o están obsoletos sus metadatos de dimensión importados; una compilación falla si la cuadrícula de glifos declarada no se ajusta a la textura importada.

Define una fuente predeterminada para la escena o selecciona otra en elementos Text o Button individuales. La escala de fuentes está restringida a la escala de sprite de número entero desde 1 hasta 4. El tiempo de ejecución de PS1 alinea cada línea renderizada a la izquierda, al centro o a la derecha dentro del rectángulo de elementos. Con Word Wrap habilitado, se envuelve en el último espacio disponible y vuelve a un límite de carácter cuando una sola palabra es más ancha que la línea.

Canvas Default usa la fuente configurada para la escena o la fuente integrada cuando no se encuentra una fuente definida. Font Scale también funciona con esa fuente integrada tanto en el editor como en PS1, así que no necesitas un atlas propio para ampliar el texto. Los valores fraccionarios se redondean a la escala entera compatible más cercana.

Las fuentes de mapa de bits son atlas de caracteres de bytes de cuadrícula fija, no fuentes vectoriales o un sistema de modelado Unicode dinámico.

Programación durante la ejecución

Lua puede controlar la interfaz de usuario de autor con el módulo UI:

local promptId = -1
local healthId = -1
local hudCanvas = -1

function Start(gameObjectId)
    hudCanvas = Canvas.Find("HUD")
    promptId = UI.Find("Prompt Text")
    healthId = UI.Find("Health")
    Canvas.SetEnabled(hudCanvas, true)
    Text.SetText(promptId, "Press Cross")
    Graphic.SetEnabled(promptId, true)
    ProgressBar.SetValue(healthId, 1.0)
end

function Update(gameObjectId, dt)
    if Input.GetButtonDown(Input.CROSS) then
        Text.SetText(promptId, "Activated")
    end
end

ProgressBar.SetValue(elementId, value) fija el valor a 0.0..1.0 y devuelve false cuando el identificador de elemento no existe.

Las funciones de Canvas son:

• Canvas.Find(name) devuelve un ID de lienzo o -1;
• Canvas.SetEnabled(canvasId, enabled) devuelve un booleano;
• Canvas.IsEnabled(canvasId) devuelve false para un ID que falta;
• Canvas.SetSortOrder(canvasId, sortOrder) limita el valor a -1024..1024;
• Canvas.GetCount() devuelve el recuento de lienzos creados de la escena activa.

Para ver la API completa, consulta Scripting: UI.

Callbacks de botones

Un botón puede llamar a una función Lua a través de su configuración On Click. La validación de compilación comprueba si la función de script referenciada existe cuando puede resolver el destino.

Mantén las callbacks de botón pequeñas. Úsalas para cargar escenas, actualizar el estado de guardado, cambiar el enfoque o llamar a una función de juego.

Límites de PS1

El tiempo de ejecución actual tiene presupuestos fijos de ocho lienzos de interfaz de usuario, 32 elementos de interfaz de usuario en esos lienzos y tres fuentes de mapa de bits por escena. Mantén la interfaz de usuario simple:

• reutiliza paneles,
• prefiere textos cortos,
• evitar elementos anidados innecesarios,
• mantén pequeños los elementos de UI que usan texturas,
• Validar la escena antes de construir.

Los elementos deshabilitados y las fuentes siguen contando en el presupuesto. Ocultar un Canvas no descarga sus assets. Last Exit reutiliza elementos para inventario y baúl, y usa UI de escena para menús, diálogos y ayudas.