Skip to Content
defold-typescript libraries
Pause-Gamesflow

Pause-Games/flow/flow.ui

Flow's gui_script renderer: mounts onto a script's self, renders an element tree to runtime GUI nodes and routes input to it.

  • GitHub: Pause-Games/flow — pinned to 1.0.0
    1. Pick a release from Pause-Games/flow releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as ui from "flow.ui"

Functions

register(type_name: string, def: LuaTable): LuaTable

Register a custom element type definition. Every element type string ("box", "text", "button", etc.) must be registered before it can appear in a UI tree. The definition describes how to create, update, and interact with the corresponding Defold GUI node.

Required fields in def: create_node(el) -> userdata — creates and returns a new gui node

Optional fields in def: apply(self, el, node, alpha) — update node visuals each frame is_visible(el) -> boolean — custom visibility check is_hittable(el) -> boolean — custom hit-test eligibility is_scroll_container -> boolean — marks element as scroll root clips_children -> boolean — node is used as parent for children capture_descendant_hits -> boolean — returns self instead of child on hit is_backdrop_click_target -> boolean — receives backdrop click events get_text_anchor(el) -> "left"|"center"|"right" — text pivot anchor for positioning hover_begin(self, el, deps) — called when pointer enters element hover_end(self, el, deps) — called when pointer leaves element press_begin(self, el, deps) — called when element is pressed press_update(self, el, is_hot, deps) — called while dragging over element press_end(self, el, activated, deps) — called on release on_wheel(self, el, delta, deps) — called on mouse wheel on_drag_start(self, el, x, y, t, deps) — called when drag begins on_drag_move(self, el, x, y, t, deps) — called each drag frame on_drag_end(self, el, action, t, deps) — called when drag ends update_anim(el, dt, deps) -> bool,bool — per-frame animation tick render_extras(self, el, prefix, alpha, deps) — render auxiliary nodes collect_extra_keys(el, prefix, keys, deps) — declare extra cached node keys get_child_extra_offset_y(el) -> number — additional Y offset for children

Parameters

  • type_name: string — The element type string (e.g. "box", "scroll")
  • def: LuaTable — Renderer definition table; must contain create_node

Returns

  • LuaTable — The registered def, same reference as the argument

get_size(): LuaMultiReturn<[number, number]>

Return the logical GUI display size (same as the [display] settings). Exposed on the module so external code can query the design resolution.

Returns

  • number — Logical display width in pixels
  • number — Logical display height in pixels

mount(self: LuaMap<string, unknown> | PlainTable, opts?: Flow_MountOptions)

Initialize the renderer state on a gui_script self table. Must be called once in gui_script init() before any other ui calls. Creates self.ui with an empty node cache, redraw flag, and debug toggle.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table to mount onto
  • opts?: Flow_MountOptions — Options table

set_debug(self: LuaMap<string, unknown> | PlainTable, enabled: boolean): boolean

Enable or disable debug logging for input and hit-testing. When enabled, every touch press emits debug logs through flow.log under the ui.input context.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • enabled: boolean — True to enable debug output, false to disable

Returns

  • boolean — The new debug state

_set_layout_space_unsafe(self: LuaMap<string, unknown> | PlainTable, space: string)

Internal: switch between "window" and "gui" layout spaces. In "window" mode, layout is computed in physical pixels and nodes are scaled back to GUI space via _scale_x/_scale_y. This gives pixel-perfect rendering on high-DPI displays. Not intended for direct consumer use.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • space: string — "window" for physical pixels, anything else for GUI units

request_redraw(self: LuaMap<string, unknown> | PlainTable)

Request a renderer redraw so the next M.update() call triggers a full re-render. Call this whenever the data driving the UI tree changes and you want the screen to reflect the new state immediately.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer

request_tree_redraw(tree?: Flow_Element | undefined)

Request a redraw for an element tree so renderer_core.update() re-renders it. Use this when you hold a reference to a tree and want to force a re-layout without going through the full renderer self table.

Parameters

  • tree?: Flow_Element | undefined — The root element to flag for redraw; no-op if nil

update(self: LuaMap<string, unknown> | PlainTable, tree?: Flow_Element | undefined): boolean

Update the renderer: re-layout and re-apply all nodes if the tree or display size has changed since the last frame. Internally delegates to renderer_core.update() with the full dependency bundle.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • tree?: Flow_Element | undefined — The element tree to render; may be nil (no-op)

Returns

  • boolean — True if a re-render was performed this frame

hit_test(self: LuaMap<string, unknown> | PlainTable, x: number, y: number): Flow_Element | undefined



Perform a point hit-test against the current element tree. Coordinates must be in GUI space (as received from on_input action.x/y). Returns the deepest hittable element whose layout bounds contain the point, or nil if nothing was hit.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • x: number — X coordinate in GUI space
  • y: number — Y coordinate in GUI space

Returns

  • Flow_Element | undefined — The hit element, or nil

on_input(self: LuaMap<string, unknown> | PlainTable, action_id: Hash | undefined, action: { x?: number; y?: number; pressed?: boolean; released?: boolean }): boolean

Route a Defold input action to the appropriate element. Handles touch press/move/release, scroll wheel, and drag gestures. Call this from gui_script on_input(); returns true if the input was consumed.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • action_id: Hash | undefined — The Defold action id hash (e.g. hash("touch"))
  • action: { x?: number; y?: number; pressed?: boolean; released?: boolean } — The Defold action table with x, y, pressed, released fields

Returns

  • boolean — True if the input was consumed and should not propagate

update_animations(self: LuaMap<string, unknown> | PlainTable, dt: number): boolean



Advance all per-element animations by one frame (dt seconds). Iterates the current tree and calls each element's update_anim handler. Requests a redraw when at least one element is still animating. Call this every frame from gui_script update() before M.update().

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • dt: number — Delta time in seconds since the last frame

Returns

  • boolean — True if at least one animation is still running

render(self: LuaMap<string, unknown> | PlainTable, tree: Flow_Element, w?: number | undefined, h?: number | undefined)

Force a full layout + render pass using the given tree and dimensions. Bypasses redraw gating — always re-computes and re-applies all nodes. Prefer M.update() for normal frame rendering; use M.render() when you need to guarantee an immediate re-render (e.g. after a window resize event detected in on_input).

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • tree: Flow_Element — The element tree to render
  • w?: number | undefined — Available width in pixels (nil/0 = use GUI size)
  • h?: number | undefined — Available height in pixels (nil/0 = use GUI size)

render_if_size_changed(self: LuaMap<string, unknown> | PlainTable, tree?: Flow_Element | undefined): boolean

Re-render only if the display size has changed since the last render pass. Cheaper than M.update() — no redraw-flag check, just a size comparison. Returns true when a re-render was performed.

Parameters

  • self: LuaMap<string, unknown> | PlainTable — The gui_script self table with a mounted renderer
  • tree?: Flow_Element | undefined — The element tree to render; falls back to self.ui.tree

Returns

  • boolean — True if a re-render was performed

On this page