# coding-material

**Repository Path**: laixhe/coding-material

## Basic Information

- **Project Name**: coding-material
- **Description**: 用 rust 程序化生成素材资源
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# coding-material

用 Rust **程序化生成**游戏离线素材，并用**真实引擎**（Bevy 0.19 / Godot 4.7）做发布门禁验证的资产管线。

## 核心思路

- **清单即配置**：[assets.toml](assets.toml) 是单一事实源。种子（seed）+ 可选覆盖（配色 / 身材 / 帧数）→ 确定性导出全套离线资源。
- **确定性 & 可回归**：同一清单两次导出逐字一致（`doctor --strict` 门禁保证）；改参数即同步，产物随代码演进可复现。
- **2D / 3D 同源**：立绘、精灵表、GLB 低模角色共用同一套「角色投影」数据——改身材/配色，一处生效处处同步。
- **导出 + 展示 + 验证闭环**：资产由同一生成器导出、预览页实时可看、真实引擎编译/装载/播放逐层验证。

## 快速开始

```bash
cargo run -p artgen                  # 全量导出到 assets/（40+ 产物 + assets.json 索引）
cargo run -p artgen -- serve         # 本地预览 http://127.0.0.1:8420/preview/
cargo run -p artgen -- watch         # 预览 + 监听 assets.toml 自动重生成
cargo test --workspace               # 全部单元测试
```

## CLI 一览（`cargo run -p artgen -- --help`）

| 命令 | 作用 |
|---|---|
| `artgen` | 按清单全量导出 |
| `artgen --seed <N> / --out <dir>` | 覆盖种子 / 输出目录 |
| `artgen --variants <N>` | 批量导出 N 个连续种子变体到 `<out>/seed<seed>/` |
| `artgen --seeds 3,17,42` | 任意种子批量导出（重复去重；孤儿 seed 目录自动清理） |
| `artgen adopt <seed>` | 采纳种子回写清单（watch 下即时生效） |
| `artgen bundle <dest>` | 发布快照 + FNV 清单（**只打包索引声明的产物**） |
| `artgen check <dir>` | 校验 bundle 快照：对照 MANIFEST 逐个文件比对 FNV-1a / 大小 |
| `artgen diff <dirA> <dirB>` | 对比两个导出目录：按相对路径 + FNV/大小 报告 M 变更 / + 新增 / - 删除（跳过冒烟脚手架等瞬态目录） |
| `artgen doctor [--strict]` | 自检索引↔磁盘一致（含**索引外孤儿文件提示**）；`--strict` 另做确定性复检 |
| `artgen --examples [--engine godot\|bevy\|all]` | 导出引擎消费示例（2D/3D） |
| `artgen --godot-smoke [--godot <exe>]` | Godot headless 引擎内冒烟（几何 + 六剪辑 + 2D/3D 示例实例化，3D walk 真播放推进） |
| `artgen --bevy-smoke` | 用 Bevy 0.19.1 编译检查导出片段 |
| `artgen --bevy-probe` | Bevy 真实装载 + 真播放 character.glb（六剪辑断言 + 节点变换推进） |
| `artgen --verify [--godot <exe>]` | 发布门禁 5 步：重导出 → Bevy 编译 → Bevy 装载播放 → Godot 冒烟 → 确定性复检（逐步报告落盘 `assets/verify_report.json`） |

## 实时编辑（`watch` 模式）

`artgen watch` 启动后，预览页可直接改参并即时生效（回写清单 → 自动重生成 → 自动刷新）：

| 端点 / 页面 | 作用 |
|---|---|
| `POST /__adopt?seed=N` | 采纳种子（gallery 卡片 & board 种子输入） |
| `POST /__manifest-patch`（JSON） | 身材滑杆写 `[glb.body]`/`gait_scale`；角色取色器写 `[character]`；UI 主题取色器写 `[ui.palette]` |
| `POST /__rebuild-variants?count=N` | 用当前 manifest/生成器重建 `build/` 变体（并清理孤儿 seed 目录）；`?seeds=3,17,42` 可重建任意种子组合 |
| board 实时捏人 | 身材/步态滑杆 + 角色 4 取色器 + UI 主题 3 取色器 + 种子采纳 |
| gallery | 变体 2D 对照 / 3D 查看（`model.html?seed=N`）/ 一键采纳 / 重建 |

校验结果落盘可视化：`assets/verify_report.json`（verify 逐步状态/耗时，成功与失败都写）、`assets/bevy_probe.json`、`assets/godot_smoke.json`，制图板（board.html）显示对应状态卡。

重生成失败（如清单写错）会在**所有预览页顶部**显示红色错误横幅（`/__rev.json` 附带 error 字段，live.js 渲染），修复保存、重生成成功后自动恢复。

## 工作区结构

| 目录 | 职责 |
|---|---|
| [audio-wav](audio-wav) | 程序化脚步/UI 音效（`lib` + 独立 CLI） |
| [image-svg](image-svg) | 角色立绘 SVG + PNG 离线栅格化（`lib` + CLI） |
| [lowpoly-glb](lowpoly-glb) | 低模角色 + 六段动画（idle/walk/run/jump/dead/hurt）GLB；同源 2D 精灵表；Bevy/Godot 消费示例与装载探针 |
| [character-core](character-core) | 角色配色 / 身材模型（2D/3D 共享） |
| [ui-png](ui-png) | UI 美术素材（图标 / 按钮 / 进度条 + 图集） |
| [tools/artgen](tools/artgen) | 统一导出入口 + 预览服务器 + 验证门禁 |

每个成员同时提供 `lib`（纯生成内核 + spec 类型，供 artgen / 测试复用）与 `bin`（独立 CLI，可用 `--spec <file.toml>` 覆盖参数）。

## 产物一览（seed 7 默认）

`assets/`（不入库，由生成器产出）：

- `character.glb` — 低模角色 + 六动画
- `character.json` — 侧车元数据（精灵表 / 剪辑帧数 / fps / UI 图）
- `character_sheet.{svg,png}` / `character_walk.svg` / `character_sprites.{svg,png}` — 同源 2D 设定图与精灵表
- `character_portrait.png` / `character_icon.png` — 与 GLB 同源投影的 UI 头像 / 全身图标
- `beast.glb` — 四足兽 + 六动画；`beast.json` 侧车；
  `beast_sheet.{svg,png}` / `beast_walk.svg` / `beast_sprites.{svg,png}` — 同源 2D 精灵产物
  （与 GLB 节点树同一骨架投影；逐帧 PNG 时帧名带 `beast_` 前缀）
- 六骨预设（`[[glb.characters]]` 里 `model = "xiake" | "shanzei"`，jinglinshan-town 提取）：
  - `xiake.*` — 侠客：月白道袍 + 斗笠 + 背剑，附加 `attack` 挥剑剪辑
  - `shanzei*.glb` — 山贼 6 变体各一条正式预设：grunt 喽啰 / scout 探子 /
    berserker 悍匪 / shaman 妖道（法杖，附加 `cast`）/ slinger 投石兵 / boss 山王
    （战锤，附加 `slam`）；变体决定武器与附加剪辑
  每个预设同款全套：`_sheet.{svg,png}` / `_walk.svg` / `_sprites.{svg,png}` /
  `_portrait.png` / `_icon.png` + `<stem>_{walk,run,jump,hurt,dead}.wav`；
  六骨单段肢体，6 段内置剪辑（idle/walk/run/jump/dead/hurt）+ 1 段变体附加。
  侧车 `<stem>.json`（character / beast / 各预设**同构**）带顶层 `clips`：每段
  name / duration / loops，如实反映作者设定的循环/一次性——rig6 预设的 hurt/dead
  与变体附加 attack/cast/slam 为 loops=false；person/beast 的 dead 为 false、
  hurt 为循环剪辑。引擎据此写通用加载器即可区分循环与一次性。
- 自定义动画：`[[glb.animations]]` 声明任意剪辑（六关节通道的 [时间,角度] 关键帧
  折线 + `loops`）；GLB 动画表追加对应剪辑，`[glb.sprites].extra_rows` 同名条目还会
  生成精灵表追加行（character / beast / 预设共用）
- `*.wav` — 全局脚步与 UI 音效 + 每角色 `<stem>_{walk,run,jump,hurt,dead}.wav`
  （步态落步间隔 = 该角色 walk/run 剪辑时长一半，音高随身材缩放；四足兽同规则）
- `ui_atlas.png` + 图标 / 按钮 / 进度条等 UI 资源
- `character_player.gd` / `character_3d.gd` / `character_player_loading.rs` / `character_glb_loading.rs` — 引擎消费示例（Godot/Bevy × 2D/3D，随资产导出）
- `preset_glb_loading.rs` — Bevy 0.19 六骨预设名册示例（按 `B3P_MODEL` 装载 xiake / 任一
  shanzei 变体，断言完整剪辑表含变体附加 attack/cast/slam，再播 walk；附加剪辑为一次性，经
  `#Animation(6)` 触发）
- `assets.json` — 全量索引；`characters` 数组按角色分组（model / meta / sprites / ui / audio +
  **角色摘要** kind / variant / clips，引擎免开侧车即可知道骨架种类、山贼变体与每段剪辑的
  循环/一次性），引擎可按角色一次性取全套资产

## 预览页

`serve` 后访问 `/preview/`：总览 / 制图板（Bevy 播放探针 + Godot 冒烟**双状态卡**、实时捏人面板）/ 动画回放 / 模型（六剪辑 + 一次性/循环语义 + 速度，支持 `?seed=` 看变体）/ 音频 / UI / 消费示例 / 变体画廊（2D 对照 · 3D 直通 · 一键采纳 · 一键重建）等页面，均由生成产物驱动。

## 仓库约定

- **生成物不入库**：`assets/`、`build/`、`target/` 等见 [.gitignore](.gitignore)，仓库只保留「生成器 + manifest」。
- 引擎验证脚手架（`assets/bevy-smoke/`、`assets/godot-smoke/`）由验证命令生成、运行后保留在本地，不属于发布物。