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

```text
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:

```lua
runtime.import(moduleName)
```

Modules must be declared in the game manifest.

## Runtime Lua assets

Shared Lua helper modules live here:

```text
assets/runtime/lua/
```

Supported shared modules currently include:

```text
runtime_ui.lua
runtime_widgets.lua
runtime_commands.lua
layout.lua
```

Game manifests may reference them with restricted `runtime:` paths:

```json
{
  "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:

```text
scripts/*.lua
```

## Public API surface

The public barrel is:

```text
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

```text
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:

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

For the example app:

```bash
cd example
flutter analyze
flutter test
```

For publish readiness:

```bash
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`