# Anim Studio — 游戏动画自动化 · 可视化资源库

一个本地网站：填入大模型 key → 点「开始」批量生成动画资产 → 在网页里以**资源库**形式列出，并能**实时预览**每个角色/特效/动效动起来。

## 启动（几乎零依赖）

```bash
cd anim_studio
pip install Pillow          # 唯一必需的第三方库
python server.py
```

浏览器打开 **http://127.0.0.1:7861**

> 后端用 Python 标准库（http.server）写，不需要 Flask/Django；图像接口用标准库 urllib。所以装个 Pillow 就能跑。

## 网站长什么样

- **顶部「生成面板」**：填 Provider / API Key / Base URL / 模型 / 尺寸，编辑 `animation_manifest.json`，点 **▶ 开始生成**。日志实时显示，完成后资源库自动刷新。
- **三个标签页 = 三个库**：
  - **角色库**：每个角色一张卡片，图片按生成的关键帧**实时播放果冻抖动**（idle/win 可下拉切换），显示尺寸与文件数。
  - **特效库**：每个粒子特效一个 **canvas 实时粒子预览**（金币雨、爆光等），显示模板与参数。
  - **动效库**：每个 UI 动效一个 demo 方块，点「播放」实时演示（弹入、回弹、数字滚动…）。
- **game 选择器**：切换不同游戏的资源库；「刷新」重新读取。
- **📦 导出 Cocos 整合包**：把当前 game 一键打包成可直接拖进 Cocos 的整合包（见下方「一键导出 Cocos」）。
- **🗑 删除该资源库**：把当前 game 从磁盘删除（`out/<game>` 整个文件夹，二次确认、不可恢复），用于清理测试产物。

预览用的就是后端生成动画时的**同一套关键帧数据**，所以网页里看到的＝Cocos 里跑出来的，不依赖外部播放器、版本零兼容问题。

## 产物（同时落盘，可直接进 Cocos）

```
out/<game>/
  library.json                  # 资源库索引（网站读它）
  characters/<id>.json|.atlas|.png   # Spine 三件套（含程序化动画）
  vfx/<id>.particle.json        # Cocos ParticleSystem2D 配置
  ui/TweenPresets.ts            # UI 动效预设库（cc.tween）
```

进 Cocos：角色三件套作为 `sp.SkeletonData` 挂 `sp.Skeleton`；粒子配置喂 `ParticleSystem2D`；`TweenPresets.ts` 放进 scripts，`TweenPresets.play('scale_bounce', node).start()`。建议都放远程包 `page-main-res` 按需加载。

## 一键导出 Cocos（零基础推荐）

不想手动整理？在网页里选好 game，点 **📦 导出 Cocos 整合包**，会在下面生成一个可直接拖进 Cocos 的包：

```
out/<game>/cocos-pack/
  把素材接进Cocos-零基础教程.md      # 从装软件到点播放的保姆教程
  assets/
    resources/characters/*.json|.atlas|.png
    resources/vfx/*.json + particle.png   # 自动补一张柔光粒子贴图
    scripts/JellyDemo.ts                  # 演示脚本（按本 game 资源自动生成）
    scripts/ParticleConfig.ts             # 粒子配置 → ParticleSystem2D 加载器
    scripts/TweenPresets.ts
```

新建一个 Cocos 空项目 → 把 `cocos-pack/assets/` 里的 `resources`、`scripts` 拖进项目 `assets` → 新建场景 → 把 `JellyDemo.ts` 挂到一个空节点上 → 点 ▶ 播放，全部角色排队果冻抖动、按钮可触发 WIN 和粒子特效。细节见包内教程。

> 命令行也可单独导出：`python exporter.py <game>`

## 从游戏需求自动生成 manifest

当前后半段已经跑通：`animation_manifest.json` → 自动生图/动画 → 资源库预览 → Cocos 整合包。下一步建议补前半段：规范需求 + 参考图说明 → 文字模型生成游戏细则 → 生成 manifest → 校验 → 自动生图。

详细流程见：[游戏定义到自动生图工作流.md](游戏定义到自动生图工作流.md)

如果目标是 slot / 老虎机类电子游戏，先用玩法配置层约束用户选择，再生成 manifest：

- [老虎机玩法配置工作流.md](老虎机玩法配置工作流.md)
- [slot_game_config_template.json](slot_game_config_template.json)

## Cocos 编辑器扩展（连拖文件都省）

`cocos-extension/anim-studio-importer/` 是一个 Cocos Creator **3.8.x** 编辑器扩展，装一次后在编辑器里点菜单即可导入素材并布置场景，不用手动拖文件、建节点。

安装：把 `anim-studio-importer` 文件夹放进 Cocos 扩展目录（项目内 `extensions/`，或全局 `~/.CocosCreator/extensions/`），在「扩展管理器」里启用。纯 JS、免编译。

用法：

1. 网站点 **📦 导出 Cocos 整合包** 得到 `cocos-pack/`；
2. 编辑器菜单 **扩展 → Anim Studio → 「1. 导入 cocos-pack 资源」**，选该文件夹，自动拷进工程并刷新；
3. 打开/新建一个含 Canvas 的场景，点 **「2. 在当前场景布置演示节点」**，自动建节点 + 挂 `JellyDemo`；
4. 保存（Ctrl/Cmd+S）→ ▶ 播放。

至此整链路为：**生成 → 导出整合包 → 编辑器点两下菜单 → 播放**，全程零代码。详见 `cocos-extension/安装说明.md`。

> 「导入资源」是纯文件拷贝+刷新，最稳；「布置节点」为尽力自动，个别版本接口不符时会弹出手动兜底步骤（在 Canvas 下建空节点 + 拖 `JellyDemo.ts`，效果一致）。

## 文件说明

| 文件 | 作用 |
|---|---|
| `server.py` | 网站后端（标准库），**主入口** |
| `web/index.html` | 可视化前端（资源库 + 实时预览） |
| `pipeline.py` | 生成管线：manifest → 资产 + library.json |
| `exporter.py` | 把某 game 打包成 Cocos 整合包（导出按钮 / 命令行调用） |
| `cocos-extension/` | Cocos 3.8.x 编辑器扩展：菜单一键导入资源 + 布置演示场景 |
| `providers.py` | 图像模型调用（OpenAI，可扩展） |
| `spine_builder.py` | 角色图 → Spine 三件套 + 程序化抖动动画 |
| `particle_builder.py` | 粒子模板 → Cocos 粒子配置 |
| `tween_builder.py` | UI 动效预设 → TypeScript |
| `app.py` | （可选）旧的 Gradio 极简表单界面，需额外 `pip install gradio` |

## v1 能做 / 不做（重要）

**能做**（纯 key + 一键）：AI 生成透明角色图 → 自动套**单骨骼果冻 squash/stretch 抖动**（idle/win）；粒子按模板+颜色批量出配置；UI 全套 tween 预设。

**暂不做**（已留扩展结构）：多部件骨骼（拆头/手分别绑骨做关节动作）、SAM 自动拆件、Blender 序列帧。这些在 `spine_builder.build_skeleton_json` 与《Spine量产工作流》文档里有扩展指引。

## 兼容性

生成的 `skeleton.json` 标 spine `4.0.00`，Cocos 3.8.x 一般直接加载；个别版本报错就把 json 拖进 Spine 编辑器再导出一次兜底。