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