星火 2.0 开发文档

主题

从新项目到可播放官方动作的人形模型 ​

适用于外部 agent：用户已有 TapTap Maker 使用资格，并希望生成自定义人形、导入星火项目、调整尺寸朝向，再使用星火官方动作。最后交付能在项目资源库预览并播放动作的星火 JSON prefab。

连接当前项目与两套 MCP ​

先打开用户的新建星火项目，等待 SDK 与项目加载完成。Maker 是资产生成服务，Editor MCP 是星火资源导入与重定向服务，两者不能互相代替。

通过当前工具列表确认 Maker 的 create_3d_asset，以及完整编辑器的 editor_get_context、resource_import_model_package、resource_get_preview_info、resource_get_skeleton、resource_retarget_animations、resource_open_preview、resource_reload、editor_reload_project。缺少新工具时更新编辑器并重连；独立 TriggerMcpHost 不能替代完整编辑器。

若 AI 客户端未直接暴露 Editor MCP，可从项目根调用随项目生成的脚本：

pwsh -File ai/tools/Invoke-SceEditorMcp.ps1 -Context -Pretty
pwsh -File ai/tools/Invoke-SceEditorMcp.ps1 -ListTools -ToolPrefix resource_ -Pretty
pwsh -File ai/tools/Invoke-SceEditorMcp.ps1 -RequestJsonPath ai/model-import-request.json -Pretty

请求文件使用单次调用格式 {"tool":"resource_import_model_package","arguments":{...}}。没有 pwsh 时使用 Windows PowerShell。确认 context.ready=true 且 project.path 是用户目标项目，不硬编码示例或其它项目。

Maker 使用已绑定的专用资产工作目录，并明确传 target_dir。星火项目新建不代表已有 Maker 绑定；需要时按本 Skill 的官方 init/login 流程处理，不把 token 粘贴到项目或聊天中，也不默认另建 Maker 应用。

生成人形并完成绑骨 ​

要求一个独立人形，明确中立 A-pose、完整四肢、手脚分离，不把武器、坐骑和背景一起生成人形。需要武器时单独准备后再适配挂点。

在实际 create_3d_asset schema 上发起 start，payload 使用 generation_strategy=reviewed、subject_type=biped、合适的 quality_tier 与具体 prompt。按返回的 asset_id、step_id 和轮询间隔完成 query；reviewed 返回预览时展示全部预览，获得明确确认后才 continue。用户已明确选择直接生成可丢弃测试模型时，按该授权与实时 schema 使用 direct。

当前 create_3d_asset 的模型生成与绑骨是两步。生成完成后，用户的人形动画要求已经授权绑骨时，不必再次询问是否需要运动，继续调用：

{
  "action": "post_process",
  "asset_id": "返回的同一个资产 ID",
  "target_dir": "已绑定的资产工作目录",
  "payload": { "operation": "rig", "options": { "rig_type": "biped" } }
}

query 等待 rig 成功并由本地代理交付最终 MDL 包。记录最终 local_delivery 路径与实际文件；同一目录可能同时保留静态和带骨 prefab，读取 XML 选择 AnimatedModel 对应的入口，不能选回旧静态版本。当前工具未开放骨骼动作生成，rig 不代表已有动作；后续使用官方动作重定向。

导入与尺寸、朝向 ​

用 resource_import_model_package 将完整目录或 ZIP 导入新的 res/characters/<name> 目录，指定最终 rigged entryPoint。使用 animations={} 仅导入骨骼，不把其它骨架的官方 ANI 混入源包。先 dryRun=true，再按已有授权执行 dryRun=false，检查 boneCount>0、skeletalMeshCount、validation 和 dependenciesReady。

Maker XML prefab 不能直接当星火 JSON prefab 使用，UUID 由导入器解析，材质由导入器适配。保留原始生成包。不要要求用户寻找 FBX，也不要把项目资源放入 user_files。

根据实际尺寸选择 sourceUpAxis、scale 或 targetWidth，并按用途设置 alignGround；星火 XY 为水平面、Z 为高度。不要把固定 256 倍或固定 X+90 度当成所有 Maker 模型的规则。

若源轴向和大小已有明确元数据，可直接在导入 dryRun 中设置；若不明确，先导入唯一的探查目录，使用 resource_get_preview_info 与 resource_get_skeleton 读取网格尺寸和人体髋到头的方向，再将同一源包以正确参数导入另一个正式目录。工具不会覆盖探查目录。Y 向上转为 Z 向上是 sourceUpAxis=y 的用途；其它朝向需根据实际骨架及预览判断。

为指定人体高度计算等比 scale 时，以选定源向上轴的模型高度计算，并通过实际骨骼预览复核；targetWidth 指 X 宽度，不是人物高度。重定向会保留目标 prefab 外层的方向、缩放与贴地变换，动作内部还需下一步的模型空间对齐。

选择官方动作、映射与空间对齐 ​

Maker 模型的默认入口是本节的显式骨架检查和重定向流程，不是直接填写 GameDataModel.HumanoidSourceAnimations。HumanoidSourceAnimations 只能把动画加入普通烘焙清单，不能从 MDL 自动推出可靠的骨骼语义映射、动作参考模型或模型空间对齐。除非导入资源已有经过验证的 rig 配置，并且与所选动作家族确认同骨架同空间，否则不要把该字段当作首次适配方案。

从项目 docs/resources/animations.json 或资源库搜索选择动作。先用 resource_get_preview_info 确认源动作可加载，再选择该动作的实际参考 MDL。下面是标准人形大剑的已验证示例，不能推广成所有官方动作的默认参考模型：

  • 源模型：characters0/human/body/model/m.mdl。
  • 待机：anim/human/sword_anim/DaJianZhanShi/idle.ani。
  • 攻击示例：anim/human/sword_anim/DaJianZhanShi/skill_01.ani、skill_02.ani。

从目标 prefab 的预览获取它引用的 MDL，分别 resource_get_skeleton 读取两套骨架。建立完整的主骨骼对应 boneMap：源骨名为键，目标骨名为值；不要仅改名或强行套用官方骨骼。检查髋、骨盆、脊柱、头、两侧肩臂腕和腿脚的层级与对应。

alignmentBones 也使用已经映射的源骨名。上例可选择：

{
  "upStart": "Bip001 Pelvis",
  "upEnd": "Bip001 Head",
  "rightStart": "Bip001 L UpperArm",
  "rightEnd": "Bip001 R UpperArm"
}

这些骨名只有在本次两套骨架和 boneMap 中实际存在时才可使用。工具以真实参考方向和距离计算 sourceToTargetRotation 与 sourceUnitScale，不能用 Maker 来源或 MDL 文件名猜固定旋转。普通同骨架同空间应得到单位旋转、比例 1。

调用 resource_retarget_animations：targetPrefab 是刚导入的项目 prefab，sourceModel 是动作参考模型，boneMap 和 alignmentBones 已补齐；animations 为 {source,name} 数组，将待机映射到 idle、动作映射到 attack 等用途名；destination 使用新的 res/characters/<name>_animated 目录。先 dryRun=true，检查源/目标骨数、未映射目标骨骼、绑定姿势误差与实际生成的动作摘要，再 dryRun=false。

生成前的绑定姿势检查只是一项必要条件，不等于所有运动姿势正确。若人体方向、轴向或尺寸不对，修正上一步导入参数；若动作扭曲，检查映射、alignmentBones 和实际参考姿势，不以增加 scale 或修改 prefab 朝向掩盖动作内部问题。

输出保留原模型，生成新 prefab、目标骨名 ANI 与映射配置；新 prefab 继续引用原项目目录中的材质和贴图，需保留原目录。继续增加跨模型空间的官方动作也使用此 MCP 流程，不假定传统直接添加动作的界面会执行相同空间对齐。

实际验收与交付 ​

resource_get_preview_info 的所有动作应匹配目标轨道且 dependenciesReady=true。resource_open_preview 打开新 prefab 后，在美术资源库「项目资源」选中模型，选择「骨骼模型(组件) → 动画」。核对待机、至少一个攻击的肩肘腕、躯干、腿脚、实际大小和朝向；必要时与原始官方动作对照。若 GPU 画面无法由 agent 获取，请说明尚未验证的画面项目，并让用户实际观察，不将数据 success=true 当成画面通过。

确认项目无未保存修改后用 editor_reload_project 重载，等待生命周期成功，再复查骨骼、动作列表和预览。源包、导入目录与带动画的最终 prefab 都应可追溯。交付最终 prefab 的项目相对路径和资源库位置，区分它与旧静态 prefab、探查版本及未修正的测试版本。

这里仅改资源时不需要 GameEntry 双端编译。用于单位或玩法时，再按所选框架接入 GameDataModel/Actor 并完成必要双端验证。模型自带的骨骼不足以做手指开合，握剑接触仍需实际武器挂点与动作适配。

完成显式重定向后，如果项目的资源统计需要看到这些生成的动画，可以将项目拥有的目标动画列入 HumanoidSourceAnimations；这一步是资源声明，不会重新替代或隐式完成骨骼适配。

项目 res 已随客户端包封装，不需要资源统计或 objref.txt。详细参数可读目标项目 docs/sdk/guides/ProjectModelImport.md，或 src/WasiCoreSDK.props 指向 SDK 的 docs/guides/ProjectModelImport.md；项目-local Skill 镜像不能假定拥有 SDK 原目录的跨目录相对链接。