104 lines
2.9 KiB
Markdown
104 lines
2.9 KiB
Markdown
# Architecture
|
|
|
|
`flame_lua_runtime` separates generic runtime infrastructure from game-specific Lua packages.
|
|
|
|
## Boundary
|
|
|
|
```text
|
|
RuntimeEvent -> Lua -> GameDiff / RuntimeCommand -> Flame
|
|
```
|
|
|
|
- Dart receives input, lifecycle, resource, and host events.
|
|
- Dart forwards white-listed runtime events to Lua.
|
|
- Lua returns a `GameDiff` and/or `RuntimeCommand` list.
|
|
- Dart validates and applies diffs/commands to Flame-owned components.
|
|
|
|
## Responsibilities
|
|
|
|
### Dart / Flutter / Flame owns
|
|
|
|
- Rendering tree and `Component` lifecycle.
|
|
- Resource loading and cache ownership.
|
|
- Audio playback.
|
|
- Spine and particle object creation.
|
|
- Input/event dispatch.
|
|
- Package validation and activation.
|
|
- Runtime command execution.
|
|
- Diagnostics and error reporting.
|
|
|
|
### Lua owns
|
|
|
|
- Game state transitions.
|
|
- UI tree description.
|
|
- Layout calculation.
|
|
- Event handling decisions.
|
|
- Command/node table construction.
|
|
|
|
Lua should only describe desired runtime state. It must not receive or retain Dart/Flame object references.
|
|
|
|
## Key Dart areas
|
|
|
|
```text
|
|
lib/runtime/models/ Protocol data models
|
|
lib/runtime/protocol/ Protocol validation/parsing
|
|
lib/runtime/scripting/ Lua engine boundary
|
|
lib/runtime/packages/ Manifest/package loading and activation
|
|
lib/runtime/rendering/ Flame render tree adapter
|
|
lib/runtime/commands/ Runtime command execution
|
|
lib/runtime/resources/ Resource loading and cache management
|
|
lib/runtime/events/ Event dispatch and gates
|
|
lib/runtime/lifecycle/ Async/session/task safety
|
|
```
|
|
|
|
## Package loading
|
|
|
|
Game packages are manifest-driven. Bundled assets and remote/downloaded packages should flow through the same package abstraction where possible.
|
|
|
|
Shared Runtime Lua modules are loaded from `RuntimeOptions.runtimeLuaRoot`.
|
|
|
|
Default source-tree root:
|
|
|
|
```text
|
|
assets/runtime/lua
|
|
```
|
|
|
|
Package dependency root:
|
|
|
|
```text
|
|
packages/flame_lua_runtime/assets/runtime/lua
|
|
```
|
|
|
|
## Safety model
|
|
|
|
- Lua module loading is manifest-declared.
|
|
- `runtime.import(moduleName)` is the only intended module import API.
|
|
- `runtime:` module paths are restricted to `runtime:*.lua`.
|
|
- Package-local scripts are restricted to `scripts/*.lua`.
|
|
- Runtime protocol fields are white-listed.
|
|
- Invalid diffs/commands should fail clearly instead of being silently ignored.
|
|
|
|
## Extension guidance
|
|
|
|
When adding features, prefer this order:
|
|
|
|
1. Lua helper composition if it can be represented by existing nodes/commands.
|
|
2. Generic protocol field if multiple games need the capability.
|
|
3. Generic Runtime node/command if it requires Dart/Flame ownership.
|
|
4. Avoid game-specific Dart code.
|
|
|
|
Examples of valid generic runtime features:
|
|
|
|
- `listView` node.
|
|
- `particle` node.
|
|
- `toast` command.
|
|
- `copy_text` command.
|
|
- `play_spine_animation` command.
|
|
- Button image states.
|
|
|
|
Examples that should stay Lua-side:
|
|
|
|
- Game board rules.
|
|
- Game-specific dialog composition.
|
|
- Showcase category/menu behavior.
|
|
- Ludo/flight-specific animation choices.
|