feat: add puzzle clear template runtime
This commit is contained in:
77
docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md
Normal file
77
docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# 拼消消玩法模板 PRD
|
||||
|
||||
日期：`2026-05-30`
|
||||
|
||||
## 目标
|
||||
|
||||
新增玩法模板 **拼消消**，工程域与 `playId` 均为 `puzzle-clear`，公开作品码前缀为 `PC-`。拼消消以拼图的交换 / 拖拽手感为原型，但运行态规则独立：玩家移动 1x1 卡牌碎片，把同一复合图案组拼成完整矩形后消除；消除产生空位后，由顶部对应纵列的卡牌准备区下落补位。
|
||||
|
||||
首版必须完成公开闭环：
|
||||
|
||||
```text
|
||||
创作入口 -> 轻表单工作台 -> 独立生成页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式 runtime -> 基础统计 / 作品架 / 广场
|
||||
```
|
||||
|
||||
## 创作工具平台接入声明
|
||||
|
||||
- 工作台模式：表单 / 图片输入创作工作台。
|
||||
- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态。
|
||||
- 单图资产槽位：
|
||||
- `board-background` / `ui-background` / `中央场地底图` / `boardBackgroundPrompt` 优先、空值时回退 `themePrompt`，并支持用户上传图 / 写回 `draft.boardBackgroundAsset`、`draft.boardBackgroundPrompt`、`work.boardBackgroundAsset` 与 `work.boardBackgroundPrompt` / 允许历史图 / 允许 AI 重绘。
|
||||
- 中央场地底图的字段名沿用平台表面口径，实际作用是玩家逐步消除清空中央棋盘后慢慢看到的主题目标图；AI 生成尺寸必须与中央棋盘一致，使用 1:1 正方形画面。prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，带来探索、揭开全貌和追求目标完成的感受；不得继续要求“画面干净”或“适合作为卡牌棋盘底图”。
|
||||
- 系列素材槽位：
|
||||
- `batchId=puzzle-clear-pattern-atlas-v1`。
|
||||
- `sheetSpec`：4 张素材工作表，每张 `1024x1536` 竖版，后台按 `4 列 x 6 行` 裁切，每个 1x1 单元为 `256x256`；服务端再把切片合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数为 `35`，形状配比 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`，总计 `95` 个 1x1 卡牌切片。
|
||||
- `slotSpecs`：每个复合图案组一个 `patternGroup`，服务端预排 `groupId`、`shape`、atlas 坐标和 1x1 切片坐标。
|
||||
- 切图规则：生图 prompt 只要求复合图案组能按 4x6 素材工作表均等切成 1x1 方形小份，不允许模型在图上绘制切分线、边框、网格线或裁切参考线；服务端按 sheet 布局直接裁出 1x1 卡牌碎片，校验每个编号占格数与领域图案组面积一致，再合成最终 atlas，写入 `patternGroups[]` 与 `cardAssets[]`。
|
||||
- 透明化规则：首版保留完整方形卡面，不强制透明化；若 provider 输出带边框、切分线、网格、裁切参考线或文字，生成任务失败并回写审计。
|
||||
- 失败回写：生成页写回 `generationStatus=failed` 与失败阶段；结果页保留重试入口。
|
||||
- 局部重生成：v1 允许整批 4 张素材工作表重试，不做单组局部重生。
|
||||
- API 命名空间：`/api/creation/puzzle-clear/...` 与 `/api/runtime/puzzle-clear/...`。
|
||||
- 业务真相：草稿、发布、runtime snapshot、胜负、补牌、防死局、统计均由后端裁决；前端只做动画和交互表现。
|
||||
- 创作工具模式例外：无。
|
||||
- 验证命令：`npm run check:encoding`、`npm run typecheck`、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`；涉及 SpacetimeDB schema 后运行 `npm run spacetime:generate`、`npm run check:spacetime-runtime-access`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`。
|
||||
|
||||
## 工作台字段
|
||||
|
||||
| 字段 | 契约字段 | 默认值 | 校验 | 落库 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 作品标题 | `workTitle` | 空 | 必填，1-30 字 | session draft / work profile |
|
||||
| 简介 | `workDescription` | 空 | 0-120 字 | session draft / work profile |
|
||||
| 主题词 | `themePrompt` | 空 | 必填，1-80 字 | 生成 prompt 与草稿 |
|
||||
| 场地底图主题词 | `boardBackgroundPrompt` | 空 | 0-80 字；为空时底图生成回退 `themePrompt` | session draft / work profile / 主题目标图生成 prompt |
|
||||
| 中央场地底图 | `boardBackgroundAsset` | 空 | 上传或 AI 生成至少一种 | 单图资产槽位 |
|
||||
| AI 生成底图 | `generateBoardBackground` | `true` | boolean | 生成编排参数 |
|
||||
|
||||
规则参数不开放创作者编辑：棋盘尺寸、倒计时、消除次数、形状解锁、防死局发牌和半锁定规则固定。
|
||||
|
||||
## 运行规则
|
||||
|
||||
| 关卡 | 棋盘 | 目标消除 | 倒计时 | 解锁形状 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | 6x6 | 35 | 10 分钟 | 1x2、1x3、2x2、2x3 |
|
||||
|
||||
- 开局每个小格子从背面翻向正面。
|
||||
- 可消除图由横向或纵向复合图案组组成，最小消除单位为两张图拼接。
|
||||
- 完成一个复合图案组后，该组所有 1x1 卡牌碎片消除。
|
||||
- 消除后空位按列由顶部卡牌准备区下落补齐。
|
||||
- 每次补牌至少保证掉落卡中有一张可以与场上剩余某张卡拼接，防止死局。
|
||||
- 非 2 格消除时，若场上已有局部完成的半锁定拼接组，补牌不得破坏它。
|
||||
- 半锁定拼接组可整体拖动；玩家用外部单格撞入组内某格时，只交换该格，组其余部分保留，组状态退回半完成。
|
||||
- 超时只判当前关失败，可重试当前关；完成 35 次目标并清空当前棋盘后整局完成。
|
||||
|
||||
## 结果页
|
||||
|
||||
结果页展示：素材 atlas、中央场地底图、发布状态、试玩入口和失败重试。结果页不写功能说明类文案，不开放规则编辑器，不新增排行榜配置。
|
||||
|
||||
## 统计
|
||||
|
||||
首版只记录正式 `published` run：
|
||||
|
||||
- 开局。
|
||||
- 全局完成。
|
||||
- 当前关失败。
|
||||
- 耗时。
|
||||
- 消除统计。
|
||||
|
||||
草稿试玩不写正式统计，不进入排行榜；v1 不做排行榜。
|
||||
115
docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md
Normal file
115
docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# 拼消消玩法模板技术方案
|
||||
|
||||
日期：`2026-05-30`
|
||||
|
||||
## 总体边界
|
||||
|
||||
拼消消使用独立工程域 `puzzle-clear`，不复用拼图运行态规则本体。实现按 DDD 分层：
|
||||
|
||||
- `module-puzzle-clear`：纯领域规则，覆盖图案组规划、棋盘、交换、半锁定、消除、补牌、防死局、关卡状态。
|
||||
- `shared-contracts` / `packages/shared`：工作台输入、生成素材、结果页、作品摘要、runtime snapshot 与 action DTO。
|
||||
- `spacetime-module`：session、work profile、runtime run、事件 / 统计、公开 source view。
|
||||
- `spacetime-client`：typed facade 与 row mapper。
|
||||
- `api-server`：Axum 路由、鉴权、入口熔断、生成编排、资产持久化、BFF。
|
||||
- `platform-image` / OSS / asset object：图片生成、切图、上传、换签和失败审计。
|
||||
- 前端：轻表单、生成页、结果页与 runtime 动画，不承接正式业务真相。
|
||||
|
||||
## 资产生成方案
|
||||
|
||||
素材目标从“单张超大 atlas 生图”收敛为 4 张素材工作表，再由服务端合成最终 atlas：
|
||||
|
||||
- image2 调用：4 次，每次生成 1 张 `1024x1536` 竖版素材工作表。
|
||||
- sheet 裁切：每张按 `4 列 x 6 行` 裁切，每个 1x1 单元为 `256x256`。
|
||||
- 最终 atlas：服务端把 95 个切片按领域坐标合成 `10x10 / 2560x2560` PNG，空单元保留浅色背景。
|
||||
- 运行态素材：最终写回 `35` 个复合图案组和 `95` 个 1x1 卡牌切片。
|
||||
|
||||
服务端固定布局如下：
|
||||
|
||||
| 形状 | 数量 | 单组单元数 | 解锁 |
|
||||
| --- | ---: | ---: | --- |
|
||||
| 1x2 | 23 | 2 | 第 1 关 |
|
||||
| 1x3 | 5 | 3 | 第 1 关 |
|
||||
| 2x2 | 4 | 4 | 第 1 关 |
|
||||
| 2x3 | 3 | 6 | 第 1 关 |
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
主题词 / 场地底图主题词 / 用户底图 -> 4 张 sheet 坐标规划 -> gpt-image-2 生成素材工作表 -> 按 4x6 裁切 1x1 -> 合成最终 atlas -> atlas 与卡牌切片持久化 -> OSS / asset_object / bind -> session draft 回写
|
||||
```
|
||||
|
||||
中央场地底图的 prompt 来源固定为：若用户填写 `boardBackgroundPrompt`，AI 生成底图只读取该字段；若该字段为空，才回退读取 `themePrompt`。用户直接上传底图资产时不再用主题词重写该资产，只执行平台资产持久化与换签。中央场地底图在运行态不是普通棋盘衬底，而是玩家逐渐消除卡牌后露出的主题目标图；生成请求使用与中央棋盘一致的 1:1 正方形尺寸，prompt 必须强调探索、揭开全貌、追求完成目标、精致主题主视觉和强主题表现，不写“画面干净”或“适合作为卡牌棋盘底图”。
|
||||
|
||||
### 素材工作表风险与切片验证
|
||||
|
||||
风险：4x6 工作表 prompt 仍需要告诉 provider 编号布局；如果模型把布局理解成 UI 海报、说明图或卡牌模板，可能画出文字、编号、边框、切分线、贴纸外框或重复主体。若 provider 无法严格按布局输出，切片后可能出现跨格、主体贴边、重复图案、文字或图案错位。
|
||||
|
||||
验证策略：
|
||||
|
||||
- 生图 prompt 明确禁止文字、水印、UI、边框标签、切分线、网格线、裁切参考线和跨格主体。
|
||||
- 复合图案组本身不画任何可见分割辅助线，但 prompt 必须说明每个 `1x2`、`1x3`、`2x2`、`2x3` 图案都能被服务端按等大的 1x1 方形单元切分；纵向 `1x2` 按横向切线分成两个 1x1，小图案内不显示切线；横向 `1x2` 按纵向切线分成两个 1x1，小图案内不显示切线；其他形状同理。
|
||||
- 服务端保留 `PuzzleClearPatternGroup` 坐标清单，切片前校验每个 sheet 编号出现次数等于领域图案组 `width * height`，并要求同编号区域是完整连续矩形；切片后还应对尺寸、非空像素比例和重复 hash 做校验。
|
||||
- 首版若当前 provider 无法稳定产出可切 atlas，生成任务进入 `failed`，错误写入审计；不得退回前端假素材或绕过平台资产底座。
|
||||
- 草稿编译和作品发布都必须拒绝缺失 atlas、缺失卡牌切片、空 `assetObjectId` / `imageObjectKey` 或 `placeholder` 占位资产；`spacetime-client` 不再为编译请求合成默认 atlas / card assets。
|
||||
- 技术回退需要用户确认后才能改成更多 sheet、降低切片规格或改为逐图生成；当前需求固定为 4 张 `1024x1536` sheet 与最终 `2560x2560` atlas。
|
||||
|
||||
## 领域规则
|
||||
|
||||
`module-puzzle-clear` 已固定以下规则：
|
||||
|
||||
- 关卡配置：单关 `6x6/35`，600 秒。
|
||||
- 图案组配比：`1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。
|
||||
- 开局随机铺满并保证至少一步可解。
|
||||
- 补牌按列重力下落；补牌后仍保证至少一步可解。
|
||||
- 完整图案组消除并清空对应格。
|
||||
- 半锁定拼接组只由玩家主动交换 / 撞入打散，补牌不破坏。
|
||||
- 超时失败只作用于当前单关，可重试；完成 35 次消除目标并清空棋盘后整局完成。
|
||||
|
||||
## API 命名空间
|
||||
|
||||
- `POST /api/creation/puzzle-clear/sessions`
|
||||
- `GET /api/creation/puzzle-clear/sessions/{sessionId}`
|
||||
- `POST /api/creation/puzzle-clear/sessions/{sessionId}/actions`
|
||||
- `GET /api/creation/puzzle-clear/works`
|
||||
- `GET /api/creation/puzzle-clear/works/{profileId}`
|
||||
- `POST /api/creation/puzzle-clear/works/{profileId}/publish`
|
||||
- `GET /api/runtime/puzzle-clear/works/{profileId}`
|
||||
- `POST /api/runtime/puzzle-clear/runs`
|
||||
- `POST /api/runtime/puzzle-clear/runs/{runId}/swap`
|
||||
- `POST /api/runtime/puzzle-clear/runs/{runId}/retry-level`
|
||||
- `POST /api/runtime/puzzle-clear/runs/{runId}/next-level`
|
||||
- `POST /api/runtime/puzzle-clear/runs/{runId}/time-up`
|
||||
|
||||
api-server 路由熔断使用 SpacetimeDB 创作入口配置 `puzzle-clear`，不得新增前端硬编码事实源。
|
||||
|
||||
## Runtime 事件与统计载荷
|
||||
|
||||
正式 `published` run 记录开局、全局完成、当前关失败、耗时和消除统计。runtime action 返回的终态事件包括：
|
||||
|
||||
- `run-finished`：第 1 关完成并结束整局，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
|
||||
- `level-failed`：当前关超时失败，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
|
||||
|
||||
草稿试玩只消费同一份 snapshot/action 结果做表现，不写正式统计。
|
||||
|
||||
## 前端阶段
|
||||
|
||||
新增阶段：
|
||||
|
||||
- `puzzle-clear-workspace` -> `/creation/puzzle-clear`
|
||||
- `puzzle-clear-generating` -> `/creation/puzzle-clear/generating`
|
||||
- `puzzle-clear-result` -> `/creation/puzzle-clear/result`
|
||||
- `puzzle-clear-runtime` -> `/runtime/puzzle-clear`
|
||||
|
||||
runtime 移动端优先，首屏结构为顶部倒计时 / 单关铭牌、顶部列准备区、棋盘、失败 / 完成弹层。棋盘主网格、半锁定组覆盖层和消除 / 掉落覆盖层统一使用 3px 格间距。动画包括开场翻转、列补牌下落和消除表现，不再有下一关切换。消除和补牌动画只能作为当前后端 snapshot 的表现层覆盖；已有场上卡片因重力下沉后的最终格不得被旧消除坐标或掉落覆盖层隐藏，避免出现“下方空位但上方卡片未下落”的视觉假象。
|
||||
|
||||
## 验证计划
|
||||
|
||||
- `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`
|
||||
- `cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`
|
||||
- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml puzzle_clear_compile_requires_real_atlas_assets_from_api_server`
|
||||
- `npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`
|
||||
- `npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`
|
||||
- `npm run test -- src/routing/appPageRoutes.test.ts src/services/publicWorkCode.test.ts`
|
||||
- `npm run check:encoding`
|
||||
- `npm run typecheck`
|
||||
- 接入 SpacetimeDB schema 后：`npm run spacetime:generate`、`npm run check:spacetime-runtime-access`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`
|
||||
@@ -619,6 +619,45 @@ npm run check:server-rs-ddd
|
||||
- Rust 结构体：`PuzzleWorkProfileRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
|
||||
|
||||
### `puzzle_clear_agent_session`
|
||||
|
||||
- Rust 结构体：`PuzzleClearAgentSessionRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
|
||||
- 说明：拼消消创作会话表，保存轻表单草稿、生成状态、已发布 profile 关联和更新时间；只由拼消消 procedure 读写。
|
||||
|
||||
### `puzzle_clear_work_profile`
|
||||
|
||||
- Rust 结构体：`PuzzleClearWorkProfileRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
|
||||
- 说明：拼消消作品 profile 表，保存中央底图资产、4 张素材工作表切片后合成的最终 atlas、35 个复合图案组、95 个 1x1 卡牌切片、卡背占位图、发布状态、可见性和基础 play count；公开列表 / 详情只通过 read model 消费，不让前端直接订阅源表。
|
||||
- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
|
||||
|
||||
### `puzzle_clear_runtime_run`
|
||||
|
||||
- Rust 结构体：`PuzzleClearRuntimeRunRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
|
||||
- 说明：拼消消正式 runtime run 表，保存当前关卡、已消除次数、棋盘 snapshot、开始 / 完成时间和 run 状态；正式胜负、重试、完成、超时和交换结果以后端 procedure 裁决为准。
|
||||
|
||||
### `puzzle_clear_event`
|
||||
|
||||
- Rust 结构体：`PuzzleClearEventRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
|
||||
- 说明：拼消消基础 runtime 事件表，记录 published run 的开局、关卡完成、全局完成、失败、超时和消除统计来源；首版不做排行榜。
|
||||
|
||||
### SpacetimeDB view：`puzzle_clear_gallery_view`
|
||||
|
||||
- Rust view：`puzzle_clear_gallery_view`
|
||||
- 返回类型：`Vec<PuzzleClearGalleryViewRow>`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear.rs`
|
||||
- 说明：拼消消公开详情 source 投影，只暴露 `publication_status = published` 且 `visible = true` 的作品，包含 atlas、底图、图案组和卡牌切片等详情级字段；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。
|
||||
|
||||
### SpacetimeDB view：`puzzle_clear_gallery_card_view`
|
||||
|
||||
- Rust view：`puzzle_clear_gallery_card_view`
|
||||
- 返回类型：`Vec<PuzzleClearGalleryCardViewRow>`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear.rs`
|
||||
- 说明：拼消消公开列表 source 投影，只暴露平台卡片需要的公开字段；统一公开列表主路径通过 `public_work_gallery_entry` 消费该 view，`/api/runtime/puzzle-clear/gallery` 保留玩法专属 HTTP shape。
|
||||
|
||||
### SpacetimeDB view：`puzzle_gallery_view`
|
||||
|
||||
- Rust view：`puzzle_gallery_view`
|
||||
@@ -648,6 +687,7 @@ npm run check:server-rs-ddd
|
||||
- `SELECT * FROM public_work_detail_entry`
|
||||
- `SELECT * FROM bark_battle_gallery_view`
|
||||
- `SELECT * FROM puzzle_gallery_card_view`
|
||||
- `SELECT * FROM puzzle_clear_gallery_card_view`
|
||||
- `SELECT * FROM jump_hop_gallery_card_view`
|
||||
- `SELECT * FROM wooden_fish_gallery_card_view`
|
||||
- `SELECT * FROM custom_world_gallery_entry`
|
||||
@@ -664,6 +704,7 @@ npm run check:server-rs-ddd
|
||||
- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'visual-novel'`
|
||||
- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'big-fish'`
|
||||
- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'bark-battle'`
|
||||
- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle-clear'`
|
||||
- `SELECT * FROM creation_entry_config`
|
||||
- `SELECT * FROM creation_entry_type_config`
|
||||
- `SELECT * FROM asset_object`
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 本地开发验证与生产运维
|
||||
# 本地开发验证与生产运维
|
||||
|
||||
更新时间：`2026-05-15`
|
||||
|
||||
@@ -47,6 +47,8 @@ npm run dev:api-server
|
||||
|
||||
开发态 `npm run dev` 与 `npm run dev:api-server` 会默认注入 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，因此密码登录在本地开发环境可直接注册未知手机号账号；生产环境仍按 `api-server` 配置默认关闭该开关。
|
||||
|
||||
本地只做账号/UI smoke 且需要短信登录时，`SMS_AUTH_PROVIDER` 应显式设为 `mock`，并把 `SMS_AUTH_MOCK_VERIFY_CODE` 设为固定值（当前常用 `123456`），再重启 `npm run dev` 或 `npm run dev:api-server`。如果 `.env.local` 还保留 `SMS_AUTH_PROVIDER=aliyun`，`POST /api/auth/phone/login` 用 mock 验证码会稳定报“验证码错误”，不是前端表单问题。真实短信联调再切回 `aliyun` 并重启。
|
||||
|
||||
如果本地 `GET /api/creation-entry/config` 返回 `No such procedure`，或 `api-server` 日志出现 `no such table: puzzle_gallery_card_view` / `no such table: wooden_fish_gallery_card_view` 这类公开 view 缺失，通常是 `.env.local` 指向的 SpacetimeDB 库还没有发布当前 `spacetime-module`，或当前 CLI 身份无权发布该库。debug 构建的 `api-server` 会临时使用后端默认入口配置兜底，避免创作作品架整块消失；正式修复仍应切换到拥有目标库权限的 SpacetimeDB 身份后重新运行 `npm run dev` 完成发布，或用 gitignored 的 `spacetime.local.json` 指向可发布的本地库。
|
||||
|
||||
本地排查 schema 漂移时，先用当前 dev server 显式查询目标库，例如：
|
||||
|
||||
@@ -171,6 +171,34 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
|
||||
平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='wooden-fish'` 与 `WF-*` 公开作品号识别敲木鱼作品；公开列表应走 `wooden_fish_gallery_card_view` 订阅缓存，公开详情或运行态启动时卡片摘要不足则补读完整 work profile。
|
||||
|
||||
## 拼消消
|
||||
|
||||
对外名称：拼消消。工程域与 `playId`：`puzzle-clear`。公开作品码前缀：`PC-`。当前按新增玩法 SOP 接入完整公开闭环，不复用拼图运行态规则本体。
|
||||
|
||||
链路为：
|
||||
|
||||
```text
|
||||
创作入口 -> 轻表单工作台 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式运行态
|
||||
```
|
||||
|
||||
工作台字段固定为作品标题、简介、主题词、场地底图主题词 `boardBackgroundPrompt`、中央场地底图槽位、是否 AI 生成底图。中央场地底图必须复用 `CreativeImageInputPanel`，支持上传、历史图和 AI 重绘；若用户填写 `boardBackgroundPrompt`，AI 生成底图只读取该字段，字段为空时才回退读取 `themePrompt`；用户上传底图时不再用主题词重写该资产。中央场地底图的字段名保留平台口径，但实际语义是玩家逐步消除清空棋盘后露出的主题目标图，生成尺寸必须与中央棋盘一致，按 1:1 正方形出图；prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，不再要求“画面干净”或“适合作为卡牌棋盘底图”。运行态必须把中央场地底图作为棋盘内部静态底图使用，不能降级成整页氛围背景；卡牌消除后产生的空位和拖拽源位应露出该棋盘底图。卡面背面背景 v1 使用默认占位图，不作为创作者配置项。规则参数不开放编辑：单关 `6x6`、每局 10 分钟、35 次目标消除、形状解锁、防死局发牌和半锁定规则均由后端规则集固定。
|
||||
|
||||
素材生成使用拼消消专用编排，但必须复用 `platform-image`、VectorEngine `gpt-image-2`、OSS、`asset_object`、换签和失败审计。素材目标是 4 张 `1024x1536` 竖版工作表，每张后台按 `4 列 x 6 行` 裁切，每格 `256x256`；服务端从工作表切出总计 95 个 1x1 卡牌碎片，再合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数固定为 35，形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。服务端先预排每个复合图案组的 sheet 布局、最终 atlas 坐标和形状，再按坐标切成 1x1 卡牌碎片作为运行态素材；sheet 生图 prompt 只能要求复合图案组可按后台 4x6 均等切成 1x1 方形小份，不能让模型在小图案上绘制切分线、边框、网格线、编号或裁切参考线。当前只有单关，同关内复合图案不重复。草稿编译和发布都必须使用 api-server 已持久化的真实 atlas / card assets，拒绝缺失、空对象键或 `placeholder` 占位素材，不允许 `spacetime-client` 或 SpacetimeDB 侧合成临时素材绕过平台图片底座。
|
||||
|
||||
运行态规则：
|
||||
|
||||
1. 单关固定为 `6x6 / 35次消除`。
|
||||
2. 每局固定 10 分钟；超时只判当前关失败，可重试当前关。
|
||||
3. 当前关直接出现 `1x2`、`1x3`、`2x2` 和 `2x3`。
|
||||
4. 开局棋盘随机铺满并保证至少一步可解；补牌后也必须由后端保证至少一步可解。
|
||||
5. 顶部卡牌准备区按纵列补位，某列有空格时该列卡牌从顶部下落。
|
||||
6. 非 2 格消除时，补牌不得破坏已完成局部；只有玩家主动交换或撞入才允许打散半锁定拼接组。
|
||||
7. 正式 runtime 只消费后端 snapshot 与 action 结果；前端负责开局翻转、拖拽、掉落、消除和弹层动画。
|
||||
拖拽手感必须对齐拼图模板：开局小卡片只翻转一次，交换落位不得重新翻牌；按住后可见卡片立即跟随鼠标或手指，源位置即时留出空槽；放下时被替换卡片要快速飞向对应空位；已完成局部拼接组要以连续整体呈现并可作为整组拖起。拖拽浮层必须挂到页面级 `document.body` portal，避免平台壳层 transform 让 `position: fixed` 和 `clientX/clientY` 坐标系错位。
|
||||
8. 正式 `published` run 的终态事件使用 `run-finished` 和 `level-failed`，事件结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta` 和 `elapsedMs`，供基础统计与排障回读。
|
||||
|
||||
新增阶段为 `puzzle-clear-workspace`、`puzzle-clear-generating`、`puzzle-clear-result` 和 `puzzle-clear-runtime`；路由为 `/creation/puzzle-clear`、`/creation/puzzle-clear/generating`、`/creation/puzzle-clear/result` 与 `/runtime/puzzle-clear`。API 命名空间为 `/api/creation/puzzle-clear/*` 与 `/api/runtime/puzzle-clear/*`。验证命令见 `docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md` 与 `docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
|
||||
|
||||
## 抓大鹅 Match3D
|
||||
|
||||
对外名称：`抓大鹅`。工程域：`match3d`。
|
||||
|
||||
Reference in New Issue
Block a user