Files
Genarrative/docs/technical/PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md
高物 ddcb5d5c8c
Some checks failed
CI / verify (push) Has been cancelled
Rework story engine flow and reorganize project docs
2026-04-06 23:19:00 +08:00

745 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PixelMotion 技术方案拆解2026-04-04
## 1. 文档目的
拆解 [PixelMotion](https://www.pixelmotion.art/#features) 当前线上版本的产品形态与技术实现思路,重点回答下面几个问题:
- 它到底是不是“AI 一键做像素动画”
- 前端、后端、数据层分别怎么分工
- 它为什么能比普通图生图更稳定地产出可用 Sprite Sheet
- 如果我们在自己的项目里复刻类似能力,应该保留哪些关键设计
本次拆解时间截至:`2026-04-04`
---
## 2. 调研范围与证据等级
本次只基于**线上公开可见信息**进行拆解,未拿到 PixelMotion 的私有后端代码。
### 2.1 已实际核对的公开对象
- 首页 HTML
- `manifest.json`
- `sw.js`
- 前端打包产物 `assets/index-BHdWGq2s.js`
- 前端样式产物 `assets/index-DFENcMpn.css`
- 公开接口:
- `/api/utils?type=stats`
- `/api/utils?type=gifs`
- `/api/showcase?limit=3`
- 线上响应头
### 2.2 本文的标记规则
- `【已确认】`:可直接从公开页面、脚本、接口返回或响应头确认
- `【高概率推断】`:无法看到后端源码,但从前端契约和数据形态可以较高把握推断
- `【推测】`:仅作为方案猜测,不能当成已确认事实
---
## 3. 先说结论
PixelMotion 本质上不是“运行时实时动画引擎”,而是一个**面向社交传播和轻量游戏资产生产的 AI Sprite Sheet 工坊**。
它的核心不是:
- 生成视频后再让前端临时播放
- 在浏览器里做复杂骨骼动画
- 给任意图片自由发挥动作
它真正的关键设计是:
1. 把输出格式强约束成 **4x4、16 帧的 Sprite Sheet PNG**
2. 把动作空间强约束成 **模板动作 + 极强提示词规则**
3. 把生成后的可用性问题交给 **前端二次编辑** 解决:
- 隐藏坏帧
- 调整帧序
- 调整 FPS
- 导出 PNG / GIF / Set
4. 把账号、存储、积分、分享、审核全部接进同一套 BaaS 与 API 网关
一句话概括:
**它不是在做“无限自由的 AI 动画”,而是在做“高约束、可编辑、可分享的像素精灵表生成流水线”。**
---
## 4. 产品形态拆解
## 4.1 用户主流程
【已确认】从前端路由、文案和接口可以还原出主流程:
1. 上传角色图
2. 选择动作
3. 可选开启 AI 角色分析,或直接用图片参考
4. 提交生成
5. 得到一张 16 帧 Sprite Sheet
6. 在编辑页中调帧序、隐藏帧、改 FPS
7. 导出 PNG / GIF / 多角色 Set
8. 保存到个人资产库
9. 可投稿到 Showcase 社区
## 4.2 它卖的不是视频,而是精灵表
【已确认】前端内部把结果当成一个 `4 x 4` 的 sprite sheet 来处理:
- 默认按 `rows=4``cols=4`
- 一共 `16`
- GIF 导出是从单张图里切格子,不是播放视频
- PNG 导出也是从同一张大图里重组
这说明 PixelMotion 的核心资产格式是:
- 生成结果主文件:`Sprite Sheet PNG`
- 预览导出:浏览器侧再转 `GIF`
所以它更像:
- 游戏资产小工坊
- 社交素材制作器
而不是:
- 视频生成器
- 骨骼动画编辑器
---
## 5. 前端技术栈
## 5.1 应用框架
【已确认】
- 前端是 **React SPA**
- 打包方式很像 **Vite**
- 路由是 **React Router**
- 国际化使用 **i18next**
- 样式是 **Tailwind 风格的 utility CSS**
确认依据:
- HTML 使用 `type="module"` 加载单入口 bundle
- bundle 中可见 React 生产构建标识
- 存在 `/`, `/home`, `/edit`, `/terms`, `/privacy`, `/admin/review` 等前端路由
- CSS 中存在大量 `--tw-*` 变量与 utility class
## 5.2 UI 结构
【已确认】它不是纯 landing page而是两层产品
- 落地页:首页、功能说明、社区展示、定价入口
- 工具页:`/edit`
这种拆法的好处是:
- SEO 与转化页保持轻量
- 真正复杂的工具状态集中在编辑页
## 5.3 PWA 与缓存
【已确认】
-`manifest.json`
- 注册了 `serviceWorker`
- `sw.js` 会缓存核心静态资源
- 运行时采用近似 **network first + cache fallback**
这说明它把产品定位成:
- 可被收藏到手机桌面
- 网络不稳时仍能较快打开外壳
---
## 6. 部署与托管
## 6.1 静态站托管
【已确认】
- 响应头里有 `x-vercel-id`
- 也有 Cloudflare 相关头
这说明它大概率是:
- **Vercel 托管应用**
- **Cloudflare 在前层做缓存 / 统计 / 防护**
## 6.2 API 组织方式
【已确认】所有业务接口都挂在同域 `/api/*` 下,例如:
- `/api/analyze-proxy`
- `/api/transform-action`
- `/api/generate-proxy`
- `/api/generate-beta-actions`
- `/api/remove-background`
- `/api/payment/create`
- `/api/payment/creem-create`
- `/api/showcase`
- `/api/user-actions`
- `/api/utils?type=geo`
- `/api/utils?type=stats`
【高概率推断】这类路径风格非常像:
- Vercel Serverless Functions
- 或同类 Node/Edge API 层
其目的非常明确:
- 把模型供应商密钥藏到服务端
- 把支付和鉴权放到服务端
- 把不同模型调用统一封装成同域 API
---
## 7. 数据层与 BaaS 方案
## 7.1 Supabase 接入
【已确认】前端 bundle 中直接包含 Supabase 项目地址,并创建了 Supabase client。
可确认能力包括:
- `auth`
- `storage`
- `database`
- `rpc`
## 7.2 已暴露出的主要表与存储桶
【已确认】
存储桶:
- `pixel-assets`
- `showcase`
数据表:
- `user_assets`
- `user_actions`
- `user_credits`
RPC
- `redeem_credits`
## 7.3 数据职责推断
【高概率推断】这些表/桶的职责大致如下:
### `user_assets`
- 保存用户生成结果
- 主文件是 sprite sheet 的存储路径
- 还会附带 `action_metadata`
- `action_metadata` 里至少保存:
- action 信息
- `activeFrames`
- `frameOrder`
- `fps`
### `user_actions`
- 保存动作收藏 / 用户动作偏好
- 也可能承载“每日刷新动作配额”相关信息
### `user_credits`
- 保存积分余额
### `showcase`
- 保存社区投稿所需的上下文图和结果 GIF
- 可见字段包括:
- `title`
- `content`
- `author`
- `context_images`
- `result_gifs`
- `is_private`
- `private_flags`
---
## 8. 生成链路拆解
## 8.1 不是单模型一步到位
【已确认】从接口命名和编辑页流程看PixelMotion 至少拆成了 4 类能力:
1. 角色理解:`/api/analyze-proxy`
2. 动作文本结构化:`/api/transform-action`
3. 精灵表生成:`/api/generate-proxy`
4. 背景去除:`/api/remove-background`
【高概率推断】这意味着它后端不是一个模型完成全部事情,而是多步骤流水线。
## 8.2 两种输入模式
【已确认】编辑器存在两种模式:
- `AI Character Analysis`:更慢、更精确
- `Direct image reference`:更快
【高概率推断】对应两条链路:
### 模式 A分析后生成
1. 上传图片
2.`analyze-proxy`
3. 把角色描述文本 + 动作模板一起送去生成
优点:
- 更容易抽出稳定的角色语义
- 对脏图、照片、复杂背景更友好
缺点:
- 多一次模型调用
- 时延更高
### 模式 B直接图参考
1. 上传图片
2. 跳过分析
3. 直接把参考图 base64 传给 `generate-proxy`
优点:
- 更快
缺点:
- 对输入质量更敏感
## 8.3 自定义动作不是直接裸喂一句话
【已确认】自定义动作会先走 `/api/transform-action`
【高概率推断】这一步的作用是:
- 把用户自由文本改写成更结构化的动作描述
- 降低“自定义动作太抽象、太文学化”导致的失控
这其实非常关键,因为 PixelMotion 并不是让用户把任何想法直接丢给绘图模型,而是先做一层“动作编排翻译”。
## 8.4 最终输出契约
【已确认】`generate-proxy` 返回的是单个 `imageBase64`,前端将其当成一张 4x4 精灵表处理。
【高概率推断】服务端最终对前端暴露的契约就是:
- 输入prompt + 可选参考图
- 输出:一张最终可切片的 Sprite Sheet
这有两个可能实现:
### 方案 1直接让模型产出 4x4 精灵表
优点:
- 前端最简单
- 一次请求得到最终结果
风险:
- 帧间一致性很难控
- 容易出现局部漂移
### 方案 2后端逐帧生成后再拼表
优点:
- 更可做重试和筛帧
风险:
- 成本更高
- 延迟更大
【我的判断】结合它前端动作模板的写法PixelMotion 当前更像是**强约束 prompt 直接产出整张精灵表**,或者至少对模型暴露的是“直接出 16 帧表”的任务,而不是先生成视频再切帧。
---
## 9. 为什么它比普通图生图更稳
PixelMotion 真正有价值的不是“模型多强”,而是它把自由度砍掉了。
## 9.1 固定 16 帧、固定网格
【已确认】
- 固定 `4 x 4`
- 固定 `16`
好处:
- 模型目标明确
- 导出逻辑简单
- 编辑器也更容易做
## 9.2 动作模板非常强约束
【已确认】游戏动作模板不是只写“run”“attack”这种词而是把动作分成明确阶段
- 起势
- 主动作
- 收势 / 回正
并且强制约束:
- 始终朝同一方向
- 不允许左右镜像翻转
- 身体水平位置固定
- 武器不换手
- 循环动作必须首尾闭合
【高概率推断】这类 prompt 工程是 PixelMotion 稳定性的核心来源之一。
它本质上是在把“动画导演规则”提前写进 prompt而不是把结果完全交给模型即兴发挥。
## 9.3 后编辑能力兜底
【已确认】它允许:
- 拖拽调整帧序
- 双击隐藏坏帧
- 调整 FPS
- 保存布局
这一步非常重要,因为 AI 结果不可能永远 16 帧都完美。
PixelMotion 的思路不是追求“模型一次全对”,而是:
- 先把结果做出来
- 再让用户低成本修整
这比试图用一次模型调用直接得到完美动画更现实。
## 9.4 导出链路放到浏览器
【已确认】
- PNG 导出使用 canvas 重排
- GIF 导出使用 `gif.js`
- 透明背景导出时按需调用 `/api/remove-background`
这意味着:
- 昂贵的 AI 只负责生成主资产
- 廉价的导出和重排交给前端本地完成
这个分工非常合理。
---
## 10. 编辑器能力拆解
## 10.1 编辑页不是“看结果页”,而是轻量资产编辑器
【已确认】编辑页至少具备这些能力:
- 查看单张 sprite sheet
- 播放动画预览
- 调 FPS
- 隐藏帧
- 调整帧顺序
- 保存布局
- 导出 PNG
- 导出 GIF
- 多选导出 Set
## 10.2 布局持久化
【已确认】保存布局时会把状态写回 `user_assets.action_metadata`
这说明它没有把“AI 结果”和“人工修整结果”分离成两套系统,而是把二次编辑直接沉淀到资产元数据里。
这个做法很实用,因为:
- 同一资产可反复继续编辑
- 资产库里保存的是“可用版本”,不是原始毛坯
---
## 11. 社区与增长设计
## 11.1 Showcase
【已确认】首页有公开社区展示,数据来自 `/api/showcase?limit=20`
公开返回里能看到:
- 原始上下文图
- 结果 GIF
- 作者名
- 标题和故事文案
这说明 PixelMotion 不是只强调“工具效率”,还在做:
- UGC 内容传播
- 首页案例社证
- 情绪价值展示
## 11.2 审核后台
【已确认】前端存在 `/admin/review` 页面,审核通过后可发布 Showcase。
说明社区能力不是完全开放式自动发布,而是有人工审核流。
## 11.3 隐私模式
【已确认】Showcase 数据里存在:
- `is_private`
- `private_flags`
【高概率推断】它支持对原始参考图做局部隐私隐藏或模糊,只公开结果,不完全公开全部上下文。
---
## 12. 账号、积分与支付
## 12.1 账号体系
【已确认】
- 使用 Supabase Auth
- 支持邮箱注册登录
- 支持找回密码
- 支持 OAuth 登录入口
## 12.2 积分体系
【已确认】
- 生成主流程消耗 credits
- 刷新动作推荐也可能消耗 credits
- 前端存在 `NO_CREDITS``freeCreditsExhausted` 等状态
- 可通过 `redeem_credits` 兑换码充积分
## 12.3 定价方案
【已确认】前端内置了三档套餐:
| 套餐 | 人民币 | 美元 | 基础积分 | 赠送 |
| --- | --- | --- | --- | --- |
| `basic` | `9.9` | `4.99` | `5` | `0` |
| `pro` | `49.5` | `24.9` | `25` | `3` |
| `studio` | `99` | `46.9` | `50` | `10` |
## 12.4 区域支付分流
【已确认】
- 中国区:`/api/payment/create`
- 国际区:`/api/payment/creem-create`
结合文案还可确认:
- 中国区支持微信 / 支付宝语境
- 国际区有信用卡语境
这说明它做了明显的地域分流支付设计。
---
## 13. 一个更完整的技术架构图
```mermaid
flowchart LR
A["首页 / 编辑页<br/>React SPA"] --> B["同域 API 层<br/>/api/*"]
A --> C["Supabase Auth"]
A --> D["Supabase Storage / DB"]
B --> E["角色分析服务<br/>analyze-proxy"]
B --> F["动作文本结构化<br/>transform-action"]
B --> G["精灵表生成服务<br/>generate-proxy"]
B --> H["去背景服务<br/>remove-background"]
B --> I["支付服务<br/>China / Intl"]
G --> J["返回 4x4 Sprite Sheet PNG"]
J --> A
A --> K["本地导出层<br/>Canvas + gif.js"]
A --> L["Showcase 投稿"]
L --> D
```
---
## 14. 如果我们复刻,最该学什么
如果要学 PixelMotion我认为最值得学的不是 UI而是下面 6 个工程判断。
## 14.1 先把资产格式定死
不要一开始就追求:
- 任意帧数
- 任意布局
- 任意动作长度
先定死一个可生产、可编辑、可导出的资产标准,例如:
- 16 帧
- 4x4
- PNG sprite sheet
## 14.2 模型前面一定要有动作模板层
用户说“跑步”“攻击”“比心”,不应该原样送给模型。
应该先转换成:
- 朝向约束
- 位移约束
- 起承转合
- 武器规则
- 循环规则
## 14.3 允许生成后修帧
不要试图只靠模型一次完成。
至少要有:
- 隐藏帧
- 排序
- FPS
否则大量“差一点能用”的结果会直接报废。
## 14.4 导出放前端,本地完成
像 PNG 重排、GIF 预览、透明导出这类低成本操作,完全没必要都放到后端。
## 14.5 资产库和社区是增长飞轮
PixelMotion 不只是一个生成按钮,它还做了:
- 我的资产库
- 作品展示
- 投稿审核
- 分享内容化
这能把一次性生成工具,变成可留存产品。
## 14.6 支付、积分、地域适配要早做
它不是等产品成熟后才补商业化,而是从一开始就把:
- credits
- 兑换码
- 地域支付
- 国际支付
串进主流程里了。
---
## 15. 对 PixelMotion 后端方案的推断版复原
下面给一个我认为比较接近它真实实现的“后端内部分层草图”。
## 15.1 推荐复原结构
### API Gateway 层
- 鉴权
- 积分扣减
- 配额判断
- 路由到不同 AI 服务
### Prompt Builder 层
- 读取动作模板
- 合成角色描述
- 合成单方向、单中心点、16 帧规则
### Generation Worker 层
- 调视觉模型生成 sprite sheet
- 失败时重试
- 返回 base64 PNG
### Asset Service 层
- 存储到 `pixel-assets`
-`user_assets`
- 保存布局元数据
### Export Layer
- 前端本地切帧
- 前端本地生成 GIF
### Community Layer
- 投稿
- 审核
- 公开展示
---
## 16. 风险与局限
因为没有后端源码,本拆解仍有边界。
## 16.1 不能确认的部分
- 实际调用了哪一家模型供应商
- 是单次整图生成,还是逐帧生成后拼图
- 支付后端的真实实现细节
- 服务端有没有额外的安全审核与图像后处理
## 16.2 但可以较确定的部分
- 前端是 React + Vite 风格 SPA
- 数据层是 Supabase
- 输出主资产是 16 帧 sprite sheet
- 编辑器支持帧编辑和本地导出
- 产品采用积分制
- 社区、审核、展示是正式能力,不是临时 demo
---
## 17. 最终判断
PixelMotion 的成功点,不在于它“偷偷用了某个神秘模型”,而在于它把一个本来极不稳定的问题,拆成了一个高度约束的资产生产流程:
- 输入被约束
- 动作被模板化
- 输出被标准化
- 错误被编辑器兜底
- 结果被资产库与社区承接
如果我们要借鉴它,最应该借鉴的是这套**产品约束 + 资产契约 + 编辑兜底**的整体设计,而不是只学“上传一张图点生成”这层表面交互。
---
## 18. 资料来源
本次拆解实际使用了以下公开来源:
- 官网首页:
[https://www.pixelmotion.art/](https://www.pixelmotion.art/)
- PWA Manifest
[https://www.pixelmotion.art/manifest.json](https://www.pixelmotion.art/manifest.json)
- Service Worker
[https://www.pixelmotion.art/sw.js](https://www.pixelmotion.art/sw.js)
- 公开统计接口:
[https://www.pixelmotion.art/api/utils?type=stats](https://www.pixelmotion.art/api/utils?type=stats)
- 公开 GIF 列表接口:
[https://www.pixelmotion.art/api/utils?type=gifs](https://www.pixelmotion.art/api/utils?type=gifs)
- 公开 Showcase 接口示例:
[https://www.pixelmotion.art/api/showcase?limit=3](https://www.pixelmotion.art/api/showcase?limit=3)
- 首页前端 bundle 与样式产物:
- `https://www.pixelmotion.art/assets/index-BHdWGq2s.js`
- `https://www.pixelmotion.art/assets/index-DFENcMpn.css`