Runtime protocol

The runtime protocol is the stable boundary between Lua and Dart.

RuntimeEvent -> Lua -> GameDiff / RuntimeCommand -> Flame

RuntimeEvent

Dart sends white-listed events to Lua. Events represent input, lifecycle, command/resource outcomes, and host/runtime notifications.

Lua should treat events as data and return explicit state changes.

GameDiff

A GameDiff describes desired changes to the runtime render tree.

Typical operations include creating, updating, and removing runtime nodes. Dart validates node fields before applying them to Flame components.

RuntimeNode

Runtime nodes are generic render descriptions. They are not Flame objects.

Supported node concepts include:

Containers/panels.
Text.
Sprites/images.
Buttons.
List views.
Particles.
Spine nodes.

Lua may compose higher-level widgets, but those widgets must normalize into supported runtime nodes.

Color and alpha

RuntimeNode.color supports #RRGGBB and #AARRGGBB. When the alpha channel is present in the color, it is multiplied with RuntimeNode.alpha and any runtime animation alpha.

Final opacity = color alpha × node alpha × runtime animation alpha

#RRGGBB colors behave as fully opaque colors. #00000000 is fully transparent.

Text shadow

Text-capable nodes may use flat shadow fields:

textShadowColor: #RRGGBB or #AARRGGBB shadow color.
textShadowOffsetX / textShadowOffsetY: shadow offset in runtime pixels.
textShadowBlur: non-negative blur radius.

The shadow color alpha is multiplied by RuntimeNode.alpha and any runtime animation alpha.

RuntimeCommand

Runtime commands request generic side effects owned by Dart/Flame.

Examples:

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

Commands must remain generic. Do not add commands like roll_ludo_dice or move_airplane_piece; those belong in Lua game logic.

Validation expectations

Unknown protocol fields should not become implicit behavior.
Required fields should fail clearly when absent.
Helper-only aliases must be normalized before Dart protocol validation.
Runtime code should not silently convert invalid game state into fake success.

Where to change protocol code

lib/runtime/models/          Data models
lib/runtime/protocol/        Protocol validation
lib/runtime/commands/        Command validation/execution
lib/runtime/rendering/       Runtime node to Flame component mapping
assets/runtime/lua/          Lua helper constructors/aliases

When protocol changes affect Lua authoring, update:

tool/lua_runtime_defs_common.lua

Then run:

dart run tool/generate_lua_runtime_defs.dart

2.9 KiB Raw Blame History Unescape Escape