# 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.