载具自定义着色器数据
中文 | English
在仓库根目录运行以下命令,用本机 Unity MCP 回放本页示例。 命令也会重拍两种语言的配图。
python Docs/Manual/manual/tools/tutorials.py run custom-shader-data --capture
点击展开 MCP 操作点击收起 MCP 操作
准备教学样例。${变量} 由配方提供。
{
"variables": {
"package": "${fixture}/Docs_${runId}_Package.asset",
"pipeline": "${fixture}/Docs_${runId}_Pipeline.asset",
"shaderData": "${fixture}/Tutorial_CustomShader.asset",
"packageGuid": "4ccfd3f8-eabc-44d6-b599-82486dbd4604"
},
"calls": [
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateFolder",
"args": [
"${fixtureParent}",
"${folder}"
]
},
"expect": {
"contains": "(String)"
}
},
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateAsset",
"args": [
"@static:UnityEngine.ScriptableObject/CreateInstance(ShanghaiWindy.Core.ModPackageData)",
"${package}"
]
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateAsset",
"args": [
"@static:UnityEngine.ScriptableObject/CreateInstance(ShanghaiWindy.Core.ModPackageBuildPiplineData)",
"${pipeline}"
]
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${package}/localizedModName/defaultName",
"value": "Tutorial Package"
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${package}/localizedDescription/defaultName",
"value": "Documentation teaching package"
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${package}/author",
"value": "Documentation"
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${package}/supportURL",
"value": "https://doc.game.windyverse.net/"
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${package}/guid",
"value": "${packageGuid}"
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "inspect_set",
"arguments": {
"path": "asset:${pipeline}/linkedModPackage",
"value": "@asset:${package}"
},
"expect": {
"contains": "OK:"
},
"phase": "build"
}
]
}
当载具需要内置着色器类型无法提供的 Shader 与材质时,使用本教程。CustomShaderData 保存自定义材质与通道名称映射,CoreRPMatComponent 则在运行时按渲染器的材质槽选择它。
自定义着色器本身是一个独立的 Unity 着色器工程。如果还不熟悉 Unity 材质、Shader Graph 或 URP/HDRP 基础,请先阅读相关教程;本页只说明如何把材质接入载具。
1. 准备材质
- 在目标渲染管线(URP 或 HDRP)中制作并测试你的 Shader Graph / Shader,不要在另一条管线上验证后直接套用。
- 每条管线各创建一个使用该 Shader 的材质。URP 材质与 HDRP 材质是两个独立资产,且各自需要匹配的管线环境;为 HDRP 打包的材质不能用于 URP。
- 车辆原始贴图(漫反射、法线、Mask)和基础色不要写死在自定义材质里。游戏会在运行时按你配置的通道名写回这些数据,因此 Shader 必须暴露对应名称。
2. 创建 Custom Shader Data
在 Project 窗口选择 Create > A Panzer War - 装甲纷争 > C Config - 配置 > Custom Material - 自定义材质,创建 CustomShaderData 资产。
打开该资产后,其 Inspector(CustomShaderDataEditor)会自动生成 guid,并提供:
- 复制唯一标识 - Copy Guid:把生成的
guid复制到剪贴板。稍后在组件中粘贴的就是这个标识。 - 创建新的唯一标识 - Create new guid:清空 guid 并重新生成。旧 guid 的所有引用都会失效,因此只应在还没有载具或其他模组引用它之前使用。
在 Custom Material(overrideMaterialPath)中从材质下拉列表选择你测试过的材质。运行时会把该材质的属性复制到载具材质上。
Default 与 Custom Vehicle Option 的区别
customShaderType 有两种取值:
- 默认 - Default(
Default)显示overrideMaterialPath和customKeywords。加载器仍可按默认通道名称回填载具贴图与颜色。 - 自定义载具选项 - Custom Vehicle Option(
VehicleOption):额外显示游戏写回载具自身贴图与颜色时使用的通道名:
| 字段 | 含义 | 默认值 |
|---|---|---|
customMainTexName |
写入载具漫反射贴图的通道 | _BaseMap |
customNormalTexName |
写入载具法线贴图的通道 | _BumpMap |
customMaskTexName |
写入载具 Mask 贴图的通道 | _MaskMap |
customBaseColor |
写入载具基础色的通道 | _BaseColor |
只有当你的 Shader 使用不同属性名时才需要修改。名称必须与 Shader 完全一致,包括大小写。
3. 配置 CoreRPMatComponent

- 给拥有目标
MeshRenderer的对象添加 CoreRPMatComponent。 - 勾选 基于组件数据 - Component Based(
isComponentBased)。 - 在
indexCoreRPMatParams中为每个要覆盖的材质槽添加一项。index是该 Mesh Renderer 上的材质槽序号,从 0 开始。 - 每一项的 Shader(
coreRPShaderType)选择Custom,此时会显示customNatParam。 - 填写
customNatParam:urpMaterialGuid:目标为 URP 的 CustomShaderData 的guid。hdrpMaterialGuid:目标为 HDRP 的 CustomShaderData 的guid。- 两个 GUID 必须不同,且各自指向对应管线构建的材质数据。不要把 URP 的 GUID 填进
hdrpMaterialGuid。
GUID 在载具资源加载时解析。GUID 为空时使用该渲染器的默认着色器。非空 GUID 解析失败或材质 Bundle 缺失时,加载器会记录回退。需要自定义外观的每条管线都应填入有效且匹配的数据。
customNatParam 还支持按槽位写入通道:
customTextureChannels:channelName加channelTex,直接写入材质。customColorChannel:channelName加普通颜色;勾选isHDR时可填写 HDR 颜色。
这些适合逐载具的差异(标识、灯具颜色、徽章),无需为每辆车单独制作共享材质。
4. 打包
- 单个载具:把 CustomShaderData 与该载具的
VehicleInfo及其他载具资源放在同一个模组包中一起构建。 - 跨载具或跨模组共享:把 CustomShaderData(及其材质)作为独立模组包构建,并在载具模组中按其包 GUID 显式声明依赖。不要依赖加载顺序,也不要假定资产存在于其他包中就能生效。
发布后的 guid 属于运行时契约。用新 GUID 重建共享着色器模组会静默破坏所有依赖方,因此发布后应把 GUID 视为稳定值。
5. 运行时行为
当渲染器某槽位解析为 Custom 时,着色器资产管理器会:
- 通过对应管线的 GUID(
urpMaterialGuid或hdrpMaterialGuid)解析 CustomShaderData。 - 加载自定义材质,把其 Shader 赋给载具材质,并复制其属性(包括勾选项和下拉框的值)。
- 写回载具自身数据:漫反射、法线和 Mask 贴图以及基础色分别写入
customMainTexName、customNormalTexName、customMaskTexName、customBaseColor。 - 按
customKeywords的isTextureChannelCondition条件(即引用的贴图通道已赋值)启用对应关键词,并写入按槽位的贴图与颜色通道。
属性复制发生在写回载具数据之前,因此自定义材质在这四个映射通道上设置的内容会被载具自身贴图与颜色覆盖。需要保留的值请使用其他属性名。
并非所有属性都一定保留:复制是按名称通用进行的,而载具贴图与基础色是显式写回的。请在真实游戏构建中核对你依赖的属性。
6. 可选的通道约定
载具涂装与污渍系统使用一组约定名称。它们是可选的:只有你的 Shader 实现了对应行为时才需要使用。这些是 Shader 侧约定,不是加载器保证填充的属性。
| 通道名称 | 类型 | 约定用途 |
|---|---|---|
_Smoothness |
float | 光滑度 |
_CamoPatternMap |
Texture2D | 涂装样式图 |
_CamoPatternTiling |
Vector4 | 样式图的缩放比 |
_CamoBlackTint |
Color | 样式图黑色通道对应的颜色 |
_CamoRedTint |
Color | 样式图红色通道对应的颜色 |
_CamoGreenTint |
Color | 样式图绿色通道对应的颜色 |
_CamoBlueTint |
Color | 样式图蓝色通道对应的颜色 |
_Lerp |
float(0-1) | 涂装颜色占比 |
_DirtTex |
Texture2D | 污渍贴图 |
_DirtRange |
float(0-1) | 污渍占比 |
_KEYWORD_ENABLE_CAMO |
keyword | 是否启用涂装(当前由 VehicleCamoManager 使用) |
_KEYWORD_ENABLE_CAMO_COLOR_TEX |
keyword | 是否启用贴图涂装 |
_KEYWORDENABLEDIRT |
keyword | 是否启用污渍贴图 |
说明:
_KEYWORD_ENABLE_CAMO与_KEYWORD_ENABLE_CAMO_COLOR_TEX是当前VehicleCamoManager驱动的关键词。旧着色器里可能见到的_EnableCamo/_EnableCamoColorTex属性名并不是同一套东西。_KEYWORDENABLEDIRT是污渍关键词名。下面的混合逻辑是旧版示例着色器的做法,用来演示通道可以如何组合,并非加载器强制规则。不处理污渍通道的自定义 Shader 只是没有污渍效果。
旧版示例的污渍行为:启用 _KEYWORDENABLEDIRT 时,载具 AO 贴图会按 _DirtRange 指定的强度与 _DirtTex 混合。若想要该效果,请在 Shader Graph 中自行实现。
7. RGBA 样式图与 tint 技法
示例着色器使用的涂装技法:把 _CamoPatternMap 视为四个独立遮罩,拆分 RGBA 通道,用各通道作为遮罩把对应 tint 颜色(_CamoBlackTint、_CamoRedTint、_CamoGreenTint、_CamoBlueTint)lerp 进基础色,最后按 _Lerp(限制在 0-1)把整体结果与基础色混合。用 _KEYWORD_ENABLE_CAMO / _KEYWORD_ENABLE_CAMO_COLOR_TEX 控制该分支,使没有涂装的载具保持原有外观。
同一思路适用于任意逐载具数据:一张遮罩贴图加若干 tint 颜色即可实现标识、喷绘或磨损样式,无需为每辆车单独提供材质。
8. Shader 编写注意事项
- 资产 Inspector 建议关键词使用
multi_compile。若使用shader_feature,请配合 Shader Variants 构建,避免变体被裁剪导致关键词在玩家构建中静默失效。 - 在 Shader 中声明所有由
customKeywords切换的关键词,并保持关键词字符串与资产字段完全一致。 - 避免只在编辑器存在的
shader_feature变体;要检查玩家构建,而不只是在 Play Mode 中观察。
9. 在目标渲染器中验证
- 在 URP 工程中打开载具确认自定义外观,然后在 HDRP 工程中用 HDRP 的 GUID 与材质重复检查。两条管线必须分别验证。
- 临时修改基础色或替换贴图,确认载具自身的漫反射、法线、Mask 与基础色确实写入了目标通道。
- 切换涂装或污渍选项,确认关键词在构建中真正改变效果,而不仅是在编辑器中。
- 加载另一辆共用同一着色器模组的载具,确认共享包依赖可以解析。
- 检查日志中是否存在 GUID 无法解析或材质 Bundle 缺失的错误;这类错误通常意味着 GUID 错误、管线不匹配,或包未包含该资产。
MCP 示例用教学材质和数据资产构建 Windows 模组包。实际渲染效果按上述步骤在目标管线中检查。
点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"local sample=assert(loadfile(\"../../Docs/Manual/tutorials/custom-shader-data/example.lua\"))()\nreturn sample(\"${fixture}\")",
"docs-custom-shader-data",
"null"
]
},
"expect": {
"contains": "Vehicle Option and material channel bindings verified"
}
},
{
"tool": "invoke",
"arguments": {
"path": "asset:${pipeline}/linkedObjects/Add",
"args": [
"@asset:${shaderData}"
]
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.EditorUtility/SetDirty",
"args": [
"@asset:${pipeline}"
]
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/SaveAssetIfDirty",
"args": [
"@asset:${pipeline}"
]
},
"expect": {
"contains": "OK:"
},
"phase": "build"
},
{
"tool": "modpack_plan",
"arguments": {
"pipeline": "${pipeline}"
},
"expect": {
"equals": {
"ok": true,
"built": false
},
"contains": "csd"
},
"phase": "build"
},
{
"tool": "modpack_build",
"arguments": {
"pipeline": "${pipeline}"
},
"expect": {
"equals": {
"ok": true,
"archiveExists": true,
"published": false,
"installed": false
}
},
"capture": {
"archivePath": {
"path": "archivePath"
}
},
"phase": "build"
},
{
"tool": "invoke",
"arguments": {
"path": "static:Frontend.Editor.ModPackageWorkshopMeta/WriteSidecar",
"args": [
"${archivePath}"
]
},
"expect": {
"contains": ".modpack.json"
},
"phase": "build"
}
]