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- Pick a release from Pause-Games/flow releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as ui from "flow.ui"
- Pick a release from Pause-Games/flow releases and add its Source code (zip) URL (or a packaged
Functions
register(type_name: string, def: LuaTable): LuaTableget_size(): LuaMultiReturn<[number, number]>mount(self: LuaMap<string, unknown> |PlainTable, opts?: Flow_MountOptions)set_debug(self: LuaMap<string, unknown> |PlainTable, enabled: boolean): boolean_set_layout_space_unsafe(self: LuaMap<string, unknown> |PlainTable, space: string)request_redraw(self: LuaMap<string, unknown> |PlainTable)request_tree_redraw(tree?: Flow_Element | undefined)update(self: LuaMap<string, unknown> |PlainTable, tree?: Flow_Element | undefined): booleanhit_test(self: LuaMap<string, unknown> |PlainTable, x: number, y: number): Flow_Element | undefinedon_input(self: LuaMap<string, unknown> |PlainTable, action_id:Hash| undefined, action: { x?: number; y?: number; pressed?: boolean; released?: boolean }): booleanupdate_animations(self: LuaMap<string, unknown> |PlainTable, dt: number): booleanrender(self: LuaMap<string, unknown> |PlainTable, tree: Flow_Element, w?: number | undefined, h?: number | undefined)render_if_size_changed(self: LuaMap<string, unknown> |PlainTable, tree?: Flow_Element | undefined): boolean
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 pixelsnumber— 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 ontoopts?: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 rendererenabled: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 rendererspace: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 renderertree?: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 rendererx:number— X coordinate in GUI spacey: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 rendereraction_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 rendererdt: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 renderertree:Flow_Element— The element tree to renderw?: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 renderertree?:Flow_Element | undefined— The element tree to render; falls back to self.ui.tree
Returns
boolean— True if a re-render was performed