API控制三维场景

约 8764 字大约 29 分钟

2025-12-08

一、可视化API场景控制调试

说明

api 地址： http://onetwin.cn/api/v1/socket/pushMessage
post 请求

注意

⚠️ 1. 必须是已发布或者保存待发布的看板ID
⚠️ 2. 使用了【数字孪生threeD】组件
⚠️ 3.【数字孪生threeD】组件内开启了【远程遥控】模式

可视化界面调试

二、API场景控制

1.控制模型移动

说明

kanbanId：看板唯一标识，用于路由到指定场景。
message.type：固定为 "modelMove"，表示模型移动指令。
payload.groupArray：要控制的模型组名称列表（如 ["坦克"]）。
payload.customPath：路径点数组，每个点包含位置、旋转、缩放等。
payload.loop：是否循环执行路径（仅 fullPath 模式有效）。
payload.cameraFollowing：是否启用相机跟随。
payload.css2DFollow：CSS2D 标签跟随配置，follow 开关，nameList 是标签类名或 ID 列表。
rotationAtOnce / scaleAtOnce：是否立即应用旋转/缩放（不插值）。
cameraOffset：相机相对于模型的偏移量（x, y, z）。

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "modelMove",
    "payload": {
      "groupArray": [
        {
          "name": "坦克"
        }
      ],
      "customPath": [
        {
          "position": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "rotation": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "scale": {
            "x": 1,
            "y": 1,
            "z": 1
          },
          "animationTime": 2000,
          "rotationAtOnce": true,
          "scaleAtOnce": true
        }
      ],
      "loop": false,
      "animationTime": 2000,
      "cameraFollowing": false,
      "css2DFollow": {
        "follow": false,
        "nameList": [
          "坦克"
        ]
      }
    }
  }
}

2.控制按钮组切换

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "tabsBtnChange",
          payload: {
            tabName: "流动线条轨迹2"
          }
        }
      }

3.控制单按钮点击

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "bottonClick",
          payload: {
            bottonName: "坦克巡逻"
          }
        }
      }

4.控制CSS2D点击

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "css2dClick",
          payload: {
            css2dName: "标注示例"
          }
        }
      }

5.控制CSS2D关闭

{
        kanbanId: "6878e76c6f55c70fa8c15482",
        message: {
          type: "css2dClose",
          payload: {
            css2dName: "标注示例"
          }
        }
      }

6.控制相机切换

说明

type: 固定为 "camera"
payload.camera.changeCameraPosition: 相机目标位置 (x, y, z)
payload.camera.changeCameraLookAt: 相机观察点 (x, y, z)

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "camera",
    "payload": {
      "camera": {
        "changeCameraPosition": { "x": -80, "y": 60, "z": 48 },
        "changeCameraLookAt": { "x": 0, "y": 0, "z": 0 }
      }
    }
  }
}

7.控制相机重置

说明

type: 固定为 "restoreCamera"
将相机恢复到初始位置和角度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "restoreCamera",
    "payload": {}
  }
}

8.控制动画播放/停止

说明

type: 固定为 "playAnimation"
payload.animation.loop: 循环模式（"LoopRepeat" | "LoopOnce" | "LoopPingPong"）
payload.animation.timeScale: 时间缩放（0.1 ~ 5.0，默认 1.0）
payload.animation.weight: 权重（0 ~ 1，默认 1.0）
payload.animation.play: 要播放的动画名称数组
payload.animation.stop: 要停止的动画名称数组

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "playAnimation",
    "payload": {
      "animation": {
        "loop": "LoopRepeat",
        "timeScale": 1,
        "weight": 1,
        "play": ["风电发电_旋转.001"],
        "stop": []
      }
    }
  }
}

三、API着色器效果控制

说明

着色器用于在场景中叠加动态视觉特效，如火焰、水面、雷达扫描等。所有着色器指令通过以下三种类型触发：

createShader: 创建着色器效果
updateShader: 更新现有着色器参数
removeShader: 删除着色器效果

🎯 关于位置设置：两种模式详解

在使用着色器时，您可选择以下两种方式确定效果位置

✅ 模式一：绑定模型名称（推荐）

勾选 "使用模型名称" 开关
输入有效的模型名称（groupName），如 "车间1"、"Tank_01"。
系统将自动计算该模型的视觉中心（包围盒中心）作为着色器位置：
优势：无需手动输入坐标，避免因模型移动或缩放导致位置错误。
适用场景：火焰、雷达等需要附着在具体模型上的效果

✍️ 模式二：手动输入位置

关闭 "使用模型名称" 开关
手动填写 position.x/y/z（单位：米）。
风险：若坐标错误，效果可能出现在空中、地下或远离目标区域。
适用场景：海面、大型围墙等覆盖固定地理区域的效果。

注意

💡 最佳实践：优先使用模型名称绑定，确保效果始终贴合目标对象。

1.触发火焰着色器（模拟火灾）效果

说明

shaderName: 固定为 "fire"。
key: 必填，用于唯一标识该火焰实例（关闭时需相同 key）。
position: 火焰中心的世界坐标（单位：米）。
✅ 强烈建议使用模型名称绑定（见上文）自动获取视觉中心位置，避免手动输入错误。
globalScale: 火焰整体缩放（默认 10.0，范围 0.1 ~ 50）。
options: 当前版本暂无自定义参数，保留空对象 {}。
若同时传入 groupName，系统会自动将 position 覆盖为该模型的包围盒视觉中心（即 Box3().- getCenter()），此时 position 字段仅作偏移参考（当前未启用偏移，实际以模型中心为准）。

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "fire",
      "shaderOptions": {
        "key": "fire_001",
        "position": { "x": -127.184, "y": 18.624, "z": 206.200 },
        "globalScale": 10.0,
        "options": {}
      }
    }
  }
}

2.触发海面着色器（水面效果）

说明

shaderName: 固定为 "sea"。
key: 必填，用于后续关闭或更新。
globalScale: 对海面整体缩放（通常保持 1.0）。
options 参数详解：
width / height: 水面平面尺寸（单位：米，默认 5000×5000）。
waterColor: 水体颜色（支持 HEX 或 RGBA 字符串）。
yPosition: 水面在 Y 轴的高度（例如地面为 0，则水面设为 10 表示高于地面 10 米）。
xPosition / zPosition: 水面中心在 X/Z 轴的偏移（默认居中于场景原点）。
⚠️ 海面不支持 groupName 绑定（因其覆盖大面积区域，通常独立存在）。

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "sea",
      "shaderOptions": {
        "key": "ocean_main",
        "globalScale": 1.0,
        "options": {
          "width": 5000,
          "height": 5000,
          "waterColor": "#4AA0C5",
          "distortionScale": 3.7,
          "yPosition": 10,
          "xPosition": 0,
          "zPosition": 0
        }
      }
    }
  }
}

3.触发围墙着色器（动态光墙/围栏）

说明

shaderName: 固定为 "wall"。
key: 必填。
globalScale: 通常保持 1.0。
options 参数详解：
width / length / height: 围墙尺寸（宽 × 长 × 高，单位：米）。
position: 围墙中心的世界坐标（X/Y/Z）。
baseColor: 围墙主色（HEX 格式）。
amplitude: 波纹振幅（0.1 ~ 5）。
frequency: 波纹密度（1 ~ 20）。
speed: 动画速度（10 ~ 200）。

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "wall",
      "shaderOptions": {
        "key": "perimeter_wall",
        "globalScale": 1.0,
        "options": {
          "width": 20,
          "length": 40,
          "height": 4,
          "baseColor": "#00ff80",
          "amplitude": 1.0,
          "frequency": 10.0,
          "speed": 130.0,
          "position": { "x": 0, "y": 0, "z": 0 }
        }
      }
    }
  }
}

4.触发雷达扫描着色器（圆形扫描光效）

说明

shaderName: 固定为 "radar"。
key: 必填。
position: 扫描中心点（世界坐标）。
globalScale: 扫描半径缩放（默认 10.0，值越大范围越广）。
options.color: 扫描光颜色（HEX 格式）。
✅ 支持 groupName 绑定：若提供 groupName，系统将自动使用该模型的视觉中心作为position，忽略手动传入的位置值。

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "radar",
      "shaderOptions": {
        "key": "radar_01",
        "position": { "x": -127.184, "y": 18.624, "z": 206.200 },
        "globalScale": 10.0,
        "options": {
          "color": "#BCF2FE"
        }
      }
    }
  }
}

5.更新任意着色器效果

说明

type: 固定为 "updateShader"
必须提供与创建时完全相同的 key
可以更新任何参数（position、globalScale、options 等）
系统会销毁旧实例并用新配置重新创建

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "updateShader",
    "payload": {
      "shaderName": "fire",
      "shaderOptions": {
        "key": "fire_001",
        "position": { "x": -130, "y": 20, "z": 210 },
        "globalScale": 15.0,
        "options": {}
      }
    }
  }
}

6.关闭任意着色器效果

说明

type: 固定为 "removeShader"
必须提供与创建时完全相同的 key

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "removeShader",
    "payload": {
      "shaderName": "fire",
      "shaderOptions": {
        "key": "fire_001"
      }
    }
  }
}

7.抛物线飞向着色器（数据传输效果）

说明

shaderName: 固定为 "parabolaFlight"
key: 必填
startPoint: 起点坐标 (x, y, z)
endPoint: 终点坐标 (x, y, z)
options.color: 轨迹颜色（HEX 格式）
options.glowColor: 高光颜色
options.speed: 飞行速度（0.1 ~ 5.0）
options.interval: 飞行间隔（秒，0 ~ 5）
options.trailLength: 拖尾长度（0.1 ~ 1.0）
options.intensity: 发光强度（0.5 ~ 10）
options.opacity: 透明度（0 ~ 1）
options.arrowSize: 箭头大小（1 ~ 20）
options.arcHeight: 抛物线高度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "parabolaFlight",
      "shaderOptions": {
        "key": "data_flow_01",
        "startPoint": { "x": 0, "y": 0, "z": 0 },
        "endPoint": { "x": 100, "y": 0, "z": 100 },
        "options": {
          "color": "#00ffff",
          "glowColor": "#ffffff",
          "speed": 1.0,
          "interval": 0.5,
          "trailLength": 0.3,
          "intensity": 3.0,
          "opacity": 0.9,
          "arrowSize": 8,
          "arcHeight": 30
        }
      }
    }
  }
}

8.城市扫描光着色器（建筑/地面扫描）

说明

shaderName: 固定为 "cityScanLight"
key: 必填
position: 扫描中心点
options.scanMode: 扫描模式（"ground" 地面模式 | "building" 建筑模式）
options.scanDirection: 扫描方向（"vertical" 从下往上 | "radial" 从中心往外）
options.maxRadius: 最大扫描半径
options.scanHeight: 扫描高度
options.scanSpeed: 扫描速度
options.interval: 扫描间隔（秒）
options.scanWidth: 扫描宽度
options.trailLength: 拖尾长度
options.scanColor: 扫描颜色
options.glowColor: 发光颜色
options.intensity: 发光强度
options.opacity: 透明度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "cityScanLight",
      "shaderOptions": {
        "key": "scan_building",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "scanMode": "building",
          "scanDirection": "vertical",
          "maxRadius": 200,
          "scanHeight": 300,
          "scanSpeed": 0.5,
          "interval": 0,
          "scanWidth": 0.12,
          "trailLength": 0.5,
          "scanColor": "#00ffff",
          "glowColor": "#28af65",
          "intensity": 1,
          "opacity": 0.8
        }
      }
    }
  }
}

9.管道流动着色器（材质流动效果）

说明

shaderName: 固定为 "pipe"
key: 必填
options.groupName: 必填，模型名称（如 "管道A"）
options.baseColor: 基础颜色
options.flowColor: 流动颜色
options.speed: 流动速度
options.repeat: 重复频率
options.spiral: 螺旋程度
options.glow: 发光强度
options.direction: 流动方向（1 正向 | -1 反向）
options.style: 样式（0 | 1 | 2）
options.isOverlay: 是否材质叠加（true | false）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "pipe",
      "shaderOptions": {
        "key": "pipe_flow_01",
        "options": {
          "groupName": "主管道",
          "baseColor": "#002222",
          "flowColor": "#00ffff",
          "speed": 3.0,
          "repeat": 5.0,
          "spiral": 2.0,
          "glow": 2.0,
          "direction": 1,
          "style": 0,
          "isOverlay": true
        }
      }
    }
  }
}

10.雨滴着色器（下雨效果）

说明

shaderName: 固定为 "rain"
key: 必填
position: 雨滴区域中心
globalScale: 整体缩放
options.count: 雨滴数量（默认 50000）
options.size: 雨滴大小
options.speed: 下落速度
options.areaWidth/areaHeight/areaDepth: 降雨区域尺寸
options.color: 雨滴颜色
options.opacity: 透明度
options.windEffect: 是否启用风效
options.windStrength: 风力强度
options.windDirection: 风向 (x, y, z)
options.yPosition: 起始高度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "rain",
      "shaderOptions": {
        "key": "rain_effect",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 1.0,
        "options": {
          "count": 50000,
          "size": 3,
          "speed": 500,
          "areaWidth": 400,
          "areaHeight": 200,
          "areaDepth": 400,
          "color": "#88CCFF",
          "opacity": 0.8,
          "windEffect": true,
          "windStrength": 0.3,
          "windDirection": { "x": 1, "y": 0, "z": 0 },
          "yPosition": 40
        }
      }
    }
  }
}

11.雪花着色器（下雪效果）

说明

shaderName: 固定为 "snow"
key: 必填
position: 雪花区域中心
globalScale: 整体缩放
options.count: 雪花数量（默认 50000）
options.size: 雪花大小
options.speed: 下落速度
options.swayAmount: 摇摆幅度
options.rotationSpeed: 旋转速度
options.areaWidth/areaHeight/areaDepth: 降雪区域尺寸
options.color: 雪花颜色
options.opacity: 透明度
options.windEffect: 是否启用风效
options.windStrength: 风力强度
options.windDirection: 风向
options.yPosition: 起始高度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "snow",
      "shaderOptions": {
        "key": "snow_effect",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 1.0,
        "options": {
          "count": 50000,
          "size": 2,
          "speed": 2.0,
          "swayAmount": 0.3,
          "rotationSpeed": 0.5,
          "areaWidth": 200,
          "areaHeight": 50,
          "areaDepth": 200,
          "color": "#FFFFFF",
          "opacity": 0.9,
          "windEffect": true,
          "windStrength": 0.2,
          "windDirection": { "x": 1, "y": 0, "z": 0.5 },
          "yPosition": 40
        }
      }
    }
  }
}

12.电弧效果着色器

说明

shaderName: 固定为 "electricArc"
key: 必填
position: 电弧中心点
options.startX/startY/startZ: 起点坐标
options.endX/endY/endZ: 终点坐标
options.color: 电弧颜色
options.arcWidth: 电弧宽度
options.flickerSpeed: 闪烁速度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "electricArc",
      "shaderOptions": {
        "key": "arc_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "startX": 0,
          "startY": 0,
          "startZ": 0,
          "endX": 10,
          "endY": 0,
          "endZ": 0,
          "color": "#ffff00",
          "intensity": 1.0,
          "branches": 3,
          "flickerSpeed": 10.0,
          "arcWidth": 0.1
        }
      }
    }
  }
}

13.选中光环着色器

说明

shaderName: 固定为 "selectionRing"
key: 必填
position: 光环中心
options.color: 光环颜色
options.opacity: 透明度
options.spreadSpeed: 扩散速度
options.maxRadius: 最大半径
options.ringWidth: 光环宽度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "selectionRing",
      "shaderOptions": {
        "key": "ring_select",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "color": "#00ffff",
          "opacity": 0.8,
          "spreadSpeed": 1.0,
          "maxRadius": 5.0,
          "ringWidth": 0.3
        }
      }
    }
  }
}

14.科技网格地面着色器

说明

shaderName: 固定为 "gridGround"
key: 必填
position: 网格中心
options.gridColor: 网格颜色
options.lineColor: 线条颜色
options.gridSize: 网格大小
options.lineWidth: 线条宽度
options.flowSpeed: 流动速度
options.opacity: 透明度
options.pulseIntensity: 脉冲强度
options.width/height: 地面尺寸

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "gridGround",
      "shaderOptions": {
        "key": "tech_grid",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "gridColor": "#0088ff",
          "lineColor": "#00ffff",
          "gridSize": 10,
          "lineWidth": 0.02,
          "flowSpeed": 0.5,
          "opacity": 0.8,
          "pulseIntensity": 0.3,
          "width": 200,
          "height": 200
        }
      }
    }
  }
}

15.魔法阵着色器

说明

shaderName: 固定为 "magicCircle"
key: 必填
position: 魔法阵中心
options.color1/color2: 双色渐变
options.rotationSpeed: 旋转速度
options.ringCount: 环数
options.glowIntensity: 发光强度
options.opacity: 透明度
options.radius: 半径

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "magicCircle",
      "shaderOptions": {
        "key": "magic_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "color1": "#ff00ff",
          "color2": "#ffff00",
          "rotationSpeed": 0.3,
          "ringCount": 5,
          "glowIntensity": 1.5,
          "opacity": 0.7,
          "radius": 50
        }
      }
    }
  }
}

16.熔岩地面着色器

说明

shaderName: 固定为 "lavaGround"
key: 必填
position: 熔岩中心
options.lavaColor1/lavaColor2: 熔岩双色
options.glowColor: 发光颜色
options.flowSpeed: 流动速度
options.turbulence: 湍流程度
options.glowIntensity: 发光强度
options.opacity: 透明度
options.width/height: 地面尺寸

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "lavaGround",
      "shaderOptions": {
        "key": "lava_floor",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "lavaColor1": "#ff4400",
          "lavaColor2": "#ff8800",
          "glowColor": "#ffff00",
          "flowSpeed": 0.3,
          "turbulence": 2.0,
          "glowIntensity": 1.5,
          "opacity": 0.9,
          "width": 200,
          "height": 200
        }
      }
    }
  }
}

17.能量光柱着色器

说明

shaderName: 固定为 "cityScan"
key: 必填
position: 光柱中心
options.color: 光柱颜色
options.glowColor: 发光颜色
options.scanSpeed: 扫描速度
options.scanHeight: 扫描高度
options.scanWidth: 扫描宽度
options.intensity: 发光强度
options.opacity: 透明度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "cityScan",
      "shaderOptions": {
        "key": "energy_beam",
        "position": { "x": 0, "y": 0, "z": 0 },
        "options": {
          "color": "#00ffff",
          "glowColor": "#ffffff",
          "scanSpeed": 1.0,
          "scanHeight": 100,
          "scanWidth": 200,
          "intensity": 2.0,
          "opacity": 0.6
        }
      }
    }
  }
}

18.圆形波纹着色器

说明

shaderName: 固定为 "circle"
key: 必填
position: 波纹中心
globalScale: 整体缩放
options.color: 波纹颜色（RGB 数组）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "circle",
      "shaderOptions": {
        "key": "ripple_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 5.0,
        "options": {
          "color": [68, 222, 255]
        }
      }
    }
  }
}


### **19.烟雾着色器**

::: tip 说明
- shaderName: 固定为 "smoke"
- key: 必填
- position: 烟雾区域中心
- globalScale: 整体缩放
- options.count: 烟雾粒子数量（默认 3000）
- options.color: 烟雾颜色（HEX 格式）
- options.opacity: 透明度（0~1）
- options.speed: 上升速度
- options.areaWidth/areaHeight/areaDepth: 烟雾区域尺寸
- options.windEffect: 是否启用风效
- options.windStrength: 风力强度
- options.windDirection: 风向 (x, y, z)
- options.yPosition: 起始高度偏移
:::

``` json
{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "smoke",
      "shaderOptions": {
        "key": "smoke_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 10.0,
        "options": {
          "count": 3000,
          "color": "#aaaaaa",
          "opacity": 0.6,
          "speed": 1.0,
          "areaWidth": 30,
          "areaHeight": 20,
          "areaDepth": 30,
          "windEffect": false,
          "windStrength": 0.3,
          "windDirection": { "x": 1, "y": 0, "z": 0 }
        }
      }
    }
  }
}

20.传送门着色器

说明

shaderName: 固定为 "portal"
key: 必填
position: 传送门中心
globalScale: 整体缩放
options.radius: 传送门半径
options.color1: 主色调
options.color2: 辅色调
options.rotationSpeed: 旋转速度
options.glowIntensity: 发光强度
options.opacity: 透明度
options.ringCount: 环数

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "portal",
      "shaderOptions": {
        "key": "portal_01",
        "position": { "x": 0, "y": 5, "z": 0 },
        "globalScale": 10.0,
        "options": {
          "radius": 5,
          "color1": "#8800ff",
          "color2": "#00ccff",
          "rotationSpeed": 1.0,
          "glowIntensity": 2.0,
          "opacity": 0.9,
          "ringCount": 5
        }
      }
    }
  }
}

21.能量护盾着色器

说明

shaderName: 固定为 "shield"
key: 必填
position: 护盾中心
globalScale: 整体缩放
options.radius: 护盾半径
options.color: 护盾颜色
options.opacity: 透明度
options.hexSize: 六边形大小
options.pulseSpeed: 脉冲速度
options.glowIntensity: 发光强度
options.hitEffect: 是否启用受击效果

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "shield",
      "shaderOptions": {
        "key": "shield_01",
        "position": { "x": 0, "y": 5, "z": 0 },
        "globalScale": 10.0,
        "options": {
          "radius": 5,
          "color": "#00aaff",
          "opacity": 0.7,
          "hexSize": 0.5,
          "pulseSpeed": 1.0,
          "glowIntensity": 1.5,
          "hitEffect": false
        }
      }
    }
  }
}

22.光束/激光着色器

说明

shaderName: 固定为 "laserBeam"
key: 必填
position: 光束发射点
globalScale: 整体缩放
options.color: 光束颜色
options.glowColor: 辉光颜色
options.beamWidth: 光束宽度
options.beamLength: 光束长度
options.intensity: 发光强度
options.opacity: 透明度
options.pulseSpeed: 脉冲速度
options.flickerEffect: 是否启用闪烁
options.direction: 发射方向 (x, y, z)

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "laserBeam",
      "shaderOptions": {
        "key": "laser_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 10.0,
        "options": {
          "color": "#ff0000",
          "glowColor": "#ff6666",
          "beamWidth": 0.3,
          "beamLength": 50,
          "intensity": 2.0,
          "opacity": 0.9,
          "pulseSpeed": 2.0,
          "flickerEffect": false,
          "direction": { "x": 0, "y": 1, "z": 0 }
        }
      }
    }
  }
}

23.脉冲冲击波着色器

说明

shaderName: 固定为 "shockwave"
key: 必填
position: 冲击波中心
globalScale: 整体缩放
options.color: 冲击波颜色
options.glowColor: 辉光颜色
options.maxRadius: 最大扩散半径
options.speed: 扩散速度
options.ringWidth: 环宽度
options.intensity: 发光强度
options.opacity: 透明度
options.interval: 冲击波间隔（秒）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "shockwave",
      "shaderOptions": {
        "key": "shock_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 10.0,
        "options": {
          "color": "#ff8800",
          "glowColor": "#ffcc00",
          "maxRadius": 20,
          "speed": 1.0,
          "ringWidth": 2.0,
          "intensity": 2.0,
          "opacity": 0.8,
          "interval": 2.0
        }
      }
    }
  }
}

24.漩涡/龙卷风着色器

说明

shaderName: 固定为 "vortex"
key: 必填
position: 漩涡底部中心
globalScale: 整体缩放
options.count: 粒子数量（默认 8000）
options.color: 漩涡颜色
options.opacity: 透明度
options.rotationSpeed: 旋转速度
options.riseSpeed: 上升速度
options.radius: 漩涡半径
options.height: 漩涡高度
options.funnelRatio: 漏斗比（0.05~1，越小漏斗越尖）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "vortex",
      "shaderOptions": {
        "key": "vortex_01",
        "position": { "x": 0, "y": 0, "z": 0 },
        "globalScale": 10.0,
        "options": {
          "count": 8000,
          "color": "#cccccc",
          "opacity": 0.7,
          "rotationSpeed": 2.0,
          "riseSpeed": 1.0,
          "radius": 5,
          "height": 30,
          "funnelRatio": 0.3
        }
      }
    }
  }
}

25.全息投影着色器（Entity模式）

说明

shaderName: 固定为 "hologram"
key: 必填
options.groupName: 必填，模型名称
options.color: 全息颜色
options.scanSpeed: 扫描速度
options.scanWidth: 扫描宽度
options.fresnelPower: 菲涅尔边缘强度
options.opacity: 透明度
options.glitchIntensity: 故障效果强度（0=关闭）
options.lineDensity: 扫描线密度
options.isOverlay: 是否材质叠加

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "hologram",
      "shaderOptions": {
        "key": "holo_01",
        "options": {
          "groupName": "建筑A",
          "color": "#00ccff",
          "scanSpeed": 1.0,
          "scanWidth": 0.1,
          "fresnelPower": 2.0,
          "opacity": 0.6,
          "glitchIntensity": 0.0,
          "lineDensity": 50.0,
          "isOverlay": true
        }
      }
    }
  }
}

26.透视扫描着色器（Entity模式）

说明

shaderName: 固定为 "xray"
key: 必填
options.groupName: 必填，模型名称
options.color: 透视颜色
options.edgeColor: 边缘颜色
options.scanSpeed: 扫描速度
options.edgePower: 边缘强度
options.opacity: 透明度
options.scanDirection: 扫描方向（"vertical" | "radial"）
options.isOverlay: 是否材质叠加

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "xray",
      "shaderOptions": {
        "key": "xray_01",
        "options": {
          "groupName": "设备B",
          "color": "#00ff44",
          "edgeColor": "#88ffaa",
          "scanSpeed": 1.0,
          "edgePower": 1.5,
          "opacity": 0.5,
          "scanDirection": "vertical",
          "isOverlay": true
        }
      }
    }
  }
}

27.边缘发光着色器（Entity模式）

说明

shaderName: 固定为 "glowEdge"
key: 必填
options.groupName: 必填，模型名称
options.color: 发光颜色
options.glowIntensity: 发光强度
options.edgePower: 边缘强度
options.opacity: 透明度
options.pulseSpeed: 脉冲速度
options.pulseEffect: 是否启用脉冲效果
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "glowEdge",
      "shaderOptions": {
        "key": "glow_01",
        "options": {
          "groupName": "仓库C",
          "color": "#ffaa00",
          "glowIntensity": 2.0,
          "edgePower": 2.0,
          "opacity": 0.8,
          "pulseSpeed": 1.0,
          "pulseEffect": false,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

28.极光着色器（Standalone模式）

说明

shaderName: 固定为 "aurora"
key: 必填
options.color1: 主色调
options.color2: 辅色调
options.color3: 第三色调
options.opacity: 透明度
options.waveSpeed: 波动速度
options.waveAmplitude: 波动幅度
options.bandCount: 飘带数量
options.height: 极光高度
options.width: 极光宽度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "aurora",
      "shaderOptions": {
        "key": "aurora_01",
        "config": {
          "position": { "x": 0, "y": 20, "z": 0 },
          "globalScale": 10.0,
          "options": {
            "color1": "#00ff88",
            "color2": "#8800ff",
            "color3": "#00ccff",
            "opacity": 0.6,
            "waveSpeed": 0.5,
            "waveAmplitude": 3.0,
            "bandCount": 5,
            "height": 30,
            "width": 80
          }
        }
      }
    }
  }
}

29.沙尘暴着色器（Standalone模式）

说明

shaderName: 固定为 "sandstorm"
key: 必填
options.color: 沙尘颜色
options.opacity: 透明度
options.windSpeed: 风速
options.areaWidth/areaHeight/areaDepth: 区域范围
options.density: 粒子密度
options.turbulence: 湍流强度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "sandstorm",
      "shaderOptions": {
        "key": "sand_01",
        "config": {
          "position": { "x": 0, "y": 0, "z": 0 },
          "globalScale": 10.0,
          "options": {
            "count": 5000,
            "color": "#c4a35a",
            "opacity": 0.5,
            "windSpeed": 3.0,
            "areaWidth": 80,
            "areaHeight": 20,
            "areaDepth": 80,
            "density": 1.0,
            "turbulence": 1.0
          }
        }
      }
    }
  }
}

30.弹道轨迹着色器（Standalone模式）

说明

shaderName: 固定为 "bulletTrail"
key: 必填
options.color: 轨迹颜色
options.glowColor: 辉光颜色
options.trailLength: 轨迹长度
options.trailWidth: 轨迹宽度
options.speed: 速度
options.fadeLength: 拖尾渐变
options.coreIntensity: 核心亮度
options.direction: 方向向量

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "bulletTrail",
      "shaderOptions": {
        "key": "trail_01",
        "config": {
          "position": { "x": 0, "y": 0, "z": 0 },
          "globalScale": 10.0,
          "options": {
            "color": "#ff4400",
            "glowColor": "#ffaa00",
            "trailLength": 30,
            "trailWidth": 0.3,
            "speed": 5.0,
            "opacity": 0.9,
            "fadeLength": 0.6,
            "pulseSpeed": 3.0,
            "coreIntensity": 3.0,
            "direction": { "x": 0, "y": 1, "z": 0 }
          }
        }
      }
    }
  }
}

31.量子隧道着色器（Standalone模式）

说明

shaderName: 固定为 "quantumTunnel"
key: 必填
options.radius: 隧道半径
options.length: 隧道长度
options.color1: 主色调
options.color2: 辅色调
options.rotationSpeed: 旋转速度
options.ringCount: 环数量
options.energyIntensity: 能量强度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "quantumTunnel",
      "shaderOptions": {
        "key": "tunnel_01",
        "config": {
          "position": { "x": 0, "y": 0, "z": 0 },
          "globalScale": 10.0,
          "options": {
            "radius": 3,
            "length": 40,
            "color1": "#8800ff",
            "color2": "#00ffcc",
            "opacity": 0.7,
            "rotationSpeed": 1.0,
            "ringCount": 20,
            "pulseSpeed": 2.0,
            "energyIntensity": 2.0
          }
        }
      }
    }
  }
}

32.溶解效果着色器（Entity模式）

说明

shaderName: 固定为 "dissolve"
key: 必填
options.groupName: 必填，模型名称
options.edgeColor: 边缘颜色
options.dissolveProgress: 溶解进度（0~1）
options.edgeWidth: 边缘宽度
options.noiseScale: 噪声缩放
options.edgeGlow: 边缘发光强度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "dissolve",
      "shaderOptions": {
        "key": "dissolve_01",
        "options": {
          "groupName": "建筑A",
          "edgeColor": "#ff6600",
          "dissolveProgress": 0.0,
          "edgeWidth": 0.1,
          "opacity": 1.0,
          "noiseScale": 1.0,
          "edgeGlow": 2.0,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

33.热力图着色器（Entity模式）

说明

shaderName: 固定为 "heatMap"
key: 必填
options.groupName: 必填，模型名称
options.coldColor: 冷色
options.warmColor: 暖色
options.hotColor: 热色
options.intensity: 热力强度
options.heatRadius: 热源半径
options.scanSpeed: 扫描速度
options.pulseEffect: 脉冲效果
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "heatMap",
      "shaderOptions": {
        "key": "heat_01",
        "options": {
          "groupName": "管道系统",
          "coldColor": "#0000ff",
          "warmColor": "#ffff00",
          "hotColor": "#ff0000",
          "intensity": 0.5,
          "opacity": 0.7,
          "scanSpeed": 0.5,
          "heatCenter": { "x": 0, "y": 0, "z": 0 },
          "heatRadius": 10,
          "pulseEffect": false,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

34.晶体化着色器（Entity模式）

说明

shaderName: 固定为 "crystallize"
key: 必填
options.groupName: 必填，模型名称
options.crystalColor: 晶体颜色
options.edgeColor: 边缘颜色
options.fresnelPower: 菲涅尔强度
options.facetSize: 晶面大小
options.sparkleIntensity: 闪烁强度
options.refractionStrength: 折射强度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "crystallize",
      "shaderOptions": {
        "key": "crystal_01",
        "options": {
          "groupName": "设备B",
          "crystalColor": "#88ddff",
          "edgeColor": "#ffffff",
          "opacity": 0.6,
          "fresnelPower": 2.0,
          "facetSize": 2.0,
          "sparkleIntensity": 1.0,
          "refractionStrength": 0.5,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

35.腐蚀效果着色器（Entity模式）

说明

shaderName: 固定为 "corrosion"
key: 必填
options.groupName: 必填，模型名称
options.corrosionColor: 腐蚀颜色
options.rustColor: 锈蚀颜色
options.edgeColor: 边缘颜色
options.corrosionProgress: 腐蚀进度（0~1）
options.noiseScale: 噪声缩放
options.edgeWidth: 边缘宽度
options.spreadSpeed: 扩散速度
options.pittingEffect: 坑蚀效果
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "corrosion",
      "shaderOptions": {
        "key": "corrosion_01",
        "options": {
          "groupName": "金属管道",
          "corrosionColor": "#4a7a3a",
          "rustColor": "#8b4513",
          "edgeColor": "#aaff44",
          "opacity": 0.8,
          "corrosionProgress": 0.3,
          "noiseScale": 2.0,
          "edgeWidth": 0.08,
          "spreadSpeed": 0.5,
          "pittingEffect": false,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

36.冰冻效果着色器（Entity模式）

说明

shaderName: 固定为 "frost"
key: 必填
options.groupNames: 必填，模型名称数组
options.frostColor: 冰霜颜色
options.iceColor: 冰晶颜色
options.frostAmount: 结霜程度
options.iceCrystalDensity: 冰晶密度
options.shimmerSpeed: 闪烁速度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "frost",
      "shaderOptions": {
        "key": "frost_01",
        "options": {
          "groupNames": ["设备A"],
          "frostColor": "#aaddff",
          "iceColor": "#ffffff",
          "opacity": 0.6,
          "frostAmount": 0.5,
          "fresnelPower": 2.0,
          "iceCrystalDensity": 30.0,
          "shimmerSpeed": 2.0,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

37.电磁场着色器（Entity模式）

说明

shaderName: 固定为 "electricField"
key: 必填
options.groupNames: 必填，模型名称数组
options.arcColor: 电弧颜色
options.glowColor: 辉光颜色
options.arcDensity: 电弧密度
options.arcSpeed: 电弧速度
options.arcIntensity: 电弧强度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "electricField",
      "shaderOptions": {
        "key": "elec_01",
        "options": {
          "groupNames": ["变压器"],
          "arcColor": "#44aaff",
          "glowColor": "#0066ff",
          "opacity": 0.7,
          "arcDensity": 8.0,
          "arcSpeed": 5.0,
          "arcIntensity": 2.0,
          "fresnelPower": 1.5,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

38.数据流着色器（Entity模式）

说明

shaderName: 固定为 "dataFlow"
key: 必填
options.groupNames: 必填，模型名称数组
options.flowColor: 流光颜色
options.dataColor: 数据颜色
options.flowSpeed: 流动速度
options.lineCount: 线条数量
options.dataDensity: 数据密度
options.pulseWidth: 脉冲宽度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "dataFlow",
      "shaderOptions": {
        "key": "data_01",
        "options": {
          "groupNames": ["服务器柜"],
          "flowColor": "#00ff88",
          "dataColor": "#00ffcc",
          "opacity": 0.6,
          "flowSpeed": 2.0,
          "lineCount": 10.0,
          "dataDensity": 20.0,
          "pulseWidth": 0.3,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

39.警告闪烁着色器（Entity模式）

说明

shaderName: 固定为 "warning"
key: 必填
options.groupNames: 必填，模型名称数组
options.warningColor: 警告颜色
options.glowColor: 辉光颜色
options.flashSpeed: 闪烁速度
options.pattern: 闪烁模式（pulse/scan/stripe）
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "warning",
      "shaderOptions": {
        "key": "warn_01",
        "options": {
          "groupNames": ["反应堆"],
          "warningColor": "#ff4400",
          "glowColor": "#ff8800",
          "opacity": 0.7,
          "flashSpeed": 2.0,
          "fresnelPower": 1.5,
          "scanLineSpeed": 3.0,
          "pattern": "pulse",
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

40.隐身效果着色器（Entity模式）

说明

shaderName: 固定为 "cloak"
key: 必填
options.groupNames: 必填，模型名称数组
options.tintColor: 色调
options.distortion: 扭曲程度
options.fresnelPower: 菲涅尔强度
options.rippleSpeed: 波纹速度
options.rippleScale: 波纹缩放
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.05）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "cloak",
      "shaderOptions": {
        "key": "cloak_01",
        "options": {
          "groupNames": ["隐形装置"],
          "tintColor": "#4488ff",
          "opacity": 0.15,
          "distortion": 0.02,
          "fresnelPower": 3.0,
          "rippleSpeed": 2.0,
          "rippleScale": 5.0,
          "isOverlay": true,
          "baseOpacity": 0.05
        }
      }
    }
  }
}

41.生锈效果着色器（Entity模式）

说明

shaderName: 固定为 "rust"
key: 必填
options.groupNames: 必填，模型名称数组
options.rustColor: 锈色
options.darkRustColor: 深锈色
options.flakeColor: 剥落色
options.rustProgress: 生锈进度（0~1）
options.noiseScale: 噪声缩放
options.flakeDensity: 剥落密度
options.edgeDarkness: 边缘暗度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "rust",
      "shaderOptions": {
        "key": "rust_01",
        "options": {
          "groupNames": ["旧管道"],
          "rustColor": "#8b4513",
          "darkRustColor": "#5c2e0e",
          "flakeColor": "#a0522d",
          "opacity": 0.85,
          "rustProgress": 0.4,
          "noiseScale": 2.0,
          "flakeDensity": 15.0,
          "edgeDarkness": 1.5,
          "isOverlay": true,
          "baseOpacity": 0.15
        }
      }
    }
  }
}

42.能量场着色器（Standalone模式）

说明

shaderName: 固定为 "energyField"
key: 必填
options.color1/color2: 主/辅色调
options.radius: 球体半径
options.pulseSpeed: 脉冲速度
options.waveCount: 波纹数量
options.energyIntensity: 能量强度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "energyField",
      "shaderOptions": {
        "key": "energy_01",
        "config": {
          "position": { "x": 0, "y": 5, "z": 0 },
          "globalScale": 10.0,
          "options": { "color1": "#ffaa00", "color2": "#ff4400", "opacity": 0.5, "radius": 5, "pulseSpeed": 1.5, "waveCount": 8, "energyIntensity": 2.0 }
        }
      }
    }
  }
}

43.黑洞着色器（Standalone模式）

说明

shaderName: 固定为 "blackHole"
key: 必填
options.color1/color2: 内/外圈颜色
options.radius: 半径
options.rotationSpeed: 旋转速度
options.spiralArms: 螺旋臂数

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "blackHole",
      "shaderOptions": {
        "key": "blackhole_01",
        "config": {
          "position": { "x": 0, "y": 10, "z": 0 },
          "globalScale": 10.0,
          "options": { "color1": "#ff6600", "color2": "#8800ff", "opacity": 0.8, "radius": 5, "rotationSpeed": 2.0, "spiralArms": 3 }
        }
      }
    }
  }
}

44.雷暴着色器（Standalone模式）

说明

shaderName: 固定为 "thunderStorm"
key: 必填
options.color: 闪电颜色
options.flashInterval: 闪烁间隔
options.boltCount: 闪电数量
options.areaWidth/areaHeight/areaDepth: 区域范围

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "thunderStorm",
      "shaderOptions": {
        "key": "thunder_01",
        "config": {
          "position": { "x": 0, "y": 0, "z": 0 },
          "globalScale": 10.0,
          "options": { "color": "#aaccff", "opacity": 0.7, "flashInterval": 3.0, "boltCount": 5, "areaWidth": 60, "areaHeight": 40, "areaDepth": 60 }
        }
      }
    }
  }
}

45.晶簇着色器（Standalone模式）

说明

shaderName: 固定为 "crystalCluster"
key: 必填
options.color1/color2: 主/辅色调
options.crystalCount: 晶体数量
options.maxHeight: 最大高度
options.glowIntensity: 发光强度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "crystalCluster",
      "shaderOptions": {
        "key": "crystal_01",
        "config": {
          "position": { "x": 0, "y": 0, "z": 0 },
          "globalScale": 10.0,
          "options": { "color1": "#00ffcc", "color2": "#ff00ff", "opacity": 0.8, "crystalCount": 8, "maxHeight": 5, "floatSpeed": 1.0, "glowIntensity": 2.0 }
        }
      }
    }
  }
}

46.信号波着色器（Standalone模式）

说明

shaderName: 固定为 "signalWave"
key: 必填
options.color: 信号颜色
options.radius: 扩散半径
options.waveCount: 波纹数量
options.speed: 扩散速度
options.thickness: 波纹厚度

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "signalWave",
      "shaderOptions": {
        "key": "signal_01",
        "config": {
          "position": { "x": 0, "y": 0, "z": 0 },
          "globalScale": 10.0,
          "options": { "color": "#00ffaa", "opacity": 0.6, "radius": 10, "waveCount": 3, "speed": 2.0, "thickness": 0.1 }
        }
      }
    }
  }
}

47.矩阵代码着色器（Entity模式）

说明

shaderName: 固定为 "matrix"
key: 必填
options.groupNames: 必填，模型名称数组
options.color: 代码颜色
options.speed: 下落速度
options.density: 代码密度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "matrix",
      "shaderOptions": {
        "key": "matrix_01",
        "options": {
          "groupNames": ["服务器"],
          "color": "#00ff41", "opacity": 0.6, "speed": 3.0, "density": 20.0, "fresnelPower": 1.5, "isOverlay": true, "baseOpacity": 0.15
        }
      }
    }
  }
}

48.脉冲波着色器（Entity模式）

说明

shaderName: 固定为 "pulseWave"
key: 必填
options.groupNames: 必填，模型名称数组
options.color: 脉冲颜色
options.pulseSpeed: 脉冲速度
options.pulseWidth: 脉冲宽度
options.waveCount: 波纹数量
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "pulseWave",
      "shaderOptions": {
        "key": "pulse_01",
        "options": {
          "groupNames": ["反应堆"],
          "color": "#ff0066", "opacity": 0.7, "pulseSpeed": 2.0, "pulseWidth": 0.2, "fresnelPower": 1.5, "waveCount": 3, "isOverlay": true, "baseOpacity": 0.15
        }
      }
    }
  }
}

49.幽灵效果着色器（Entity模式）

说明

shaderName: 固定为 "ghost"
key: 必填
options.groupNames: 必填，模型名称数组
options.color: 幽灵颜色
options.fresnelPower: 菲涅尔强度
options.flickerSpeed: 闪烁速度
options.driftSpeed/driftAmount: 飘动速度/幅度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.05）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "ghost",
      "shaderOptions": {
        "key": "ghost_01",
        "options": {
          "groupNames": ["幽灵体"],
          "color": "#8888ff", "opacity": 0.3, "fresnelPower": 2.5, "flickerSpeed": 3.0, "driftSpeed": 1.0, "driftAmount": 0.02, "isOverlay": true, "baseOpacity": 0.05
        }
      }
    }
  }
}

50.电路纹理着色器（Entity模式）

说明

shaderName: 固定为 "circuit"
key: 必填
options.groupNames: 必填，模型名称数组
options.traceColor: 走线颜色
options.glowColor: 辉光颜色
options.traceDensity: 走线密度
options.flowSpeed: 流动速度
options.nodeDensity: 节点密度
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "circuit",
      "shaderOptions": {
        "key": "circuit_01",
        "options": {
          "groupNames": ["电路板"],
          "traceColor": "#00ff66", "glowColor": "#003311", "opacity": 0.7, "traceDensity": 15.0, "flowSpeed": 2.0, "nodeDensity": 8.0, "isOverlay": true, "baseOpacity": 0.15
        }
      }
    }
  }
}

51.损伤裂纹着色器（Entity模式）

说明

shaderName: 固定为 "damage"
key: 必填
options.groupNames: 必填，模型名称数组
options.crackColor: 裂纹颜色
options.glowColor: 辉光颜色
options.damageLevel: 损伤程度（0~1）
options.crackWidth: 裂纹宽度
options.noiseScale: 噪声缩放
options.isOverlay: 是否材质叠加
options.baseOpacity: 叠加模式下原材质透明度（默认0.15）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "createShader",
    "payload": {
      "shaderName": "damage",
      "shaderOptions": {
        "key": "damage_01",
        "options": {
          "groupNames": ["受损墙体"],
          "crackColor": "#ff2200", "glowColor": "#ff8800", "opacity": 0.8, "damageLevel": 0.3, "crackWidth": 0.03, "noiseScale": 3.0, "fresnelPower": 1.5, "isOverlay": true, "baseOpacity": 0.15
        }
      }
    }
  }
}

四、API按名称替换或恢复材质

提示

✨ 全新能力：无需修改模型文件，通过 API 动态替换任意模型或材质的外观。

🔍 匹配逻辑

提示

若 targetName 匹配 Object3D.name（如 "水泵A"）→ 替换该对象下所有子 mesh 的材质
若 targetName 匹配 Material.name（如 "墙面_砖"）→ 仅替换使用该材质的所有 mesh
支持批量操作：输入多个名称，用英文逗号 ,、分号 ; 或换行分隔。

1.📦 替换材质（replaceMesh）

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "replaceMesh",
    "payload": {
      "type": "replaceMesh",
      "targetName": ["车间外墙", "屋顶"],
      "options": {
        "image": "/textures/metal_rust.jpg",
        "color": 16777215,
        "wrapMode": "repeat",
        "metalness": 0.3,
        "roughness": 0.7,
        "textureQuality": "high"
      }
    }
  }
}

options 参数说明：

字段	类型	说明
image	string	贴图 URL（相对或绝对路径）
color	number	基础色（十六进制转十进制，如 #ffffff → 16777215）
wrapMode	"repeat" \| "clamp"	纹理包裹模式
metalness	number (0~1)	金属度
roughness	number (0~1)	粗糙度
textureQuality	"high" \| "normal" \| "pixel"	渲染质量策略

提示：color 可留空，仅用贴图；image 可为空，仅用纯色。

2.🔄 恢复原始材质（restoreMesh）

{
 "kanbanId": "68a6742ff6e8a11600de95dc",
 "message": {
   "type": "replaceMesh",
   "payload": {
     "type": "restoreMesh",
     "targetName": ["车间外墙"]
   }
 }
}

无需 options
自动还原模型加载时的原始材质

五、语音控制场景调试

说明

语音控制功能支持通过语音指令控制三维场景，实现免手操作的沉浸式交互。基于 Vosk 离线语音识别引擎，支持唤醒词检测、命令识别与执行、AI 意图增强解析、TTS 语音反馈等能力。

✅ 适用场景：展厅大屏、指挥中心、工业巡检等需要免手操作的场景。

1.功能架构

用户语音 → Vosk离线识别 → 唤醒词检测 → 命令模式 → 意图匹配 → 执行场景命令
                                                        ↓ (匹配失败且AI开启)
                                                   AI意图解析 → 执行场景命令

核心模块：

模块	说明
离线语音识别	基于 Vosk 引擎，无需联网即可识别中文语音
唤醒词检测	支持"你好小壹"等唤醒词，拼音模糊匹配（相似度≥0.75）
意图匹配器	本地拼音/关键词/子串多维度匹配，综合评分≥0.4 即执行
AI 意图增强	本地匹配失败时，调用后端 AI 接口解析用户意图
TTS 语音反馈	命令执行结果通过语音合成播报给用户
控制列表管理	用户可配置的语音命令列表，支持 IndexedDB 持久化
命令组管理	将多个命令组合为一个语音触发单元

2.唤醒词

系统内置以下唤醒词（说出任一即可进入命令模式）：

唤醒词	说明
你好小壹	主唤醒词
你好小一	同音变体
你好壹孪	品牌名变体
你好一孪	同音变体
你好小伊	同音变体
你好小依	同音变体

进入命令模式后，系统会播放提示音并 TTS 播报"我在"，随后等待 20 秒接收命令。说出"退出"、"停止"或"取消"可退出命令模式。

3.支持的命令类型

语音命令通过 pushMessage API 执行，与手动 API 控制使用相同的消息格式。以下为所有支持的命令类型：

API 名称	中文名	说明
scenePreset	场景预设切换	切换环境预设（白天/夜晚/雨天等）
modelMove	模型移动	控制模型按路径移动
tabsBtnChange	按钮组切换	切换按钮组 Tab 状态
bottonClick	单按钮点击	触发单按钮点击事件
css2dClick	CSS2D 点击	点击 CSS2D 标签
css2dClose	CSS2D 关闭	关闭 CSS2D 标签
camera	相机控制	控制相机视角和位置
restoreCamera	相机重置	重置相机到初始位置
playAnimation	动画控制	播放/停止模型动画
modelVisibility	模型隐藏/显示	控制模型显隐
createShader	着色器效果	创建着色器特效
removeShader	删除着色器	移除着色器特效
updateShader	更新着色器	更新着色器参数
replaceMesh	替换网格	替换模型材质
digitalHumanControl	数字人播报	控制数字人播报内容

📌 每种命令的 payload 格式与上文对应章节完全一致，语音控制仅是触发方式不同。

4.意图匹配关键词

系统通过以下关键词从语音文本中提取动作意图：

意图	关键词
切换	切换、换成、变成、转到、换到、切到、变为、设为、设置
打开	打开、开启、启动、开始、运行、播放、执行
关闭	关闭、关掉、停止、停掉、取消、结束、退出
移动	移动、走、去、到、前进、后退、左转、右转、上升、下降
显示	显示、出现、展示、看得见、亮起来
隐藏	隐藏、消失、看不见、藏起来、暗掉
重置	重置、恢复、还原、回到、复位
调整	调整、调节、修改、改变、变大、变小、加快、减慢、升高、降低

匹配算法权重： 关键词 × 0.3 + 子串 × 0.3 + 拼音 × 0.3 + 名称 × 0.05 + 描述 × 0.05

综合评分 ≥ 0.4 即视为匹配成功，自动执行对应命令。

5.语音命令配置流程

步骤一：开启语音控制

在项目管理中开启「语音控制」开关
或在调试页面中点击「语音控制」卡片进入配置

步骤二：添加语音命令

在各功能调试页面（相机控制、着色器效果、动画控制等）中调试好参数
点击页面底部的 【添加到语音控制】 按钮
在弹出的对话框中填写：
- 名称：命令的显示名称（如"切换到夜间模式"）
- 描述：命令的功能描述
- 触发关键词：语音触发时匹配的关键词（如"夜间、夜晚、晚上"）
- 分类：命令所属分类

步骤三：配置命令组（可选）

在「命令组管理」面板中创建命令组
将多个命令添加到同一组
说出命令组名称即可一次性执行所有命令

步骤四：配置 TTS 反馈（可选）

在语音控制面板中开启「语音回应」开关
选择语音角色、语速、音量、音调
开启「AI 增强」可让 AI 理解更自然的口语表达

6.语音控制 API 接口

保存语音控制数据

POST /api/v1/visual-project/update-voice-control

{
  "_id": "68a6742ff6e8a11600de95dc",
  "voiceControlData": {
    "controlList": [
      {
        "id": "cmd_001",
        "name": "切换到夜间模式",
        "description": "将场景切换为夜晚环境预设",
        "keywords": ["夜间", "夜晚", "晚上"],
        "category": "环境",
        "apiName": "scenePreset",
        "params": {
          "type": "scenePreset",
          "payload": { "presetName": "夜晚" }
        }
      }
    ],
    "commandGroups": [
      {
        "id": "grp_001",
        "name": "应急模式",
        "description": "一键切换火灾应急场景",
        "keywords": ["应急", "火灾", "报警"],
        "commands": ["cmd_001", "cmd_002"]
      }
    ],
    "ttsConfig": {
      "voice": "default",
      "rate": 1.0,
      "volume": 1.0,
      "pitch": 1.0
    },
    "ttsSwitch": {
      "enabled": true,
      "aiEnhanced": false
    }
  },
  "isTemplate": false
}

语音命令执行（复用 pushMessage）

语音命令执行时，系统自动调用 pushMessage API，消息格式与手动 API 控制完全一致：

{
  "kanbanId": "68a6742ff6e8a11600de95dc",
  "message": {
    "type": "scenePreset",
    "payload": {
      "presetName": "夜晚"
    }
  }
}

7.使用示例

示例一：语音切换场景预设

用户说出："你好小壹"
系统播报："我在"
用户说出："切换到夜晚"
系统匹配到"场景预设切换"命令，关键词命中"切换"
执行 scenePreset 命令，场景切换为夜晚预设
TTS 播报："已切换到夜晚模式"

示例二：语音触发着色器效果

用户说出："你好小壹"
系统播报："我在"
用户说出："打开火焰效果"
系统匹配到"着色器效果"命令，关键词命中"打开"
执行 createShader 命令，创建火焰着色器
TTS 播报："火焰效果已开启"

示例三：语音触发命令组

用户说出："你好小壹"
系统播报："我在"
用户说出："启动应急模式"
系统匹配到"应急模式"命令组
依次执行命令组中的所有命令（切换环境预设 + 开启警告着色器 + 播放警报动画）
TTS 播报："应急模式已启动"

8.注意事项

小贴士

语音识别基于 Vosk 离线引擎，无需联网即可使用基础功能。
开启「AI 增强」后，本地匹配失败的命令会调用后端 AI 接口解析，需要联网。
命令模式有 20 秒超时，超时后自动回到唤醒模式，需重新说唤醒词。
建议在安静环境中使用，背景噪音可能影响识别准确率。
触发关键词建议设置 2-3 个同义词，提高识别率。

注意

语音控制功能需要浏览器授权麦克风权限。
Vosk 离线模型首次加载需要下载约 50MB 的模型文件，请确保网络畅通。
语音控制仅支持中文语音指令。
同一看板下所有语音命令的 key 必须唯一，避免冲突。
语音控制数据保存在项目级别，不同项目需分别配置。