Initial flame_lua_runtime package

README.md

@@ -0,0 +1,103 @@
+# 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`.
+
+## 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',
+  ),
+)
+```
+
+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
+```
+
+## 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.