threejs-3d-generator

Three.js 3D 生成器

为浏览器游戏制作的生产级 3D 资产，适用于 Three.js。提供方：Tripo。

根据实际加载的技能文件解析 <this-skill-dir>。优先在其旁边查找同级技能，然后使用运行器发现的路径。不要混用已安装的版本，也不要假定特定的主目录。

参考资料

文件	何时阅读
references/api-notes.md	端点和任务决策、模型版本、轮询、后处理、转换、绑定、动画、下载
references/threejs-integration.md	将输出导入浏览器游戏、加载 GLB/FBX、根运动、动画接线
references/image-generator-workflows.md	配合 threejs-image-generator 生成概念图、纹理、UI 美术，或作为图像转 3D 的输入

API 密钥

脚本读取 --api-key 或 TRIPO_API_KEY。密钥不得放入技能文件、游戏代码或报告中。

python3 <this-skill-dir>/scripts/threejs_3d_asset.py probe   # TRIPO_API_KEY=SET|MISSING

仅在 shell 配置文件中定义的密钥可能不会出现在进程环境中。如果普通探测意外输出 MISSING，请使用 threejs-game-director/scripts/probe_asset_credentials.sh，它会加载配置文件并一次探测全部三个提供方。

下载 URL 会很快过期——任务成功后立即下载。

命令

python3 <this-skill-dir>/scripts/threejs_3d_asset.py --help

文本转 3D，适用于高品质主角模型，且为默认方式：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py text \
  --prompt "game-ready sci-fi hover bike, sleek armored panels, strong readable silhouette, layered hard-surface detail, PBR materials, clean topology, centered pivot, front facing, no text" \
  --model-version v3.1-20260211 --texture-quality detailed --geometry-quality detailed \
  --checkpoint artifacts/hover-bike-job.json \
  --wait --download --out-dir assets/models/hover-bike

根据生成的概念图进行图像转 3D：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py image \
  --image assets/concepts/hover-bike-front.png --model-version v3.1-20260211 \
  --enable-image-autofix --texture-alignment original_image --texture-quality detailed \
  --wait --download --out-dir assets/models/hover-bike

状态、下载和后处理（texture_model、animate_prerigcheck、animate_rig、animate_retarget、conversion、stylize_model）：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py status TASK_ID
python3 <this-skill-dir>/scripts/threejs_3d_asset.py download TASK_ID --out-dir assets/models
python3 <this-skill-dir>/scripts/threejs_3d_asset.py postprocess --type conversion \
  --original-task-id TASK_ID --format GLTF --face-limit 20000 --wait --download --out-dir assets/models/gltf

动画角色工作流：按身体类型路由生成、预绑定检查、带有限重试的验证绑定、动作重定向和下载。使用检查点，并在各阶段之间暂停检查，再投入后续工作：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py character-pipeline \
  --prompt "stylized cyber runner character, T-pose, full body, game-ready outfit, readable silhouette" \
  --animations preset:idle,preset:walk,preset:run,preset:jump \
  --checkpoint artifacts/cyber-runner-job.json --stop-after model \
  --out-dir assets/models/cyber-runner

# After inspecting the downloaded model/preview:
python3 <this-skill-dir>/scripts/threejs_3d_asset.py resume artifacts/cyber-runner-job.json --stop-after rig
# After inspecting the validated rig:
python3 <this-skill-dir>/scripts/threejs_3d_asset.py resume artifacts/cyber-runner-job.json --stop-after animations

python3 <this-skill-dir>/scripts/threejs_3d_asset.py character-pipeline \
  --prompt "stylized wolf, quadrupedal stance, all four legs planted and separated, full body" \
  --rig-type quadruped --animations preset:quadruped:walk \
  --checkpoint artifacts/wolf-job.json --stop-after model --out-dir assets/models/wolf

恢复与故障处理

--checkpoint PATH 是可选参数，可用于 text、image、postprocess 和 character-pipeline。它会立即记录已受理任务的 ID、阶段状态和已下载文件的指纹；检查点中不会写入 API 密钥或带签名的输出 URL。每个任务使用单独的检查点。已有检查点必须恢复使用，不得覆盖；并发使用会受到锁定。

运行后台单任务生成时，省略 --wait，保留输出的任务 ID/检查点，之后再运行 resume CHECKPOINT。单任务恢复只会等待/下载该任务，不会添加绑定。角色恢复会复用已完成的阶段，并继续处理动画，除非使用 --stop-after model|rig|animations 限制本次调用。凭据仍从当前环境读取。检查点记录的是本地绝对路径，因此请确保其引用的文件保持原位。

此辅助工具会使用有界退避策略重试安全的状态读取/下载操作，但绝不会重试需要付费的任务提交。缺少凭据、额度耗尽、输入无效、暂时性错误和提交状态不确定等情况会分别报告。若操作中断，请恢复现有任务，而不要从头开始。如果 POST 可能已成功，但未收到任务 ID，请在提供方的历史记录中查找该任务，并使用 resume CHECKPOINT --task-id RECOVERED_ID；不要编造 ID，也不要盲目提交替代任务。如果无法找回 ID，请先报告这种不确定性，再进行任何可能导致重复扣费的操作。

对于协调式游戏，请遵循 director 的 references/asset-recovery.md；生成进行期间，继续独立的实现工作。明确要求程序化生成或不使用外部服务时，应覆盖生成资产的默认做法。在项目备注中记录待处理任务和用户更正，保留已完成的资产，不要重复生成。

骨架绑定与动画

这些规则可以避免几乎所有代价高昂的失败。完整的参数表及其测量依据见 references/api-notes.md。

• 将角色生成为一个融合网格：保持 --quad 和 --generate-parts 关闭（generate_parts 会禁用纹理，quad 会强制输出 FBX）。
• 要求角色采用完整的 T 姿势或 A 姿势，双臂远离身体、姿势对称，且没有与轮廓融合的道具。绑定前检查渲染预览，确认姿势确实符合要求；否则重新生成。
• 首先运行 animate_prerigcheck（不需要模型版本，也不花费额度），并使用检测到的 rig_type。riggable=false 意味着应使用更清晰的姿势重新生成，而不是强行绑定。
• 绑定版本根据身体结构选择。 人形角色使用 v1.0-20240301——带有扭转骨骼和大型 preset:biped:* 库的解剖骨架。v2.x 肢体链绑定器在人形网格（无论是否穿甲）上的成功率为 0/16，生成的链条始终不对称。生物使用 v2.5-20260210。character-pipeline 会自动选择。
• riggable=true 不保证绑定可用。重定向前先验证骨架——validate-rig rig-model.glb --rig-type biped——检查骨骼是否齐全以及链条深度；一条腿只有 1 根骨骼就会导致每个动画片段都变形。缺少绑定 GLB 或其格式错误都属于失败，包括使用 --force-rig 时。自动绑定具有非确定性：失败时，在选定的预算范围内重试绑定任务（约 25 个额度），然后再重新生成模型。硬表面装甲角色通常需要最多次重试。
• animate_retarget 接受的是绑定任务 ID，不是生成任务 ID。非双足绑定每个任务最多可批量处理 5 个预设；批量返回的动画片段会按请求顺序命名为 NlaTrack、NlaTrack.001、……，因此应按索引进行映射，并在导入后重命名。
• 重定向 v1.0 绑定时使用 --model-version default——枚举不接受显式指定 v1.0-20240301，会返回 HTTP 400 错误代码 2017，但服务端默认值会正确处理。
• v1.0 重定向必须使用 --out-format fbx（脚本会强制执行）：Tripo 在此路径上的 GLB 烘焙会将扭转骨骼变换写入错误的坐标空间，导致肢体塌入躯干。v2.5 生物重定向使用 GLB 没问题。
• 切勿传入 --animate-in-place。 它会破坏烘焙结果：v1.0 会出现肢体镜像和交叉，v2.5 会出现蒙皮爆裂。应保留烘焙后的根运动，并在导入时将其移除；引擎代码片段见 references/threejs-integration.md。
• 每种生物各使用一个移动预设，且没有 preset:attack（使用 preset:slash 或 preset:shoot）。生物网格的姿势会影响预设的呈现效果——四足行走动画用在直立的龙身上，看起来就像人在走路，因此生成生物时应采用动画预设所需的姿势。
• 多模式生物（例如既会爬行又会飞行的龙）需要对同一模型绑定两次：移动时使用地面绑定类型，翼链则使用 avian。
• 如果要重定向 Tripo 预设，请使用 --spec tripo（默认值）；--spec mixamo 绑定无法通过 Tripo 重定向，只能用于外部流程。
• 下载后，运行 validate-animation clip.glb（检查缩放轨道、导致肢体拉伸的平移、极端旋转、每个动画片段的时长和通道覆盖情况），然后在连接 AnimationMixer 前检查 gltf.animations 的名称和数量。

质量

改进用户的提示词，补充材质、轮廓、镜头可读性、比例和游戏用途方面的约束。要求生成 GLB/PBR，并根据性能预算限制面数和匹配纹理质量；对于移动端，优先使用 smart_low_poly、face_limit 或后续低多边形后处理。将生成的 3D 内容用作核心内容，并通过程序化方式构建周围的道具套件。

集成后，取消暂停并检查游戏内的运动：片段过渡、变形、根运动、脚底滑动以及攻击／接触时机。动画任务需进行 QA 运动检查；下载成功或骨架检查通过，都不能证明动画质量良好。

报告任务 ID、检查点／输出路径、模型版本、纹理和几何设置、动画、转换设置、Three.js 导入说明、导入前后的渲染器诊断信息、游戏运行截图、观察到的运动，以及任何失败情况。将详细证据放入项目产物中，供负责人汇总报告。