94 lines
2.2 KiB
Markdown
94 lines
2.2 KiB
Markdown
# 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
|
|
```
|