UI and Canvas

Polygon Engine UI is authored as named Canvases containing Panel, Text, Image, Button, and Progress Bar elements. Use typed tables to change only the property owned by that element or component. UI.DrawText remains available for transient diagnostics.

Lookup

UI.Find(name) returns a scene-global element ID or -1. Canvas.Find(name) returns a Canvas ID or -1. Cache both IDs in Start.

UI.GetCount() and Canvas.GetCount() report authored counts. UI.GetType(elementId) returns the element type code or nil for a missing ID:

Code	Element
0	Panel
1	Button
2	Text
3	Image
4	Progress Bar

Canvas Visibility and Order

Method	Purpose
Canvas.SetEnabled(canvasId, enabled)	Shows or hides one Canvas.
Canvas.IsEnabled(canvasId)	Reads Canvas visibility.
Canvas.SetSortOrder(canvasId, sortOrder)	Changes draw order in the validated range.

An Interactable Prompt Canvas also has transient range visibility. That gate does not overwrite the enabled value set through Canvas.SetEnabled.

Element APIs

Table	Methods
Text	Text.SetText(elementId, text), Text.GetText(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)
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)

Positions and sizes return two scalar values. Colors use 8-bit RGBA channels; alpha defaults to 255. Progress values are clamped to 0.0..1.0. Image texture changes use the imported texture GUID, not a source filename.

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

Controller Navigation and Buttons

Buttons use authored automatic or explicit navigation. Selectable.Select moves focus, while Button.SetInteractable removes or restores a Button as a valid selection and submit target.

On submit, the configured function runs on the target Lua Behaviour with:

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

The first argument is the target GameObject ID, followed by the Button element ID, element name, and "click". The authored Function field must match exactly. Keep callbacks small and move longer flows into normal script state updated by Update.

Immediate Debug Text

UI.DrawText(x, y, text) queues text for one frame:

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

Use authored Text for shipping HUDs and menus so layout, fonts, visibility, and focus remain consistent.

PS1 Limits

One scene supports up to eight Canvases, 32 authored UI elements across them, and three bitmap fonts. Build validation also checks font glyph grids against the imported atlas dimensions. Keep hierarchy and text short, reuse Panels, and test controller navigation at 320x240.

See UI Canvas for authoring and bitmap fonts.