UI y Canvas

La UI de Polygon Engine se organiza en Canvas con nombre que contienen elementos Panel, Text, Image, Button y Progress Bar. Usa las tablas de la API específicas de cada tipo para modificar las propiedades de ese elemento o componente. UI.DrawText sigue disponible para diagnósticos temporales.

Consulta

UI.Find(name) devuelve un ID de elemento global de la escena o -1. Canvas.Find(name) devuelve un ID de Canvas o -1. Guarda ambos ID en caché en Start.

UI.GetCount() y Canvas.GetCount() devuelven las cantidades de elementos creados. UI.GetType(elementId) devuelve el código de tipo del elemento o nil si el ID no existe:

Código	Elemento
0	Panel
1	Button
2	Text
3	Image
4	Progress Bar

Visibilidad y orden de Canvas

Método	Finalidad
`Canvas.SetEnabled(canvasId, enabled)`	Muestra u oculta un Canvas.
`Canvas.IsEnabled(canvasId)`	Consulta la visibilidad del Canvas.
`Canvas.SetSortOrder(canvasId, sortOrder)`	Cambia el orden de dibujo dentro del intervalo validado.

Un Canvas interactivo también tiene una condición temporal de visibilidad según la distancia. Esa condición no sobrescribe el estado habilitado que se establece mediante Canvas.SetEnabled.

API de elementos

Tabla	Métodos
`Text`	`Text.SetText(elementId, text)`, `Text.GetText(elementId)`, `Text.SetVisibleCharacterCount(elementId, count)`, `Text.GetVisibleCharacterCount(elementId)`, `Text.SetColor(elementId, r, g, b[, a])`, `Text.GetColor(elementId)`
`Image`	`Image.SetTexture(elementId, textureGuid)`, `Image.GetTexture(elementId)`
`Button`	`Button.SetInteractable(elementId, interactable)`, `Button.IsInteractable(elementId)`
`RectTransform`	`RectTransform.SetPosition(elementId, x, y)`, `RectTransform.GetPosition(elementId)`, `RectTransform.SetSize(elementId, width, height)`, `RectTransform.GetSize(elementId)`, `RectTransform.SetScale(elementId, x, y)`, `RectTransform.GetScale(elementId)`
`Graphic`	`Graphic.SetColor(elementId, r, g, b[, a])`, `Graphic.GetColor(elementId)`, `Graphic.SetEnabled(elementId, enabled)`, `Graphic.IsEnabled(elementId)`
`Selectable`	`Selectable.Select(elementId)`, `Selectable.GetSelected()`
`ProgressBar`	`ProgressBar.SetValue(elementId, value)`, `ProgressBar.GetValue(elementId)`

Las posiciones y tamaños devuelven dos valores escalares. Los colores usan canales RGBA de 8 bits; los valores predeterminados alfa son 255. Los valores de progreso se fijan a 0.0..1.0. Los cambios de textura de la imagen usan el GUID de textura importado, no un nombre de archivo de origen.

Image.SetTexture e Image.GetTexture también funcionan con Buttons y Panels con textura en Play Mode y PS1. Úsalos en elementos con imagen, no Text. Si el elemento no existe, el setter devuelve false y el getter nil. En PS1, el setter también devuelve false si el GUID está vacío o la textura aún no está cargada. Asignarla en Play Mode no demuestra que esté disponible en disco. Referencia cada textura posible en la UI de la escena, incluso en elementos inicialmente deshabilitados, para incluirla en la compilación. La UI oculta sigue contando en los presupuestos de elementos, texturas y VRAM. Usa Graphic.SetEnabled para ocultar una imagen de inspección vacía; un slot vacío no debe conservar la imagen del objeto anterior.

local hudCanvasId = -1
local statusTextId = -1
local healthBarId = -1
local resumeButtonId = -1

function Start(gameObjectId)
  hudCanvasId = Canvas.Find("HUD")
  statusTextId = UI.Find("Status Text")
  healthBarId = UI.Find("Health")
  resumeButtonId = UI.Find("Resume Button")

  Canvas.SetEnabled(hudCanvasId, true)
  Text.SetText(statusTextId, "READY")
  ProgressBar.SetValue(healthBarId, 1.0)
  Selectable.Select(resumeButtonId)
end

function SetHealth(gameObjectId, currentHealth, maximumHealth)
  local value = maximumHealth > 0 and currentHealth / maximumHealth or 0.0
  ProgressBar.SetValue(healthBarId, value)
end

Los Buttons usan la navegación automática o explícita configurada en el editor. Selectable.Select mueve el foco; Button.SetInteractable determina si un Button se puede seleccionar y activar.

Al enviar, la función configurada se ejecuta en el Lua Behaviour de destino con:

function OpenLevel(gameObjectId, elementId, elementName, eventName)
  if eventName == "click" then
    SceneManager.LoadScene("Scenes/level.json")
  end
end

El primer argumento es el ID del GameObject de destino, seguido del ID del Button, su nombre y "click". El campo Function configurado debe coincidir exactamente. Mantén breves los callbacks y procesa los flujos más largos mediante el estado del script actualizado por Update.

Texto de depuración inmediata

UI.DrawText(x, y, text) pone en cola el texto de un cuadro:

function Update(gameObjectId, deltaTime)
  UI.DrawText(8, 8, "Debug build")
end

Usa elementos Text creados en el editor para los HUD y menús de la versión final, de modo que la distribución, las fuentes, la visibilidad y el foco se mantengan consistentes.

Límites de PS1

Una escena admite hasta ocho Canvas, 32 elementos de interfaz de usuario creados en ellos y tres fuentes de mapa de bits. La validación de compilación también comprueba las cuadrículas de glifos de fuentes contra las dimensiones importadas del atlas. Mantén la jerarquía y el texto cortos, reutiliza los paneles y prueba la navegación del controlador a 320x240.

Consulta UI Canvas para crear la interfaz y configurar fuentes de mapa de bits.

Texto progresivo y escala visual

Text.SetVisibleCharacterCount revela un prefijo sin cambiar los renglones ni la alineación. Usa -1 para mostrar todo, 0 para ocultar los glifos o 1..127 para un prefijo en bytes. Las fuentes son atlas por byte: espacios y saltos cuentan; no se ofrece composición Unicode. El setter acepta Text y Button; devuelve false si el ID no existe, el tipo no corresponde o el número está fuera de -1..127. Limita cada etiqueta o página de PS1 a 127 bytes. GetVisibleCharacterCount consulta el límite. SetColor / GetColor de Text cambian el tinte del texto separado del fondo de Graphic.

local label = UI.Find("Dialogue Text")
Text.SetText(label, "The full sentence stays in the layout.")
Text.SetVisibleCharacterCount(label, 0)
Text.SetVisibleCharacterCount(label, 12)
Text.SetVisibleCharacterCount(label, -1)
Text.SetColor(label, 223, 222, 194, 255)
RectTransform.SetScale(UI.Find("Dialogue Panel"), .96, .96)

RectTransform.SetScale / GetScale exponen una transformación X/Y alrededor del pivote entre 0 y 4, heredada por hijos y geometría de navegación. La escala cero quita el foco a esa jerarquía. Usa fuentes bitmap importadas para escalar texto; la fuente de depuración conserva su tamaño fijo. La transparencia de PS1 usa mezcla por hardware: es preferible animar tinte RGB y movimiento al alfa suave.

El dialogue.lua de Last Exit usa tiempo sin escalar, pausas de puntuación y estados de entrada/escritura/espera/cambio/salida. Cruz completa las letras antes de que otra pulsación avance o confirme; Círculo cancela. Controls > Cuadrado alterna escritura progresiva/texto instantáneo. Las reglas siguen en flow.lua.

Temporizador de escritura progresiva

Crea un elemento Text habilitado llamado Dialogue Text con una fuente bitmap. Este behaviour mínimo revela 30 bytes por segundo, incluso durante una pausa. Asigna la cadena completa una sola vez para que las letras no cambien de renglón conforme aparecen.

local label = -1
local line = "The warehouse is locked."
local elapsed = 0
local visible = 0

function Start(gameObjectId)
  label = UI.Find("Dialogue Text")
  elapsed, visible = 0, 0
  Text.SetText(label, line)
  Text.SetVisibleCharacterCount(label, 0)
end

function Update(gameObjectId, deltaTime)
  if label < 0 or visible >= #line then return end
  elapsed = elapsed + Time.UnscaledDeltaTime()
  local nextCount = math.min(#line, math.floor(elapsed * 30))
  if Input.GetButtonDown(Input.CROSS) then nextCount = #line end
  if nextCount ~= visible then
    visible = nextCount
    Text.SetVisibleCharacterCount(label, visible)
  end
end

Para un diálogo completo, controla avanzar/cancelar por separado y consume la pulsación que completa el texto antes de aceptar otra para avanzar. Anima el panel con Animaciones independientes; deshabilita su Canvas solo cuando termine la salida. Reproduce el sonido de apertura al pasar de cerrado a abierto, en lugar de hacerlo en cada Update o por cada letra.

Consulta​

Visibilidad y orden de Canvas​

API de elementos​

Navegación y botones del controlador​

Texto de depuración inmediata​

Límites de PS1​

Texto progresivo y escala visual​

Temporizador de escritura progresiva​