8ddc3be3a7
- Add RuntimeOptions.basePackages for loading framework packages before game package - Add ScriptEngine.loadPackages() for multi-package module merging - LuaDardoScriptEngine merges modules from all packages, game overrides framework - PackageActivationController loads base packages first, then game package - GamePackageManifest parses optional 'base' field - Update docs: README, quick-start, lua-package-format, architecture - Update all test mocks with loadPackages() implementation
128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
# flame_lua_runtime
|
|
|
|
A Flutter + Flame + Lua runtime kit for manifest-driven 2D game packages.
|
|
|
|
The package provides a reusable runtime boundary:
|
|
|
|
```text
|
|
RuntimeEvent -> Lua -> GameDiff / RuntimeCommand -> Flame
|
|
```
|
|
|
|
It is designed for Flutter apps that want to host Lua-authored 2D games or interactive showcases while keeping the Flutter/Flame side generic.
|
|
|
|
## Features
|
|
|
|
- `LuaGameWidget` for embedding a Lua game package in a Flutter app.
|
|
- Manifest-driven Lua module, resource, audio, and package loading.
|
|
- Controlled Lua modularization through `runtime.import(moduleName)`.
|
|
- Generic Runtime nodes for panels, text, sprites, buttons, particles, Spine, and list views.
|
|
- Runtime commands for movement, fading, scaling, rotation, sequencing, audio, resources, toast, clipboard, and Spine animation.
|
|
- Shared Lua helper modules under `assets/runtime/lua/`.
|
|
- Configurable Runtime Lua asset root via `RuntimeOptions.runtimeLuaRoot`.
|
|
- Multi-package loading: shared framework packages loaded once, game packages loaded on top.
|
|
|
|
## Example
|
|
|
|
This package includes a runnable Flutter showcase app under `example/`:
|
|
|
|
```bash
|
|
cd example
|
|
flutter run --dart-define=LUA_GAME_ID=showcase
|
|
```
|
|
|
|
Other bundled example packages can be selected with:
|
|
|
|
```bash
|
|
flutter run --dart-define=LUA_GAME_ID=template
|
|
flutter run --dart-define=LUA_GAME_ID=ludo
|
|
flutter run --dart-define=LUA_GAME_ID=flight
|
|
```
|
|
|
|
## Quick start
|
|
|
|
Add the package to your app:
|
|
|
|
```yaml
|
|
dependencies:
|
|
flame_lua_runtime: ^0.1.0
|
|
```
|
|
|
|
Embed a game package:
|
|
|
|
```dart
|
|
import 'package:flame_lua_runtime/flame_lua_runtime.dart';
|
|
|
|
LuaGameWidget(
|
|
gameId: 'template',
|
|
runtimeOptions: const RuntimeOptions(
|
|
runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
|
|
),
|
|
)
|
|
```
|
|
|
|
With a shared framework package:
|
|
|
|
```dart
|
|
LuaGameWidget(
|
|
gameId: 'ludo',
|
|
runtimeOptions: const RuntimeOptions(
|
|
runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
|
|
basePackages: ['_framework'],
|
|
),
|
|
)
|
|
```
|
|
|
|
Your app should provide game package assets such as:
|
|
|
|
```text
|
|
assets/games/template/manifest.json
|
|
assets/games/template/scripts/main.lua
|
|
assets/games/template/scripts/state.lua
|
|
assets/games/template/scripts/ui.lua
|
|
```
|
|
|
|
The game manifest declares package-local scripts and shared Runtime Lua modules:
|
|
|
|
```json
|
|
{
|
|
"modules": {
|
|
"main": "scripts/main.lua",
|
|
"runtime_ui": "runtime:runtime_ui.lua",
|
|
"runtime_widgets": "runtime:runtime_widgets.lua",
|
|
"runtime_commands": "runtime:runtime_commands.lua",
|
|
"layout": "runtime:layout.lua"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Runtime asset path
|
|
|
|
When used as a published package, configure:
|
|
|
|
```dart
|
|
const RuntimeOptions(
|
|
runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
|
|
)
|
|
```
|
|
|
|
For source-tree development, the default remains:
|
|
|
|
```dart
|
|
RuntimeOptions.defaultRuntimeLuaRoot // assets/runtime/lua
|
|
```
|
|
|
|
## Documentation
|
|
|
|
For AI agents and maintainers, start with:
|
|
|
|
- [`AGENTS.md`](AGENTS.md) — package boundaries, rules, public API, and validation commands.
|
|
- [`docs/quick-start.md`](docs/quick-start.md) — host app integration.
|
|
- [`docs/architecture.md`](docs/architecture.md) — Dart/Lua/Flame responsibilities.
|
|
- [`docs/lua-package-format.md`](docs/lua-package-format.md) — manifest, Lua package rules, and multi-package loading.
|
|
- [`docs/protocol.md`](docs/protocol.md) — RuntimeEvent, GameDiff, RuntimeNode, RuntimeCommand boundary.
|
|
- [`docs/validation.md`](docs/validation.md) — checks, smoke tests, and release flow.
|
|
|
|
## Status
|
|
|
|
This package is in early extraction stage. Public API is intentionally small and centered on `LuaGameWidget`, `FlameLuaGame`, `RuntimeOptions`, package repositories, and script engine interfaces.
|