# runtime — 元景 W-10 运行时执行引擎

## 用途

W-10 运行时执行引擎 v1：前端 JS 运行时引擎（事件循环 + 实体状态 + 脚本执行）+ 可选服务端辅助。
能力覆盖 W-10a~W-10i：

- **W-10a** 世界运行时初始化：构建运行态实体树（父子树 + 扁平索引）
- **W-10b** 实体运行时状态管理（state 机 + 位置/速度）
- **W-10c** 脚本运行时执行调度（对接 script_engine 编译产物 actions 数组）
- **W-10d** 事件分发：事件队列 → 路由到对应实体绑定的脚本
- **W-10e** 定时器管理（tick 驱动，非 setInterval）
- **W-10f** 碰撞检测（AABB 两两检测 → onCollide）
- **W-10g** 运行时暂停/恢复/停止
- **W-10h** 错误处理与降级（捕获不整页崩溃）
- **W-10i** 独立世界本地引擎（independent 模式，后端不可用仍运行）

## 数据表

本模块为交互层模块，**无自有数据表**。服务端辅助只读复用 `world` 模块数据
（`world` 表 + 尽力而为的 `world_entity`/`scene` 表），库名经 `get_module_dbname('world')` 获取。

## 文件结构

```
runtime/
├── runtime/               Python 包（服务端辅助）
│   ├── __init__.py        导出（三处同步注册之②）
│   ├── init.py            load_runtime(env) 注册（三处同步注册之③）
│   └── runtime_service.py 实现（三处同步注册之①）
├── wwwroot/
│   ├── runtime.js         前端核心引擎
│   ├── play.html          游戏运行页（验收入口）
│   ├── index.ui           模块入口页
│   └── api/               load_world / runtime_status / runtime_event / runtime_control .dspy
├── scripts/load_path.py   RBAC 路径注册
├── skill/SKILL.md         模块技能文档
├── pyproject.toml         打包配置
└── README.md
```

## 安装与集成（宿主 scense 应用）

1. 模块包安装：`pip install .`（依赖 sqlor、bricks_for_python）
2. 宿主 `app/scense.py`：`from runtime.init import load_runtime` + init() 内 `await load_runtime(env)`
3. `build.sh` 链接 wwwroot：`ln -sf <runtime>/wwwroot/runtime.js scense_app/wwwroot/runtime/`
4. RBAC：执行 `scripts/load_path.py`（any/logined 分层，无通配符）
5. 菜单：`index.ui` 卡片「开始玩」→ `{{entire_url('/runtime/play.html')}}`

## 验收（9 项）

| # | 验收项 | 操作 | 期望 |
|---|--------|------|------|
| 1 | 开始玩初始化实体树 | 打开 play.html 自动启动 | 日志出现「世界初始化完成/降级独立模式」+ 5 个实体绘制 |
| 2 | 点击触发事件执行脚本 | 点击任意实体 | 事件路由日志 + 实体 state 变化 |
| 3 | 定时器按间隔触发 | 等待 3s | box1 每 3s 下移 10px |
| 4 | 脚本抛错降级不崩溃 | 点击「箱子B」 | 错误日志 + 引擎继续运行（错误计数递增） |
| 5 | 碰撞检测 | 点 hero 两次移动撞 box1 | 碰撞日志 |
| 6 | 暂停/恢复 | 点暂停→点恢复 | 暂停后画面停止，恢复继续 |
| 7 | 服务端模式 | 后端就绪时 | 模式=server，实体来自世界库 |
| 8 | 独立模式 | 后端不可用 | 模式=independent，本地构建运行 |
| 9 | 状态查询 | 调 runtime_status.dspy | 返回引擎状态 JSON |

## 服务端辅助 API

- `GET /runtime/api/load_world.dspy?world_id=xxx`
- `GET /runtime/api/runtime_status.dspy?runtime_id=xxx`
- `POST /runtime/api/runtime_event.dspy`（event_type/entity_id/payload）
- `POST /runtime/api/runtime_control.dspy`（action=start/pause/resume）

详见 `skill/SKILL.md`。