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

41 种 piece 目录与关键 options、测点数据驱动、路径动画、事件与动作、VP-TSX 写法。 返回目录：index.md；全量选项字典（最权威）：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

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 写法示例

<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 对，逐功能→综合：0118 逐功能、1930 综合大屏、3139 GIS 与新能力、4042 组态实战·冷站群控/化工罐区/110kV 变电站、43 人员定位、44 智慧家居、45 收费站车流）。
  • 完整清单与标签见 examples/catalog.md。