flutter_lua_runtime/docs/protocol.md

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.

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