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

Implement scene-based chapter quest progression
Some checks failed
CI / verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
高物
2026-04-08 11:58:47 +08:00
parent 9d2fc9e4b8
commit bd9fdcbe31
170 changed files with 18259 additions and 1049 deletions
Download Patch File Download Diff File Expand all files Collapse all files

645
docs/technical/ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md Normal file
View File

@@ -0,0 +1,645 @@
# 阿里云 NPC 角色形象与动作动画编辑器实验方案（2026-04-07）
## 1. 文档目的
本文不是再写一份泛化的“AI 角色动画大方案”，而是专门回答当前编辑器里要怎么实验这条链路：
- 接入阿里云百炼的文生图、图生图、图生视频、参考视频动作模型
- 以 **NPC 角色形象 + 动作动画资产化** 为目标
- 最终产物仍然要落回当前项目的 `CharacterAssetPanel -> publish -> CharacterAnimator`
本文把方案拆成 4 条实验线：
1. 先文生角色形象图，再图生动作序列帧图并解析
2. 先文生角色形象图，再图生视频
3. 先文生角色形象图，再走“参考视频驱动”的动作模板链
4. 先文生角色形象图，再走“参考生视频 / 剧情演出”链
查阅与核对时间：`2026-04-07`
---
## 1.1 当前实现状态（2026-04-07）
当前仓库已经把下面这些能力接进 `CharacterAssetPanel`：
- 阶段 A：`wan2.7-image-pro / wan2.7-image` 主形象候选生成
- 阶段 B：4 条动作方案都已接入真实模型
- 阶段 C：方案四单独拆成“演出片段”预览区
- 方案三增加了“内置模板库”入口，可直接把项目现有角色序列帧合成为参考视频
- 最近一次主形象任务 / 动作任务状态会回显到编辑器
- 已补动作模板列表接口与视频导入接口
当前实现的本地接口为：
- `POST /api/character-visual/generate`
- `GET /api/character-visual/jobs/:id`
- `POST /api/character-visual/publish`
- `POST /api/animation/generate`
- `GET /api/animation/jobs/:id`
- `GET /api/animation/templates`
- `POST /api/animation/import-video`
- `POST /api/animation/publish`
当前视频后处理采用：
- 模型端生成真实视频
- 浏览器端抽帧、缩放、简单绿幕抠像
- 发布阶段再写入 `public/generated-animations`
也就是说，这份文档里原先一些“推荐下一步”已经落地，但还有一部分“更重的任务化路由”尚未继续拆开。
---
## 2. 当前仓库里的可复用基础
这次实验不应该另起炉灶，因为仓库里已经有 3 个很关键的基础。
### 2.1 编辑器入口已经存在
- 路由 `/character-asset-studio` 已经接到 `PresetEditor`，说明“角色资产工坊”入口是现成的。
- 当前核心页面是 `src/components/preset-editor/CharacterAssetPanel.tsx`。
### 2.2 主形象 / 动作两段式 UI 已经存在
当前 `CharacterAssetPanel` 已经分成：
- 阶段 A：主形象
- 阶段 B：基础动作
- 阶段 C：演出片段
旧版本里生成逻辑确实是本地 mock：
- 主形象候选来自 `buildVisualCandidatesFromSource`
- 动作草稿来自 `buildAnimationClipFromMaster`
现在这层已经被真实模型链路替换，但仍然保留了这些本地能力作为后处理工具：
- 参考视频模板合成
- 视频抽帧
- 简单绿幕抠像
- 生成发布用帧集
### 2.3 本地 API 插件里已经有 DashScope 接入样板
`scripts/dev-server/localApiPlugins.ts` 里已经接了自定义世界场景图：
- 默认 DashScope base URL 已经存在
- 已经有异步任务创建、轮询、下载、落盘、写 manifest 的完整样板
这意味着这次实验最合理的做法是：
- 继续沿用 `/api/*` 本地代理模式
- 新增角色图 / 角色动作的 job 路由
- 复用现有的任务轮询和文件落盘思路
---
## 3. 阿里云当前可直接利用的模型能力
基于 2026-04-07 查阅的阿里云官方文档，当前和本实验最相关的是下面几类能力。
| 能力 | 推荐模型 | 适合用途 | 备注 |
| --- | --- | --- | --- |
| 文生图 / 图生图 / 图像编辑 | `wan2.7-image-pro`、`wan2.7-image` | 生成 NPC 主形象图、做风格统一、生成组图候选 | 官方文档明确支持多图参考与组图输出 |
| 图生视频 | `wan2.7-i2v` | 单角色主形象转动作视频 | 支持首帧、首尾帧、续写片段 |
| 参考生视频 | `wan2.7-r2v`、`wan2.6-r2v-flash` | 多参考图/参考视频驱动剧情演出 | 更适合演出，不是最优基础动作线 |
| 图生动作 | `wan2.2-animate-move` | 主形象 + 参考动作视频 -> 标准动作视频 | 动作控制更强，适合模板动作库 |
| 视频换人 | `wan2.2-animate-mix` | 模板视频里的角色替换成 NPC 形象 | 适合动作模板“复刻” |
需要特别说明：
- 方案一会用到 `wan2.7-image-pro` 的组图 / 顺序组图能力，但 **官方并没有把它定义为“动作逐帧模型”**。
- 所以方案一是“利用图像模型能力去逼近动作帧生产”的实验线，不是官方标准动作生产线。
- 方案二、三、四更贴近阿里云官方为视频生成准备的主线能力。
---
## 4. 方案一：文生角色形象图 -> 图生动作序列帧图 -> 解析成动画
## 4.1 目标
直接得到 `png` 帧集，尽量少碰视频编解码。
## 4.2 模型链路
1. 用 `wan2.7-image-pro` 生成 NPC 主形象图
2. 再把主形象图作为参考图输入 `wan2.7-image-pro`
3. 对每个动作槽位生成一组候选图片
4. 打开组图输出，必要时启用 `enable_sequential`
5. 本地按动作顺序解析这些图，写回帧序列
## 4.3 为什么它成立
阿里云图像生成与编辑 API 当前明确支持：
- 文生图
- 图生图
- 多图参考
- 一次输出多张图
- 顺序组图输出 `enable_sequential`
因此可以在编辑器里做这样的实验：
- 输入：主形象图 + 动作描述 + 固定 seed
- 输出：同一动作的一组关键帧候选
- 后处理：按姿态差异、角色一致性、武器完整度排序，补成帧集
## 4.4 编辑器里的具体玩法
建议在当前“阶段 B：基础动作”里加一个策略选项：
- `帧序列实验（图像组图）`
每次动作生成时：
1. 选择动作槽位，如 `idle / run / attack / hurt`
2. 选择目标帧数，如 `4 / 6 / 8`
3. 传入主形象图
4. 拼出动作提示词，例如“同一角色，侧身朝右，单人，全身，武器完整，连续 6 帧，跑步动作，从预备到迈步再到回收”
5. 请求组图结果
6. 本地做帧序评分
7. 生成 `frames/*.png + manifest.json`
## 4.5 优点
- 直接产出图片，天然适合当前项目的帧资产结构
- 不需要先生成视频再解帧
- 某些短动作可以直接人工挑帧，编辑器可控性高
- 对 `idle`、`acquire`、`hurt` 这种短动作实验门槛较低
## 4.6 风险
- 最大风险是帧间一致性，特别容易出现衣摆、武器、手部、头发抖动
- 组图的“顺序性”不等于真正的视频时序连续性
- `run`、`jump`、`dash` 这类长动作很可能不稳定
- 如果没有额外姿态评分和人工筛选，最后帧序会很跳
## 4.7 结论
这是 **低基础设施成本、高人工筛选成本** 的方案。
适合：
- 编辑器里先做原型实验
- 验证 NPC 主形象一致性能不能维持到多帧
- 生成短动作关键帧
不适合直接作为第一版唯一主线。
---
## 5. 方案二：文生角色形象图 -> 图生视频 -> 解帧资产化
## 5.1 目标
先让视频模型负责动作连续性，再由本地后处理把视频转成项目动画资产。
## 5.2 模型链路
1. 用 `wan2.7-image-pro` 生成 NPC 主形象图
2. 用 `wan2.7-i2v` 基于主形象图生成动作视频
3. 下载视频结果
4. 本地抽帧
5. 做裁切、稳帧、像素化、去闪烁
6. 输出序列帧、Sprite Sheet、manifest
## 5.3 方案二里的两种子模式
### A. 首帧生视频
适合：
- `attack`
- `hurt`
- `die`
- `cast`
特点：
- 主形象图作为 `first_frame`
- 文本控制动作
- 最快接入，链路最短
### B. 首尾帧生视频
适合：
- `idle`
- `run`
- 循环站姿
特点：
- `first_frame` 是起始站姿
- `last_frame` 是回正后的收尾姿态
- 更利于做循环动作和回到可衔接状态
## 5.4 编辑器里的具体玩法
建议在“阶段 B：基础动作”里加：
- `图生视频（首帧）`
- `图生视频（首尾帧）`
参数建议：
- 时长：`2s / 3s / 4s`
- 目标 FPS：先统一导入到本地后再重采样
- 循环动作：是否要求首尾近似
- 提示词模板：按动作槽位固化
## 5.5 优点
- 动作连续性通常明显强于方案一
- `wan2.7-i2v` 是官方主线能力，兼容性和迭代空间更好
- 很适合作为当前编辑器的第一条“真实动作生成”主线
- 本地后处理完成后，仍然能回到当前项目的帧资源体系
## 5.6 风险
- 需要稳定的视频后处理链
- 解帧后仍要处理轮廓闪烁、脚底漂移、武器变形
- 主形象复杂时，单图生视频可能会有角色漂移
- 相比方案一，I/O 和处理耗时更高
## 5.7 结论
这是 **最适合作为编辑器第一版正式实验主线** 的方案。
原因：
- 模型能力更贴近官方主线
- 动作连续性通常更稳定
- 生成结果仍可资产化
---
## 6. 方案三：文生角色形象图 -> 参考视频驱动动作模板链
## 6.1 目标
不是只靠文本“想象动作”，而是给动作一个明确模板视频，让模型做可控迁移。
## 6.2 模型链路
推荐两条可选子线：
### A. `wan2.2-animate-move`
输入：
- NPC 主形象图
- 参考动作视频
输出：
- NPC 执行该动作的视频
### B. `wan2.2-animate-mix`
输入：
- NPC 主形象图
- 模板视频
输出：
- 保留模板视频场景/动作，但把角色替换成 NPC
## 6.3 它和方案二的本质区别
方案二是：
- 主形象图 + 文本描述 -> 视频
方案三是：
- 主形象图 + 模板动作视频 -> 视频
因此方案三最大的价值不是“更自由”，而是“更可控”。
## 6.4 编辑器里的具体玩法
在“阶段 B：基础动作”里新增：
- `动作模板库`
每个动作槽位先配一份官方/自制模板：
- `idle_loop`
- `run_side`
- `attack_slash`
- `hurt_back`
- `die_fall`
工作流：
1. 先锁定 NPC 主形象
2. 选择动作槽位
3. 选择一个模板视频
4. 调用 `animate-move` 或 `animate-mix`
5. 下载视频
6. 解帧、稳帧、裁切
7. 发布为该动作槽位正式资产
## 6.5 优点
- 可控性明显高于纯文本图生视频
- 非常适合做“基础动作槽位不能为空”的项目要求
- 一旦模板库建立起来，多角色批量复用效率很高
- 对 `run`、`attack`、`hurt` 这种标准动作尤其友好
## 6.6 风险
- 要先建设动作模板库
- `wan2.2-animate-move` 官方输入更偏“单人清晰主体”，对严格侧视游戏素材要额外测试
- 模板视频如果镜头、背景、构图不统一，后处理成本会增加
- 模板库前期准备成本高于方案二
## 6.7 结论
这是 **最适合做战斗基础动作标准化生产** 的方案。
如果只看“当前项目需要补齐 `idle / run / attack / hurt / die` 这些基础槽位”，方案三的长期价值甚至高于方案二。
建议排序：
- 第一阶段先做方案二跑通链路
- 第二阶段尽快把方案三补成稳定模板库主线
---
## 7. 方案四：文生角色形象图 -> 参考生视频 / 剧情演出链
## 7.1 目标
这条线不是优先服务“战斗基础动作”，而是服务：
- 剧情演出
- 招募演出
- NPC 说话/表态
- 立绘转小段表演视频
## 7.2 模型链路
推荐：
- `wan2.7-r2v`
- 成本敏感或无声短片可考虑 `wan2.6-r2v-flash`
参考生视频支持把图片、视频作为参考条件输入，再结合文本生成视频。
## 7.3 它和方案三的区别
方案三更像：
- 我已经知道动作模板，就要把它迁过去
方案四更像：
- 我给你角色参考和演出参考，请你生成一段新的镜头表达
所以它更适合：
- NPC 出场特写
- 对话演出
- 剧情镜头
- 情绪表演
不适合优先用于：
- 项目所有基础战斗动作槽位
## 7.4 编辑器里的具体玩法
当前已单独拆成：
- `演出片段`
字段建议：
- 角色主形象
- 参考图最多若干张
- 参考视频片段
- 台词或情绪提示
- 是否保留音频
输出：
- `preview.mp4`
- 关键帧截图
- 可选封面图
## 7.5 优点
- 角色一致性上限更高
- 更适合做剧情演出而不是纯动作片段
- 后续和 `CharacterChatModal`、NPC 招募、事件特写更容易联动
## 7.6 风险
- 对当前战斗帧资产体系帮助没有前三条直接
- 更容易产出“好看的视频”，但不一定容易切成稳定序列帧
- 这条线如果过早投入，会稀释基础动作资产生产的主线
## 7.7 结论
这是 **剧情演出增强线**，不建议抢在方案二、三之前做。
---
## 8. 四种方案横向对比
| 方案 | 动作连续性 | 可控性 | 资产化难度 | 适合基础动作 | 适合剧情演出 | 推荐阶段 |
| --- | --- | --- | --- | --- | --- | --- |
| 方案一：组图帧序列 | 低到中 | 中 | 低到中 | 中 | 低 | 研究线 |
| 方案二：图生视频 | 中到高 | 中 | 中到高 | 高 | 中 | 第一阶段主线 |
| 方案三：模板视频驱动 | 高 | 高 | 中到高 | 很高 | 中 | 第一阶段后半 / 第二阶段主线 |
| 方案四：参考生视频 | 中到高 | 中到高 | 高 | 中 | 很高 | 第三阶段增强 |
一句话总结：
- 要最快落地：先做 **方案二**
- 要把基础动作做稳：尽快补 **方案三**
- 要低成本试帧：可以并行试 **方案一**
- 要做剧情镜头：后续再做 **方案四**
---
## 9. 面向当前编辑器的落地状态与下一步
## 9.1 第一轮
这一轮已经完成：
- 阶段 A：`wan2.7-image-pro` 主形象生成
- 阶段 B：`wan2.7-i2v` 图生视频
原因：
- 最少改 UI
- 最快复用当前 `CharacterAssetPanel`
- 最容易复用 `localApiPlugins.ts` 里现有 DashScope 异步任务模式
## 9.2 第二轮
这一轮已经完成：
- `图生视频`
- `模板视频驱动`
- `帧序列实验`
并且已经补上：
- 方案三的内置模板库入口
- 方案四的独立“演出片段”区
## 9.3 第三轮
下一步仍然值得继续做的是：
- 把当前同步 `generate` 继续拆成显式 `jobs`
- 把视频导入后处理继续拆成独立 `import-video`
- 给方案三补更多正式模板素材与模板清单管理
- 给方案四补关键帧归档、封面和片段列表
---
## 10. 推荐的编辑器任务路由
当前已落地接口：
- `POST /api/character-visual/generate`
- `GET /api/character-visual/jobs/:id`
- `POST /api/character-visual/publish`
- `POST /api/animation/generate`
- `GET /api/animation/jobs/:id`
- `GET /api/animation/templates`
- `POST /api/animation/import-video`
- `POST /api/animation/publish`
当前职责：
### `POST /api/character-visual/generate`
负责：
- 调 `wan2.7-image-pro`
- 生成主形象候选
- 下载并落盘
- 返回草稿图路径
### `GET /api/character-visual/jobs/:id`
负责：
- 返回最近一次主形象任务状态
- 返回模型、提示词、结果草稿等任务记录
### `POST /api/animation/generate`
负责：
- 按策略调不同模型
- `i2v`
- `animate-move`
- `animate-mix`
- `r2v`
- 返回顺序组图或视频草稿
### `GET /api/animation/jobs/:id`
负责：
- 返回最近一次动作任务状态
- 返回策略、模型、输出草稿路径和错误信息
### `GET /api/animation/templates`
负责：
- 返回方案三内置模板库清单
- 供编辑器选择 `idle_loop / run_side / attack_slash / hurt_back / die_fall`
### `POST /api/animation/import-video`
负责：
- 把浏览器侧生成或上传的视频导入本地草稿目录
- 返回可复用的本地视频路径
### `POST /api/animation/publish`
负责：
- 把草稿帧写入 `public/generated-animations`
- 生成动作 manifest
- 更新 `characterOverrides.json`
### 仍建议后续继续加强的部分
- 把当前“同步 generate + 立即返回结果”继续拆成更完整的异步 job 生命周期
- 给 `import-video` 增加更重的服务端后处理，而不只是导入草稿
- 给模板库补正式素材管理与模板清单编辑
---
## 11. 第一批建议验证的动作
不要一上来就跑全量 12 个基础动作，先验证 4 个最关键动作：
1. `idle`
2. `run`
3. `attack`
4. `hurt`
原因：
- 这 4 个已经能覆盖循环动作、位移动作、攻击动作、受击动作
- 最容易测出“主形象一致性 + 动作连续性 + 贴地稳定性”
---
## 12. 具体推荐结论
如果只给当前编辑器实验一个最务实的建议：
1. **主形象统一先接 `wan2.7-image-pro`**
2. **动作第一条真链路先接方案二：`wan2.7-i2v`**
3. **基础动作标准化的主线尽快切到方案三：`wan2.2-animate-move / animate-mix`**
4. **方案一保留为低成本帧序实验线，方案四保留为剧情演出增强线**
换句话说：
- 方案二负责“尽快跑通”
- 方案三负责“真正稳定生产”
- 方案一负责“低成本试错”
- 方案四负责“后续演出升级”
---
## 13. 资料来源
阿里云官方文档：
- 图像生成与编辑 API 参考：
[https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference](https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference)
- 图生视频 API 参考：
[https://help.aliyun.com/zh/model-studio/image-to-video-api-reference/](https://help.aliyun.com/zh/model-studio/image-to-video-api-reference/)
- 参考生视频 API 参考：
[https://help.aliyun.com/zh/model-studio/reference-to-video-api-reference/](https://help.aliyun.com/zh/model-studio/reference-to-video-api-reference/)
- 视频生成总览：
[https://help.aliyun.com/zh/model-studio/use-video-generation](https://help.aliyun.com/zh/model-studio/use-video-generation)
- 图生动作 API 参考：
[https://help.aliyun.com/zh/model-studio/wan-video-to-video-api-reference](https://help.aliyun.com/zh/model-studio/wan-video-to-video-api-reference)
仓库内相关代码与文档：
- `src/components/preset-editor/CharacterAssetPanel.tsx`
- `src/components/preset-editor/characterAssetStudioModel.ts`
- `src/components/preset-editor/characterAssetStudioPersistence.ts`
- `src/routing/appRoutes.tsx`
- `src/services/ai.ts`
- `scripts/dev-server/localApiPlugins.ts`
- `docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md`

850
docs/technical/QWEN_IMAGE_2_PIXELMOTION_REPRODUCTION_WORKFLOW_2026-04-07.md Normal file
View File

@@ -0,0 +1,850 @@
# 基于 Qwen-Image-2.0 复刻 PixelMotion 的全流程操作手册（2026-04-07）
## 1. 文档目的
基于 [PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md](./PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md) 的拆解结果，给出一套用 `Qwen-Image-2.0` 复现 PixelMotion 核心能力的实际操作手册。
本文重点不是泛泛讲“可以做”，而是把下面这些环节写成可以直接照着执行的流程：
- 如何先把资产格式定死成 `4x4 / 16 帧 / Sprite Sheet PNG`
- 如何先锁角色，再做动作
- 如何给 `Qwen-Image-2.0` 写更像 PixelMotion 的强约束提示词
- 如何修坏帧、调帧序、调 FPS，并导出 PNG / GIF / Set
---
## 2. 一句话结论
如果要用 `Qwen-Image-2.0` 复刻 PixelMotion，正确思路不是“让模型自由发挥做动画”，而是：
1. 先把输出契约定死成 `4x4 + 16 帧 + 同方向 + 同中心点`
2. 先做一张稳定的角色标准图，把角色身份锁住
3. 再把动作写成**模板化的 16 帧节奏描述**
4. 用 `Qwen-Image-2.0` 生成整张 Sprite Sheet 或半成品
5. 用同模型继续做修帧和一致性修补
6. 把不好的一小部分问题交给编辑器兜底，而不是要求模型一次全对
这才是最接近 PixelMotion 真实产品逻辑的复现路径。
---
## 3. 复刻目标边界
这份方案默认只用 `Qwen-Image-2.0` 这一条图像模型主线，不依赖视频模型。
也就是说，我们复刻的是 PixelMotion 最核心的能力：
- 上传或提供角色参考
- 选择动作
- 生成 `16` 帧 Sprite Sheet
- 编辑坏帧
- 导出 PNG / GIF / 角色动作集
而不是先走：
- 图生视频
- 视频抽帧
- 再转 Sprite Sheet
因为 PixelMotion 的关键也不是“视频生成”，而是“高约束的精灵表资产生产流水线”。
---
## 4. 先定死的资产契约
在写任何提示词之前，先把下面几件事固定下来，不要让用户自由选。
### 4.1 单个动作的标准输出
- 单动作固定输出一张 `Sprite Sheet PNG`
- 固定 `4` 列 `4` 行
- 固定 `16` 帧
- 固定角色始终朝右
- 固定全身入镜
- 固定地面线高度基本一致
- 固定角色在格子中的尺度接近一致
### 4.2 建议分辨率
- 快速试错：`1024*1024`
- 武器细节较多或动作较复杂：`1536*1536`
对应单格尺寸大致为：
- `1024*1024` -> 每格约 `256*256`
- `1536*1536` -> 每格约 `384*384`
### 4.3 背景策略
不要一开始就要求复杂场景背景。
建议统一：
- 纯白背景
- 或纯绿背景
- 或极浅灰纯色背景
原因很简单：
- 更容易做后续去背景
- 更容易观察轮廓漂移
- 更容易判断脚底是否稳定
### 4.4 必存元数据
每个动作至少保存：
- `action`
- `rows=4`
- `cols=4`
- `frameCount=16`
- `fps`
- `activeFrames`
- `frameOrder`
- `seed`
- `masterPrompt`
- `negativePrompt`
---
## 5. Qwen-Image-2.0 能力与参数建议
根据阿里云官方文档，截至 `2026-04-07`，`Qwen-Image-2.0` 属于**图像生成与编辑融合模型**，适合我们这条链路，因为它既能做：
- 文生图
- 图生图 / 图像编辑
- 多图融合
也支持我们最需要的几个参数：
- `seed`
- `size`
- `negative_prompt`
- `prompt_extend`
- 多图输入编辑
### 5.1 推荐参数
| 参数 | 推荐值 | 用途 |
| --- | --- | --- |
| `model` | `qwen-image-2.0` | 主线模型 |
| `size` | `1024*1024` 或 `1536*1536` | 精灵表正方形输出 |
| `watermark` | `false` | 不要水印 |
| `prompt_extend` | 试错期 `true`，定稿期 `false` | 先帮你补描述，再固定可复现性 |
| `seed` | 每个动作固定一个整数 | 保持相对稳定 |
| `negative_prompt` | 始终填写 | 压住镜头漂移、变脸、缺手缺脚等问题 |
### 5.2 推荐的参考输入包
如果走编辑模式，推荐最多准备 3 张输入图：
1. `master.png`
角色锁定图，只负责身份一致性
2. `pose_board.png`
动作参考板，负责姿势节奏
3. `draft_sheet.png`
当前草稿图，负责网格与已有结果延续
这三张图的职责不要混。
### 5.3 成本估算
按阿里云中国内地官方价格，`qwen-image-2.0` 文生图和图像编辑都是 `0.2 元/张`。
粗略估算一条动作的成本：
- 初版候选 `4` 张
- 修帧 `2~4` 张
- 最终补救 `1~2` 张
合计通常在 `7~10` 张，约 `1.4 ~ 2 元 / 动作`。
如果先做 `idle / run / attack / hurt / die` 五个动作，首轮实验成本通常在 `7 ~ 10 元` 量级，可以接受。
---
## 6. 整体流程总览
推荐严格按下面顺序做，不要上来就直接要求模型“生成完美 16 帧攻击动画”。
### 6.1 主流程
1. 先产出角色标准图 `master.png`
2. 给动作写模板，不直接写一句“跑步”就丢模型
3. 先出整张 `4x4` 精灵表草稿
4. 挑一张最接近的版本
5. 对坏帧做局部修复
6. 进入编辑器调 `activeFrames / frameOrder / fps`
7. 导出 `sheet.png / gif / set`
### 6.2 两种执行模式
#### 模式 A：最快跑通
- 角色标准图
- 直接整张 `4x4` 生成
- 编辑器隐藏坏帧
适合：
- 首次试验
- 做 MVP
- 快速验证某个动作模板是否成立
#### 模式 B：更接近生产
- 角色标准图
- 动作模板卡
- 整张 `4x4` 生成多候选
- 单帧修复
- 收尾帧修复
- 编辑器保存布局
适合：
- 真正想做出可复用动作库
- 要求角色一致性更高
- 武器 / 发型 /配件不允许乱飞
后文默认都按模式 B 来写。
---
## 7. 第一步：锁定角色标准图
这一阶段的目标不是“画一张最好看的海报”，而是产出一张适合后续动作生成的**标准角色图**。
### 7.1 标准图要求
- 单人
- 全身
- 朝右
- 脚底完整可见
- 武器完整
- 背景纯净
- 轮廓清楚
- 不能是正面立绘
- 不能是夸张透视
### 7.2 文生标准图提示词模板
```text
单人，全身，2D 横版游戏角色标准设定图，角色始终朝右侧，侧视角为主，站立待机姿态，脚底完整可见，武器完整，身体比例稳定，轮廓清楚，适合后续制作 sprite sheet 动画。
角色设定：
[角色性别/年龄感]
[发型]
[服装]
[武器]
[配色]
[身份气质]
画面要求：
纯色浅背景，画面中心构图，角色占画面高度 75% 左右，不要裁切头顶和脚底，不要多角色，不要复杂环境，不要镜头透视，不要特写。
风格要求：
高可读性游戏角色设定图，偏像素动画前置设计稿，形体清晰，服装层次明确，武器握持合理，便于后续连续动作生成。
```
### 7.3 图生标准图提示词模板
如果你已经有角色参考图，推荐改成下面这种写法：
```text
使用图1作为唯一角色身份参考，保留该角色的发型、脸型、服装主结构、武器类型和整体配色，将其规范成适合 2D 横版游戏 sprite 动画制作的标准角色图。
要求：
单人，全身，始终朝右，站立待机，脚底完整可见，武器完整，轮廓清晰，背景改为纯浅色，移除杂乱环境和多余装饰，角色保持在画面中央，方便后续生成动作精灵表。
不要把角色改成正面，不要把角色改成三分之二视角，不要改发型，不要改武器手，不要裁切脚底。
```
### 7.4 角色标准图负向提示词
```text
正面视角，左朝向，镜头透视，半身像，脚被裁切，头顶被裁切，多角色，复杂背景，武器消失，武器换手，额外手臂，额外腿，服装变化，脸部变化，过度写实，模糊，运动模糊，强光斑，文字，水印，UI 元素
```
### 7.5 通过标准
满足下面 5 条再进入下一步：
1. 一眼就能看出角色身份
2. 朝向明确是右侧
3. 全身完整
4. 武器没有错手或消失
5. 这张图可以作为所有动作的唯一主参考
---
## 8. 第二步：把动作需求翻译成模板卡
不要把“跑步”“攻击”“比心”这种裸词直接丢给模型。
应该先把动作翻成结构化模板。
### 8.1 动作模板卡字段
每个动作先写一张卡，字段固定如下：
- `actionName`
- `loop`
- `facing`
- `bodyTravel`
- `weaponRule`
- `frames1to4`
- `frames5to8`
- `frames9to12`
- `frames13to16`
- `endState`
### 8.2 动作模板卡通用写法
```text
动作名：[actionName]
是否循环：[是/否]
角色朝向：始终朝右
身体位移：[原地 / 小幅前移 / 中幅前移]
武器规则：[武器始终在右手 / 双手握持 / 不换手]
1-4 帧：[起势描述]
5-8 帧：[主动作前半]
9-12 帧：[主动作后半]
13-16 帧：[收势或回正]
结尾要求：[与首帧接近 / 停在收招姿态 / 停在受击后姿态]
```
### 8.3 常用动作模板示例
#### `idle`
```text
动作名：idle
是否循环：是
角色朝向：始终朝右
身体位移：原地
武器规则：武器始终在右手，位置稳定
1-4 帧：稳定站姿，轻微呼吸起伏
5-8 帧：胸腔与肩膀轻微抬起，衣摆轻微变化
9-12 帧：呼气回落，重心恢复
13-16 帧：逐渐回到与首帧接近的站姿
结尾要求：第 16 帧自然衔接第 1 帧
```
#### `run`
```text
动作名：run
是否循环：是
角色朝向：始终朝右
身体位移：小幅前移但角色中心基本固定
武器规则：武器始终在右手，不换手
1-4 帧：右腿前摆，左腿后蹬，身体前倾
5-8 帧：双腿交替经过身体下方，手臂反向摆动
9-12 帧：左腿前摆，右腿后蹬，身体继续前倾
13-16 帧：回到与 1-4 帧对应的另一半跑步循环
结尾要求：第 16 帧能与第 1 帧无缝循环
```
#### `attack_slash`
```text
动作名：attack_slash
是否循环：否
角色朝向：始终朝右
身体位移：中幅前探
武器规则：右手持剑，始终右手，不换手
1-4 帧：轻微收身蓄力，剑向后收
5-8 帧：重心前压，挥剑开始
9-12 帧：斩击达到最大幅度，动作最有力量
13-16 帧：顺势收刀，回到可接下一动作的姿态
结尾要求：第 16 帧停在收招后稳定姿态
```
#### `hurt`
```text
动作名：hurt
是否循环：否
角色朝向：始终朝右
身体位移：原地或极小后仰
武器规则：武器不要脱手，不要换手
1-4 帧：突然受击，头肩后仰
5-8 帧：身体失衡最明显
9-12 帧：手臂和武器随受击惯性摆动
13-16 帧：逐渐恢复到勉强站稳的姿态
结尾要求：第 16 帧能接回 idle 或下一个动作
```
---
## 9. 第三步：生成整张 4x4 Sprite Sheet
这是最关键的一步。
建议优先走：
- `图像编辑模式`
- 输入 `master.png`
- 如有动作参考，再输入 `pose_board.png`
- 输出一整张 `4x4` 表
### 9.1 通用主提示词骨架
```text
使用图1作为唯一角色身份参考，[如果有图2则：使用图2作为动作节奏参考]。
生成一张 4x4 的 sprite sheet，共 16 帧，展示同一个角色的连续动作。角色始终朝右，全身完整出现在每一个格子里，脚底始终可见，地面线高度基本一致，角色在每一格中的尺度基本一致，镜头固定不变，不要切换景别，不要切换视角，不要左右翻转。
动作要求：
[粘贴动作模板卡的 1-16 帧描述]
输出要求：
每一格都要清晰分开，网格顺序从左到右、从上到下，动作连续，首尾关系明确，轮廓稳定，发型稳定，服装结构稳定，武器始终在正确的手中，背景为纯浅色，适合后续切成 sprite frames。
风格要求：
2D side-view game sprite sheet，readable silhouette，clean outline，consistent character design，animation-ready，game asset oriented。
```
### 9.2 全局负向提示词
```text
多角色，左右朝向混乱，前视图，背视图，镜头切换，景别变化，特写，脚底裁切，头顶裁切，缺手，缺脚，额外肢体，武器消失，武器换手，服装变化，脸部变化，发型变化，动作不连续，重复帧过多，构图混乱，背景复杂，强透视，运动模糊，残影，文字，水印，UI，边框覆盖角色
```
### 9.3 `idle` 整表提示词示例
```text
使用图1作为唯一角色身份参考。
生成一张 4x4 的 sprite sheet，共 16 帧，内容是同一个角色的 idle 循环动画。角色始终朝右，全身完整，脚底始终可见，地面线稳定，角色尺度稳定，镜头固定。
动作节奏：
1-4 帧稳定站姿并轻微吸气，
5-8 帧胸腔和肩膀轻微抬起，衣摆和头发只有极轻微变化，
9-12 帧呼气回落，
13-16 帧逐渐回到与第 1 帧接近的站姿。
要求循环自然，16 帧能无缝接回 1 帧。每格清晰分开，背景纯浅色，轮廓清楚，服装和武器绝对保持一致。
2D side-view game sprite sheet，clean silhouette，consistent character，animation-ready。
```
### 9.4 `run` 整表提示词示例
```text
使用图1作为唯一角色身份参考，使用图2作为跑步动作节奏参考。
生成一张 4x4 的 sprite sheet，共 16 帧，内容是同一个角色的 run 循环动画。角色始终朝右，全身完整，地面线稳定，角色中心基本固定，镜头固定。
动作节奏：
1-4 帧右腿前摆左腿后蹬，身体略前倾，
5-8 帧双腿交叉经过身体下方，手臂反向摆动，
9-12 帧左腿前摆右腿后蹬，
13-16 帧完成另一半跑步循环并回到可接第 1 帧的状态。
要求首尾闭环，脚步节奏清楚，手臂摆动自然，武器始终在右手，不换手，不消失。
2D side-view game sprite sheet，side scrolling runner animation，clean outline，consistent anatomy，game asset oriented。
```
### 9.5 `attack_slash` 整表提示词示例
```text
使用图1作为唯一角色身份参考，使用图2作为攻击动作节奏参考。
生成一张 4x4 的 sprite sheet，共 16 帧，内容是同一个角色的侧身挥砍攻击动作。角色始终朝右，全身完整，镜头固定，地面线稳定。
动作节奏：
1-4 帧轻微收身蓄力，剑向后收，
5-8 帧身体前压，挥剑开始，
9-12 帧斩击达到最大幅度，动作力量最强，
13-16 帧顺势收刀，回到可接下一动作的稳定姿态。
要求动作有明显起势、主挥砍、收势三个阶段；剑始终在右手，不能换手，不能消失；角色脸部、服装、武器、发型在 16 帧中保持同一人。
2D side-view attack sprite sheet，clear slash motion，consistent character design，clean silhouette，animation-ready。
```
### 9.6 建议的生成策略
不要只生成 1 张。
建议每个动作先做 `4` 个候选：
- 提示词相同
- `seed` 不同
例如：
- `idle`: `1101 / 1102 / 1103 / 1104`
- `run`: `2101 / 2102 / 2103 / 2104`
- `attack`: `3101 / 3102 / 3103 / 3104`
这样你能更快选出“最少需要修”的那一张，而不是死磕单张。
---
## 10. 第四步：筛选结果时看什么
不要凭“感觉还行”选图，按下面的检查顺序来。
### 10.1 第一优先级
- 是不是同一个角色
- 朝向是不是始终一致
- 武器有没有消失或换手
- 脚底有没有持续落在同一条地面线附近
### 10.2 第二优先级
- 动作节奏是不是清楚
- 首尾是否可循环
- 斩击或受击是否有明确峰值
### 10.3 第三优先级
- 衣摆 / 头发是否轻微稳定
- 背景是否干净
- 单格边界是否清楚
### 10.4 取舍原则
- 如果坏帧在 `1~3` 帧，优先修
- 如果坏帧在 `4~6` 帧，看是否能靠隐藏和调序救
- 如果超过 `6` 帧都不稳，直接换候选，不要浪费修图次数
---
## 11. 第五步：坏帧修复
PixelMotion 很关键的一点，不是要求 16 帧都完美，而是允许修。
这里也一样。
### 11.1 修帧原则
优先修：
- 武器消失
- 手脚畸形
- 脸突然变了
- 某一帧朝向错了
- 某一帧幅度过大导致不连贯
不要优先修：
- 背景一点点噪点
- 很轻微的衣摆变化
- 肉眼几乎不影响播放的小细节
### 11.2 单帧修复操作
推荐做法：
1. 从 `sheet.png` 裁出坏帧单格
2. 准备上一帧或下一帧的好帧
3. 再带上 `master.png`
4. 让 `Qwen-Image-2.0` 只重绘这一格
推荐输入图职责：
- 图1：`master.png`
- 图2：前一帧或后一帧的好帧
- 图3：当前坏帧
### 11.3 单帧修复提示词模板
```text
使用图1作为角色身份与服装武器的唯一标准，参考图2的动作连续性，修复图3这一个单帧。
要求输出一张单独的动作帧图片，不要网格，不要背景细节。角色始终朝右，全身完整，脚底位置稳定，保持与图2连续，并且与图1是同一个角色。修复图3中的错误，使这一帧适合插回原来的 sprite sheet 中。
重点修复：
[这里明确写问题，例如：右手缺失 / 武器消失 / 身体朝向错误 / 头部变形]
保持不变：
发型、服装结构、主配色、武器类型、朝向。
```
### 11.4 循环收尾修复提示词模板
如果 `idle` 或 `run` 的第 16 帧接不回第 1 帧，单独修第 16 帧。
```text
使用图1作为角色身份标准，参考图2作为第 1 帧起始姿态，修复图3作为第 16 帧结束姿态。
目标是让第 16 帧自然衔接第 1 帧，形成循环动画。角色始终朝右，全身完整，脚底稳定，服装武器不变，动作幅度自然，不要跳变。
```
### 11.5 武器一致性修复提示词模板
```text
使用图1作为角色与武器标准，修复图2这一帧。
要求武器始终在右手，武器长度、形状和握持方式与图1一致，不要消失，不要换手，不要新增第二把武器。只修复武器和持握关系，其余动作姿态尽量保持原样。
```
---
## 12. 第六步：编辑器兜底规则
这一层就是 PixelMotion 真正有价值的地方，必须做。
### 12.1 编辑器必须有的能力
- 按 `4x4` 自动切帧
- 逐帧预览
- 播放预览
- `activeFrames` 开关
- `frameOrder` 拖拽排序
- `fps` 调整
- 保存动作元数据
- 导出 PNG
- 导出 GIF
### 12.2 最小可用的操作规则
#### `activeFrames`
适合处理：
- 某一帧彻底坏掉
- 某一帧重复度太高
- 某一帧突然变脸
#### `frameOrder`
适合处理：
- 动作节奏顺序错位
- 峰值帧放早了或放晚了
- 跑步循环左右腿对应顺序不顺
#### `fps`
建议默认值：
- `idle`: `8`
- `run`: `10 ~ 12`
- `attack`: `10 ~ 12`
- `hurt`: `8 ~ 10`
- `die`: `8`
### 12.3 什么时候该隐藏帧，什么时候该重修
优先隐藏：
- 重复帧
- 接近但无意义的过渡帧
优先重修：
- 武器错了
- 手脚断了
- 脸变了
- 朝向反了
---
## 13. 第七步：导出与资产落盘
推荐导出三种产物：
### 13.1 主资产
- `sheet.png`
### 13.2 预览资产
- `preview.gif`
### 13.3 元数据
```json
{
"action": "run",
"rows": 4,
"cols": 4,
"frameCount": 16,
"fps": 12,
"activeFrames": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
"frameOrder": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
"seed": 2102
}
```
### 13.4 推荐目录结构
```text
pixelmotion-qwen/
refs/
master.png
pose_board_run.png
drafts/
run_candidate_2101.png
run_candidate_2102.png
repairs/
run_frame_07_fix.png
exports/
run/
sheet.png
preview.gif
metadata.json
```
---
## 14. 一套可以直接抄走的负向提示词
下面这组建议作为默认全局负向提示词起步，后面按动作微调。
```text
多角色，左右镜像混乱，前视图，背视图，特写，镜头切换，景别变化，头顶裁切，脚底裁切，脚离地漂浮，缺手，缺脚，额外肢体，武器消失，武器换手，服装变化，脸部变化，发型变化，动作不连续，重复帧过多，模糊，运动模糊，背景复杂，文字，水印，UI 元素，边框覆盖角色
```
---
## 15. 提示词拼装公式
如果你不想每次都重写整段，可以按这个公式拼。
### 15.1 角色锁定模块
```text
使用图1作为唯一角色身份参考，保持发型、脸型、服装主结构、主配色、武器类型一致。
```
### 15.2 构图锁定模块
```text
角色始终朝右，全身完整，脚底始终可见，地面线稳定，镜头固定，角色尺度稳定。
```
### 15.3 网格输出模块
```text
生成一张 4x4 的 sprite sheet，共 16 帧，从左到右、从上到下排列，每格清晰分开。
```
### 15.4 动作模板模块
```text
1-4 帧起势，5-8 帧主动作前半，9-12 帧主动作后半，13-16 帧收势或回正。
```
### 15.5 风格模块
```text
2D side-view game sprite sheet，clean silhouette，animation-ready，game asset oriented。
```
把这 5 段拼起来，再插入具体动作内容，基本就是一条能用的 PixelMotion 风格提示词。
---
## 16. 常见失败与修正方式
### 16.1 角色每帧都像不同人
修正：
- 强化“图1为唯一角色身份参考”
- 先不要复杂背景
- 先不要复杂光影
- 用编辑模式，不要只用纯文生图
### 16.2 跑步像站桩抖动
修正：
- 动作模板里明确写腿部交换节奏
- 写清“身体略前倾，手臂反向摆动”
- 写清“第 16 帧能接回第 1 帧”
### 16.3 攻击看起来没力量
修正：
- 明确写“1-4 蓄力，5-8 发动，9-12 峰值，13-16 收势”
- 明确写“第 9-12 帧是最大动作幅度”
### 16.4 武器容易消失
修正：
- 在主体描述里写一次武器
- 在动作规则里再写一次“始终在右手”
- 在负向提示词里再写“武器消失，武器换手”
### 16.5 网格里角色大小忽大忽小
修正：
- 强化“角色在每一格中的尺度基本一致”
- 背景改成纯色
- 减少镜头语言
---
## 17. 推荐的第一批动作
如果你第一次搭这条链，不要一上来就做十几个动作。
先做下面 4 个：
1. `idle`
2. `run`
3. `attack_slash`
4. `hurt`
原因：
- 足够覆盖循环动作、位移动作、峰值动作、受击动作
- 最容易暴露角色一致性问题
- 最容易验证提示词模板是否成立
---
## 18. 最后给一个最务实的落地建议
如果你要做第一版，建议这样推进：
### 第 1 轮
- 只支持上传 `master.png`
- 只支持 `idle / run / attack / hurt`
- 只支持 `4x4 / 16 帧`
- 只支持隐藏帧、调序、调 FPS
### 第 2 轮
- 加坏帧局部修复
- 加循环首尾修复
- 加透明背景导出
### 第 3 轮
- 加动作库
- 加资产库
- 加社区 Showcase
这就已经非常像 PixelMotion 的核心骨架了。
---
## 19. 参考资料
- 仓库内拆解文档：
[PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md](./PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md)
- 阿里云百炼 Qwen-Image 文生图说明：
[https://help.aliyun.com/zh/model-studio/text-to-image](https://help.aliyun.com/zh/model-studio/text-to-image)
- 阿里云百炼文生图 Prompt 指南：
[https://help.aliyun.com/zh/model-studio/text-to-image-prompt](https://help.aliyun.com/zh/model-studio/text-to-image-prompt)
- 阿里云百炼 Qwen-Image API：
[https://help.aliyun.com/zh/model-studio/qwen-image-api](https://help.aliyun.com/zh/model-studio/qwen-image-api)
- 阿里云百炼 Qwen-Image 编辑说明：
[https://help.aliyun.com/zh/model-studio/qwen-image-edit-guide](https://help.aliyun.com/zh/model-studio/qwen-image-edit-guide)
- 阿里云百炼 Qwen-Image 编辑 API：
[https://help.aliyun.com/zh/model-studio/qwen-image-edit-api](https://help.aliyun.com/zh/model-studio/qwen-image-edit-api)
- 阿里云百炼模型价格：
[https://help.aliyun.com/zh/model-studio/model-pricing](https://help.aliyun.com/zh/model-studio/model-pricing)

1
docs/technical/README.md
View File

@@ -5,6 +5,7 @@
## 文档列表
- [AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md](./AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md)：AI 生成角色形象与角色动画的技术路线。
- [ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md](./ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md)：面向编辑器的阿里云 NPC 形象与动作实验方案，按 4 条生成链路对比。
- [PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md](./PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md)：PixelMotion 产品形态与能力拆解。
- [SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md](./SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md)：服务端部署、代理层与 CORS 方案。