载具开发疑难排查
中文 | English
在仓库根目录运行以下命令,用本机 Unity MCP 回放本页示例。 命令也会重拍两种语言的配图。
python Docs/Manual/manual/tools/tutorials.py run vehicle-dev-qa --capture
点击展开 MCP 操作点击收起 MCP 操作
准备教学样例。${变量} 由配方提供。
{
"variables": {
"asset": "${fixture}/Tutorial_VehicleQA.asset"
},
"calls": [
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateFolder",
"args": [
"${fixtureParent}",
"${folder}"
]
},
"expect": {
"contains": "(String)"
}
}
]
}
载具无法加载
检查 模组安装 的目录和目标平台。在 运行日志 查第一条报错,确认模组包关联了正确的构建管线。载具能加载但行为异常时,先对照 VehicleTextData 检查载具配置、伤害模型、履带、炮弹、发动机和开火音效引用。
旧工程曾遇到模组包与载具同名时加载错误。若载具内部名为 T-72,可把模组包改为 Vehicle-T-72 后重新构建,检查是否能加载。车辆已出现但无法进入时,在 VehicleData 依次打开主模型、伤害预制体、VehicleTextData 的移动和开火引用,和 SDK 中可运行的模板做对照。
炮管无法抬升或下压
普通炮管填写正值作为 仰角和俯角的幅度。例如 UpMaxDegree = 20、DownMaxDegree = 8 对应 -8° 到 20°。检查共享炮塔配置和按方向覆盖的限制。炮塔横向旋转的 maxTurretPositiveAngle 与 maxTurretNegativeAngle 是另一组字段。

点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CopyAsset",
"args": [
"Packages/com.shanghaiwindy.coreresources/Editor/DocumentationSamples/vehicle-text-data/Tutorial_VehicleTextData.asset",
"${asset}"
]
},
"expect": {
"contains": "(Boolean) True"
}
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${asset}/sharedTurretData",
"value": "null"
},
"expect": {
"contains": "OK:"
}
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${asset}/MTParameter/UpMaxDegree",
"value": "20"
},
"expect": {
"contains": "OK:"
}
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${asset}/MTParameter/DownMaxDegree",
"value": "8"
},
"expect": {
"contains": "OK:"
}
},
{
"tool": "inspect",
"arguments": {
"path": "asset:${asset}/GetTurretParam()/UpMaxDegree"
},
"expect": {
"contains": "(Single) 20"
}
},
{
"tool": "inspect",
"arguments": {
"path": "asset:${asset}/GetTurretParam()/DownMaxDegree"
},
"expect": {
"contains": "(Single) 8"
}
}
]
坦克行驶或悬挂异常
- 在 VehicleTextData → 移动核对整车质量,单位为 kg。旧图里的 T-72 是
44100 kg。用符合你模型的质量,检查有没有把吨数直接填进 kg 字段。 - 打开移动页引用的 WheelCollider 预制体。组件的 Mass 是车轮质量。旧图示例为
320 kg、Radius0.5、Wheel Damping Rate0.25和 Suspension Distance0.2。旧指南把轮质量不超过1000 kg作为调参建议。 - Suspension Spring 可先用当前模板的 Spring
205000、Damper14500、Target Position0.5,再按轮径和整车质量试车调整。轮组与摩擦配置
模型明暗或正反面异常
- 选中法线贴图,在导入 Inspector 把 Texture Type 设为 Normal Map 并点击 Apply,确认材质的法线槽使用这张贴图。
- 在 Blender 的视图叠加菜单开启 Face Orientation。对于封闭网格,选中外侧显示红色的面,在 Edit Mode 用 Mesh → Normals → Recalculate Outside 或翻转选中的法线。对有意做成双面的网格,核对它的材质。其他不可见部件按 模型显示排查 检查。
副炮切换时出现数组越界
从日志确认报错指向炮弹数据,再逐个打开副炮实际使用的 bulletData。检查每个列表至少有一发有效炮弹,并确认当前选中索引小于列表长度。对照 载具开发笔记 和模板载具。