---
name: scense
description: 元景 W-08 游戏展示模块——游戏会话/结果管理 + bricks 前端游戏页（全屏渲染+交互）。开发/修改 scense 相关功能前必读。
---

# scense 模块（W-08 游戏展示）

## 数据表
| 表 | 作用 | 关键字段 |
|----|------|----------|
| game_session | 游戏会话 | status(created/playing/paused/ended), score, level, elapsed_ms, progress_json, share_token |
| game_result | 游戏结果 | session_id, score, duration_ms, level, result_json |

## 会话状态机（会话级）
- 开始玩：无会话→playing；已有 playing/paused→恢复 playing（续玩）
- playing ⇄ paused（pause/resume）
- playing/paused → ended（end 唯一结算出口，写 game_result）
- 任意状态 → playing（restart 重置分数/关卡）
- save 保存进度快照（不改变状态）

## API 端点（wwwroot/game/api/*.dspy，全部 logined）
| 文件 | 功能 | 对应功能点 |
|------|------|-----------|
| game_list.dspy | 游戏列表 + 历史会话 | W-08a |
| game_start.dspy | 开始玩（进入运行态） | W-08b |
| game_pause.dspy | 暂停 | W-08c |
| game_resume.dspy | 继续 | W-08d |
| game_end.dspy | 结束结算（写 game_result） | W-08e/f/g |
| game_restart.dspy | 重新开始（重置） | W-08f |
| game_share.dspy | 生成/解析分享链接 | W-08h |
| game_save.dspy | 保存进度快照 | W-08j |

## 前端
- `game/index.ui` — bricks 游戏列表入口页
- `game/game_play.html` — 全屏游戏页（canvas + HUD + 结算面板 + 交互），验收入口
- `game/game.js` — 游戏交互（开始/暂停/继续/结束/重开/分享/保存/点选实体）
- `game/game_list.js` — 列表页渲染

## 依赖
- W-10 runtime（runtime.js RuntimeEngine，前端运行态 + /runtime/api/load_world.dspy）
- world 模块（游戏世界来源，防御式降级独立模式）
- sqlor/ahserver/ServerEnv

## 陷阱
1. dspy 禁 import/print/uuid/f-string；显式 return；try/except 包裹；返回值必须 json.dumps。
2. 取库名 `get_module_dbname('scense')`（.dspy 全局）或 `ServerEnv().get_module_dbname('scense')`（.py），禁硬编码 DBNAME。
3. 状态非法流转返回 400（ValueError → code 400），不得 500。
4. sor.C 必须显式 created_at/updated_at；sor.U 同理更新 updated_at。
5. game_play.html 独立 HTML 可用 fetch/setInterval；bricks script actiontype 禁 fetch——列表交互放 game_list.js。
6. RBAC 禁通配符，逐条显式（scripts/load_path.py）。
7. ID 生成用 getID()（appPublic.uniqueID），禁 uuid.uuid4。
8. game_play.html 引用 runtime.js 用绝对路径 `/runtime/runtime.js`（runtime 模块 any 权限自动服务）。