GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into codex/public-work-readmodel-smooth-transition

Browse Source
This commit is contained in:
kdletters
2026-05-26 16:38:38 +08:00
parent aeee782fe0 ed0257ee2d
commit d50e69560b
130 changed files with 2966 additions and 511 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/README.md
View File

@@ -17,6 +17,8 @@
拼图生成页步骤真进度、步骤内假进度和精简展示口径见 [【玩法创作】拼图生成页进度口径-2026-05-23.md](./%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E6%8B%BC%E5%9B%BE%E7%94%9F%E6%88%90%E9%A1%B5%E8%BF%9B%E5%BA%A6%E5%8F%A3%E5%BE%84-2026-05-23.md)。
从文字需求生成高一致性美术素材流程抽象出的发明专利交底稿见 [【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md](./%E3%80%90%E4%B8%93%E5%88%A9%E4%BA%A4%E5%BA%95%E3%80%91%E4%B8%80%E7%A7%8D%E6%9E%81%E4%BD%8E%E6%88%90%E6%9C%AC%E5%BF%AB%E9%80%9F%E7%94%9F%E6%88%90%E9%AB%98%E8%B4%A8%E9%87%8F2D%E5%B0%8F%E6%B8%B8%E6%88%8F%E9%AB%98%E4%B8%80%E8%87%B4%E6%80%A7%E7%BE%8E%E6%9C%AF%E7%B4%A0%E6%9D%90%E7%9A%84%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88-2026-05-25.md)。
生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)。

184
docs/【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md Normal file
View File

@@ -0,0 +1,184 @@
# 一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案
更新时间：`2026-05-25`
> 本文为内部发明专利交底稿，目标是把“文字需求 -> 画面图 -> 透明 spritesheet -> 自动边界检测 -> 元素绑定”这一条高一致性美术素材生成链路抽象为可申请的通用技术方案。
## 摘要
本发明涉及一种极低成本快速生成高质量 2D 小游戏高一致性美术素材的解决方案。该方案接收文字形态的需求描述，调用图片生成模型生成一张用于表达整体视觉关系的游戏画面图；再以所述游戏画面图作为参考，继续调用图片生成模型生成一张透明背景的 spritesheet 图片，所述 spritesheet 图片承载需要随不同设备分辨率自适应调整位置的素材；随后基于自动边界检测算法对所述 spritesheet 图片中的素材进行逐一解析，按照从上到下、从左到右的顺序，将解析出的素材与文字形态需求描述中的画面元素一一对应，并将代码中的元素标识与对应素材绑定。该方案通过单次文字输入驱动画面图生成、基于画面图派生透明 spritesheet、自动边界检测替代人工切图、顺序映射替代手工命名和手工对图，从而在较少人工干预和较低重复生成成本下，快速得到风格统一、可直接绑定代码的高一致性美术素材。
## 技术领域
本发明属于人工智能图像生成、2D 小游戏美术素材生产、图像分割解析和元素绑定技术领域，具体涉及一种根据文字需求描述自动生成游戏画面图、spritesheet 美术素材和元素映射关系的方法及系统。
## 背景技术
现有 2D 小游戏的美术素材生产通常包含以下步骤：先由设计人员撰写文字需求，再由美术人员分别绘制画面图、按钮图、状态图和装饰图，之后由前端或游戏程序员进行切图、命名、排布和代码绑定。该流程存在如下问题：
1. 素材往往分散生成，整体风格不统一。
2. 多分辨率适配时，需要人工调整大量元素位置，维护成本高。
3. 切图和命名依赖人工，容易出现遗漏、错位和绑定错误。
4. 文字需求与最终代码元素之间缺少稳定映射，后续修改代价大。
5. 若每个素材分别生成，会增加生成次数和等待成本。
因此，需要一种能够把文字需求直接转化为成套美术素材，并且能够自动解析、自动映射、自动绑定到代码中的方法。
## 发明内容
### 要解决的技术问题
本发明主要解决以下技术问题：
1. 如何根据文字形态的需求描述快速生成一张完整游戏画面图。
2. 如何基于该画面图进一步生成透明背景的 spritesheet 图片。
3. 如何基于自动边界检测算法逐一解析 spritesheet 中的素材。
4. 如何按照从上到下、从左到右的顺序将素材与文字描述中的画面元素一一对应。
5. 如何将映射结果稳定绑定到代码，减少人工切图和手工配置成本。
### 技术方案
本发明提供一种高一致性美术素材生成方法，包括如下步骤：
```text
文字形态需求描述
-> 游戏画面图生成
-> 透明背景 spritesheet 生成
-> 自动边界检测解析素材
-> 顺序映射文字元素
-> 代码绑定
```
其中，所述文字形态需求描述至少包含画面元素名称、语义说明、布局意图和顺序信息。所述游戏画面图用于表达整体视觉风格和元素关系；所述 spritesheet 图片用于承载需要随不同设备分辨率自适应调整位置的素材；所述自动边界检测算法用于把 spritesheet 中的独立素材一一切分出来；所述顺序映射用于将解析结果与文字描述中的元素一一对应；所述代码绑定用于将元素标识、资源地址、边界框或布局参数写入代码配置或元素表。
### 有益效果
与现有技术相比，本发明至少具有以下效果：
1. 降低人工切图成本。
2. 降低人工命名和代码绑定成本。
3. 提升整体美术素材一致性。
4. 提升多分辨率适配效率。
5. 减少重复生成和重复调整次数。
6. 让文字需求到代码元素的映射更稳定、更可维护。
## 附图说明
图 1 为本发明从文字需求描述到元素绑定的总体流程图。
图 2 为游戏画面图生成与 spritesheet 生成的派生关系示意图。
图 3 为自动边界检测算法解析透明背景 spritesheet 的流程图。
图 4 为素材顺序与文字形态需求描述中的画面元素一一对应的映射关系示意图。
## 具体实施方式
### 一、系统组成
本发明的系统可以包括如下模块：
1. 输入采集模块：用于接收文字形态需求描述。
2. 图像生成模块：用于根据文字形态需求描述生成游戏画面图。
3. 图集生成模块：用于根据游戏画面图生成透明背景 spritesheet 图片。
4. 边界检测模块：用于对 spritesheet 图片执行自动边界检测算法。
5. 顺序映射模块：用于将解析出的素材按照从上到下、从左到右的顺序与文字描述中的画面元素对应。
6. 代码绑定模块：用于将元素标识与对应素材绑定。
### 二、方法步骤
#### S100：接收文字形态需求描述
系统接收用户输入的文字形态需求描述。该需求描述可写成一段自然语言，也可写成按元素顺序排列的结构化文本。需求描述中应至少能够识别出画面元素名称、语义含义和布局顺序。
#### S200：生成游戏画面图
图像生成模块调用图片生成模型，根据所述文字形态需求描述生成一张完整游戏画面图。所述游戏画面图用于表达整体视觉关系、主次层级和风格基调，为后续 spritesheet 生成提供统一参考。
#### S300：生成透明背景 spritesheet 图片
图集生成模块以所述游戏画面图为参考，再次调用图片生成模型，生成一张透明背景的 spritesheet 图片。所述 spritesheet 图片中包含需要随不同设备分辨率自适应调整位置的素材，例如按钮、状态条、提示气泡、装饰元素或其他需要由代码控制位置的元素。
#### S400：自动边界检测解析素材
边界检测模块对所述 spritesheet 图片执行自动边界检测算法，对透明背景中的每个独立素材进行逐一解析，输出素材边界框、素材索引和必要的资源属性。所述自动边界检测算法优选采用 alpha 通道连通域检测、边界矩形检测或二者组合；在一个优选实施方式中，可复用拼图场景中已验证的自动边界检测思路，以提高解析稳定性。
#### S500：按照顺序映射文字元素
顺序映射模块将解析出的素材按照从上到下、从左到右的顺序进行排列，并与文字形态需求描述中的画面元素内容一一对应。若需求描述中已显式给出元素顺序，则优先按该顺序映射；若仅给出自然语言描述，则可先抽取元素列表，再按布局顺序排序。由此形成元素索引与语义名称之间的稳定映射关系。
#### S600：代码绑定
代码绑定模块将所述映射关系写入代码配置、元素表或资源清单中。代码侧只需读取元素标识，即可找到对应素材的资源地址、边界框和布局参数，从而完成美术素材与程序逻辑之间的直接绑定。
#### S700：输出美术素材包
系统最终输出至少包括游戏画面图、透明背景 spritesheet 图片、素材映射表和代码绑定结果。由于 spritesheet 图片与游戏画面图来自同一视觉链路，且素材顺序与文字描述顺序一一对应，因此可得到风格统一、可直接绑定、可适配多分辨率的高一致性美术素材包。
### 三、核心机制
1. 文字驱动：一次文字描述即可驱动画面图和 spritesheet 生成。
2. 单图派生：spritesheet 以游戏画面图为参考生成，减少风格漂移。
3. 自动解析：边界检测算法替代人工切图。
4. 顺序对应：素材顺序与文字元素顺序一致，减少命名和对图错误。
5. 代码绑定：映射结果可直接进入代码配置或资源表。
### 四、实施例
#### 实施例一：界面型 2D 小游戏素材生成
用户输入“科技实验室界面，顶部标题栏，中部主角色，底部三个操作按钮，右侧状态提示”。系统先生成一张完整游戏画面图，再生成一张透明背景 spritesheet 图片。边界检测模块解析出标题栏、主角色、操作按钮和状态提示等素材，顺序映射模块按从上到下、从左到右的顺序将其与文字描述对应，代码绑定模块将这些元素写入代码配置，最终形成可直接用于界面装配的素材包。
#### 实施例二：需要自适应位置的素材生成
用户输入“横版战斗界面，血条、技能按钮、提示气泡、道具栏”。系统将这些需要随设备分辨率自适应调整位置的元素集中生成到同一张 spritesheet 图片中。运行时，代码根据元素绑定结果对血条、按钮和提示元素进行位置调整，而不改变它们对应的语义关系。
#### 实施例三：代码与元素一一绑定
系统为解析出的每个素材分配唯一元素标识，例如 `top_title_bar`、`center_character`、`bottom_actions`、`right_status_hint`。代码侧通过元素标识直接读取对应素材的边界框和资源路径，从而消除人工对图和人工命名的步骤。
## 权利要求书草案
1. 一种极低成本快速生成高质量 2D 小游戏高一致性美术素材的方法，其特征在于，包括：接收文字形态需求描述；根据所述文字形态需求描述调用图片生成模型生成游戏画面图；以所述游戏画面图为参考图再次调用图片生成模型生成透明背景的 spritesheet 图片；对所述 spritesheet 图片执行自动边界检测算法，逐一解析素材边界；按照从上到下、从左到右的顺序将解析出的素材与所述文字形态需求描述中的画面元素一一对应；将代码中的元素标识与对应素材绑定。
2. 根据权利要求 1 所述的方法，其特征在于，所述文字形态需求描述至少包括画面元素名称、语义说明和布局顺序。
3. 根据权利要求 1 所述的方法，其特征在于，所述游戏画面图用于表达整体视觉风格和元素关系，所述 spritesheet 图片用于承载需要随不同设备分辨率自适应调整位置的素材。
4. 根据权利要求 1 所述的方法，其特征在于，所述 spritesheet 图片具有透明背景，且素材之间通过透明区域分隔。
5. 根据权利要求 1 所述的方法，其特征在于，所述自动边界检测算法包括基于 alpha 通道的连通域检测、边界矩形检测或二者组合。
6. 根据权利要求 5 所述的方法，其特征在于，所述自动边界检测算法复用拼图场景中已验证的素材边界解析思路。
7. 根据权利要求 1 所述的方法，其特征在于，所述从上到下、从左到右的顺序用于建立元素索引与语义名称之间的映射表。
8. 根据权利要求 1 所述的方法，其特征在于，所述代码绑定包括为每一素材写入唯一元素标识，并在代码中通过所述元素标识读取对应素材的资源地址、边界框或布局参数。
9. 根据权利要求 1 所述的方法，其特征在于，所述 spritesheet 图片中的素材包括按钮、状态条、提示元素、装饰元素或其他需要自适应布局的画面元素。
10. 根据权利要求 1 所述的方法，其特征在于，所述游戏画面图与所述 spritesheet 图片由同一视觉链路生成，以保持美术素材的一致性。
11. 根据权利要求 1 所述的方法，其特征在于，所述元素绑定结果用于在不同设备分辨率下动态调整素材位置，而不改变元素语义对应关系。
12. 一种极低成本快速生成高质量 2D 小游戏高一致性美术素材的系统，其特征在于，包括输入采集模块、图像生成模块、图集生成模块、边界检测模块、顺序映射模块和代码绑定模块；所述各模块被配置为执行权利要求 1 至 11 任一项所述的方法。
13. 一种电子设备，包括处理器和存储器，所述存储器中存储有计算机程序，其特征在于，所述计算机程序被所述处理器执行时实现权利要求 1 至 11 任一项所述的方法。
14. 一种计算机可读存储介质，其上存储有计算机程序，其特征在于，所述计算机程序被处理器执行时实现权利要求 1 至 11 任一项所述的方法。
## 可重点保护的创新点
1. 文字需求直接驱动一张游戏画面图。
2. 基于该画面图再生成透明背景 spritesheet。
3. 自动边界检测替代人工切图。
4. 按从上到下、从左到右的顺序把素材与文字元素一一对应。
5. 通过元素标识直接绑定代码与素材，减少人工命名和对图成本。
## 正式申请前建议
1. 检索是否已有“文字生成画面图 + spritesheet 自动解析 + 元素绑定”的相近专利，再确定独立权利要求的保护重心。
2. 将“极低成本”“高质量”等效果性表述尽量放在说明书效果部分，权利要求中改写为“减少人工切图”“减少重复生成”“提高一致性”等技术特征。
3. 避免在权利要求中绑定特定供应商或模型名称；模型名称可保留在实施例中。
4. 如需扩大保护范围，可将“2D 小游戏”进一步上位为“交互式图像驱动应用”的美术素材生成方法。
5. 如需增强授权稳定性，可将“文字驱动生成 + 透明 spritesheet + 自动边界检测 + 顺序映射 + 代码绑定”组合为主权利要求的必要技术特征。

2
docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
View File

@@ -160,7 +160,7 @@ npm run check:server-rs-ddd
- LLM：`GENARRATIVE_LLM_*`，创意 Agent 另用 `APIMART_BASE_URL` / `APIMART_API_KEY`。
- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。APIMart 只保留给创意 Agent `gpt-5` Responses 文本 / 多模态链路；DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。
- Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端固定从该 sheet 解析并持久化 20 个物品、每个 5 个形态；通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
- Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
- Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
- Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
- 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 真实透明 alpha PNG 并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物上传 OSS 前不做服务端抠图后处理，避免误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。

11
docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
View File

@@ -72,7 +72,7 @@ RPG 从作品架、广场详情或作品号搜索点击“启动”前，入口
RPG 运行态的战斗终局、继续冒险、继续探索和切场景都属于服务端 runtime 快照真相：`module-runtime-story` 必须在终局战斗 action 后调用 post-battle finalization，持久写入 `story_continue_adventure`、`deferredOptions`、`deferredRuntimeState.storyEngineMemory.currentSceneActState` 和清理后的战斗状态；`idle_travel_next_scene` / `camp_travel_home_scene` 必须由后端写入新的 `currentScenePreset`、`currentSceneActState`、`currentEncounter` 和 `runtimeStats.scenesTraveled`。前端只播放退场、进场和继续按钮表现，不能用默认 `观察/试探/调息` fallback 或本地动画假装推进剧情。旧 bootstrap 快照可能只有 `connectedSceneIds` / `forwardSceneId` 而没有 `connections`，后端生成战后旅行选项时必须兼容这些字段。
RPG / 拼图等运行态存档选择入口统一在个人中心 `次级入口 > 存档` 和设置入口区保留为独立弹窗；“玩过”弹窗可以继续合并展示可继续存档，但不能成为唯一入口。移动端“我的”页的五项常用功能宫格只放泥点充值、邀请好友、兑换码、玩家社区、反馈与建议，避免把存档挤入主宫格破坏参考图布局。前端只展示 `/api/profile/save-archives` 返回的列表并在用户选择后调用对应恢复接口，不能本地拼装或筛选正式存档真相。
RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列表为真相，恢复动作继续走对应恢复接口，但移动端“我的”页已经不再提供独立的 `次级入口 > 存档` 和设置入口存档按钮；“玩过”弹窗可以继续合并展示可继续存档，个人中心只保留设置、扫码、常用功能和条件性次级入口。移动端“我的”页的五项常用功能宫格只放泥点充值、邀请好友、兑换码、玩家社区、反馈与建议，避免把存档挤入主宫格破坏参考图布局。前端只展示 `/api/profile/save-archives` 返回的列表并在用户选择后调用对应恢复接口，不能本地拼装或筛选正式存档真相。
## 拼图
@@ -191,8 +191,8 @@ RPG / 拼图等运行态存档选择入口统一在个人中心 `次级入口 >
3. 首次调用 VectorEngine `gpt-image-2`，无参考图，竖屏 `9:16`，生成完整抓大鹅关卡画面并持久化到 `generatedBackgroundAsset.levelSceneImageSrc/levelSceneImageObjectKey`。提示词必须包含用户主题描述、顶部返回 / 标题倒计时 / 设置按钮、中间与主题匹配且贴横向边缘的容器，以及底部“移出 / 凑齐 / 打乱”三个道具按钮。
4. 关卡整图完成后并发发起三次 `gpt-image-2` 编辑请求，三者都以关卡整图作为参考图：`1K`、`1:1` 的 UI spritesheet 写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`；`1K`、`9:16` 的背景图写入 `imageSrc/imageObjectKey`；`2K`、`1:1` 的物品 spritesheet 写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。
5. UI spritesheet 提示词固定要求按从上到下、从左到右整理纯绿色绿幕背景素材：返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮；后端上传 OSS 前必须把绿幕扣成透明 PNG。背景图提示词固定要求移除全部 UI 组件和容器内含物，完整保留容器和背景，并补全被 UI 覆盖的背景内容。
6. 物品 spritesheet 固定 `10行*10列`、统一纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；素材间距严格均匀分布，每一行包含两种物品，每种物品五个不同形态，物品来自参考图中心容器中的 2D 素材，严禁高相似度物品。新流程每次固定解析并持久化 `20` 种物品，物品信息列表全部展示这 `20` 种；持久化单格映射必须按 `row = itemIndex / 2 + 1`、`col = itemIndex % 2 * 5 + viewIndex + 1` 写入通用系列素材图集，不能再用 `row = itemIndex + 1`。`generatedItemAssets[].imageViews[]` 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退。
7. 前端和运行态统一使用 alpha 连通域矩形检测解析 spritesheet：UI 图按返回、设置、方格、移出、凑齐、打乱顺序映射回原 UI 位置；物品图按检测顺序每 `5` 个区域组成一个物品的五个形态，最多 `20` 个物品。透明背景是解析前提，不能在前端按固定像素坐标写死切片。
6. 物品 spritesheet 固定 `10行*10列`、统一纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；素材间距严格均匀分布，每一行包含两种物品，每种物品五个不同形态，物品来自参考图中心容器中的 2D 素材，严禁高相似度物品。新流程每次解析并持久化 `20` 种物品，物品信息列表全部展示这 `20` 种；后端切 `generatedItemAssets[].imageViews[]` 时优先按透明 alpha 连通域识别真实素材矩形，再按原图从上到下、从左到右排序，每 `5` 个区域组成一个物品的五个形态；只有识别出的区域数量不足时才回退 `10*10` 固定网格。持久化单格映射元数据仍按 `row = itemIndex / 2 + 1`、`col = itemIndex % 2 * 5 + viewIndex + 1` 写入通用系列素材图集，不能再用 `row = itemIndex + 1`。`generatedItemAssets[].imageViews[]` 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退。
7. 前端和运行态统一使用 alpha 连通域矩形检测解析 spritesheet：UI 图先把识别出的透明素材矩形按行聚类，再在每一行内按横向 `x` 坐标排序，最后按返回、设置、方格、移出、凑齐、打乱顺序映射回原 UI 位置；不能只按全局 `y` 坐标排序，否则同一行素材上下略有错位时会把方格和底部道具按钮顺序打乱。物品图按检测顺序每 `5` 个区域组成一个物品的五个形态，最多 `20` 个物品。透明背景是解析前提，不能在前端按固定像素坐标写死切片。
8. 文本生成物品名称时必须同时生成 `itemSize`，只允许 `大`、`中`、`小`。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
9. 当前抓大鹅音频生成关闭：入口无 `生成音效`，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递。
10. 背景、UI spritesheet、物品 spritesheet 和历史容器兼容字段的持久化真相仍在 `generatedItemAssets[].backgroundAsset` 与提升后的 `generatedBackgroundAsset`；Agent session、work summary/detail、结果页和运行态入口都必须把该字段提升为 `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照；HTTP facade 不能只依赖 work detail 回读补齐 UI 资产，外部回读为空时也不得清空草稿内已有的背景 / 图集。平台壳层从作品架、广场、生成完成回调、结果页保存 / 发布 / 试玩回调进入 Match3D profile 时也要先归一化并提升，避免首次试玩、手动试玩、推荐流或公开详情运行态退回默认背景。
@@ -215,12 +215,15 @@ RPG / 拼图等运行态存档选择入口统一在个人中心 `次级入口 >
- 难度只决定本局加载的物品种类数量：轻松 3、标准 9、进阶 15、硬核 20。硬核仍保留 21 次消除和 63 件总物品，运行态按 20 种素材循环复用，不要求生成第 21 种素材。
- 运行态启动前要预加载 `generatedItemAssets[].imageViews[]`、顶层 `generatedBackgroundAsset`、物品挂载 `backgroundAsset` 中的背景、UI spritesheet 和物品 spritesheet；首次生成自动试玩、结果页手动试玩、推荐流和公开详情启动都必须传入提升后的 profile。卡片摘要缺图集字段时，进入运行态前必须补读 work detail。补读后的 profile 也要再次提升 `generatedItemAssets[].backgroundAsset`，确保背景和图集字段传给 `Match3DRuntimeShell`。
- 背景图作为运行态全屏背景，图内已经保留容器；旧 `containerImage*` 只作为历史透明容器兼容字段。若 `containerImage*` 与 `uiSpritesheetImage*` 同源，运行态不得把 UI spritesheet 当中心容器图叠到棋盘上。
- 抓大鹅运行态 HUD 需贴近拼图顶部信息条的视觉口径：左上只保留透明返回按钮；右上不再暴露设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板和同造型，并在牌面左侧挂上 `media/logo.png` 产品 logo；下方备选栏和道具图标只保留内容与交互边界，不再显示灰白半透底板；中央容器图层视觉可隐藏，但棋盘命中边界仍保留。
- generated 私有图换签未完成时，局内物品先隐藏等待，不得短暂显示默认积木；同一批资源在重启 run 时保留已解析签名 URL，只有资源源列表变化或换签失败后才允许进入兜底视觉。
- `itemSize` 只缩放生成 2D 图片本体：`大`、`中`、`小` 均按相对尺寸缩放，其中 `大` 也比原始图片略小，`中` 和 `小` 进一步缩小；不改变后端下发的布局半径、点击半径或三消规则。
- 物品进入底部物品栏时按同类型插入：如果物品栏已有同类物品，新物品插到该类型最后一个物品后面，后续物品整体后移；没有同类时追加到当前末尾。达到三件同类时，在飞入物品栏动画结束后，左侧和右侧同类物品向中间合成，三件一起消失，播放合成音效，不展示星星图标，后面的物品再向前补位。该动效只是前端表现层，后端和本地试玩仍负责权威插入、指定点击类型清除与补位后的槽位快照。
- 抓大鹅运行态右上角常驻设置入口，不直接暴露重新开始按钮；重新开始收口到设置面板内，结算弹层仍保留结果态的再来一局动作。
- 抓大鹅运行态不渲染右上角设置入口，也不在局内直接暴露重新开始按钮；结算弹层仍保留结果态的再来一局动作。
- 高 DPR 移动端 WebGL canvas 必须锁定 CSS 尺寸，避免右下溢出。
发现页可挂载官方抓大鹅静态 demo，用于验证生图、切图和运行态资源闭环。当前 demo profile 固定为 `match3d-demo-20260525`，公开作品号为 `M3-20260525`，静态资源位于 `public/match3d-demo/undersea-candy-market/`；公开卡片、作品号搜索和详情启动都走平台现有公开作品详情，不新建页面。demo 运行态使用前端本地 `createLocalMatch3DRuntimeAdapter`，不调用正式 Match3D runtime 后端、不新增 SpacetimeDB schema，也不写正式作品统计；后续若要把 demo 资源转成正式公开作品，必须改为后端 profile / gallery 投影真相后再接正式 runtime。
## 视觉小说
当前视觉小说只吸收外部 TXT 玩法的创作与运行经验，不迁入外部平台社区、支付、榜单、私有存档或回放。

6
docs/【项目基线】当前产品与工程约束-2026-05-15.md
View File

@@ -93,9 +93,9 @@ server-rs + Axum + SpacetimeDB
7. 主站入口已锁定移动端页面级缩放；单个游戏页面不要再重复实现整页缩放锁定。
8. 图像输入通用 UI 统一走 `src/components/common/CreativeImageInputPanel.tsx`。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
9. 发现页 `分类` 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。
10. 移动端“我的”页按参考图顺序组织为顶部头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口、次级入口带和法律信息；`media/profile/` 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；存档和填邀请码保留在次级入口带，不挤入五宫格。
11. “我的”页泥点、游戏时长、已玩游戏数量三张统计卡只展示各自标签和值，内容不换行，不在统计区底部展示“更新于”时间，字号维持平台普通 UI 档位；移动端昵称、会员卡、每日任务、常用功能和法律信息也应保持 `10px` 到 `14px` 的普通 UI 字号区间，避免展示级字号挤压内容。
12. 移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、每日任务、五项常用功能、次级入口和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
10. 移动端“我的”页顶部品牌行承载扫码和设置入口，正文按参考图顺序组织为头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口、可选次级入口和法律信息；`media/profile/` 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；页面不再提供独立存档按钮入口，填邀请码仅在新用户可填写窗口内展示为次级入口。
11. “我的”页泥点、游戏时长、已玩游戏数量三张统计卡只展示各自标签和值，三个统计 icon 使用小尺寸普通 UI 档位，内容不换行，不在统计区底部展示“更新于”时间；移动端昵称、会员卡、每日任务、常用功能和法律信息也应保持 `10px` 到 `14px` 的普通 UI 字号区间，避免展示级字号挤压内容。
12. 移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、每日任务、五项常用功能、可选次级入口和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
13. RPG 等运行态的战斗飘字、血量变化和即时反馈必须在暗色、噪声高的场景背景上保持可读：使用高亮文字、深色描边、强阴影或小面积半透明底，不只依赖红/绿文字本身表达伤害或治疗。
14. 平台亮色 UI 配色以陶泥儿主视觉为准：暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；新增界面优先复用 `src/index.css` 的 `--platform-*` 主题变量和 `apps/admin-web/src/styles/admin.css` 的同系色值，不再引入粉红、蓝绿等独立主色方案。