# scene-3d —— 三维场景（builder 型，vjmap3d/three.js 内核）

> 41 种 piece 目录与关键 options、测点数据驱动、路径动画、事件与动作、VP-TSX 写法。
> 返回目录：[index.md](index.md)；全量选项字典（最权威）：[widget-schema.generated.json](../widget-schema.generated.json)。

## 7b. scene-3d —— 三维场景（builder 型，vjmap3d/three.js 内核，默认 WebGPU 自动回退 WebGL）

- **type**: `scene-3d`　**默认尺寸**: `[640,420]`　**默认名**: 三维场景
- 用途：真三维数字孪生/工业组态场景——几何体（含全息/透射/流光渐变/Shadertoy 预设库/镜面五种特效材质）、glb 模型、灯光阴影、CSS2D 值标签/标记点/动效光圈标记、三维文字、发光流动管道/飞线、管网巷道（手工路径或 CAD 图纸动态生成）、人员点位（定位数据源驱动平滑移动+轨迹回放+最近出口路线）、光墙围栏、雷达扫描、热力图、粒子特效（含 40 种在线预设库）、批量实例、序列帧动画、图表贴片、Lottie 动画、后期特效全家桶（辉光/描边/SSAO/景深/像素化/故障/色差…）、补间动画、路径动画/漫游、CAD 图纸转 3D 模型（按查询规则转墙体/体块/地面/线稿），全部由 `pieces` 描述；测点数据驱动颜色/闪烁/流动。
- **务必写 `"scene3d-initialized": true`**（否则空场景会播种演示内容）。
- **pieces 必含两个固定 uid 单例**：场景设置 `{ "uid": "scene3d-scene", "type": "scene3d-scene" }` 与相机 `{ "uid": "scene3d-camera", "type": "scene3d-camera" }`（uid 必须逐字用这两个固定值）。其余 piece 形如 `{ uid, type, name?, enabled?, options }`。`scene3d-effects` 建议每场景只放一个（引擎效果是 App 级参数）。⚠️ **`raw.pieces` 回显只是存储层接受，不等于渲染有效**——缺了两个单例时其他 piece 照样回显，但场景不会正常渲染。校验渲染有效要看画布，别信回显。
- **多实例纪律**：同一页面 3D 场景实例默认上限 4 个（`VITE_VP_SCENE3D_MAX` 可调），且强制同一服务配置（`service-url`+`service-token` 签名一致，不符则拒绝渲染并提示）；渲染引擎不强制一致但建议统一；页签隐藏自动暂停渲染。参考网格 `grid` 编辑/播放态一致生效（运行画面不要网格就置 `grid:false`）；坐标轴 `axes` 仅编辑态，播放自动隐藏。
- 服务级联：`scene3d-scene` 的 `service-url`/`service-token` 留空 → 项目设置 → 全局默认（vjmap 公开演示服务），开箱即用。

### 7b.1 piece 目录与关键 options

| piece type | 名称 | 关键 options（默认值） |
|---|---|---|
| `scene3d-scene` | 场景设置(单例,uid=`scene3d-scene`) | `engine`(`webgpu`/`webgl`)；背景 `bg-mode`(`color`/`transparent`/`panorama`/`sky` 程序化天空)+`scene-bg`(#0d1220)+`bg-image`(file,jpg/png/hdr)+`sky-preset`(`night` 星空/`dusk` 晚霞/`dawn` 晨曦/`nebula` 极光,零素材)+`sky-stars`(1,0..2 星星密度)+`bg-blur`(0..1)；环境反射 `env-mode`(`room` 推荐/`background`/`none`)+`env-intensity`(1)——sky/全景配 `background` 可让金属映出天色；网格 `grid`(true)/`grid-infinite`(true)/`grid-cell`(1)/`grid-section`(10)/`grid-cell-color`/`grid-section-color`/`axes`(false)；雾 `fog`(false)+`fog-mode`(`linear` 近远距离/`exp` 指数大气感)+`fog-color`/`fog-near`(30)/`fog-far`(300,线性)/`fog-density`(0.015,指数)；**剖切分析** `clip-enable`(false)+`clip-axis`(`x`/`y`/`z`)+`clip-position`(0)+`clip-invert`(false)——全场景剖切面看内部结构，运行层用 `scene3dClip` 动作控制（特效类自定义材质可能不参与裁剪）；服务 `service-url`/`service-token`(留空继承) |
| `scene3d-camera` | 相机(单例,uid=`scene3d-camera`) | 视角 `position`([14,10,14])/`target`([0,0,0])/`fov`(45)；**入场飞入** `entry-fly`(false,播放态开场从远处俯冲飞向初始视角)+`entry-duration`(2.5s)+`entry-scale`(2.2,起飞距离=视距×倍数)；巡航 `cruise-mode`(`off`/`orbit` 自动环绕/`tour` 书签巡航/`path` 路径漫游)+`orbit-speed`(10°/s)+`tour-interval`(6s)+`cruise-play-only`(true)；路径漫游 `cruise-path`(多行 `x,z` 或 `x,y,z`)+`cruise-path-duration`(20s)+`cruise-path-loop`(`loop`/`yoyo`)+`cruise-follow-distance`(2,越小越像第一人称)+`cruise-follow-angle`(25°)——漫游期间手动操控无效；**第一人称行走** `walk-enable`(false,播放态 W/S 前后 A/D 平移 Q/E 转向 R/F 升降 Shift 加速)+`walk-speed`(4)+`walk-rotate-speed`(60°/s)——建议关巡航配俯仰限制；小地图 `minimap`(false,右下角俯视鹰眼)+`minimap-size`(180px)+`minimap-view`(24,俯视世界宽度)+`minimap-rotate`(true,跟随主相机朝向旋转：屏幕上方=航向、中心箭头=取景中心；关=固定俯视原点北向上)+`minimap-play-only`(true)——小地图是独立渲染面板不可拖拽，只有主视图能轨道操控；操控限制 `min-distance`/`max-distance`(0=不限)、`min-polar`(0°)/`max-polar`(90°=不穿地)、`allow-pan`(true)、`dolly-speed`(1)/`truck-speed`(2)/`smooth-time`(0.25) |
| `scene3d-light` | 灯光 | `light-kind`(`ambient`/`directional`/`point`/`spot`/`hemisphere`)、`light-color`、`light-intensity`(0..10)、`position`([10,20,10])、`light-target`(平行/聚光照向,[0,0,0])、`spot-angle`(30°)/`spot-penumbra`(0.3)/`light-distance`(0=∞)、`light-color2`(半球地面色)、`show-helper`(true,编辑态辅助线)；阴影 `cast-shadow`(false)+`shadow-quality`(512/1024/2048)；**镜头光晕** `lensflare`(false,平行/点/聚光：朝灯看时光核+星芒+沿视线鬼影,纹理程序化零素材,WebGPU 自动换 TSL 版)+`flare-size`(420px)+`flare-color`(留空跟随灯色) |
| `scene3d-shape` | 形状 | `shape`(`box`/`sphere`/`cylinder`/`cone`/`capsule`/`plane` 地面/`torus`/**`helicoid` 双曲螺旋**/**`sphube` 圆角立方**——后两种为参数化科技装饰件,尺寸=包围盒,配自转+特效材质=中心能量装置)、`shape-size`([2,2,2])、`pickable`(true；关=点击/悬停射线略过、点它视同点空白，地面/背景板建议关)；**材质类型 `mat-kind`**：`standard`(默认 PBR：`mat-color`/`mat-map`/`mat-metalness`(0.2)/`mat-roughness`(0.6)/`mat-opacity`/`mat-emissive`/`mat-wireframe`/`mat-double-side`) / `hologram` 全息(`holo-color`(#51a4de)/`holo-brightness`(1.2)/`holo-speed`(0.45)/`holo-blink`(true)) / `transmission` 玻璃透射(无参) / `flow-gradient` 流光渐变(`grad-color`/`grad-top-color`/`grad-light-color`/`grad-speed`(2s)/`grad-light-width`(0.15)) / `shadertoy`(**`shader-preset`**：`custom` 自定义(读 `shader-code`,留空用内置示例)/`pulse` 脉冲光盘/`rings` 彩虹圆环/`diffuse` 扩散涟漪/`electric` 电光涟漪/`radar` 雷达表盘/`clock` 电子时钟(实时)/`water` 水波纹/`lightning` 风暴闪电——8 种成品特效免写代码；WebGPU 自动转译失败回退) / `reflector` 镜面反射(仅 plane,`reflect-strength`(0.25))；`glow`(false,辉光,需后期效果)；`cast-shadow`/`receive-shadow`(true)；变换 `position`([0,1,0])/`rotation`(°)/`scale`/`billboard`(false 公告牌：始终面向相机，plane+贴图=图片指示牌)；路径动画（见 7b.2a）；自转 `spin`(false)+`spin-axis`(`y`/`x`/`z`)+`spin-speed`(30°/s,负=反向)+`spin-play-only`(true)——风机叶片/雷达碟；**呼吸脉动** `pulse`(false,心跳缩放:告警强调/待机呼吸)+`pulse-scale`(1.15×)+`pulse-speed`(1.2Hz)+`pulse-play-only`(true)——形状/模型/拉伸体同款；**表面热力** `surface-heat`(false,按三维测值点插值体积色场刷到表面：温度场/信号强度分析,开启期间替换材质)+`sheat-points`(多行 `x,y,z,值`,世界坐标)+`sheat-min`(0)/`sheat-max`(100)+`sheat-segment`(10,采样密度)+`sheat-colors`(多行 `位置,颜色` 自定义色表,留空默认彩虹)+`sheat-data-key`(测点 JSON `[[x,y,z,v],…]` 整批刷新)——形状/模型同款(reflector 除外)；测点 `data-key`+`state-rules`(仅 standard 生效)+`blink-values` |
| `scene3d-extrude` | 拉伸体 | `ext-outline`(多行 `x,z` 底面轮廓,≥3 点自动闭合)、`ext-height`(4)、`position`/`rotation`；材质 `mat-kind`(`standard` PBR 全套 / `flow-gradient` 城市楼宇光效同形状参数)；**科技轮廓线** `edges`(true 棱线发光描边)+`edge-color`(#5fd0ff)；`glow`(false)；`cast-shadow`/`receive-shadow`(true)；自转组同形状；测点 `data-key`+`state-rules`(仅 standard)+`blink-values`。楼宇体块/围墙/异形台体首选 |
| `scene3d-model` | 模型 | `model-url`(file,glb/gltf/fbx/obj/3ds,≤200MB 直传)、`model-scale`(1)、`model-anchor`(`default`/`center`/`middle-bottom`)、编辑器另有「自适应大小」按钮（模型过大/过小看不见时按最大边≈10 世界单位重算 `model-scale` 并取景）、`position`/`rotation`、`cast-shadow`/`receive-shadow`(true)、`glow`(false)、动画 `anim-autoplay`(false)+`anim-index`(0)；路径动画（见 7b.2a，另有 `path-anim-clip` 行进骨骼动画名）；自转组同形状；**表面热力** `surface-heat` 组同形状（模型内每个网格刷体积色场，蒙皮/实例化网格除外）；**子对象样式** `sub-rules[*]` 簇（按模型内部命名节点做部件级效果：`match` 可编辑下拉直接选部件（模型加载后列出全部路径）,也可手输名称/路径 `a/b/c`,支持 `*` 通配与 `\|` 多选 + `color` 重涂/`emissive` 自发光/`opacity`(<1 生效)/`visible`(`''` 不改/`show`/`hide`)/`blink`(0.5s 闪烁) + 可选测点门控 `data-key`+`on-values`(命中值才应用,做"部件报警变红")；克隆材质替换、关规则即恢复；surface-heat 开启期间材质字段让位只保留显隐/闪烁；编辑器「场景图层」展开模型可定位/复制部件,子节点「+」一键生成预填规则）；**子树裁剪/打散** `sub-root`(仅显示该部件子树)+`sub-exclude`(剔除部件,`\|` 分隔)——场景图层子节点「打散为独立元素」自动生成:选中节点的各命名子部件各拆一个「同 URL+仅显示子树」的模型元素,命名子部件之外的无名网格/自身材质自动补一件「其余」承接,并从原模型剔除该节点(**拆前拆后渲染集合完全一致**;拆件继承外观/变换/子对象样式规则,可单独选中/移动/配交互/删除;克隆共享几何体代价小;上限 50 个部件)。同层重名部件路径段自动带 #N 序号（如 `BLACK_PLASTIC#2`,加载后固化,跨裁剪稳定）,路径可精确到第 N 个;按名称匹配则命中全部重名件;匹配串整串写 `/正则/`（如 `/^BLACK/i`）按正则；`sub-root` 与规则 `match` 下拉候选列**完整模型**部件（裁剪后仍可重选）,可 ✕ 清空,另有「恢复完整模型」按钮一键清裁剪;sub-root 命中 sub-exclude 的自身/祖先时剔除让位（不会整树消失）,精确路径失配按末段部件名自愈；测点 `data-key`+`blink-values` |
| `scene3d-label` | 值标签(CSS2D 广告牌) | `label-text`(固定文本)、`data-key`(测点键→显示值)、`unit`/`decimals`(1)、`position`([0,3,0])、`anchor`(`bottom`/`center`/`top`/`left`/`right`)、`occlusion`(false 被遮挡淡出)、`enter-anim`(`none`/`bounce` 弹跳落位/`drop` 坠落落位,入场动效)、`font-size`(14)/`text-color`/`bg-color`；测点 `state-rules`(文字状态色)+`blink-values`；播放态点击也派发 `scene3d-piece-click` |
| `scene3d-text` | 三维文字(真三维,可辉光/遮挡) | `text`(多行,中文免字体)、`text-size`(1,单行世界高度)、`text-billboard`(true 始终朝相机;关=固定平面可 `rotation`)、`position`([0,3,0])；外观 `text-color`(#e6f2ff)/`text-bg`(空=透明)/`text-stroke`(true 深色描边)/`glow`(false)；测点 `data-key`+`state-rules`(文字色)+`blink-values` |
| `scene3d-marker` | 标记点(CSS2D 装饰标注) | `marker-style`(`beacon` 呼吸光圈/`ring` 旋转光环/`pin` 图钉)、`marker-text`(下方说明文字)、`marker-icon`(file,替换中心圆点)、`position`([0,2,0])、`anchor`(`center`/`bottom` 图钉推荐/`top`)、`occlusion`(false)、`enter-anim`(`none`/`bounce` 弹跳落位/`drop` 坠落落位,入场动效)；外观 `marker-color`(#00e5ff)/`marker-size`(46px)；测点 `data-key`+`state-rules`+`blink-values`；播放态点击派发 `scene3d-piece-click` |
| `scene3d-fxmarker` | 动效标记(引擎动画光圈 CSS2D) | `fx-style`(`breathing` 呼吸光圈/`diffused` 扩散光点/`fluorescence` 荧光点/`halo-ring` 发光光环/`rotating-aperture` 旋转光圈/`rotating-textborder` 旋转文字边框——引擎成品多层动效,动画自带)、`marker-text`(动效中的文字,文字边框样式建议必填)、`position`([0,2,0])、`anchor`(`center`/`bottom`/`top`)、`occlusion`(false)；外观 `fx-colors`(逗号分隔一到多色,留空引擎默认配色)/`marker-size`(80px)/`text-color`/`text-size`(14)；测点 `data-key`+`state-rules`(命中即覆盖整组配色)+`blink-values`；点击派发 piece-click。与「标记点」区别：这是引擎带的成品动效（多层光圈/波纹），科技感 POI 首选 |
| `scene3d-pipe` | 管道(发光流动) | `pipe-path`(多行 `x,y,z` 文本,≥2 点自动圆滑)、`pipe-radius`(0.18)、`position`(整体偏移)；管体 `mat-color`(#3d7dd8)/`mat-metalness`(0.6)/`mat-roughness`(0.35)；流动 `flow`(true)+`flow-color`(#7fd6ff)/`flow-speed`(0.8)/`flow-density`(4)/`flow-reverse`+`glow`(false)；测点 `data-key`+`state-rules`(管体色)+`flow-rules`(`值=on/off/reverse[:速度]` 每行一条) |
| `scene3d-flyline` | 飞线(彗星脉冲) | `fly-from`/`fly-to`/`fly-height`(拱高 3)/`fly-width`(0.05)、`position`；外观 `line-color`(#2e5f9e 轨迹)/`pulse-color`(#7fd6ff)/`pulse-count`(1..6)/`glow`(false)；流动 `flow`(true)+`flow-speed`(0.6)+`flow-reverse`；测点 `data-key`+`flow-rules` |
| `scene3d-wall` | 光墙围栏(电子围栏) | `wall-path`(多行 `x,z` 贴地或 `x,y,z`,≥2 点)、`wall-height`(3)、`wall-close`(true 自动闭合)、`position`(整体偏移)；外观 `wall-color`(#00e5ff)/`wall-opacity`(0.55 基底)/`wall-flow`(true 流光扫动)+`flow-speed`(0.5)/`flow-repeat`(3 光带数)/`glow`(true)；测点 `data-key`+`state-rules`(围栏色)+`blink-values`（周界告警变红闪烁标配） |
| `scene3d-radar` | 雷达扫描(贴地圆盘) | `radar-radius`(5)、`position`([0,0.15,0] 抬高避免被地面挡住)；外观 `radar-color`(#00ffb3)/`radar-speed`(2 转速)/`radar-sector`(200° 扇区)/`radar-opacity`(0.9)/`glow`(true)；测点 `data-key`+`state-rules`(扫描色)+`blink-values` |
| `scene3d-heatmap` | 热力图(2D 贴地/3D 曲面) | `heat-mode`(`2d`/`3d`)、`heat-size`([20,0,20] 以位置为中心的宽深)、`heat-height`(3,3d 起伏)、`position`([0,0.18,0])；外观 `heat-opacity`(0.75)/`heat-radius`(40 热斑半径)；数据 `heat-points`(多行 `x,z,值` 静态点)+`heat-min`(0)/`heat-max`(100)+`data-key`(测点值为 JSON `[[x,z,v],…]` 或 `[{"x","z","value"},…]` 时整批实时替换) |
| `scene3d-trail` | 导引线(箭头流动宽线) | `trail-path`(多行 `x,y,z`,贴地建议 y≈0.18 以免被地面挡住)、`position`；外观 `trail-color`(#2ee6a8,发光箭头+底带同染)/`trail-width`(14px 屏幕像素,远近等宽)/`trail-icon-length`(18,建议≥线宽防箭头压扁)/`trail-icon-space`(6)/`trail-animate`(true)+`trail-speed`(2)/`trail-show-line`(false 半透明同色底带)+`trail-line-opacity`(0.45 底带浓度)/`glow`(true)；测点 `data-key`+`state-rules`(箭头/底带整体换色)+`flow-rules`(`值=on/off[:速度]`)+`blink-values`。疏散路线/巡检动线/导航指引 |
| `scene3d-ruler` | 测量标注(尺寸线) | `ruler-start`/`ruler-end`(vec3 两端点)；外观 `ruler-color`(#ffd166)/`ruler-decimals`(2)/`ruler-unit`(' m')/`ruler-scale`(1,显示值=距离×比例)。持久工程标注；编辑态视口工具条另有「测量」交互工具（点两点即测、可连续、清除） |
| `scene3d-video` | 视频面板(监控融合) | `video-url`(file,mp4/webm 直链或上传；静音自动循环；跨域需 CORS；留空="无信号"占位)、`video-size`([4.8,2.7] 宽高,16:9)、`video-billboard`(false 广告牌)、`position`/`rotation`；外观 `video-frame`(true 发光边框)+`frame-color`(#3fa8ff)/`video-opacity`(1)/`glow`(false)。监控墙/设备屏/广告屏 |
| `scene3d-points` | 数据点云(批量点位) | `points-shape`(`sphere`/`box`/`diamond`)、`points-size`(0.4)、`points-size-by-value`(false 值大点大)、`position`(整体偏移)、`glow`(true)；量程配色 `points-min`(0)/`points-max`(100)+`points-color-low`(#22c55e)/`points-color-mid`(#eab308)/`points-color-high`(#ef4444)；数据 `points-data`(多行 `x,y,z,值`)+`data-key`(测点值 JSON `[[x,y,z,v],…]` 整批刷新，容量内零重建)。InstancedMesh 单次绘制承载上千点位 |
| `scene3d-ledtext` | LED 字幕屏(滚动文字) | `led-text`(滚动文本)、`led-direction`(`horizon` 跑马灯/`vertical` 多行滚屏)、`led-speed`(0.05)、`led-size`([6,1.2] 宽高)、`position`/`rotation`；外观 `led-color`(#ffb02e)/`led-bg`(#120a02)/`led-font-size`(48px)/`glow`(true)；测点 `data-key`(测点值直接上屏,配 `led-prefix` 前缀)+`state-rules`(文字色)+`blink-values`。车站告示/厂区标语/告警滚动 |
| `scene3d-pipenet` | 管网(分支拓扑/巷道) | **路径来源 `net-source`**：`static`(默认) `net-paths`(多行 `x,y,z`,空行或 `---` 分段,每段一条管道,端点重合自动生成节点球建拓扑) / **`cad` CAD 图纸查询动态生成**——`cad-mapid`(必填,演示巷道图 `sys_tube`)+`cad-version`/`cad-layer`(留空默认)+`cad-condition`(留空默认查带高程的多段线 `name=='AcDbPolyline' or name=='AcDb3dPolyline'`,人类可读写法自动翻译)+`cad-limit`(3000)+`fit-size`(200,平面外接盒等比缩放最大边长,底面自动对齐最低高程；矿井巷道/综合管廊直接用图纸生成)；`position`；断面 `net-shape`(`circle` 圆管/`arch` 拱形管廊巷道/`rect` 风管桥架)+`net-radius`(0.3,圆)+`net-rect-width`(1.2)/`net-rect-height`(0.8,拱/矩)+`net-node-radius`(0.45)；外观 `net-color`(#3f7dd8)/`net-inner-color`(#1a2c44)/**`net-flow`(false 流动箭头贴图)**+`net-flow-speed`(1,负值反向,配 `scene3dSetOption` 运行时开关)/`glow`(false)；测点 `data-key`+`state-rules`+`blink-values`。给水/电力/燃气分支网络、综合管廊与矿井巷道；`scene3dNetRoute` 动作可在其拓扑上高亮「最近出口路线」 |
| `scene3d-persons` | 人员点位(定位数据驱动) | **数据** `data-key`(测点值 JSON `[[编号,x,y,z,姓名?],…]` 或对象数组；连接刷新/`scene3dWritePoint` 写入即按 id 差分——新增出现/缺失移除/其余 `move-duration`(3000ms,0=瞬移) 平滑补间移动,并记录 `trail-limit`(400) 条历史轨迹)、`follow-net`(关联管网 uid：人员坐标视为该管网 CAD 图纸原始坐标自动换算,留空=场景坐标)；**外观 `person-mode`**：`model` 三维人物模型——`model-url`(默认 three.js 士兵 glb⚠️公网直链,同 URL 缓存克隆)+`model-size`(1.8 身高)+`walk-clip`('Walk')/`idle-clip`('Idle',忽略大小写支持部分匹配,行进播行走/静止切待机)+`model-heading`(180° 模型"脸"朝向校正)，行进朝向自动最短弧转身、头顶跟随固定像素姓名标签；`sprite`(默认) 图标精灵——`person-size`(40px 固定像素)/`person-color`(#4cc3ff 内置定位针图标色)/`icon-url`(file 自定义图标)/`name-overlay`(false;开=图标铺满画布、姓名叠画在图内顶部,配自带名牌区的人物立牌图)，零素材保底；两档共用 `name-size`(13)/`name-color`(#7dffea)/`name-prefix`('人员',数据无姓名时显示 前缀+编号)、`position`(整体偏移)；**选中** `select-wave`(true 点击人员脚下扩散光波,点空白取消)+`wave-color`(#00e5ff)/`wave-size`(2.4)；**演示行走** `demo-walk`(false,沿关联管网拓扑随机游走,按 `demo-interval`(3s)/`demo-step`(6)/`demo-count`(20) 产出同格式 JSON 写回测点通道——接真实定位数据时关闭即可)。点击 payload 带 `personId`/`personName`/`personX/Y/Z`（信息面板公式 `{:personId}` 直取）；配 `scene3dPersonTrail`(轨迹回放)/`scene3dNetRoute`(最近出口路线) 动作复刻人员定位系统 |
| `scene3d-carflow` | 车流(收费站/闸口过车) | **关联** `model-piece`(主模型元素 uid,留空取首个模型)+`lane-match`('CD*' 车道锚点子对象,按名称排序,车沿世界 Z 轴过锚点)+`lane-reverse`(反向车道匹配串,如对向 `CD01\|CD02`)+`pole-match`('GZ*' 抬杆子对象,与车道按序配对)+`pole-axis`(z)/`pole-angle`(90°)/`pole-duration`(2s)；**车型与节奏** `car-urls`(每行 `模型URL[,车型名]` 随机抽取,默认 vjmap 示例六车型⚠️外网)/`car-scale`(1)/`drive-duration`(3s 驶入驶出各一段)/`dwell`(2s 杆前停留)/`pole-close-delay`(1s 过杆后降杆)/`spawn-gap`(3s 发车间隔,随机浮动)/`approach-dist`(50)/`stop-dist`(2)/`exit-dist`(60)/`flow-play-only`(true 仅播放态运行)；**信息卡** `show-card`(true 到杆前车顶弹车牌/司机/车型/状态)+`card-width`(6 世界单位)/`card-plate-prefix`('京B')/`card-abnormal-rate`(0.1)；**号牌** `lane-tags`(true 车道锚点上方 01/02… 固定像素号牌)+`tag-size`(56px)/`tag-color`/`tag-bg`。每车道循环：随机车型缓存克隆驶入 → 停杆前（抬杆自动旋转）→ 通过驶出 → 延时降杆 → 销毁；点击车辆 payload 带 `carPlate`/`carDriver`/`carType`/`carState`/`laneName`。对照 vjmap 收费站示例（exam tollstation） |
| `scene3d-beam` | 光柱标记(POI 地标) | `beam-height`(6)/`beam-width`(0.9)、`position`(底部落点贴地)；外观 `beam-color`(#00e5ff)/`beam-opacity`(0.9)/`ripple`(true 底部涟漪扩散圈)+`ripple-radius`(1.6)/`ripple-period`(2s)/`beam-top`(true 顶部悬浮自转菱形)/`glow`(true)；测点 `data-key`+`state-rules`(整柱换色)+`blink-values`。双交叉渐变面片程序化生成零素材；智慧城市/园区 POI 与告警地标标配 |
| `scene3d-board` | 数据看板牌(设备顶牌 CSS2D) | `board-title`(留空=元素名)、`position`([0,4,0])、`anchor`(`bottom`/`center`/`top`/`left`/`right`)、`occlusion`(false)；外观 `board-width`(200px)/`font-size`(13)/`board-accent`(#3fa8ff 主题条+边框)/`value-color`(#7fd6ff)/`board-bg`；数据 `board-rows`(每行 `标签\|测点键\|单位\|小数位` 后两段可省，多行=多指标)+`row-state-rules`(每行 `值=颜色`,任一行原始值命中该行数值变色)。多指标实时刷新；点击派发 `scene3d-piece-click` |
| `scene3d-tank` | 液位罐(经典组态) | `tank-shape`(`cylinder` 圆柱罐/`box` 方形水箱)、`tank-size`([3,4,3] 圆柱取宽为直径)、`position`(罐底中心)；外观 `shell-color`/`shell-opacity`(0.22 开口玻璃罐体+金属箍/座)/`liquid-color`(#22a7f0)/`liquid-low-color`(#f59e0b)/`liquid-high-color`(#ef4444)/`show-value`(true 罐顶百分比标签)/`glow`(false)；数据 `data-key`(液位测点,留空用 `tank-value` 静态值)+`tank-min`/`tank-max`(量程)+`tank-low`(20%)/`tank-high`(85% 阈值,0=不判高)+`blink-high`(true 高液位液面自发光脉冲)。半透明液柱自底缩放，独立波浪液面，值变化平滑升降换色 |
| `scene3d-sprites` | 图标点位(批量精灵) | `icon-url`(file,png/jpg/webp/svg,留空用内置发光圆点)+`icon-color`(#00e5ff 圆点色)、`sprite-size`(28)、`size-attenuation`(false=固定像素/true=世界尺寸近大远小)、`allow-overlap`(true,关=密集自动避让)、`position`(整体偏移)；**标签文字** `text-size`(13px)/`text-color`(#e6f2ff)——点位行第 4 段为标签时图标上方出批量文字精灵；数据 `points`(每行 `x,y,z[,标签]`)+`data-key`(测点值 JSON `[[x,y,z,标签?],…]` 整批刷新)。与 CSS2D 标记的区别：在 3D 渲染管线内参与深度/遮挡/拾取，单实体承载上百点位；点击派发 piece-click |
| `scene3d-line` | 线条(批量发光细线) | `line-paths`(每行 `x,y,z`,空行或 `---` 分段,一实体多条线)、`position`；外观 `line-color`(#5fd0ff)+动画 `line-animate`(`none` 常显/`grow` 生长循环/`march` 跑马亮段)+`animate-speed`(1)+`march-length`(0.25 亮段占比)+`glow`(true 细线配辉光=霓虹)；测点 `data-key`+`state-rules`(整组换色)+`blink-values`。边界勾勒/科技连线/路径示意 |
| `scene3d-html` | HTML 面板(CSS3D 立牌) | `html`(textarea 任意 HTML/内联样式,工程作者书写与自定义组件同信任级)、`position`(面板中心)、`panel-width`(4 世界宽,高按内容自适应)/`panel-px-width`(420px 排版宽,越大字越小)；外观 `panel-billboard`(false 广告牌)/`rotation`(°,非广告牌可斜放立牌)/`occlude`(true 可被场景遮挡)/`panel-bg`。与 CSS2D 看板牌区别：真正贴在三维空间（近大远小/可遮挡/可斜放）；点击派发 piece-click |
| `scene3d-zone` | 区域面(填充多边形) | `zone-points`(每行 `x,z` 贴地抬高约 0.15 或 `x,y,z`,≥3 点闭合)、`position`；外观 `zone-color`(#2e8bff)/`zone-opacity`(0.35)/`glow`(false)；测点 `data-key`+`state-rules`(区域换色)+`blink-values`。工厂分区/危险区/责任网格标配，告警分区变红闪烁。地面用 `plane` 时把地坪 Y 略降或区域 Y 写高，避免被挡住 |
| `scene3d-buildings` | 批量楼块(城市体块) | `bld-data`(每行一楼 `x,z;x,z;x,z…\|高度[\|底色[\|顶色]]`,轮廓≥3 点)、`position`/`base-height`(0)；外观 `bld-color`(#16283f 默认底色)/`bld-top-color`(#2e64b8 顶色,渐变)/`show-border`(true 发光棱线)+`border-color`/`border-top-color`/`glow`。单实体单次绘制承载上百楼；城市尺度铺量用这个，单楼精修（特效材质/测点驱动）用拉伸体 |
| `scene3d-tiles3d` | 倾斜摄影(3D Tiles) | `tiles-url`(Cesium 3D Tiles 的 tileset.json 直链：倾斜摄影实景/BIM 切片/城市实景,演示 https://vjmap.com/map3d/resources/3dtiles/demo/tileset.json)、`tiles-scale`(1,米制大场景可 0.1)、`position`、`error-target`(2,屏幕误差像素越小越清晰)。插件按需异步加载,LOD 按视距自动加载卸载；需外网/切片服务可达 |
| `scene3d-particle` | 粒子特效 | `fx-kind`(`fire` 火焰/`smoke` 烟雾/`rain` 下雨/`snow` 下雪/**`firework` 烟花**(循环绽放:球面爆散+重力下坠+暖冷随机色,位置=爆心建议 y≥10)/**`text` 文字聚字**/**`preset` 在线预设库**/`custom`)、`position`(雨雪建议 y≥12；聚字为文字底部中心)、**在线预设库**(⚠️外网)`preset-name`(40 种成品:爆炸/火球爆炸/核能爆炸/闪电球(×3)/紫色闪电落雷/紫色烟花/彩带礼花/人物光环/治愈流光/升级新星/原子环绕/星域/烛光/蓝色火舌/落叶/钞票雨/表情包(×5)/炮口焰(×4)/冰霜导弹/魔法阵…)+`preset-url-base`(留空=vjmap 演示资源,内网拷 JSON 后改自有地址)+`preset-loop`(true)、文字聚字 `fx-text`(内容)+`fx-text-height`(2.4 世界高)+`fx-text-cycle`(7s 散布→汇聚循环,正面朝 +Z,色留空=青→品红随机)、`fx-intensity`(0.1..3 发射量,内置预设生效)、`fx-size`(0.1..3,预设库/custom 下为整体缩放)、`fx-range`(12,雨雪发射盒边长)、`fx-color`(留空用预设)、custom：`fx-json-url`(远程 three.quarks JSON 地址,填了优先)/`fx-json`(粘贴引擎 particle.toJSON()) |
| `scene3d-effects` | 后期效果(建议单份) | 辉光 `bloom`(true)+`bloom-intensity`(2,0..10)+`bloom-threshold`(0.1,越低越易泛光)——各元素勾 `glow` 才参与；交互描边 `outline-hover`(true 悬停描边)/`outline-click`(false 点击选中描边,点空白清除)+`outline-color`(#7fd6ff)/`outline-strength`(3)；`hover-tip`(false,悬停元素时上方自动显示名称小气泡,免配交互)+`hover-tip-sub`(false,悬停模型内部部件时气泡附带部件名如「设备 · 泵体」)；**画质增强**：`aa-mode`(`none`/`fxaa`/`smaa`,仅 WebGL；WebGPU 引擎自带)、`ssao`(false 环境光遮蔽)+`ssao-intensity`(1)/`ssao-radius`(0.04)(WebGPU 下 GTAO 深度重建,参数固定)、`dof`(false 景深背景虚化)+`dof-focus`(2 对焦距离)/`dof-range`(5)/`dof-bokeh`(3)(WebGPU 参数固定)、`tone-mapping`(`none`/`aces` 电影/`reinhard`/`reinhard2-adaptive` 自适应/`cineon` 胶片;WebGPU 统一 Reinhard)；**风格化特效**：`pixelate`(false 像素化)+`pixelate-size`(6)、`color-depth`(false 色深压缩海报风)+`color-bits`(12)、`dot-screen`(false 网点印刷)+`dot-angle`(90°)/`dot-scale`(1)、`glitch`(false 故障干扰,赛博告警)+`glitch-wild`(false 持续强干扰)、`chromatic`(false RGB 色差)+`chroma-offset`(2‰)/`chroma-radial`(false 径向渐强)、`blur`(false 全屏模糊)、`custom-post-shader`(自定义后期着色器,pmndrs mainImage 签名,留空关闭)——网点/故障/色差在 WebGPU 下依赖 GLSL 自动转译,失败自动跳过不影响其余效果；WebGPU/WebGL 双引擎一致 |
| `scene3d-instances` | 批量实例(万级同模型) | `inst-source`(`box`/`sphere`/`cylinder`/`cone` 内置几何零素材/`model` 模型文件 `model-url`(file 上传资源库或 URL,glb/gltf/fbx/obj/3ds,⚠️外链跨域))、`inst-size`(1 基准尺寸,几何源)、**排布方式** `inst-layout`(`manual` 手动/`grid` 网格/`ring` 圆环/`line` 直线/`scatter` 随机散布,非手动按参数自动排布免手敲坐标)——manual:`inst-data`(每行 `x,y,z[,缩放[,朝向°[,#颜色]]]`,# 段任意位置识别为逐实例色)；grid:`grid-count`([行,列] 行沿Z列沿X)+`grid-gap`([X,Z] 间距)；ring:`ring-count`(16)+`ring-radius`(8)+`ring-face-center`(true 朝向圆心)；line:`line-count`(8)+`line-gap`(2)+`line-angle`(0°=沿X轴逆时针)；scatter:`scatter-count`(60)+`scatter-range`([X,Z] 矩形宽深)+`scatter-seed`(1 同种子可复现)+`scatter-jitter`(0.25 尺寸抖动±比例,散布带随机朝向)；非手动通用 `layout-origin`([0,0.5,0] 阵列中心,Y=实例中心高度)+编辑器「转为手动数据」按钮(参数阵列落回 inst-data 文本逐行微调)、基础材质 `inst-color`(#4a8fe8)/`inst-metalness`(0.2)/`inst-roughness`(0.6)、`hover-highlight`(false 播放态指到哪个实例亮哪个)+`hover-color`、`glow`(false)；数据 `data-key`(测点 JSON `[[x,y,z,缩放?,朝向?,"#色"?],…]` 或对象数组整批重排,覆盖手动/自动排布)。引擎 InstancedMeshEntity 单实体一次绘制：树阵/路灯/车位/机柜铺量首选 |
| `scene3d-chart2d` | 图表贴片(纹理面板真三维) | `chart-kind`(`bar` 柱状/`pie` 饼图/`donut` 环形)、`chart-title`、`chart-data`(每行 `标签,值[,#颜色]`,不填色用内置调色板)、`panel-width`(6)/`panel-height`(3.6 世界单位)、`chart-anim`(true 数据刷新时生长动画)、`billboard`(false)、`glow`(false)；外观 `bg-color`/`text-color`；变换 `position`/`rotation`(非公告牌可斜放贴墙)；数据 `data-key`(测点 JSON `[["标签",值,"#色"?],…]` 或 `[{label,value,color},…]` 整批刷新)。与 CSS2D 看板牌区别：真三维面——可被遮挡/可辉光/进截图,canvas 绘制零素材离线可用 |
| `scene3d-spriteanim` | 序列帧动画(精灵图逐帧) | `sheet-url`(file,精灵图必填 ⚠️外链跨域；**推荐 PNG/WebP 横向等分条带**，SVG data-URI 会先栅格成 PNG 仍建议直接给位图)、`atlas-url`(TexturePacker 图集 JSON,含帧名/多动画;留空按帧数等分)、`frames`(16,无图集时横向等分帧数)、`frame-name`(图集初始动画名)、`fps`(24)、`autoplay`(true,配 scene3dSetOption 可做播放暂停)、`loop`(true)、`flip-x`(false)、`as-sprite`(true 公告牌;关=固定平面可旋转)、`glow`(false)；变换 `position`/`rotation`/`sprite-scale`(1)；测点 `data-key`+`anim-rules`(每行 `值1|值2=帧动画名`,命中即切动画——状态→idle/run/alarm 三套动作)。火焰序列帧/角色动画/动态图标 |
| `scene3d-lottie` | Lottie 动画贴片 | `lottie-url`(AE/Bodymovin 导出 JSON 必填 ⚠️外链跨域;扩展 loader 从引擎插件服务按需下载,需服务可达)、`quality`(2,纹理分辨率倍率)、`speed`(1)/`loop`(true)、`panel-width`(4)/`panel-height`(4,建议与动画宽高比一致)、`billboard`(true)、`glow`(false)；变换 `position`/`rotation`。矢量动效 logo/动态图标/引导动画,真三维面可遮挡进截图 |
| `scene3d-view` | 视角书签 | `position`/`target`（书签巡航与 `scene3dFlyTo` 动作 `view-uid` 的目标；编辑器里有「保存当前视角/飞到此视角」按钮） |
| `scene3d-tilemap` | 瓦片地图(底图) | `tile-preset`(`osm` 免令牌默认/`gaode-vec` 高德路网/`gaode-img` 高德影像/`tianditu-img`/`tianditu-vec` 天地图需 `tile-token`/**`cad` CAD 图纸瓦片**(vjmap 服务 openMap+rasterTileUrl,`cad-mapid` 必填+`cad-version`+`cad-dark`(true 深色样式打图),服务走场景级联)/`custom` 自定义 `tile-url`+`anno-url` 注记层,模板含 `{x}{y}{z}`)；`root-tile`(`z,x,y`,`0,0,0`=世界地图,填城市瓦片铺局部如北京 `10,843,388`,仅 web 源)+`base-scale`(100 铺设世界边长)+`position`(Y 微沉防闪面)；**CAD 叠加层**（web 源上叠 WMS 配准图纸）`cad-overlay-mapid`(留空不叠)+`cad-overlay-epsg`(EPSG:4544)；**裁剪区域** `clip-polygon`(每行一顶点,web=经纬度 `lng,lat`/cad=图纸 `x,y`,≥3 点生效,行政区轮廓地图标配)+`clip-outer`(false,反选挖洞保留外侧)；样式 `style-filter`(`dark` 科技深蓝反色/`none`/`gray`/`mono`)+`mono-color`(#4586b6)；地形 `terrain-url`(terrain-rgb 高度瓦片模板,留空平面,仅 web 源)+`height-scale`(1)。瓦片联网/服务可达；底图不参与射线拾取不抢点击；CAD 打图异步 generation 防竞态 |
| `scene3d-cadwall` | CAD 转 3D | `cad-mapid`(必填，vjmap 服务上的 CAD 图,演示可用 `sys_zp`)、`cad-version`/`cad-layer`(留空默认)、`cad-condition`(全局筛选,与各规则条件 AND 合并)、`cad-limit`(2000)、`fit-size`(40 等比缩放最大边,全部规则共用同一变换自动对齐)、`position`；**转换规则** `cad-rules`(array 簇,`{indexes:['r1',…],r1:{…}}`)——每条=一个查询转成一类三维实体：`condition`(可写人类可读形态 `name=='AcDbPolyline'` 实体类型/`layerindex==2` 图层/`isclosed==1`/`radius>0.5`/`color=='#ff0000'`,发请求前自动翻成后端整数码)+`kind`(`wall` 竖直墙体/`solid` 闭合轮廓拉伸体块/`flat` 闭合轮廓填充地面/`line` 贴地线稿蓝图底纹)+`enabled`(true)/`name`/`height`(3,wall/solid)/`base`(0 底部标高,窗带可填 0.9)/`color`/`opacity`(1)/`emissive`(留空不发光)/`edges`(true,solid 科技轮廓线)+`edge-color`(#5fd0ff)/`force-close`(false,把未闭合折线当闭合轮廓,solid/flat)；**未配规则退化旧行为**：全局条件查出的线全部拉成默认墙体 `wall-height`(3)/`wall-color`/`wall-opacity`(0.92)；`glow`(false,作用于全部规则实体) |

### 7b.2 测点数据驱动（与 2D 组态同一套规则语法）

- **画板级绑定（长表）**：scene-3d 的 data 组绑 `point-key-field` + `point-value-field`（键/值两列，各 1）；运行层动作 `scene3dWritePoint` 写入同 key 覆盖。
- **元素级消费**：piece 填 `data-key`（与键列值匹配）后——
  - `state-rules`：每行 `值1|值2=颜色`（如 `run|1=#22c55e`、`fault=#ef4444`），命中即覆盖材质/文字/围栏/扫描色；
  - `blink-values`：`fault|2` 命中即闪烁（形状/模型/标签/文字/标记/光墙/雷达）；
  - `flow-rules`（管道/飞线）：每行 `值=on/off/reverse[:速度]`（如 `1=on:1.5`、`0=off`）；
  - 热力图 `data-key`：测点值为 JSON 数组时整批替换热力点（配 `scene3dWritePoint` 动作即可实时刷新）；
  - 人员点位 `data-key`：测点值 JSON `[[编号,x,y,z,姓名?],…]`——按 id 差分 + 平滑补间移动（不是整批重建），历史轨迹自动记录。
- 值标签无 `data-key` 时显示 `label-text`；有则显示 `固定文本 + 格式化值 + 单位`。

### 7b.2a 路径动画（形状/模型的「路径动画」组）

- `path-points`（多行 `x,z` 或 `x,y,z`，≥2 点生效）+ `path-duration`(10s 单程) + `path-loop`(`loop` 循环/`yoyo` 往返/`once` 单次) + `path-autoplay`(true 播放态自动跑)。
- 物体自动朝向行进方向；`path-angle-offset`(°) 校正"头"的朝向；模型另有 `path-anim-clip`（行进时播的骨骼动画名，如 `Walk`）。
- `path-camera-follow`(false) 开启第三人称跟拍（巡检漫游）：`path-follow-distance`(0=引擎默认) + `path-follow-angle`(35°)；跟拍期间手动操控视角无效。
- 编辑态不跑（避免与 gizmo 抢变换）；运行层用 `scene3dPathControl` 动作播放/暂停/复位。

### 7b.3 事件（播放态）

- **触发器**（写在 scene-3d 的 `options.interactions`）：
  - `scene3d-piece-click`（payload `pieceUid`/`name`/`pieceType`，几何拾取另含命中世界坐标 `hitX`/`hitY`/`hitZ`；命中模型内部命名部件时再含 `objectName`(最近命名节点)/`objectPath`(命名链 `a/b/c`,同层重名段带 #N 序号可精确区分)——动作选项里可用 `{{payload.objectName}}`/`{{payload.objectPath}}` 占位引用；条目里 action 加 `"triggerTarget": "<piece uid>"` 可精确到某个元素，**子对象级分流**用复合键 `"<piece uid>#<子对象名或路径>"`（如 `w_toll#SF001`，按 路径键→名称键→uid 优先匹配——"点谁的部件给谁的动作/数据"）；值标签/标记点点击也派发）；
  - `scene3d-piece-dblclick`（双击元素；payload 同点击；配 `scene3dFocus`（目标留空）= 双击聚焦任意元素）；
  - `scene3d-piece-contextmenu`（右键元素；payload 同点击；配 `scene3dPopup`/`scene3dHighlight` 等 = 右键菜单式交互）；
  - `scene3d-piece-hover`（悬停进入/离开各派发一次，payload 多 `phase`:`enter`/`leave`，enter 时命中模型内部部件同样带 `objectName`/`objectPath`；同样支持 triggerTarget；配合「后期效果」的 `outline-hover` 自动描边与 `hover-tip`+`hover-tip-sub` 气泡显示部件名）；
  - `scene3d-blank-click`（未命中任何元素）。
- **动作**：
  - `scene3dFlyTo`（`view-uid` 书签优先，否则 `fly-position`+`fly-target`，`fly-transition` 平滑）；
  - `scene3dFocus`（聚焦元素：相机按包围盒自动取景 fitToBox；`piece-uid` 留空=用触发 payload 的 pieceUid（配点击/双击触发器="点谁聚焦谁"），`object-name` 填模型内部件名称/路径可只聚焦该部件（填 `{{payload.objectPath}}`="双击部件聚焦部件"），`padding` 取景留白(1)，`fly-transition`；CSS2D 类元素退回按 position 斜上方取景）；
  - `scene3dWritePoint`（`key`+`value` 或 `payload-field`）；
  - `scene3dExplode`（`piece-uid` 留空=全部模型，`object-name` 填部件名称/路径（支持 `{{payload.objectPath}}`）=只炸开该部件子树，`mode`:`explode`/`reset`，`time`/`distance` 0=自适应按部件分布尺寸；需**多部件**，单网格拆不开）；
  - `scene3dHighlight`（`piece-uid` 留空=全部可高亮元素（支持 `{{payload.pieceUid}}` 占位），`effect`:`outline`/`bloom`，`mode`:`on`/`off`/`toggle`；整元素级——部件级用下面的 scene3dSubStyle）；
  - `scene3dSubStyle`（**模型子对象样式**：`piece-uid` 留空=payload 的 pieceUid 再空=全部模型，`object-name` 部件名称/路径（`*` 通配、`|` 多选）留空=payload 的 objectPath（配点击触发器="点谁亮谁"部件级），`mode`:`highlight` 重涂+自发光高亮/`clear` 恢复/`show`/`hide`/`toggle`，`color`(#ff4d4f)+`opacity`(1=不改,仅 highlight 用)。材质克隆替换不动原模型，`clear` 或会话结束恢复）；
  - `scene3dSetVisible`（`piece-uid` 必填，`mode`:`show`/`hide`/`toggle`，运行态临时显隐）；
  - `scene3dPlayAnim`（模型骨骼动画：`piece-uid` 留空=全部模型，`anim-index`，`mode`:`play`/`stop`）；
  - `scene3dPathControl`（路径动画：`piece-uid` 留空=全部配置路径的元素，`mode`:`play` 续播/`pause`/`reset` 回配置位）；
  - `scene3dPopup`（元素信息弹窗：`mode`:`open`/`close`，`piece-uid` 留空=用触发 payload 的 pieceUid（配点击/悬停触发器="点谁弹谁"），`object-name` 填部件名称/路径或 `{{payload.objectPath}}` 时弹窗锚到该部件、标题留空自动用部件名，`title` 留空=元素名，`content` 每行「标签=值」两栏或纯文本——title/content 支持 `{{payload.字段}}` 占位（如 `部件={{payload.objectName}}`）；弹窗悬浮在元素/部件包围盒顶部、带关闭按钮）；
  - `scene3dSnapshot`（场景截图并下载 png）；
  - `scene3dClip`（剖切分析运行时控制：`mode`:`on`/`off`/`toggle`/`set` 仅改参数/`reset` 清除覆盖回落场景选项；`axis`/`position`/`invert` 留空=不改。配多个按钮做剖切面步进）；
  - `scene3dSetOption`（万能联动：运行时改任意元素选项——`piece-uid`+`option` 选项名+`value`（JSON 优先解析，非 JSON 按原文）。日夜切换=改 scene 的 `sky-preset`、灯光强度=改 light 的 `light-intensity`、换色/换转速同理；播放会话内生效、不记历史）；
  - `scene3dTween`（补间动画：`piece-uid` 留空=用触发 payload 的 pieceUid，`object-name` 非空=作用于模型内匹配的命名子对象（* 通配 | 多选，可填 `{{payload.objectName}}`——收费站抬杆/开合门），`mode`:`start`/`toggle`(往复：原位↔目标值，点一次抬起再点降下)/`stop`(停在当前值)，`property`:`position`/`rotation`(度)/`scale`，`to` 目标值 [x,y,z]，`relative`(false 相对当前值偏移；toggle 抬杆常配 relative+`[0,0,90]`)，`duration`(1000ms)，`easing` 12 种缓动（`linear`/`easeOutQuad`/`easeInOutQuad`/`easeInOutCubic`/`easeOutQuart`/`easeOutExpo`/`easeInOutSine`/`easeOutBack` 过冲回位/`easeInBack`/`easeOutElastic` 弹性/`easeOutBounce` 落地弹跳/`easeInBounce`），`loop`:`once`/`yoyo` 往返一次/`yoyo-forever` 呼吸浮动/`loop-forever`。同目标同属性重复触发自动接管；作用于有三维实体的元素（形状/模型/拉伸体/贴片等），CSS2D 类静默跳过；运行态不落选项）；
  - `scene3dPersonTrail`（人员轨迹回放：`persons-uid` 留空=全部人员图层，`person-id` 留空=触发 payload 的 personId → 当前选中人员 → 轨迹最长/第一个人（侧栏按钮无需先点中某人），`mode`:`toggle`/`play`/`stop`，`camera-follow`(true 相机跟随)，`duration`(0=按轨迹长度自动,每点约 0.8s 上限 20s)。隐藏本尊、克隆替身沿历史轨迹行进（人物模型档替身沿途播行走动画并朝行进方向；sprite 引擎路径模块不可用时本地沿折线补间），结束自动恢复）；
  - `scene3dNetRoute`（最近出口路线：`net-uid` 留空=首个管网，`persons-uid`/`person-id` 同上定位起点人员，`mode`:`toggle`/`show`/`clear`，`route-color`(#ffd700)。按管网拓扑取度为 1 的端点作出口集合，把人员投影到折线后求最短路径，渲染「逃生指引」组合——断面稍大的高亮管段 + 指向出口的流动箭头贴图 + 起点红色脉冲环 + 出口绿色呼吸光柱/双脉冲环/「安全出口」标牌——矿井撤离/园区疏散路线）。

### 7b.4 VP-TSX 写法示例

```tsx
<scene-3d uid="w_scene" position={[24, 96]} size={[1200, 800]}
  scene3d-initialized={true}
  point-key-field={bind('conn_pts', 'tbl_pts', '测点')}
  point-value-field={bind('conn_pts', 'tbl_pts', '数值')}
  pieces={[
    { uid: 'scene3d-scene', type: 'scene3d-scene', options: { 'bg-mode': 'color', 'scene-bg': '#0a0f1c', 'env-mode': 'room' } },
    { uid: 'scene3d-camera', type: 'scene3d-camera', options: { position: [16, 12, 16], target: [0, 1, 0], 'cruise-mode': 'orbit' } },
    { uid: 'l_amb', type: 'scene3d-light', options: { 'light-kind': 'ambient', 'light-intensity': 0.6 } },
    { uid: 'l_sun', type: 'scene3d-light', options: { 'light-kind': 'directional', 'light-intensity': 2.2, position: [12, 18, 8], 'cast-shadow': true } },
    { uid: 'p_ground', type: 'scene3d-shape', options: { shape: 'plane', 'shape-size': [30, 0.1, 30], position: [0, 0, 0], 'mat-color': '#141a26', 'cast-shadow': false } },
    { uid: 'p_box', type: 'scene3d-shape', options: { shape: 'box', position: [0, 1, 0], 'data-key': 'PUMP', 'state-rules': '1=#22c55e\n0=#94a3b8\nfault=#ef4444', 'blink-values': 'fault' } },
    { uid: 'lb_box', type: 'scene3d-label', options: { 'label-text': '1#泵', 'data-key': 'FLOW', unit: ' m³/h', position: [0, 2.6, 0] } },
  ]} />
```

- 完整可导入示例（每个 `.vp.tsx` 源码与编译产物 `.vpproj.json` 成对，README 有全表）：
  - `data/三维/元素/`（**40 对，逐元素**：每个 piece type 一例，学单元素选项首选）；
  - `data/三维/场景/`（**45 对，逐功能→综合**：01~18 逐功能、19~30 综合大屏、31~39 GIS 与新能力、40~42 组态实战·冷站群控/化工罐区/110kV 变电站、43 人员定位、44 智慧家居、45 收费站车流）。
  - 完整清单与标签见 [examples/catalog.md](../../examples/catalog.md)。