v0.7.1 (build 925)
Koya home

UI/Renderable: Shared properties

Common properties and runtime controls available to all renderables and elements.

What this page covers #

Shared renderable and element-level properties that apply across box, panel, sprite, text, mesh, and circle.

By task #

Common properties shared by all renderables and element containers. These can be passed at creation to UI.createElement or adjusted later via runtime APIs.

Import #

import * as UI from 'Helix/UserInterface';

Element structure #

ElementOptions
Full element creation options passed to UI.createElement(windowId, options).
  • renderable object optional - Renderable-specific options (box, panel, sprite, text, mesh, circle) plus shared transform properties.
  • renderable.position { x, y } optional - Pixel offset for the renderable.
  • renderable.origin { x, y } optional - Transform pivot for rotation/scale. Values 0..1 are normalized; outside that range are pixel-space.
  • renderable.scale { x, y } optional - Scale factor per axis.
  • renderable.rotation number optional - Rotation in degrees.
  • inheritAnimation boolean optional - Whether this element inherits parent animation transforms. Default true.
  • layout object optional - Container layout properties (see UI/Layout).
  • item object optional - Child layout properties (see UI/Layout).
  • contentAlign { x?, y? } | 'fill' optional - Aligns the renderable inside the layout slot, or 'fill' to fill outer bounds.
  • contentPositioning 'raw' | 'contain' optional - Whether content is clamped inside the slot (contain) or allowed to overflow (raw).
  • layoutOrder number optional - Sibling sort order.

Origins and transforms (important) #

There are three different "origin" concepts in UI. They affect different layers:

  • renderable.origin (create-time) / UI.setOrigin (runtime) — the renderable transform pivot used for rotation and scale. Values in the range 0..1 are treated as normalized pivots resolved from the renderable's current local bounds. Values outside 0..1 are treated as pixel-space pivots.
  • frame.origin in sprite/panel frame data — per-frame renderable metadata belonging to the renderable definition (atlas frame), not to layout.
  • Element layout bounds (item.size, layout, contentAlign) — control where renderables are placed in the UI tree. They do not define the renderable transform pivot.
Note

If you need a stable, explicit pivot for animation/rotation, set renderable.origin and avoid overloading frame metadata for element-level intent.

Shared transform API #

UI.setPosition
Set the renderable's pixel offset.
UI.setPosition(windowId, id, { x, y })
UI.setOrigin
Set the transform pivot. 0..1 = normalized; outside = pixel-space.
UI.setOrigin(windowId, id, { x, y })
UI.setScale
Set the renderable's scale factor per axis.
UI.setScale(windowId, id, { x, y })
UI.setEnabled
Enable or disable the element.
UI.setEnabled(windowId, id, boolean)
UI.setInheritAnimation
Control whether this element inherits parent animation transforms.
UI.setInheritAnimation(windowId, id, boolean)

Measurement helpers #

UI.getRenderableBounds
Get the local AABB of the renderable.
UI.getRenderableBounds(windowId, id): { min, max, centre, size }
UI.getRenderableSize
Get renderable width and height.
UI.getRenderableSize(windowId, id): { x, y }
UI.getElementFrame
Get element bounds AABB.
UI.getElementFrame(windowId, id): { min, max, centre, size }

Notes #

  • Set creation-time transforms on renderable (position, origin, scale, rotation).
  • rotation can be changed at runtime via the animation system (no direct setter yet).
  • offset exists internally on renderables but is not exposed in the JS API; use position/origin instead.

Shader and texture overrides #

UI.setShader
Override the element's shader with custom SPIR-V.
  • blend may also be provided as blendMode.
  • Supported blend modes: 'premultiplied-alpha' (default), 'opaque', 'additive', and 'alpha'.
UI.setShader(windowId, id, { vert, frag, blend?: BlendMode })
UI.clearShader
Revert to the default shader.
UI.clearShader(windowId, id)
UI.setTexture
Set a texture on the renderable.
UI.setTexture(windowId, id, path)
UI.clearTexture
Remove the texture from the renderable.
UI.clearTexture(windowId, id)
Note

Text renderables ignore setTexture; their texture is the font atlas.

Layout API #

UI.setLayout
Update container layout properties.
UI.setLayout(windowId, id, { type, wrap?, wrapLimit?, gap?, padding?, justifyContent?, alignItems?, gridColumns?, gridRows?, columnGap?, rowGap?, gridFlowByRow?, gridAlignItems?, gridJustifyItems? })
UI.setMargin
Set a child's margin.
UI.setMargin(windowId, id, { t?, r?, b?, l? })
UI.setLayoutSize
Set child width/height.
UI.setLayoutSize(windowId, id, { x?, y? })
UI.setLayoutPosition
Set child absolute layout position (item.absolutePosition).
UI.setLayoutPosition(windowId, id, { x, y })
UI.setLayoutAABB
Set child absolute layout rectangle (item.absoluteAABB).
UI.setLayoutAABB(windowId, id, { min, max })
UI.setGrow
Set the child's flexGrow value.
UI.setGrow(windowId, id, number)
UI.setContentPositioning
Control whether content is clamped inside the slot or allowed to overflow.
UI.setContentPositioning(windowId, id, 'raw' | 'contain')

Content alignment API #

Note

UI.setPosition() moves the renderable transform. Use UI.setLayoutPosition() / UI.setLayoutAABB() when you need layout-space placement.

UI.setContentAlign
Align the renderable within its layout slot.
  • The slot is the child's item.size if specified; otherwise the size computed by the parent.
  • Requires that the element is positioned by a container with layout.type. Without a parent container, contentAlign has no effect; use origin/position instead.
  • Exception: specifying a child item.size on an absolutely positioned element allows contentAlign to work even without a parent layout.
  • Special 'fill': requests the renderable to fill the element's OUTER bounds (ignores padding). Only renderables that opt in will resize geometry (currently box).
UI.setContentAlign(windowId, id, { x?: 'start'|'center'|'end', y?: 'start'|'center'|'end' } | 'fill')

Animation #

All renderables support keyframed animation of transforms and colour. Colours accept arrays [r,g,b,a] (0..1) or hex strings (#RGB, #RGBA, #RRGGBB, #RRGGBBAA, 0xRRGGBB[AA]):

const a = UI.addAnimation(win, id, [
  { time: 0.0, position: { x: 0, y: 0 } },
  { time: 0.3, ease: 'outCubic', position: { x: 40, y: 0 }, scale: { x: 1.1, y: 1.1 } },
  { time: 0.6, ease: 'inOutQuad', rotation: 10, colour: [1,1,1,0.8] },
  { time: 1.0, position: { x: 0, y: 0 }, rotation: 0 }
]);
UI.startAnimation(win, id, a);

Supported keyframe fields: position, origin, scale, rotation (degrees), colour/color (array or hex), and advanced noise options for procedural motion. See UI/Animation for full reference.

Z-ordering and layers #

Elements render back-to-front by layer, then by Y stacking for sprites where applicable. A dedicated layer setter may be added in future; for now prefer scene ordering and Y positioning.

Sibling order #

  • Children of a container are kept sorted by a per-child order key.
  • Set at creation: order or layoutOrder in UI.createElement options.
  • Change at runtime: UI.setLayoutOrder(windowId, id, number); only affected parents are resorted.

Hit-testing #

Virtual handlers enable hit testing and receive one event object. See /helix-input for recognition and ownership.

<- UI/LayoutUI/Renderable: Box ->