flutter_lua_runtime/docs/quick-start.md

# Quick start

This package embeds manifest-driven Lua game packages in Flutter apps.

## Add dependency

For private Git usage, prefer a pinned tag:

```yaml
dependencies:
  flame_lua_runtime:
    git:
      url: https://gitea.sdws.shop/xim/flutter_lua_runtime.git
      ref: v0.1.0
```

For local development:

```yaml
dependencies:
  flame_lua_runtime:
    path: ../flame_lua_runtime
```

## Add game assets to the host app

A minimal host app should provide one game package:

```text
assets/games/template/manifest.json
assets/games/template/scripts/main.lua
assets/games/template/scripts/state.lua
assets/games/template/scripts/ui.lua
```

Declare assets in the host app `pubspec.yaml`:

```yaml
flutter:
  assets:
    - assets/games/template/manifest.json
    - assets/games/template/scripts/
    - assets/games/template/assets/
```

The runtime package itself provides shared Runtime Lua helpers from:

```text
packages/flame_lua_runtime/assets/runtime/lua/
```

## Embed in Flutter

```dart
import 'package:flutter/material.dart';
import 'package:flame_lua_runtime/flame_lua_runtime.dart';

class GameScreen extends StatelessWidget {
  const GameScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return const LuaGameWidget(
      gameId: 'template',
      runtimeOptions: RuntimeOptions(
        runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
      ),
    );
  }
}
```

## Run the package example

```bash
cd example
flutter run --dart-define=LUA_GAME_ID=showcase
flutter run --dart-define=LUA_GAME_ID=template
flutter run --dart-define=LUA_GAME_ID=ludo
flutter run --dart-define=LUA_GAME_ID=flight
```

## Minimal manifest

```json
{
  "id": "template",
  "version": "0.1.0",
  "entry": "main",
  "modules": {
    "main": "scripts/main.lua",
    "state": "scripts/state.lua",
    "ui": "scripts/ui.lua",
    "runtime_ui": "runtime:runtime_ui.lua",
    "runtime_widgets": "runtime:runtime_widgets.lua",
    "runtime_commands": "runtime:runtime_commands.lua",
    "layout": "runtime:layout.lua"
  }
}
```

## Multi-package loading (base + game)

When multiple games share common modules (event router, diff utilities, panel stack, network layer), extract them into a framework package and load it before the game package.

Framework package structure:

```text
assets/games/_framework/
  manifest.json
  scripts/
    app.lua
    diff.lua
    event_router.lua
    ids.lua
    net.lua
    panel_stack.lua
```

Framework manifest:

```json
{
  "gameId": "_framework",
  "name": "Lua Game Framework",
  "version": "1.0.0",
  "runtimeApiVersion": 1,
  "entry": "scripts/app.lua",
  "assetsBase": "assets",
  "modules": {
    "app": "scripts/app.lua",
    "diff": "scripts/diff.lua",
    "event_router": "scripts/event_router.lua",
    "ids": "scripts/ids.lua",
    "net": "scripts/net.lua",
    "panel_stack": "scripts/panel_stack.lua"
  }
}
```

Game manifest (no framework modules needed):

```json
{
  "gameId": "ludo",
  "base": "_framework",
  "modules": {
    "state": "scripts/state.lua",
    "rules": "scripts/rules.lua",
    "main": "scripts/main.lua"
  }
}
```

Game code imports framework modules transparently:

```lua
local app = runtime.import("app")       -- from framework
local state = runtime.import("state")   -- from game
```

Embed with base packages:

```dart
LuaGameWidget(
  gameId: 'ludo',
  runtimeOptions: const RuntimeOptions(
    runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
    basePackages: ['_framework'],
  ),
)
```

Module resolution order: game package modules override framework modules with the same name. The entry script always comes from the last package (game package).