Initial flame_lua_runtime package

example/assets/games/ludo/scripts/runtime_defs.lua

@@ -0,0 +1,587 @@
+---@meta
+--- COMMON RUNTIME TYPES SECTION.
+--- Source of truth: tool/lua_runtime_defs_common.lua
+--- After editing this common section, run:
+---   dart run tool/generate_lua_runtime_defs.dart
+
+
+---@alias RuntimeNodeType
+---| 'panel'
+---| 'button'
+---| 'text'
+---| 'circle'
+---| 'rect'
+---| 'line'
+---| 'progress'
+---| 'listView'
+---| 'sprite'
+---| 'image'
+---| 'spine'
+---| 'particle'
+
+---@alias RuntimeAnchor
+---| 'center'
+---| 'topLeft'
+---| 'topRight'
+---| 'bottomLeft'
+---| 'bottomRight'
+
+---@alias RuntimeTextAlign
+---| 'left'
+---| 'center'
+---| 'right'
+
+---@alias RuntimeParticlePreset
+---| 'burst'
+---| 'trail'
+---| 'snow'
+---| 'confetti'
+
+---@alias RuntimeCommandType
+---| 'move_path'
+---| 'move_to'
+---| 'fade_to'
+---| 'scale_to'
+---| 'rotate_to'
+---| 'remove_node'
+---| 'sequence'
+---| 'parallel'
+---| 'delay'
+---| 'toast'
+---| 'play_sound'
+---| 'play_bgm'
+---| 'pause_bgm'
+---| 'resume_bgm'
+---| 'stop_bgm'
+---| 'preload_resources'
+---| 'evict_resources'
+---| 'cancel_commands'
+---| 'play_spine_animation'
+---| 'copy_text'
+
+---@alias RuntimeEventType
+---| 'tap'
+---| 'animation_done'
+---| 'resize'
+---| 'scroll'
+
+---@alias RuntimeScaleMode
+---| 'fit'
+---| 'fill'
+---| 'stretch'
+---| 'none'
+
+---@alias RuntimeLayoutAlign
+---| 'start'
+---| 'center'
+---| 'end'
+
+---@alias RuntimeButtonVariant
+---| 'primary'
+---| 'secondary'
+---| 'ghost'
+
+---@class (exact) RuntimeNode
+---@field id string
+---@field type RuntimeNodeType
+---@field parent? string
+---@field asset? string Normal image/sprite/spine asset key. For button nodes this is the normal-state image.
+---@field pressedAsset? string Button pressed-state image asset key.
+---@field disabledAsset? string Button disabled-state image asset key.
+---@field animation? string
+---@field skin? string
+---@field loop? boolean
+---@field text? string
+---@field x? number
+---@field y? number
+---@field width? number
+---@field height? number
+---@field paddingLeft? number
+---@field paddingTop? number
+---@field paddingRight? number
+---@field paddingBottom? number
+---@field anchor? RuntimeAnchor
+---@field layer? integer
+---@field visible? boolean
+---@field alpha? number
+---@field scale? number
+---@field rotation? number
+---@field color? string
+---@field fontSize? number
+---@field textAlign? RuntimeTextAlign
+---@field radius? number
+---@field strokeWidth? number
+---@field value? number
+---@field scrollX? number
+---@field scrollY? number
+---@field contentWidth? number
+---@field contentHeight? number
+---@field virtualized? boolean
+---@field cacheExtent? number
+---@field inertia? boolean
+---@field scrollbarThumbColor? string
+---@field scrollbarTrackColor? string
+---@field scrollbarThickness? number
+---@field scrollbarVisible? boolean
+---@field interactive? boolean
+---@field onTap? string
+---@field onScroll? string
+---@field preset? RuntimeParticlePreset
+---@field count? integer
+---@field duration? number
+---@field speedMin? number
+---@field speedMax? number
+---@field gravityX? number
+---@field gravityY? number
+---@field spread? number
+---@field colorTo? string
+---@field radiusTo? number
+---@field autoRemove? boolean
+---@field fadeOut? boolean
+
+---@class (exact) RuntimeNodeProps
+---@field type? RuntimeNodeType
+---@field parent? string
+---@field asset? string Normal image/sprite/spine asset key. For button nodes this is the normal-state image.
+---@field pressedAsset? string Button pressed-state image asset key.
+---@field disabledAsset? string Button disabled-state image asset key.
+---@field animation? string
+---@field skin? string
+---@field loop? boolean
+---@field text? string
+---@field x? number
+---@field y? number
+---@field width? number
+---@field height? number
+---@field paddingLeft? number
+---@field paddingTop? number
+---@field paddingRight? number
+---@field paddingBottom? number
+---@field anchor? RuntimeAnchor
+---@field layer? integer
+---@field visible? boolean
+---@field alpha? number
+---@field scale? number
+---@field rotation? number
+---@field color? string
+---@field fontSize? number
+---@field textAlign? RuntimeTextAlign
+---@field radius? number
+---@field strokeWidth? number
+---@field value? number
+---@field scrollX? number
+---@field scrollY? number
+---@field contentWidth? number
+---@field contentHeight? number
+---@field virtualized? boolean
+---@field cacheExtent? number
+---@field inertia? boolean
+---@field scrollbarThumbColor? string
+---@field scrollbarTrackColor? string
+---@field scrollbarThickness? number
+---@field scrollbarVisible? boolean
+---@field interactive? boolean
+---@field onTap? string
+---@field onScroll? string
+---@field preset? RuntimeParticlePreset
+---@field count? integer
+---@field duration? number
+---@field speedMin? number
+---@field speedMax? number
+---@field gravityX? number
+---@field gravityY? number
+---@field spread? number
+---@field colorTo? string
+---@field radiusTo? number
+---@field autoRemove? boolean
+---@field fadeOut? boolean
+
+---Helper-only fields accepted by runtime_ui/runtime_widgets. They are normalized
+---before the node/update crosses the Dart Runtime protocol boundary.
+---@class RuntimeNodeInit: RuntimeNodeProps
+---@field w? number Alias for width.
+---@field h? number Alias for height.
+---@field size? number Alias for both width and height.
+---@field handler? string Alias for onTap.
+---@field onClick? string Alias for onTap.
+
+---@class (exact) RuntimeNodeUpdate
+---@field id string
+---@field props RuntimeNodeProps
+
+---@class (exact) RuntimeNodeRemove
+---@field id string
+
+---@class (exact) RuntimeDiffSection
+---@field creates? RuntimeNode[]
+---@field updates? RuntimeNodeUpdate[]
+---@field removes? (string|RuntimeNodeRemove)[]
+
+---@class (exact) RuntimeDiff
+---@field render? RuntimeDiffSection
+---@field ui? RuntimeDiffSection
+---@field commands? RuntimeCommand[]
+
+---@class (exact) RuntimeEvent
+---@field type RuntimeEventType|string
+---@field target? string
+---@field handler? string
+---@field x? number
+---@field y? number
+---@field data? table
+
+---@class (exact) RuntimeCommand
+---@field type RuntimeCommandType
+---@field target? string
+---@field scope? string
+---@field id? string
+---@field group? string
+---@field commandGroup? string
+---@field onComplete? string
+---@field duration? number
+---@field commands? RuntimeCommand[]
+---@field path? RuntimePoint[]
+---@field x? number
+---@field y? number
+---@field alpha? number
+---@field scale? number
+---@field angle? number
+---@field text? string
+---@field message? string
+---@field asset? string
+---@field name? string
+---@field volume? number
+---@field channel? string
+---@field loop? boolean
+---@field failOnError? boolean
+---@field animation? string
+---@field track? integer
+---@field queue? boolean
+---@field delay? number
+
+---@class (exact) RuntimeCommandOpts
+---@field id? string
+---@field group? string
+---@field commandGroup? string
+---@field scope? string
+---@field onComplete? string
+---@field duration? number
+
+---@class (exact) RuntimeAudioCommandOpts: RuntimeCommandOpts
+---@field volume? number
+---@field name? string
+
+---@class (exact) RuntimeBgmCommandOpts: RuntimeAudioCommandOpts
+---@field channel? string
+---@field loop? boolean
+
+---@class (exact) RuntimeSpineCommandOpts: RuntimeCommandOpts
+---@field track? integer
+---@field loop? boolean
+---@field queue? boolean
+---@field delay? number
+
+---@class (exact) RuntimeResourceCommandOpts: RuntimeCommandOpts
+---@field failOnError? boolean
+
+---@class (exact) RuntimePoint
+---@field x number
+---@field y number
+
+---@class (exact) RuntimeLocaleContext
+---@field requested string
+---@field resolved string
+---@field default string
+---@field supported string[]
+---@field languageCode string
+---@field scriptCode? string
+---@field countryCode? string
+
+---@class (exact) RuntimeScreenContext
+---@field width number
+---@field height number
+
+---@class (exact) RuntimeDesignContext
+---@field width number
+---@field height number
+
+---@class (exact) RuntimeViewportContext
+---@field x number
+---@field y number
+---@field width number
+---@field height number
+---@field scaleX number
+---@field scaleY number
+---@field scaleMode RuntimeScaleMode|string
+
+---@class (exact) RuntimeContext
+---@field screen RuntimeScreenContext
+---@field design RuntimeDesignContext
+---@field viewport RuntimeViewportContext
+---@field seed integer
+---@field runtimeApiVersion integer
+---@field gameId string
+---@field gameVersion string
+---@field locale? RuntimeLocaleContext
+
+---@class RuntimeUi
+---@field style fun(base?: RuntimeNodeProps, opts?: RuntimeNodeProps): RuntimeNodeProps
+---@field with_parent fun(parent: string, opts?: RuntimeNodeProps): RuntimeNodeProps
+---@field node fun(node_type: RuntimeNodeType, id: string, opts?: RuntimeNodeInit): RuntimeNode
+---@field panel fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field rect fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field circle fun(id: string, x: number|RuntimeNodeInit, y?: number, size?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field line fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field progress fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, value?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field particle fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field text fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field button fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, handler?: string, opts?: RuntimeNodeInit): RuntimeNode
+---@field list_view fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field image fun(id: string, asset: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field sprite fun(id: string, asset: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field spine fun(id: string, asset: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, animation?: string, opts?: RuntimeNodeInit): RuntimeNode
+---@field update fun(id: string, props: RuntimeNodeInit): RuntimeNodeUpdate
+---@field text_update fun(id: string, text: string): RuntimeNodeUpdate
+---@field visible_update fun(id: string, visible: boolean): RuntimeNodeUpdate
+---@field alpha_update fun(id: string, alpha: number): RuntimeNodeUpdate
+---@field scale_update fun(id: string, scale: number): RuntimeNodeUpdate
+---@field position_update fun(id: string, x: number, y: number): RuntimeNodeUpdate
+---@field size_update fun(id: string, width: number, height: number): RuntimeNodeUpdate
+---@field transform_update fun(id: string, x: number, y: number, scale: number, rotation: number): RuntimeNodeUpdate
+---@field batch_update fun(ids: string[], props: RuntimeNodeInit): RuntimeNodeUpdate[]
+---@field append fun(nodes: RuntimeNode[], node: RuntimeNode): RuntimeNode[]
+---@field append_all fun(nodes: RuntimeNode[], extra_nodes: RuntimeNode[]): RuntimeNode[]
+
+---@class (exact) RuntimeDialogButton
+---@field id? string
+---@field text string
+---@field handler string
+---@field color? string
+
+---@class (exact) RuntimeDialogOpts
+---@field screenWidth? number
+---@field screenHeight? number
+---@field overlay? boolean
+---@field overlayColor? string
+---@field blockInput? boolean
+---@field layer? integer
+---@field color? string
+---@field radius? number
+---@field panelStyle? RuntimeNodeProps
+---@field titleColor? string
+---@field titleSize? number
+---@field titleStyle? RuntimeNodeProps
+---@field messageColor? string
+---@field messageSize? number
+---@field messageStyle? RuntimeNodeProps
+---@field buttons? RuntimeDialogButton[]
+---@field buttonGap? number
+---@field buttonStyle? RuntimeNodeProps
+
+---@class RuntimeLabeledProgressOpts: RuntimeNodeInit
+---@field labelHeight? number
+---@field labelStyle? RuntimeNodeProps
+
+---@class RuntimePillOpts: RuntimeNodeInit
+---@field panelStyle? RuntimeNodeProps
+---@field textStyle? RuntimeNodeProps
+
+---@class RuntimeTextButtonOpts: RuntimeNodeInit
+---@field variant? RuntimeButtonVariant
+
+---@class RuntimeListItemOpts: RuntimeTextButtonOpts
+---@field selected? boolean
+---@field activeColor? string
+---@field inactiveColor? string
+
+---@class RuntimeTabItem
+---@field id? string
+---@field key? string
+---@field text string
+---@field handler? string
+---@field selected? boolean
+
+---@class RuntimeTabsOpts: RuntimeNodeInit
+---@field tabs? RuntimeTabItem[]
+---@field selected? string
+---@field gap? number
+---@field itemWidth? number
+---@field itemHeight? number
+---@field activeColor? string
+---@field inactiveColor? string
+---@field buttonStyle? RuntimeNodeProps
+
+---@class RuntimeActionItem
+---@field id? string
+---@field text string
+---@field handler? string
+---@field visible? boolean
+---@field color? string
+---@field style? RuntimeNodeProps
+
+---@class RuntimeActionRowOpts: RuntimeNodeInit
+---@field actions? RuntimeActionItem[]
+---@field gap? number
+---@field itemWidth? number
+---@field itemHeight? number
+---@field buttonStyle? RuntimeNodeProps
+
+---@class RuntimePanelHeaderOpts: RuntimeNodeInit
+---@field eyebrow? string
+---@field title string
+---@field summary? string
+---@field gap? number
+---@field eyebrowId? string
+---@field titleId? string
+---@field summaryId? string
+---@field eyebrowHeight? number
+---@field titleHeight? number
+---@field summaryHeight? number
+---@field eyebrowStyle? RuntimeNodeProps
+---@field titleStyle? RuntimeNodeProps
+---@field summaryStyle? RuntimeNodeProps
+
+---@class RuntimeWidgetTheme
+---@field primary? string
+---@field secondary? string
+---@field success? string
+---@field overlay? string
+---@field surface? string
+---@field surfaceAlt? string
+---@field card? string
+---@field text? string
+---@field muted? string
+---@field progress? string
+---@field transparent? string
+
+---@class RuntimeWidgets
+---@field configure fun(tokens?: RuntimeWidgetTheme): RuntimeWidgets
+---@field label fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field section_title fun(id: string, text: string|RuntimeNodeInit, x?: number, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field pill fun(id: string, text: string|RuntimePillOpts, x?: number, y?: number, width?: number, height?: number, opts?: RuntimePillOpts): RuntimeNode[]
+---@field text_button fun(id: string, text: string|RuntimeTextButtonOpts, x?: number, y?: number, width?: number, height?: number, handler?: string, opts?: RuntimeTextButtonOpts): RuntimeNode
+---@field list_item fun(id: string, text: string|RuntimeListItemOpts, x?: number, y?: number, width?: number, height?: number, handler?: string, opts?: RuntimeListItemOpts): RuntimeNode
+---@field tabs fun(id: string, tabs: RuntimeTabItem[]|RuntimeTabsOpts, opts?: RuntimeTabsOpts): RuntimeNode[]
+---@field action_row fun(id: string, actions: RuntimeActionItem[]|RuntimeActionRowOpts, opts?: RuntimeActionRowOpts): RuntimeNode[]
+---@field panel_header fun(id: string, opts: RuntimePanelHeaderOpts): RuntimeNode[]
+---@field overlay fun(id: string, width: number|RuntimeNodeInit, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field card fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field progress_bar fun(id: string, x: number|RuntimeNodeInit, y?: number, width?: number, height?: number, value?: number, opts?: RuntimeNodeInit): RuntimeNode
+---@field labeled_progress fun(id: string, label: string, x: number, y: number, width: number, height: number, value: number, opts?: RuntimeLabeledProgressOpts): RuntimeNode[]
+---@field button_row fun(parent: string, id: string, buttons: RuntimeDialogButton[], x: number, y: number, width: number, height: number, gap?: number, opts?: RuntimeNodeProps): RuntimeNode[]
+---@field dialog fun(id: string, title: string, message: string, x: number, y: number, width: number, height: number, opts?: RuntimeDialogOpts): RuntimeNode[]
+
+---@class (exact) RuntimeLayoutItem
+---@field node RuntimeNode
+---@field marginLeft? number
+---@field marginRight? number
+---@field marginTop? number
+---@field marginBottom? number
+
+---@class RuntimeLayoutItemOpts
+---@field margin? number
+---@field mx? number
+---@field my? number
+---@field ml? number
+---@field mr? number
+---@field mt? number
+---@field mb? number
+---@field marginLeft? number
+---@field marginRight? number
+---@field marginTop? number
+---@field marginBottom? number
+
+---@class RuntimeLinearLayoutOpts
+---@field x? number
+---@field y? number
+---@field width? number
+---@field height? number
+---@field gap? number
+---@field align? RuntimeLayoutAlign
+---@field padding? number
+---@field paddingX? number
+---@field paddingY? number
+---@field px? number
+---@field py? number
+---@field paddingLeft? number
+---@field paddingTop? number
+
+---@class RuntimeBoxLayoutOpts: RuntimeLinearLayoutOpts
+---@field rows? integer
+---@field columns? integer
+---@field cols? integer
+---@field cellWidth? number
+---@field cellHeight? number
+---@field cellW? number
+---@field cellH? number
+---@field gapX? number
+---@field gapY? number
+---@field valign? RuntimeLayoutAlign
+
+---@class RuntimeLayout
+---@field item fun(node: RuntimeNode, opts?: RuntimeLayoutItemOpts): RuntimeLayoutItem
+---@field local_position fun(origin: RuntimePoint, position: RuntimePoint): RuntimePoint
+---@field row fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeLinearLayoutOpts): RuntimeNode[]
+---@field column fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeLinearLayoutOpts): RuntimeNode[]
+---@field stack fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeLinearLayoutOpts): RuntimeNode[]
+---@field box fun(parent?: string, items: (RuntimeNode|RuntimeLayoutItem)[], opts?: RuntimeBoxLayoutOpts): RuntimeNode[]
+
+---@class RuntimeCommands
+---@field toast fun(text: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field copy_text fun(text: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field delay fun(duration: number, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field sequence fun(items: RuntimeCommand[], opts?: RuntimeCommandOpts): RuntimeCommand
+---@field parallel fun(items: RuntimeCommand[], opts?: RuntimeCommandOpts): RuntimeCommand
+---@field move_path fun(target: string, path: RuntimePoint[], opts?: RuntimeCommandOpts): RuntimeCommand
+---@field move_to fun(target: string, x: number, y: number, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field fade_to fun(target: string, alpha: number, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field scale_to fun(target: string, scale: number, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field rotate_to fun(target: string, angle: number, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field remove_node fun(target: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field play_spine_animation fun(target: string, animation: string, opts?: RuntimeSpineCommandOpts): RuntimeCommand
+---@field play_sound fun(asset: string, opts?: RuntimeAudioCommandOpts): RuntimeCommand
+---@field play_bgm fun(asset: string, opts?: RuntimeBgmCommandOpts): RuntimeCommand
+---@field pause_bgm fun(channel?: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field resume_bgm fun(channel?: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field stop_bgm fun(channel?: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field preload_group fun(group: string, opts?: RuntimeResourceCommandOpts): RuntimeCommand
+---@field evict_group fun(group: string, opts?: RuntimeCommandOpts): RuntimeCommand
+---@field cancel_id fun(id: string): RuntimeCommand
+---@field cancel_group fun(group: string): RuntimeCommand
+---@field cancel_scope fun(scope: string): RuntimeCommand
+
+---@class RuntimeImportApi
+---@field import fun(moduleName: string): table
+
+---@type RuntimeImportApi
+runtime = runtime
+
+---@alias PlayerColor 'red'|'blue'
+---@alias GamePhase 'waiting_roll'|'waiting_piece'|'animating'
+---@alias PieceStatus 'home'|'path'|'finished'
+
+---@class (exact) PieceState
+---@field id string
+---@field owner PlayerColor
+---@field path_index integer
+---@field status PieceStatus
+
+---@class (exact) LudoState
+---@field current_player PlayerColor
+---@field phase GamePhase
+---@field dice_index integer
+---@field dice_values integer[]
+---@field dice? integer
+---@field selected_piece? string
+---@field players PlayerColor[]
+---@field pieces table<string, PieceState>
+
+---@class (exact) BoardPoint
+---@field x number
+---@field y number
+
+---@class (exact) BoardData
+---@field red_home BoardPoint[]
+---@field blue_home BoardPoint[]
+---@field path BoardPoint[]
+---@field start table<PlayerColor, integer>