Enforce Genarrative play-type SOP and update docs
Rewrite Genarrative play-type integration guidance across .codex and .hermes to define a platform-level SOP: default to form/image workbench, unify single-image asset slots (CreativeImageInputPanel), standardize series-material sheet->cut->transparent->OSS pipeline, and forbid copying legacy chat/agent workflows as the default. Add decision-log entry freezing the SOP and a pitfalls note warning against direct reuse of old play tools. Update CONTEXT.md and docs/README.md, add a new PRD file, and apply related small server-side changes (module-auth, spacetime-client mappers and runtime) to align back-end code with the new contracts and flows.
This commit is contained in:
485
docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md
Normal file
485
docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md
Normal file
@@ -0,0 +1,485 @@
|
||||
# 跳一跳俯视角玩法模板 PRD 2026-05-19
|
||||
|
||||
## 1. 目标
|
||||
|
||||
新增一个可创作、可试玩、可发布的玩法模板：
|
||||
|
||||
```text
|
||||
跳一跳
|
||||
```
|
||||
|
||||
本模板参考拼图模板的创作闭环，沿用“创作入口 -> 生成过程页 -> 结果页 -> 试玩 -> 发布”的平台链路，但玩法本体改为俯视角 / 等距视角的跳跃闯关。
|
||||
|
||||
首版要求：
|
||||
|
||||
1. 初始草稿生成时，角色形象单独调用一次生图；
|
||||
2. 初始草稿生成时，地块只调用一次生图，输出 3D 视图的 2D 图片图集；
|
||||
3. 运行态不接真实 3D 网格，不生成 GLB / glTF；
|
||||
4. 作品可以直接进入试玩和发布。
|
||||
|
||||
## 2. 模板定位
|
||||
|
||||
模板 ID：
|
||||
|
||||
```text
|
||||
jump-hop
|
||||
```
|
||||
|
||||
用户展示名：
|
||||
|
||||
```text
|
||||
跳一跳
|
||||
```
|
||||
|
||||
体验关键词：
|
||||
|
||||
1. 俯视角；
|
||||
2. 等距感地块；
|
||||
3. 单局闯关；
|
||||
4. 长按蓄力，松手起跳；
|
||||
5. 轻量休闲。
|
||||
|
||||
首版采用竖屏优先的移动端体验，桌面端保持居中展示，画面比例以 `9:16` 为主。参考图的核心视觉要点是：
|
||||
|
||||
1. 大面积留白或浅色渐变背景；
|
||||
2. 角色站在单个地块上；
|
||||
3. 地块有明显顶面、侧面和投影；
|
||||
4. 整体是俯视角 / 等距视角，而不是横版平台跳跃；
|
||||
5. UI 克制，只保留必要控制，不堆说明文案。
|
||||
|
||||
## 3. 与拼图模板的复用边界
|
||||
|
||||
可以复用：
|
||||
|
||||
1. 创作入口和模板分流；
|
||||
2. 生成过程页；
|
||||
3. 结果页的草稿保存、返回编辑、试玩、发布、分享链路；
|
||||
4. 作品架展示和草稿恢复口径；
|
||||
5. 平台统一的发布与公开展示流程。
|
||||
|
||||
不复用：
|
||||
|
||||
1. 拼图关卡切片逻辑；
|
||||
2. 拼图拖拽拼块逻辑；
|
||||
3. 拼图 UI 背景和多关卡编辑结构；
|
||||
4. 任何方格拼合语义。
|
||||
|
||||
## 4. 工程接入范围
|
||||
|
||||
首版需要做到完整玩法闭环，不只做入口占位。
|
||||
|
||||
新增前端阶段：
|
||||
|
||||
```text
|
||||
jump-hop-workspace
|
||||
jump-hop-generating
|
||||
jump-hop-result
|
||||
jump-hop-runtime
|
||||
jump-hop-gallery-detail
|
||||
```
|
||||
|
||||
新增前端组件建议：
|
||||
|
||||
1. `src/components/jump-hop-creation/JumpHopWorkspace.tsx`；
|
||||
2. `src/components/jump-hop-result/JumpHopResultView.tsx`；
|
||||
3. `src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`；
|
||||
4. `src/services/jump-hop/jumpHopClient.ts`。
|
||||
|
||||
新增共享契约建议：
|
||||
|
||||
1. `packages/shared/src/contracts/jumpHop.ts`；
|
||||
2. `server-rs/crates/shared-contracts/src/jump_hop.rs`。
|
||||
|
||||
新增后端模块建议：
|
||||
|
||||
1. `server-rs/crates/module-jump-hop`：纯领域规则，包含路径生成、蓄力换算、落点判定、通关 / 失败状态机；
|
||||
2. `server-rs/crates/api-server/src/jump_hop.rs` 和 `src/jump_hop/` 子模块：HTTP handler、生成编排、资产保存和 DTO 映射；
|
||||
3. `server-rs/crates/spacetime-module/src/jump_hop.rs`：session、work profile、runtime run、公开 view 和 reducer / procedure；
|
||||
4. `server-rs/crates/spacetime-client/src/jump_hop.rs`：api-server 访问 SpacetimeDB 的 facade；
|
||||
5. `server-rs/crates/api-server/src/modules/jump_hop.rs`：路由挂载。
|
||||
|
||||
入口配置事实源必须走 SpacetimeDB `creation_entry_type_config` 默认种子和后台配置接口，不新增前端硬编码入口配置。
|
||||
|
||||
## 5. 创作输入
|
||||
|
||||
创作者需要填写以下内容：
|
||||
|
||||
1. 作品主题描述，必填；
|
||||
2. 角色形象描述，必填；
|
||||
3. 地块风格卡，必选；
|
||||
4. 难度，必选；
|
||||
5. 可选的终点氛围或节奏偏好。
|
||||
|
||||
推荐的最小输入形态是：
|
||||
|
||||
1. 一句话主题；
|
||||
2. 角色一句话描述；
|
||||
3. 风格卡；
|
||||
4. 难度卡。
|
||||
|
||||
不在首版开放手工拖拽平台编辑器。平台路径、地块间距和终点位置由系统自动生成，创作者只负责风格与难度选择。
|
||||
|
||||
### 5.1 地块风格卡
|
||||
|
||||
建议提供以下风格：
|
||||
|
||||
1. 极简积木；
|
||||
2. 纸模玩具；
|
||||
3. 霓虹玻璃；
|
||||
4. 森林石块；
|
||||
5. 未来金属；
|
||||
6. 自定义。
|
||||
|
||||
### 5.2 难度
|
||||
|
||||
建议提供以下离散档位：
|
||||
|
||||
1. 轻松；
|
||||
2. 标准；
|
||||
3. 进阶；
|
||||
4. 挑战。
|
||||
|
||||
难度主要影响：
|
||||
|
||||
1. 平台路径长度；
|
||||
2. 平台间距；
|
||||
3. 可落点容差；
|
||||
4. 完美落点窗口；
|
||||
5. 终点前的节奏变化。
|
||||
|
||||
## 6. 生成规则
|
||||
|
||||
本模板必须把生图责任拆成两条独立链路：
|
||||
|
||||
### 6.1 角色形象只生一次
|
||||
|
||||
角色形象必须只调用一次生图，输出一张可直接进入运行态的主角色图。
|
||||
|
||||
角色图要求：
|
||||
|
||||
1. 单人主角；
|
||||
2. 全身可见；
|
||||
3. 透明背景；
|
||||
4. 角色站姿或轻微前倾姿态；
|
||||
5. 镜头和透视必须匹配俯视角场景；
|
||||
6. 不要求多视角，不要求多帧动画图集。
|
||||
|
||||
角色图生成后作为作品级锚点资产使用，结果页、封面合成、试玩和发布都复用同一张图。后续如果只修改标题、标签、难度或路径，不应默认重新生角色。只有用户在结果页明确点击“重生成角色”时，才允许再调用一次角色生图。
|
||||
|
||||
### 6.2 地块只生一次图集
|
||||
|
||||
地块必须只调用一次生图，输出一张 3D 视图的 2D 图片图集，再由后端切成运行态可用的地块资产。
|
||||
|
||||
地块图集要求：
|
||||
|
||||
1. 统一使用等距 / 俯视角；
|
||||
2. 必须表现出顶面、侧面和投影；
|
||||
3. 必须与角色图保持同一光向；
|
||||
4. 必须有清晰的立体层次，但仍然是 2D 图片；
|
||||
5. 必须包含至少以下地块类型：
|
||||
- 起点地块；
|
||||
- 普通地块；
|
||||
- 目标地块；
|
||||
- 终点地块。
|
||||
|
||||
建议额外包含：
|
||||
|
||||
1. 奖励地块；
|
||||
2. 视觉强调地块；
|
||||
3. 风格化变体地块。
|
||||
|
||||
图集生成后按地块类型切分并去掉背景，运行态直接消费切好的 PNG，不在前端做复杂拼接。只有用户在结果页明确点击“重生成地块”时，才允许再调用一次地块图集生图。
|
||||
|
||||
### 6.3 不新增第三次生成
|
||||
|
||||
首版不把封面、分享海报、路径预览再拆成第三次图像生成。封面和分享图必须由角色图 + 地块图集在本地或后端轻量合成，不额外增加新的角色生图次数。
|
||||
|
||||
### 6.4 路径元数据
|
||||
|
||||
除图片资产外，系统还必须生成跳跃路径元数据：
|
||||
|
||||
1. 平台序列；
|
||||
2. 平台中心点；
|
||||
3. 平台宽度；
|
||||
4. 平台间距；
|
||||
5. 终点索引；
|
||||
6. 评分和容差参数。
|
||||
|
||||
路径由领域规则自动生成，创作者不直接编辑坐标。路径元数据不依赖 LLM 或图片生成。
|
||||
|
||||
### 6.5 推荐的难度区间
|
||||
|
||||
| 难度 | 平台数量 | 平台间距 | 节奏 |
|
||||
| --- | ---: | --- | --- |
|
||||
| 轻松 | 12 - 14 | 短 | 宽容 |
|
||||
| 标准 | 16 - 18 | 中 | 稳定 |
|
||||
| 进阶 | 20 - 24 | 中长 | 紧凑 |
|
||||
| 挑战 | 26 - 32 | 长 | 高压 |
|
||||
|
||||
平台宽度和容差由系统按难度自动缩放，不要求创作者手工填写。
|
||||
|
||||
## 7. 契约草案
|
||||
|
||||
### 7.1 草稿结构
|
||||
|
||||
`JumpHopDraft` 至少包含：
|
||||
|
||||
1. `templateId = "jump-hop"`；
|
||||
2. `templateName = "跳一跳"`；
|
||||
3. `profileId`；
|
||||
4. `workTitle`；
|
||||
5. `workDescription`；
|
||||
6. `themeTags`；
|
||||
7. `difficulty`；
|
||||
8. `stylePreset`；
|
||||
9. `characterPrompt`；
|
||||
10. `tilePrompt`；
|
||||
11. `characterAsset`；
|
||||
12. `tileAtlasAsset`；
|
||||
13. `tileAssets[]`；
|
||||
14. `path`；
|
||||
15. `coverComposite`；
|
||||
16. `generationStatus`。
|
||||
|
||||
### 7.2 资产结构
|
||||
|
||||
`JumpHopCharacterAsset` 至少包含：
|
||||
|
||||
1. `assetId`；
|
||||
2. `imageSrc`；
|
||||
3. `imageObjectKey`；
|
||||
4. `assetObjectId`；
|
||||
5. `generationProvider`；
|
||||
6. `prompt`；
|
||||
7. `width`；
|
||||
8. `height`。
|
||||
|
||||
`JumpHopTileAsset` 至少包含：
|
||||
|
||||
1. `tileType`；
|
||||
2. `imageSrc`；
|
||||
3. `imageObjectKey`；
|
||||
4. `assetObjectId`；
|
||||
5. `sourceAtlasCell`；
|
||||
6. `visualWidth`；
|
||||
7. `visualHeight`；
|
||||
8. `topSurfaceRadius`；
|
||||
9. `landingRadius`。
|
||||
|
||||
`tileType` 首版限定：
|
||||
|
||||
```text
|
||||
start | normal | target | finish | bonus | accent
|
||||
```
|
||||
|
||||
### 7.3 路径结构
|
||||
|
||||
`JumpHopPath` 至少包含：
|
||||
|
||||
1. `seed`；
|
||||
2. `difficulty`；
|
||||
3. `platforms[]`；
|
||||
4. `finishIndex`；
|
||||
5. `cameraPreset`；
|
||||
6. `scoring`。
|
||||
|
||||
`JumpHopPlatform` 至少包含：
|
||||
|
||||
1. `platformId`；
|
||||
2. `tileType`；
|
||||
3. `x`；
|
||||
4. `y`；
|
||||
5. `width`；
|
||||
6. `height`；
|
||||
7. `landingRadius`；
|
||||
8. `perfectRadius`；
|
||||
9. `scoreValue`。
|
||||
|
||||
### 7.4 运行态快照
|
||||
|
||||
`JumpHopRunSnapshot` 至少包含：
|
||||
|
||||
1. `runId`；
|
||||
2. `profileId`；
|
||||
3. `status = playing | failed | cleared`；
|
||||
4. `currentPlatformIndex`；
|
||||
5. `score`；
|
||||
6. `combo`；
|
||||
7. `lastJump`；
|
||||
8. `startedAtMs`；
|
||||
9. `finishedAtMs`。
|
||||
|
||||
`lastJump` 至少包含：
|
||||
|
||||
1. `chargeMs`；
|
||||
2. `jumpDistance`；
|
||||
3. `targetPlatformIndex`；
|
||||
4. `landedX`；
|
||||
5. `landedY`；
|
||||
6. `result = miss | hit | perfect | finish`。
|
||||
|
||||
## 8. API 草案
|
||||
|
||||
HTTP 路由建议：
|
||||
|
||||
```text
|
||||
POST /api/creation/jump-hop/sessions
|
||||
GET /api/creation/jump-hop/sessions/{sessionId}
|
||||
POST /api/creation/jump-hop/sessions/{sessionId}/actions
|
||||
POST /api/creation/jump-hop/works/{profileId}/publish
|
||||
GET /api/runtime/jump-hop/works/{profileId}
|
||||
POST /api/runtime/jump-hop/runs
|
||||
POST /api/runtime/jump-hop/runs/{runId}/jump
|
||||
POST /api/runtime/jump-hop/runs/{runId}/restart
|
||||
GET /api/runtime/jump-hop/gallery
|
||||
GET /api/runtime/jump-hop/gallery/{publicWorkCode}
|
||||
```
|
||||
|
||||
动作类型建议：
|
||||
|
||||
```text
|
||||
compile-draft
|
||||
regenerate-character
|
||||
regenerate-tiles
|
||||
update-work-meta
|
||||
update-difficulty
|
||||
```
|
||||
|
||||
`compile-draft` 是长耗时动作。前端进入生成页后必须持久化 `generationStatus=generating`，刷新后能从作品架恢复生成页。失败前需要复读 session；如果后端已经完成草稿并写回资产，前端按成功收尾。
|
||||
|
||||
## 9. SpacetimeDB 表和 view
|
||||
|
||||
建议新增表：
|
||||
|
||||
1. `jump_hop_agent_session`；
|
||||
2. `jump_hop_work_profile`；
|
||||
3. `jump_hop_runtime_run`；
|
||||
4. `jump_hop_event`；
|
||||
5. `jump_hop_leaderboard_entry`，首版可暂不对外展示；
|
||||
6. `jump_hop_gallery_view`；
|
||||
7. `jump_hop_gallery_card_view`。
|
||||
|
||||
表结构新增字段必须按 SpacetimeDB 迁移规则放在结构体末尾并设置明确默认值。新增或调整表、reducer、procedure、view 后必须同步 `migration.rs`、表目录、生成 bindings，并执行 `npm run check:spacetime-schema`。
|
||||
|
||||
公开列表主路径应优先订阅 `jump_hop_gallery_card_view` 后在 `api-server` 本地 cache 构造列表响应，不要让每个 HTTP 请求都调用 SpacetimeDB procedure 组装全量列表。
|
||||
|
||||
## 10. 结果页能力
|
||||
|
||||
结果页必须展示：
|
||||
|
||||
1. 作品标题；
|
||||
2. 作品简介；
|
||||
3. 角色形象；
|
||||
4. 地块图集；
|
||||
5. 路径预览；
|
||||
6. 标签；
|
||||
7. 试玩；
|
||||
8. 发布；
|
||||
9. 返回编辑。
|
||||
|
||||
结果页还必须支持：
|
||||
|
||||
1. 单独重生成角色；
|
||||
2. 单独重生成地块图集；
|
||||
3. 单独修改标题和简介；
|
||||
4. 单独调整标签和难度。
|
||||
|
||||
结果页不应强制再走一次封面生图。封面只做合成，不新增图像生成调用。
|
||||
|
||||
## 11. 运行态规则
|
||||
|
||||
运行态采用 2D 表现，但画面视觉上必须保留参考图那种俯视角 / 等距感。
|
||||
|
||||
### 11.1 核心玩法
|
||||
|
||||
1. 玩家长按蓄力；
|
||||
2. 松手后角色按蓄力长度起跳；
|
||||
3. 跳跃距离决定是否落到下一个地块；
|
||||
4. 落在目标区域内判定成功；
|
||||
5. 落在地块外或越界判定失败；
|
||||
6. 到达终点地块判定通关。
|
||||
|
||||
### 11.2 判定规则
|
||||
|
||||
1. 只做一个当前局面的起跳判定；
|
||||
2. 不做复杂连招动作树；
|
||||
3. 不新增生命数、体力、回合数；
|
||||
4. 不新增计时赛作为首版核心规则；
|
||||
5. 不把前端动画结果当成最终真相，通关与失败必须能回写运行态状态。
|
||||
|
||||
### 11.3 角色动画
|
||||
|
||||
角色不需要多帧生图，运行态只通过位移、缩放、轻微旋转和投影变化表达：
|
||||
|
||||
1. 蓄力时轻微压缩；
|
||||
2. 起跳时向上抬升；
|
||||
3. 空中保持可读轮廓；
|
||||
4. 落地时轻微弹性回弹；
|
||||
5. 失败时从地块边缘跌落。
|
||||
|
||||
### 11.4 摄像机与构图
|
||||
|
||||
1. 相机以当前角色和下一地块为中心；
|
||||
2. 至少保证下一个落点一直可见；
|
||||
3. 画面要留出顶部和底部的 UI 安全区；
|
||||
4. 不要把地块做得太满，保留参考图那种疏朗感。
|
||||
|
||||
### 11.5 UI
|
||||
|
||||
运行态 UI 只保留必要元素：
|
||||
|
||||
1. 分数；
|
||||
2. 暂停；
|
||||
3. 重新开始；
|
||||
4. 分享；
|
||||
5. 结算按钮。
|
||||
|
||||
不默认展示大段规则说明。首进如果需要引导，只能用一次轻量提示，不允许常驻一屏的说明文案。
|
||||
|
||||
## 12. 视觉规范
|
||||
|
||||
本模板的视觉目标是“像 3D，但仍是 2D 图片”。
|
||||
|
||||
必须遵守：
|
||||
|
||||
1. 平台有明确厚度；
|
||||
2. 侧面可见分层或材质变化；
|
||||
3. 投影统一且方向一致；
|
||||
4. 背景干净，颜色克制；
|
||||
5. 角色尺寸在小屏上依然可读；
|
||||
6. 地块不能出现过多文字、按钮或装饰信息；
|
||||
7. 不能把运行态做成重 UI 面板。
|
||||
|
||||
建议的背景策略：
|
||||
|
||||
1. 以静态浅色渐变或纯色背景为主；
|
||||
2. 不把背景也做成每次都生成的重资产；
|
||||
3. 让地块和角色成为画面的第一视觉焦点。
|
||||
|
||||
## 13. 发布后体验
|
||||
|
||||
发布后的作品必须支持：
|
||||
|
||||
1. 进入作品架和公开展示；
|
||||
2. 分享；
|
||||
3. 试玩；
|
||||
4. 重新进入结果页编辑。
|
||||
|
||||
发布后的卡片封面应优先由角色图和地块图合成，不要求单独再生成封面图。
|
||||
|
||||
首版不新增排行榜、回放和对局对抗。后续如要扩展排行，可另起版本，不要塞进首版模板范围。
|
||||
|
||||
## 14. 验收
|
||||
|
||||
1. 创作入口能看到 `跳一跳` 模板；
|
||||
2. 创作者可以填写主题、角色描述、风格和难度；
|
||||
3. 提交后只生成一次角色图和一次地块图集；
|
||||
4. 结果页能看到角色图、地块图集和路径预览；
|
||||
5. 结果页可单独重生成角色或地块；
|
||||
6. 试玩进入跳一跳运行态；
|
||||
7. 长按蓄力、松手起跳、落点判定、失败和通关都可用；
|
||||
8. 作品可以保存、发布和分享；
|
||||
9. 前端不直接读取或暴露生图密钥；
|
||||
10. 发布后的封面不依赖第三次额外生图。
|
||||
11. `npm run check:spacetime-schema` 在 schema 变更后通过；
|
||||
12. `npm run check:encoding` 通过。
|
||||
Reference in New Issue
Block a user