# Runtime protocol

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

```text
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

```text
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:

```text
tool/lua_runtime_defs_common.lua
```

Then run:

```bash
dart run tool/generate_lua_runtime_defs.dart
```