flutter_lua_runtime/README.md

flame_lua_runtime

A Flutter + Flame + Lua runtime kit for manifest-driven 2D game packages.

The package provides a reusable runtime boundary:

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.
• Asset, local file, and remote package repositories for bundled, development, and hot-update workflows.
• Remote package compatibility checks for Runtime version, host build, platform, and release channel.

Example

This package includes a runnable Flutter showcase app under example/:

cd example
flutter run --dart-define=LUA_GAME_ID=showcase

Other bundled example packages can be selected with:

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:

dependencies:
  flame_lua_runtime: ^0.1.0

Embed a game package:

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:

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:

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:

{
  "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"
  }
}

Package loading modes

• AssetGamePackageRepository: bundled app assets and fallback packages.
• FileGamePackageRepository: local development directory, useful when large images should not be bundled into the app during iteration.
• RemoteGamePackageRepository: remote zip packages with sha256 verification, compatibility checks, and stable cache fallback.

Remote compatibility is configured with RuntimeOptions.runtimeVersion, hostBuild, platform, and channel.

Runtime asset path

When used as a published package, configure:

const RuntimeOptions(
  runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
)

For source-tree development, the default remains:

RuntimeOptions.defaultRuntimeLuaRoot // assets/runtime/lua

Documentation

For AI agents and maintainers, start with:

• AGENTS.md — package boundaries, rules, public API, and validation commands.
• docs/quick-start.md — host app integration.
• docs/architecture.md — Dart/Lua/Flame responsibilities.
• docs/lua-package-format.md — manifest, Lua package rules, and multi-package loading.
• docs/protocol.md — RuntimeEvent, GameDiff, RuntimeNode, RuntimeCommand boundary.
• 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.