UI Canvas

Polygon Engine scenes can contain up to eight named UI canvases. This is the preferred path for menus, HUD, prompts, progress text, and clickable buttons that ship with the game.

Use UI.DrawText() for temporary script/debug text. Use authored UI canvases for real gameplay UI.

Canvas Model

Every scene contains a required Main canvas with ID 0 and a default reference size of 320 x 240. Add and configure canvases under View > Advanced Scene Authoring > Loading & UI.

Field	Meaning
Name	Scene-local canvas name used by the editor, Interactable, and Lua
Enabled	Whether the canvas is active
Sort Order	Canvas-level runtime draw ordering, clamped to -1024..1024
Reference Width	Canvas design width, 1..4096
Reference Height	Canvas design height, 1..4096
Elements	Panels, Buttons, Text, Images, and ProgressBars
Bitmap Fonts	Up to three texture-atlas font definitions and a scene default

The Main canvas cannot be removed. Removing another canvas moves its elements to Main, clears their parent links, and clears Interactable Prompt Canvas references that named the removed canvas. Renaming a canvas updates those references.

UI element IDs remain global and stable across all canvases. Assign an element through the Canvas field in its Inspector. Moving a parent moves its subtree to that canvas; parent-child relationships cannot cross canvas boundaries.

The PS1 runtime resolves each element against its canvas reference resolution. Visible UI is drawn deterministically using canvas sort order, element sort order, hierarchy depth, and source order. Canvas visibility combines the scene UI enabled flag, the canvas enabled flag, and any temporary Interactable prompt visibility.

Element Types

Element	Typical use
Panel	Solid backgrounds, HUD bars, grouping containers
Text	Labels, prompts, progress, menu text
Image	Logos, icons, authored texture elements
Button	Selectable menu actions with navigation and script callbacks
ProgressBar	Horizontal or vertical bounded 0.0..1.0 HUD value

Elements can be parented to other UI elements. Parent visibility affects child visibility at runtime.

Common Properties

Property	Applies to	Description
Name	All	Stable name used by Lua lookup
Enabled	All	Runtime visibility
Rect Transform	All	Position and size relative to parent/canvas
Local Scale	All	Visual X/Y scale around the pivot, 0..4, inherited by children
Sort Order	All	Draw order
Color	Panel, Button, Image	Fill or tint color
Texture GUID	Image, textured elements	Imported texture reference
Text	Text, Button	Displayed string
Text Color	Text, Button	Text color
Text Align	Text, Button	Left, center, or right
Visible Characters (-1 = all)	Text, Button	Revealed byte prefix, -1..127; wrapping still uses the complete text
Interactable	Button	Allows focus and activation
Navigation	Button	Explicit or automatic focus movement
On Click	Button	Lua function call target
Bitmap Font	Text, Button	Scene font name, integer scale 1..4, letter spacing, and word wrap
Progress Value	ProgressBar	Filled fraction, clamped to 0.0..1.0
Progress Fill Color	ProgressBar	Filled-region color
Vertical	ProgressBar	Fill bottom-to-top instead of left-to-right

Textured panels and buttons

Assign an imported texture to a Panel, Button or Image. Use white Color for its original brightness and Text Color for its label; these are separate tints. With Preserve Aspect disabled, artwork stretches over the element rectangle; enable it to fit an icon without distortion. Assigning a texture to a Button initially turns Preserve Aspect off, so review it after assignment. There is no nine-slice border setting: prepare separate frame art for substantially different proportions. Button focus still adds the native selection treatment.

For a reticle or item cutout, import a PNG with transparent pixels and choose Alpha Mode: Mask1Bit. Do not put an opaque Panel behind it unless the design needs one. Give bright text a contrasting panel or dark background and check it over both light and dark gameplay at the target resolution.

Use Rect Transform > Animate UI... for keyframe motion, scale and tint. See Standalone Animations for preview, capture and unscaled playback. Visible Characters is controlled by Lua for typewriter timing; see Scripting: UI.

Bitmap Fonts

Define bitmap fonts in Advanced Scene Authoring > Loading & UI. A font references an imported texture atlas and declares glyph width/height, first byte character, glyph count, atlas columns, letter spacing, and line spacing. The declared grid requires glyphWidth * columns by glyphHeight * ceil(glyphCount / columns) pixels. It must remain within the PS1 256 x 256 texture dimension and fit inside the atlas's actual imported output dimensions.

Build validation checks this imported width and height for every scene in Build Settings, not only the active scene. Reimport an atlas when its imported dimension metadata is missing or stale; a build fails if the declared glyph grid does not fit the imported texture.

Set a scene default or override the font on individual Text/Button elements. Font scale is restricted to whole-number sprite scaling from 1 through 4. The PS1 runtime aligns each rendered line left, center, or right within the element rectangle. With Word Wrap enabled, it wraps at the last available space and falls back to a character boundary when a single word is wider than the line.

Canvas Default uses the configured scene font or the built-in font when no authored font resolves. Font Scale also works with that built-in font in both the editor and PS1 runtime, so a custom atlas is not required for larger text. Fractional values round to the nearest supported integer scale.

Bitmap fonts are fixed-grid byte-character atlases, not vector fonts or a dynamic Unicode shaping system.

Runtime Scripting

Lua can control authored UI with the UI module:

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) clamps the value to 0.0..1.0 and returns false when the element id does not exist.

Canvas functions are:

• Canvas.Find(name) returns a canvas ID or -1;
• Canvas.SetEnabled(canvasId, enabled) returns a boolean;
• Canvas.IsEnabled(canvasId) returns false for a missing ID;
• Canvas.SetSortOrder(canvasId, sortOrder) clamps to -1024..1024;
• Canvas.GetCount() returns the active scene's authored canvas count.

For the full API, see Scripting: UI.

Button Callbacks

A Button can call a Lua function through its On Click settings. The build validation checks whether the referenced script function exists when it can resolve the target.

Keep button callbacks small. Use them to load scenes, update save state, change focus, or call a gameplay function.

PS1 Limits

The current runtime has fixed budgets of eight UI canvases, 32 UI elements across those canvases, and three bitmap fonts per scene. Keep UI simple:

• reuse panels,
• prefer short text,
• avoid unnecessary nested elements,
• keep texture-backed UI elements small,
• validate the scene before building.

Disabled elements and fonts remain part of the scene budget. Hiding a Canvas does not unload its assets. The Last Exit example reuses elements for its pack and item-box layouts and uses authored UI for menus, dialogue and prompts.