flutter_lua_runtime/AGENTS.md

flame_lua_runtime Agent Guide

This file is the first-stop guide for AI agents and maintainers working in this package.

What this package is

flame_lua_runtime is a reusable Flutter + Flame + Lua 2D game runtime.

The stable runtime boundary is:

RuntimeEvent -> Lua -> GameDiff / RuntimeCommand -> Flame

Flutter/Flame owns runtime infrastructure, rendering, resources, events, commands, diagnostics, and package lifecycle. Lua owns game logic, UI layout, event handling, and construction of diff/command tables.

Hard boundaries

Do not add game-specific logic to Dart runtime code.

Do not let Lua directly hold or mutate Flutter, Flame, Spine, Particle, or native objects.

Do not expose unrestricted Lua APIs:

• require
• package
• dofile
• loadfile
• os

Lua modularization must go through:

runtime.import(moduleName)

Modules must be declared in the game manifest.

Runtime Lua assets

Shared Lua helper modules live here:

assets/runtime/lua/

Supported shared modules currently include:

runtime_ui.lua
runtime_widgets.lua
runtime_commands.lua
layout.lua

Game manifests may reference them with restricted runtime: paths:

{
  "modules": {
    "runtime_ui": "runtime:runtime_ui.lua"
  }
}

runtime: paths must remain narrow: only runtime:*.lua, no /, no .., and no empty path.

Package-local Lua modules remain under:

scripts/*.lua

Public API surface

The public barrel is:

lib/flame_lua_runtime.dart

Keep this API intentionally small. Add exports only when host apps need them.

Current primary API:

• LuaGameWidget
• FlameLuaGame
• RuntimeOptions
• RuntimeLocaleResolver
• GamePackageRepository
• AssetGamePackageRepository
• RemoteGamePackageRepository
• ScriptEngine
• LuaDardoScriptEngine

Repository layout

assets/runtime/lua/       Shared Lua framework modules
lib/runtime/              Dart runtime implementation
lib/flame_lua_runtime.dart Public API barrel
test/                     Runtime and public API tests
tool/                     Runtime helper/check scripts
example/                  Runnable Flutter showcase app

Validation commands

Run these before committing package changes:

flutter analyze
flutter test test
dart run tool/generate_lua_runtime_defs.dart --check

For the example app:

cd example
flutter analyze
flutter test

For publish readiness:

flutter pub publish --dry-run

A warning about missing homepage / repository is acceptable until real public metadata is configured.

Development rules

• Keep protocol fields white-listed and explicit.
• Write code that ordinary maintainers can safely modify: keep control flow obvious, names explicit, abstractions shallow, and avoid clever or hidden behavior.
• Remove deprecated, unused, or superseded code promptly when replacing behavior; do not leave parallel old paths unless a documented compatibility window requires them.
• Prefer simple data models over implicit behavior.
• Runtime commands must be generic, not game-specific.
• Lua helper aliases are allowed only if normalized before protocol validation.
• Tests should cover protocol parsing, package validation, script loading, command execution, and public API exports.
• If adding Lua helper APIs, update generated defs through tool/generate_lua_runtime_defs.dart.

More docs

Read these docs before larger changes:

• docs/quick-start.md
• docs/architecture.md
• docs/lua-package-format.md
• docs/protocol.md
• docs/validation.md