170 lines
9.5 KiB
Markdown
170 lines
9.5 KiB
Markdown
# 各生成节点使用方法
|
||
|
||
## 敌方角色制作（标准方案）
|
||
|
||
采用 [敌方角色标准制作方案 v1](Doc/Design/Character/EnemyCharacterProduction.md)：静态验收→同角色骨架/空间对齐→同rig Idle/Walk/Attack→离线收尾→Enemy视觉Prefab→整段与Play验收→资源登记。配方 `Config/Art/EnemyCharacters/{Name}.json`，入口 `Tools/enemy_character_pipeline.py`；岩团团为已验证样例。骨名和运动参数按解剖配置，不能把短腿双足模板直接套到四足/飞行角色。
|
||
|
||
## 人形角色蒙皮（默认方案）
|
||
|
||
默认使用 **固定 Mixamo 骨架 + TokenRig 只预测蒙皮权重**：角色体型拟合并固定骨架 → 清除参考模型既有权重 → TokenRig 已有骨架模式预测权重 → 还原骨架并做局部权重收尾 → Unity Humanoid／实际动作验收。具体要求见 [人物角色流程](GameResProductProc.md#a-人物角色)。Mixamo 网站绑定作为参考、对照或明确选择的替代方案。
|
||
|
||
已有实现参考：`Tools/model_tools/bl_tokenrig_mixamo41_trial.py`、`Tools/model_tools/bl_lmgirl_mixamo41.py`。这些工具含参考角色的骨数、对齐或解剖参数，复用于新角色时需相应调整与验证。
|
||
|
||
## 文/图生图
|
||
- 默认模型：`gpt-image-2.5`（≤1K，如 `1024x1024` 或比例 `"1:1"` / `"16:9"`）
|
||
- VIP 模型：`gpt-image-2-vip`（>1K 像素，如 `2048x2048`、`2048x1152`）
|
||
- 接口文档：Doc\gpt-image_doc.md
|
||
- 脚本：Tools\gpt_image_generate.py
|
||
|
||
用于 3D 建模的人形角色设计图，必须原样加入 [人物角色流程](GameResProductProc.md#a-人物角色) 中的完整固定英文姿态提示词，并保留纯白背景、双手空、全身入画和 `2:3` 比例要求。
|
||
|
||
### 模型选择规则（Agent / 人工均需遵守）
|
||
1. 输出边长 **≤1024**（含 `1024x1024` 及比例写法）：用默认 `gpt-image-2.5`。
|
||
2. 输出任一边 **>1024**（如 `2048x2048` UI 图集）：**必须**改用 VIP `gpt-image-2-vip`，并传像素写法（VIP **不支持** `"16:9"` 这类比例字符串）。
|
||
3. 脚本在 `--aspect-ratio` 为 `WxH` 且任一边 >1024 时：若当前模型不是 VIP 系列，会自动升为 `gpt-image-2-vip`；已是 `gpt-image-2-vip` / `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` 则保留。
|
||
4. VIP 像素约束：边长为 16 的倍数、最大边 ≤3840、总像素约 0.64M–8.3M、长短边比 ≤3:1。
|
||
5. 当前账号下 `gpt-image-2.5-flare` 对 >1K 不可用，**不要默认使用 flare**。
|
||
|
||
### AI / 命令行调用
|
||
|
||
请在当前 shell 配置 API key（不要将 key 写入脚本或提交到 Git）：
|
||
|
||
```powershell
|
||
$env:GRSAI_API_KEY = 'sk-...'
|
||
```
|
||
|
||
脚本也接受 `GPT_IMAGE_API_KEY`、`--api-key` 和 JSON 的 `api_key`；未配置 key 时会在提交请求前明确报错。
|
||
|
||
```bash
|
||
# 文生图（默认 1K / gpt-image-2.5）
|
||
python Tools/gpt_image_generate.py -p "一只边牧在草地上奔跑" -o AIClient/Assets/Generated/dog.png
|
||
|
||
# 大于 1K（如 2048）：用 VIP，传像素尺寸
|
||
python Tools/gpt_image_generate.py -p "UI sprite atlas" -o Tools/output/ui_atlas.png --aspect-ratio 2048x2048 --model gpt-image-2-vip
|
||
|
||
# 图生图（可多次传 --image）
|
||
python Tools/gpt_image_generate.py -p "保持构图，换成赛博朋克风格" -i ref.png -o out.png
|
||
|
||
# JSON 参数（适合 Agent / 流程编排）
|
||
python Tools/gpt_image_generate.py --json "{\"prompt\":\"城市夜景\",\"output\":\"out/city.png\"}" --result-only
|
||
python Tools/gpt_image_generate.py --json "{\"prompt\":\"UI图集\",\"output\":\"out/atlas.png\",\"aspectRatio\":\"2048x2048\",\"model\":\"gpt-image-2-vip\"}" --result-only
|
||
```
|
||
|
||
### 流程回调
|
||
- `--callback-url`：每个进度/结果事件 POST JSON
|
||
- `--callback-file`：覆盖写入 `{latest, history}` 状态文件
|
||
- 默认 stdout 输出 NDJSON 事件流，最后一行为最终结果
|
||
|
||
环境变量可选覆盖：`GRSAI_API_KEY`、`GPT_IMAGE_API_KEY`。流式响应兼容 SSE 与 NDJSON；`async` 或未完成的 `json` 响应会自动调用结果查询接口轮询。
|
||
|
||
## 腾讯混元3D（图生3D → GLB）
|
||
- 网站：`https://3d.hunyuan.tencent.com/`
|
||
- 脚本：`Tools/hunyuan_3d_generate.py`
|
||
- 模块：`Tools/hunyuan_3d/`（`auth.py` 微信登录 / `client.py` 图生自动化）
|
||
- 依赖：`Tools/requirements-hunyuan.txt`（`playwright` + 本机 Microsoft Edge）
|
||
```bash
|
||
pip install -r Tools/requirements-hunyuan.txt
|
||
playwright install msedge
|
||
```
|
||
- 会话目录：`Tools/data/hunyuan/`（`storage_state.json` 为登录凭证，已 gitignore）
|
||
- 环境变量：`HUNYUAN_SESSION_DIR`、`HUNYUAN_BROWSER_CHANNEL`（默认 `msedge`）
|
||
|
||
### 能力说明
|
||
1. 首期仅 **图生3D → GLB**。文生请先用上文「文/图生图」出图，再交给本脚本。
|
||
2. 未登录、凭证失效或**当前账号额度/次数用尽**时，会 **弹出 Edge 微信扫码页**（同步阻塞，最长 `--login-timeout` 秒）；额度满时提示换号登录，成功后自动续跑。
|
||
3. 面数：`--faces 50k|500k|1m`（默认 `50k`）。
|
||
4. 任务中间文件在 `Tools/data/hunyuan/jobs/<job_id>/`；最终 GLB 写到 `-o`。
|
||
5. 生成完成后须在 `Doc/ResDesc_Model.md` 登记资源（索引见 `Doc/ResDesc.md`）。
|
||
|
||
### AI / 命令行调用
|
||
```bash
|
||
# 查看登录状态
|
||
python Tools/hunyuan_3d_generate.py --status
|
||
|
||
# 预登录（弹出微信扫码）
|
||
python Tools/hunyuan_3d_generate.py --login
|
||
|
||
# 强制换号登录（忽略本地凭证 / 额度满换号）
|
||
python Tools/hunyuan_3d_generate.py --login --force-login
|
||
|
||
# 图生3D（未登录或额度满则中途自动弹登录页）
|
||
python Tools/hunyuan_3d_generate.py -i ref.png -o Tools/output/prop.glb --faces 50k
|
||
|
||
# JSON / Agent
|
||
python Tools/hunyuan_3d_generate.py --json "{\"image\":\"ref.png\",\"output\":\"out/a.glb\",\"faces\":\"50k\"}" --result-only
|
||
|
||
# CI：禁止弹窗，未登录直接失败
|
||
python Tools/hunyuan_3d_generate.py -i ref.png -o out.glb --no-interactive-login
|
||
```
|
||
|
||
### 流程回调 / 事件
|
||
- `--callback-url` / `--callback-file` / NDJSON 与文生图脚本同模式
|
||
- 典型事件：`login_required` → `login_waiting` → `login_ok` → `stage` → `succeeded` / `failed`
|
||
- `login_required.reason`：`auth`（未登录/失效）或 `quota`（额度满需换号）
|
||
|
||
## 高模减面与贴图烘焙
|
||
|
||
**新场景组件（含独立地表）的默认入口为 `Tools/scene_component_pipeline.py`**：分件图 → 混元 50k → Studio 低模 → Studio UV → Blender 同源对齐烘焙 → 实际面数严格超过目标 130% 时保留 UV 减面。细则见 [SceneModelProduction.md](Doc/Design/Scene/SceneModelProduction.md)。下述 Blender 自动减面/展 UV 工具供历史资源复现和其他明确使用它的流程，不作为新场景组件默认方案。
|
||
|
||
- 来源：复刻 `ClientTrunk/Tools/ModelTools`（`model_decimate` + `model_bake`）
|
||
- 目录：`Tools/model_tools/`（说明见 `Tools/model_tools/README.md`）
|
||
- 依赖：本机 **Blender**（推荐 5.0）；可选 Pillow（UV 观察图）；可选 UVPackmaster 4
|
||
- 默认路径：`D:\tools\Blender\blender-5.0.0-windows-x64\blender.exe`（可用 `BLENDER_EXE` / `BLENDER_PATH` / `--blender` 覆盖）
|
||
|
||
### 流程
|
||
```text
|
||
高模（FBX / GLB / glTF）
|
||
-> 减面 + 重展 UV -> <名>_low.fbx
|
||
-> Cycles selected-to-active 烘焙
|
||
-> 五通道 PNG + 低模 FBX
|
||
-> model_translator（默认）-> XPbr 两张图 + .mat/.meta
|
||
<名>_base.png RGB=Albedo A=AO/透明
|
||
<名>_mix.png RG=球面法线 B=Metallic A=Roughness
|
||
写出 PNG 时无损压缩（Blender compression=100 + zlib 9 / Pillow optimize）
|
||
```
|
||
|
||
### AI / 命令行调用
|
||
```bash
|
||
# 一键：减面 + 烘焙 + XPbr 打包（默认）
|
||
python Tools/model_tools/model_lowpoly_bake.py Tools/output/prop.glb -o Tools/output/prop_game --tris 5000 --size 2048
|
||
|
||
# 仅五通道、跳过 XPbr
|
||
python Tools/model_tools/model_lowpoly_bake.py prop.glb -o Tools/output/prop_game --no-xpbr
|
||
|
||
# 单独 XPbr 转换（输入为烘焙后的 FBX 目录旁贴图）
|
||
python Tools/model_tools/model_translator.py Tools/output/prop_game/prop/prop.fbx -o Tools/output/prop_xpbr
|
||
```
|
||
|
||
与混元衔接：
|
||
|
||
```bash
|
||
python Tools/hunyuan_3d_generate.py -i ref.png -o Tools/output/{actor}_3d/{actor}.glb --faces 50k
|
||
python Tools/model_tools/model_lowpoly_bake.py Tools/output/{actor}_3d/{actor}.glb -o Tools/output/{actor}_game --tris 3000 --size 1024
|
||
python Tools/install_character_bundles.py -a {ActorName} --kind Human -b Tools/output/{actor}_game/{actor}_xpbr -c ref.png
|
||
# Unity Pipeline: unity command run_script --file AgentScripts/SetupCharacter.cs --entry SetupCharacter.SetupCaoCao
|
||
```
|
||
|
||
### 与 AIC#Project ModelTranslator 对比（减面/烘焙）
|
||
- **更优（AIC#）**：默认 Quad Remesher 四边拓扑、更深 seam 扫描；本仓库未捆绑 QR 引擎。
|
||
- **已对齐**：自适应烘焙射线、UV 最大单岛门限、XPbr base/mix 打包与 `Test/XPbr` 材质。
|
||
- **本仓库优势**：高模直接吃 GLB/glTF（混元产物），一键流水线含 XPbr。
|
||
|
||
游戏目录：人物 `AIClient/Assets/Bundles/Characters/Human/{ActorName}/`；高模中间件留在 `Tools/output/`。完成后登记 `Doc/ResDesc_Model.md`。
|
||
|
||
## UI 自动生成（JSON → Prefab）
|
||
|
||
总览：`Doc/UI_AutoGen_Overview.md`
|
||
|
||
```text
|
||
需求 → 写 Doc/UIPrefabCreater/{UI}.json
|
||
→ Unity Tools/UI 或获焦自动转换
|
||
→ Assets/Bundles/UI/Prefab/{UI}.prefab
|
||
→ HotUpdate C# 接管
|
||
```
|
||
|
||
- 契约提示词：`Doc/Rule/UIGenerationPrompt.md`
|
||
- 切图规范：`Doc/UI_Normal_Set.md` / `Doc/UI_Pic_Set.md`
|
||
- 风格：`Doc/Design/UI_Design_Principles.md`
|
||
- 缺切图时用上文「文/图生图」，>1K 用 `gpt-image-2-vip`；导入 `Assets/Bundles/UI/Texture/Common`
|
||
- 完成后登记 `Doc/ResDesc_Picture.md`
|