三维场景子系统

三维场景（scene-3d）是一个搭建型（builder）组件，用于真三维数字孪生 / 三维组态：园区、工厂、机房、管廊、城市等场景由三维元素（模型 / 形状 / 楼群 / 管道 / 光柱 / 看板……）搭成，由测点数据驱动状态色、液位、流动、告警闪烁，并带完整的播放态交互（点击 / 双击 / 右键 / 悬停 / 聚焦 / 弹窗）。

• 内核：vjmap3d（three.js 体系），默认 WebGPU 渲染、浏览器不支持自动回退 WebGL；特效材质在 WebGPU 下自动走 TSL 转译。
• 定位互补：2D 地图子系统管"地图上的平面标绘"，组态 SCADA 管"工艺流程图"，三维场景管"真三维空间"。三者可同页混排。

上手最快的方式

编辑器里从组件库拖入「三维场景」，双击进入后左栏变为 3D 组件库（50 张预设卡，按 场景 / 灯光 / 基础 / 形状 / 模型 / 标注 / 组态 / 特效 分组，中文拼音可搜），拖拽即插入；或直接导入示例工程——data/三维/场景/ 45 个逐功能 / 综合 / 行业实战大屏 + data/三维/元素/ 40 个逐组件（见示例库）。想先看效果再动手：三维元素手册的五个分类页里，每种元素都有一份在线预览（跑 vjmap 官方公开服务，联网即可出图），用的就是 data/三维/元素/ 里那个逐组件工程的场景。

在线演示

零素材的科技感展示平台：程序化星空 + 环境反射 + 七种几何体 × 六种材质 + 发光边界线 + 视角书签，全部由 pieces 搭成。点开后可拖拽旋转、滚轮缩放，右侧参数面板可实时改选项。

scene-3d

三维场景按需加载（每个场景独占一个 GPU 上下文，同页只保留一个活跃预览）

预览即 data/三维/元素/01-scene-场景设置.vpproj.json，跑 vjmap 官方公开服务，联网即可出图。三维每个场景独占一个 GPU 上下文，故预览按需加载。

结构：场景 + pieces

三维内容全部放在 pieces 数组里。前两个是固定 uid 的单例：场景设置 scene3d-scene 与相机 scene3d-camera（不可删除）；其余元素按需添加。

{
  "uid": "w_scene", "type": "scene-3d",
  "options": {
    "position": [0, 0], "size": [1920, 1080],
    "scene3d-initialized": true,                    // ⚠️ 写 true 禁止首挂播种演示场景
    "point-key-field":  [["conn_pts", "tbl_pts", "测点"]],   // 测点长表：键列
    "point-value-field": [["conn_pts", "tbl_pts", "数值"]]   // 测点长表：值列
  },
  "pieces": [
    { "uid": "scene3d-scene",  "type": "scene3d-scene",  "options": { "bg-mode": "sky", "sky-preset": "night", "env-mode": "room" } },
    { "uid": "scene3d-camera", "type": "scene3d-camera", "options": { "position": [24, 16, 28], "target": [0, 2, 0], "entry-fly": true } },
    { "uid": "l_sun", "type": "scene3d-light", "options": { "light-kind": "directional", "light-intensity": 1.6, "cast-shadow": true } },
    { "uid": "p_box", "type": "scene3d-shape", "options": { "shape": "box", "position": [0, 1, 0], "data-key": "STATE", "state-rules": "fault=#ef4444" } }
  ]
}

能力地图

领域	覆盖
场景与环境	程序化天空四预设（星空/晚霞/晨曦/极光）、全景图/HDR、环境反射、线性雾/指数雾、无限网格、剖切分析、服务级联
相机	初始视角、入场飞入、自动环绕/书签巡航/路径漫游、第一人称行走（WASD）、小地图（可随航向旋转）、操控限制
建模	七种几何体 × 六种材质（PBR/全息/玻璃/流光渐变/Shadertoy/镜面）、拉伸体（棱线发光）、批量楼块、批量实例（InstancedMesh 万级同模型）、外部模型（glb/gltf/fbx/obj/3ds）、倾斜摄影 3D Tiles、CAD 转 3D
GIS 底图	瓦片地图（OSM/高德/天地图/自定义/CAD 图纸瓦片/CAD WMS 叠加）、局部根瓦片、行政区裁剪、terrain-rgb 地形
组态件	管道/管网拓扑、光墙围栏、雷达、热力图、导引线、线条（生长/跑马）、液位罐、区域面、视频面板、LED 字幕屏、数据点云、人员点位（定位数据差分补间+轨迹）、车流（闸口过车模拟）
标注	值标签、三维文字、标记点、动效标记（引擎成品光圈动效）、光柱标记、数据看板牌、图表贴片（真三维图表面板）、HTML 面板（CSS3D）、图标点位（批量精灵+文字）、测量标注
特效	后期辉光/交互描边/悬停气泡、粒子（火/烟/雨/雪/烟花/文字聚字/自定义）、序列帧动画、Lottie 动画、镜头光晕、自转/呼吸脉动/路径动画
数据驱动	测点长表绑定、状态色/闪烁/流动规则、JSON 整批刷新、运行层写测点
交互	点击/双击/右键/悬停/空白五触发器（含命中世界坐标），飞行/聚焦/爆炸/高亮/显隐/动画/弹窗/截图/剖切/改选项/补间动画/人员轨迹回放/最近出口路线等 16 个专有动作

全部元素与选项见三维元素手册（五个分类页每种元素都带在线预览、全量属性表与可复制 JSON）；数据与交互详见测点数据驱动与播放态交互。

服务与多实例

• 引擎服务级联：scene3d-scene 的 service-url/service-token 留空 → 项目设置 → 全局默认（vjmap 公开演示服务）。CAD 转 3D、CAD 图纸瓦片等能力依赖该服务可达。
• 同页多实例：一页最多 4 个 scene-3d，互不串扰、各自巡航；页签隐藏自动暂停渲染。

与 AI / 代码协作

• 三维场景完整支持 VP-TSX 双向环路：page_export_tsx 导出整工程代码（pieces 原样往返）、改后 page_apply_project 应用回页面；编辑器「另存为」也可直接导出 .vp.tsx 整工程代码。见 VP-TSX 双向环路。
• AI 查证路径（不要用 vjmap 三维 SDK / list_docs path:map3d 猜选项名）：
  1. get_doc({ type: "scene-3d" }) 取本页总览与最小配方；get_doc({ type: "scene3d-shape" }) 或 docId: "scene3d/pieces" 取元素手册。
  2. get_widget_metadata({ type: "scene-3d" }) 返回 childPieces（41 种元素 type）；再对每个要用的 piece type 调一次 metadata，只写返回的 optionPath。
  3. apply 报未知选项时对照 metadata 改名重试，不要删成空场景。
• 元素选项字典由源码自动导出（widget-schema.generated.json），MCP 的 page_get_schemas / get_widget_metadata 是选项路径的唯一权威。