# 免费游戏模型库 · AI 交接文档 (HANDOFF)

> 给接手这个项目的 AI / bot 看的。先完整读完再动手。
> 最后更新：2026-10-23（由 小T.Test all 生成）

## 1. 项目是什么

- **线上地址**：https://20261023-game-models.pages.dev/
- **托管**：Cloudflare Pages，项目名 `20261023-game-models`，分支 `main`
- **用途**：Ethan 做游戏开发用的免费 3D 模型库（角色 / 场景 / 道具），可在线浏览缩略图、3D 预览、下载 GLB。
- **规模**：4539 个模型，50 个模型包，约 700 MiB；低多边形 2971、写实 324、体素 1244；带动画 83，带骨骼 44。
- **授权**：全部 CC0 1.0（可商用、可再分发、无需署名）。只收 CC0，其它协议一律不收。

## 2. 用户的硬性规矩（必须遵守）

1. **先发链接、再下载**：找到候选模型后，先把每个模型/模型包的**原始页面链接**发给 Ethan 确认，他同意后才能下载、压缩、上传 CDN。不要擅自批量塞模型进来。
2. **目录要整齐**：严格按下面第 3 节的结构放，不要在根目录乱堆文件。
3. **必须能预览**：每个模型都要有缩略图，并出现在 `index.html` 里。
4. **部署命名**：Cloudflare Pages 项目按「日期-内容」命名（如 `20261023-game-models`）。在原项目上增量更新即可，除非用户要求新建。
5. 已明确排除：V12（Makovice，禁止单独再分发）、R3（Grab3D，授权无法核实）。

## 3. CDN 上的目录结构

```
/
├── index.html            # 浏览页（中文 UI，按风格/分类/包筛选、搜索、3D 预览）
├── models.json           # 全部模型的清单（index.html 读它）
├── 授权说明.html          # 每个包的来源、作者、授权
├── files.html / files.json # 全站文件清单（树形浏览 + 搜索）
├── HANDOFF.md            # 本文档
├── tools/                # 生成流水线脚本副本（见第 6 节）
├── vendor/               # model-viewer.min.js + draco 解码器
├── models/<风格>/<分类>/<包slug>/<模型名>.glb
└── thumbs/<风格>/<分类>/<包slug>/<模型名>.webp   # 256×256 透明背景
```

- `<风格>`：`lowpoly` | `realistic` | `voxel`
- `<分类>`：`character` | `environment` | `prop`
- 模型和缩略图路径一一对应（`.glb` ↔ `.webp`）。

直接引用示例（Three.js `GLTFLoader`，部分大文件用了 Draco，要配 `DRACOLoader`）：
```
https://20261023-game-models.pages.dev/models/lowpoly/character/gobkit-free-minions/minion-a01.glb
```

## 4. models.json 格式

```json
{
  "generated": "2026-10-23",
  "license_note": "All assets CC0 1.0 (public domain dedication).",
  "packs": {
    "kenney-castle-kit": {"slug":"kenney-castle-kit","name":"Kenney Castle Kit","zh":"城堡套件",
      "style":"lowpoly","author":"Kenney","url":"https://kenney.nl/assets/castle-kit",
      "license":"CC0 1.0","note":"","count":76}
  },
  "models": [
    {"name":"minion-a01","style":"lowpoly","cat":"character","pack":"gobkit-free-minions",
      "path":"models/lowpoly/character/gobkit-free-minions/minion-a01.glb",
      "thumb":"thumbs/lowpoly/character/gobkit-free-minions/minion-a01.webp",
      "size":157156,"rigged":true,"anims":["movement"],"tris":240,"license":"CC0-1.0"}
  ]
}
```
新增模型时：在 `packs` 里加包信息，在 `models` 里加条目，字段保持一致。

## 5. Cloudflare Pages 限制（重要）

- 单文件 ≤ **25 MiB**，单项目 ≤ **20,000 个文件**（当前约 9,100 个，还有余量）。
- 超过 25 MiB 的模型：先压缩（贴图降到 1k、webp、Draco）；仍然超的不要放 Pages，告诉用户需要改用 Cloudflare R2。
- 部署命令（在包含 `dist/` 的目录执行）：
  ```
  export CLOUDFLARE_ACCOUNT_ID=2a22d54b953d488c636542b4c5c828a7
  # CLOUDFLARE_API_TOKEN 需在环境变量中（Grok Bot 的电脑上已配置）
  npx wrangler pages deploy dist --project-name 20261023-game-models --branch main
  ```
  ⚠️ 每次部署会**整体替换**线上内容，所以 `dist/` 必须是完整的站点（包含所有旧模型），不能只放新文件。

## 6. 生成流水线

**完整工作目录**在 Grok Bot 的电脑（box，所有 Grok Bot 共用）上：`/workspace/game-models/`。
同一用户的其他 Grok Bot 可以直接在那里继续做；不在这台机器上的 AI 可以从 `tools/` 下载脚本副本，但原始素材（`raw/`、`x/`、`conv/`，几 GB）不在 CDN 上，需要重新下载。

| 步骤 | 脚本 | 说明 |
|---|---|---|
| 1. 下载 | `itchdl.py`（itch.io）、`qdl.py`（Quaternius / Google Drive，用 gdown）、`phdl.py`（Poly Haven API）；Kenney 直接下 zip | 原始文件放 `raw/`、`x/`（解压后） |
| 2. 转格式 | `bl_convert.py`（Blender 无界面，FBX/OBJ → GLB）、`vox2glb.py`（MagicaVoxel .vox → GLB） | 输出到 `conv/` |
| 3. 编目 | `catalog.py` | 扫描所有 GLB，按包定义风格/分类，生成 `jobs.json` |
| 4. 优化 | `optimize.mjs`（gltf-transform：dedup、prune、贴图≤1024；>2MB 转 webp；>4MB 加 Draco） | 写入 `dist/models/...`，结果在 `opt_*.json`；可分片并行 `node optimize.mjs <起始> <步长>` |
| 5. 缩略图 | `mvbatch.mjs`（Playwright + model-viewer 截 256×256 透明 PNG；需本地 `http://localhost:8765` 服务 `dist/`）；`bl_thumb.py` 为 Blender 备用渲染 | 输出 `thumbs_png/`，`build_site.py` 转 webp |
| 6. 建站 | `build_site.py` | 生成 `models.json`、`授权说明.html`，复制 `index.html`（源文件 `site_src/index.html`）和 vendor |
| 6b. 文件清单 | 重新生成 `files.json`（遍历 `dist/` 所有文件的 `[路径, 字节数]` 列表）；`files.html` 源在 `site_src/files.html` | 每次增删文件后必须更新，否则清单页不准 |
| 7. 部署 | wrangler（见第 5 节） | |

依赖：Node（见 `tools/package.json`）、Python 3 + Pillow + gdown、Blender（无界面）、Chrome（截图用）。

## 7. 未完成 / 已跳过的内容（可继续做）

- **Quaternius 7 个包**（托管在 Google Drive，下载时一直报配额超限）：L3 Ultimate Modular Characters、L4 Ultimate Monsters、L5 Zombie/Apocalypse、L10 Medieval Village，以及 Modular Weapons、Ultimate Space Kit、Cyberpunk Game Kit。可以过段时间重试，或换镜像（如 quaternius.com 页面里的其它下载链接 / itch.io）。
- **Poly Haven 5 棵超大树木**（每个 100–958 MB）：太大，压缩后仍超 25 MiB，需要 R2 或大幅减面。
- Myuxen Arcade Voxel 的 `Environment__FlowersRed` 文件损坏，已跳过。
- Poly Haven `cannon_01` 的 glTF 原文件有问题，已用 FBX 在 Blender 中重建。

## 8. 当前收录的模型包

| 风格 | slug | 中文名 | 数量 | 作者 | 来源 |
|---|---|---|---|---|---|
| 低多边形 | `gobkit-free-minions` | Gobkit 小兵 | 8 | Gobkit | https://gobkit.itch.io/gobkit-free-minions |
| 低多边形 | `kaykit-adventurers` | KayKit 冒险者 | 37 | Kay Lousberg | https://kaylousberg.itch.io/kaykit-adventurers |
| 低多边形 | `kaykit-city-builder-bits` | KayKit 城市建造 | 41 | Kay Lousberg | https://kaylousberg.itch.io/city-builder-bits |
| 低多边形 | `kaykit-dungeon` | KayKit 地牢 | 211 | Kay Lousberg | https://kaylousberg.itch.io/kaykit-dungeon-remastered |
| 低多边形 | `kaykit-forest` | KayKit 森林 | 105 | Kay Lousberg | https://kaylousberg.itch.io/kaykit-forest |
| 低多边形 | `kaykit-furniture-bits` | KayKit 家具 | 53 | Kay Lousberg | https://kaylousberg.itch.io/furniture-bits |
| 低多边形 | `kaykit-medieval-hexagon` | KayKit 中世纪六边形 | 221 | Kay Lousberg | https://kaylousberg.itch.io/kaykit-medieval-hexagon |
| 低多边形 | `kaykit-restaurant-bits` | KayKit 餐厅 | 144 | Kay Lousberg | https://kaylousberg.itch.io/restaurant-bits |
| 低多边形 | `kaykit-skeletons` | KayKit 骷髅 | 17 | Kay Lousberg | https://kaylousberg.itch.io/kaykit-skeletons |
| 低多边形 | `kenney-blaster-kit` | 爆能枪套件 | 40 | Kenney | https://kenney.nl/assets/blaster-kit |
| 低多边形 | `kenney-car-kit` | 汽车套件 | 50 | Kenney | https://kenney.nl/assets/car-kit |
| 低多边形 | `kenney-castle-kit` | 城堡套件 | 76 | Kenney | https://kenney.nl/assets/castle-kit |
| 低多边形 | `kenney-city-kit-commercial` | 城市商业区套件 | 41 | Kenney | https://kenney.nl/assets/city-kit-commercial |
| 低多边形 | `kenney-city-kit-suburban` | 城市郊区套件 | 40 | Kenney | https://kenney.nl/assets/city-kit-suburban |
| 低多边形 | `kenney-fantasy-town-kit` | 奇幻小镇套件 | 167 | Kenney | https://kenney.nl/assets/fantasy-town-kit |
| 低多边形 | `kenney-food-kit` | 食物套件 | 200 | Kenney | https://kenney.nl/assets/food-kit |
| 低多边形 | `kenney-furniture-kit` | 家具套件 | 140 | Kenney | https://kenney.nl/assets/furniture-kit |
| 低多边形 | `kenney-graveyard-kit` | 墓地套件 | 91 | Kenney | https://kenney.nl/assets/graveyard-kit |
| 低多边形 | `kenney-mini-characters` | 迷你角色 | 26 | Kenney | https://kenney.nl/assets/mini-characters |
| 低多边形 | `kenney-mini-dungeon` | 迷你地牢 | 30 | Kenney | https://kenney.nl/assets/mini-dungeon |
| 低多边形 | `kenney-nature-kit` | 自然套件 | 329 | Kenney | https://kenney.nl/assets/nature-kit |
| 低多边形 | `kenney-pirate-kit` | 海盗套件 | 72 | Kenney | https://kenney.nl/assets/pirate-kit |
| 低多边形 | `kenney-platformer-kit` | 平台跳跃套件 | 153 | Kenney | https://kenney.nl/assets/platformer-kit |
| 低多边形 | `kenney-retro-urban-kit` | 复古城市套件 | 124 | Kenney | https://kenney.nl/assets/retro-urban-kit |
| 低多边形 | `kenney-space-kit` | 太空套件 | 153 | Kenney | https://kenney.nl/assets/space-kit |
| 低多边形 | `kenney-survival-kit` | 生存套件 | 80 | Kenney | https://kenney.nl/assets/survival-kit |
| 低多边形 | `kenney-tower-defense-kit` | 塔防套件 | 160 | Kenney | https://kenney.nl/assets/tower-defense-kit |
| 低多边形 | `quaternius-fantasy-props` | 奇幻道具大合集 | 94 | Quaternius | https://quaternius.com/packs/fantasypropsmegakit.html |
| 低多边形 | `quaternius-stylized-nature` | 风格化自然大合集 | 68 | Quaternius | https://quaternius.com/packs/stylizednaturemegakit.html |
| 写实 PBR | `polyhaven-hidden-alley` | Poly Haven 隐秘小巷 | 39 | Poly Haven 社区作者 | https://polyhaven.com/collections/hidden_alley |
| 写实 PBR | `polyhaven-namaqualand` | Poly Haven 纳马夸兰 | 30 | Poly Haven 社区作者 | https://polyhaven.com/collections/namaqualand |
| 写实 PBR | `polyhaven-pine-forest` | Poly Haven 松林 | 12 | Poly Haven 社区作者 | https://polyhaven.com/collections/pine_forest |
| 写实 PBR | `polyhaven-project-lighthouse` | Poly Haven 灯塔计划 | 112 | Poly Haven 社区作者 | https://polyhaven.com/collections/project_lighthouse |
| 写实 PBR | `polyhaven-singles` | Poly Haven 单品 | 1 | Poly Haven 社区作者 | https://polyhaven.com/models |
| 写实 PBR | `polyhaven-smugglers-cove` | Poly Haven 走私者海湾 | 32 | Poly Haven 社区作者 | https://polyhaven.com/collections/smugglers_cove |
| 写实 PBR | `polyhaven-the-shed` | Poly Haven 工具棚 | 69 | Poly Haven 社区作者 | https://polyhaven.com/collections/the_shed |
| 写实 PBR | `polyhaven-verdant-trail` | Poly Haven 绿野小径 | 17 | Poly Haven 社区作者 | https://polyhaven.com/collections/verdant_trail |
| 写实 PBR | `quaternius-universal-animation-library` | 通用动作库 | 2 | Quaternius | https://quaternius.com/packs/universalanimationlibrary.html |
| 写实 PBR | `quaternius-universal-base-characters` | 通用基础角色 | 10 | Quaternius | https://quaternius.com/packs/universalbasecharacters.html |
| 体素 | `airdinghy-voxel-ships` | 体素太空飞船 | 10 | Air Dinghy Interactive | https://airdinghy.itch.io/voxel-space-ships |
| 体素 | `geeksagon-space-robots` | 模块化体素机器人 | 79 | Geeksagon | https://geeksagon.itch.io/space-robots |
| 体素 | `kaykit-block-bits` | KayKit 方块 | 40 | Kay Lousberg | https://kaylousberg.itch.io/block-bits |
| 体素 | `kenney-blocky-characters` | 方块角色 | 18 | Kenney | https://kenney.nl/assets/blocky-characters |
| 体素 | `kytric-path-terrain` | 体素地形与道路 | 373 | Kytric | https://kytric.itch.io/voxel-path-and-terrain |
| 体素 | `kytric-vehicles` | 体素载具 | 277 | Kytric | https://kytric.itch.io/voxel-vehicles |
| 体素 | `myuxen-arcade-voxel` | 街机体素包 | 15 | Myuxen | https://myuxen.itch.io/ultimate-arcade-game-voxel-model-pack |
| 体素 | `oga-55-voxel-creatures` | 55个体素生物 | 55 | kooow | https://opengameart.org/content/55-voxel-creatures |
| 体素 | `oga-medieval-voxels` | 中世纪体素 | 363 | FuzzyManStudios | https://opengameart.org/content/medieval-theme-voxels-asset-pack |
| 体素 | `oga-voxel-buildings` | 体素建筑 | 13 | mehrasaur | https://opengameart.org/content/voxel-buildings |
| 体素 | `voxel-capy-crab` | 体素螃蟹 | 1 | Voxel Capy | https://voxel-capy.itch.io/animated-voxel-crab |

## 9. 接手后建议的第一步

1. 打开线上站点看一下现状；读 `models.json` 了解已有内容，避免重复收录。
2. 问 Ethan 这次想补什么类型（角色 / 场景 / 道具、哪种风格）。
3. 找 CC0 候选 → **发原链接给他确认** → 按第 6 节流程处理 → 部署 → 把新增内容的链接发给他。