114 lines
2.9 KiB
Markdown
114 lines
2.9 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.
|
||
|
||
### 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.
|
||
|
||
```text
|
||
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
|
||
|
||
```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
|
||
```
|