153 lines
3.5 KiB
Markdown
153 lines
3.5 KiB
Markdown
# 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`
|