vjmap3d — 唯杰地图三维引擎二次开发

pkg: vjmap3d@2.0.0        # npm 已发布（WebGPU 双引擎版）；peer: three >=0.185.0。旧版 1.0.23 为 webgl-only（peer three ^0.165）
docsMcp: https://vjmap.com/server/aimcp/mcp?products=map3d

本 skill 的 references/ 覆盖 vjmap3d v2 官方文档全部 53 篇（对应 map3d/docs/ 目录结构的离线副本，多篇含本 skill 的勘误与 npm 版增补——如 advance/webgpu.md 的 v2 版本要求、guide/quickstart.md 的 peer/TS 注记）。仍需更深细节时按下列来源查证，冲突时以 npm 包 dist/vjmap3d.d.ts 与 playground 示例为准：

示例里的 env.serviceUrl / env.accessToken / env.exampleMapId 是 playground 注入变量；自己项目里替换为你的服务地址与 token（公有云 https://vjmap.com/server/api/v1，私有化 http://<ip>:27660/api/v1，见 vjmap-service skill）。不要把 token 写进提交的代码。

安装与模板

npm i vjmap3d three          # three 为 peer 依赖。注意版本对齐：npm 上 vjmap3d@2.0.0 声明 peer `three@>=0.185.0`——装 `three@^0.185`；装 0.165 会 peer 冲突（pnpm 还会给 vjmap3d 单独再装一份 0.185 造成双 three）。旧版 vjmap3d@1.0.23（webgl-only）对应 `three@^0.165`
npm i -D @types/three        # 需要 three 类型提示时

• TS 工程：tsconfig.json 的 moduleResolution 建议 bundler（或 node16/nodenext）；旧的 node 解析方式请开 skipLibCheck: true。
• vite 模板 → templates/vite-app/（npm i 后 npm run dev，README）
• 纯 HTML / CDN 模板 → templates/cdn/（importmap 引 three 与 vjmap3d，无构建）

import * as THREE from "three";
import * as vjmap3d from "vjmap3d";
import "vjmap3d/dist/vjmap3d.min.css";

vjmap3d 是 ES 模块且内部 import "three"，纯 HTML 必须用 importmap 映射 three，不能 <script src>。three 版本须与所引 vjmap3d 的 peer 一致：npm vjmap3d@2.0.0 → three@0.185.x（此版 dist 在 WebGPU 引擎下动态 import three/webgpu/three/tsl，importmap 需保留这两条映射；webgl 引擎不触发）。旧版 1.0.23 用 three@0.165.x 且无需这两条。

心智模型

App（渲染器/场景/相机/控制/事件等模块的容器）
 └─ scene（three Scene）
     └─ Object3D（three 对象树）  ←→  Entity（模块容器，关联一个 Object3D）
                                         ├─ EventModule（悬停/点击/Popup）
                                         └─ 内置实体 = Entity + 对应 Module：
                                            MeshEntity / InstancedMeshEntity / PolygonsEntity / PolylinesEntity /
                                            GlLinesEntity / FillExtrusionsEntity / SpriteImagesEntity /
                                            SpriteTextsEntity / SpriteMarkerEntity / SpriteAnimatorEntity /
                                            SymbolEntity / MapViewEntity（CAD/瓦片地图作地面）

关键约定：

1. 创建顺序：new vjmap3d.Service(url, token) → new vjmap3d.App(svc, { container, render:{engine}, scene, camera, control }) → await app.whenReady() → 再加实体。（whenReady 自 v2.0.0 起提供：webgpu 引擎下渲染器异步初始化必须先等，webgl 下立即 resolve；旧版 1.0.23 无此方法，webgl 同步就绪可省略。）
2. 世界坐标：three 右手系 Y 向上（独立 App；MapThreeLayer 地图图层模式为 Z 向上，见 coordTransform）。MapViewEntity（baseScale）把 CAD 图映射为以图中心为原点、宽度 = baseScale 个世界单位的地面（mapBounds 须为正方形）：mapview.mapToWorld([x, y]) 得 Vector3，CAD +x → 世界 +x，CAD +y → 世界 −z；长度换算 vjmap3d.toDist(cad长度)；经纬度 mapview.lngLatToWorld([lng, lat])；二维 footprint（FillExtrusionsEntity 的 FillExtrusionItemData.coordinates 字段）用 [w.x, w.z]。
3. 三维对象位置用世界坐标：mesh.position.copy(mapview.mapToWorld(pt))，再 vjmap3d.Entity.fromObject3d(mesh).addTo(app)（不要直接 scene.add）。
4. 交互：entity.add(vjmap3d.EventModule, { hoverSelect, hoverHtmlText, popupOptions })；UI 用 Marker2D / Marker3D / Popup2D（setPosition(worldVec3)）。
5. 相机：app.cameraControl.setLookAt(px,py,pz, tx,ty,tz, animate) / loadState({ cameraPosition, cameraTarget })；control.leftButtonPan: true 与 2D 地图操作习惯一致。

按场景速查

红旗

1. 直接 scene.add(mesh) 而不用 Entity.fromObject3d → 没有实体模块（事件/高亮/动画）。
2. 用 CAD 坐标当世界坐标 → 物体在几亿单位外；一律先 mapToWorld。
3. footprint 写成 [w.x, -w.z] → 建筑上下颠倒/镜像。
4. webgpu 引擎下在 whenReady() 之前访问 app.renderer → 未初始化（webgpu/whenReady 自 v2.0.0 起提供，旧版 1.0.23 无此引擎与方法）。
5. <script src="three.min.js"> 或无 importmap 的裸 CDN → three 解析失败；三维只能 importmap + ES 模块（或打包器）。
6. 高度直接用"米"而不按图纸单位（mm 图 3 层楼 ≈ 10000）→ 拉伸看不见。
7. 忘引 vjmap3d/dist/vjmap3d.min.css → Marker2D/Popup2D/控件无样式。

参考目录

README.md   产品介绍（官方文档首页：定位、特点、双渲染引擎）
guide/      概念、设计、createapp、quickstart
core/       App、Entity、Module、Event
graphics/   相机、坐标转换、资源加载、Service
entity/     各内置实体 + entityModule 通用模块
builtin/    几何体、材质、内置对象
ui/         Marker2D/3D、Popup2D、右键菜单、控件、uiconfig
advance/    动画、行为、函数、webgpu、render2d
particle/   粒子系统 5 篇
postprocessing/ 后处理
interaction/ 编辑器、命令、输入
plugin/     3dtiles、loader、physics、algorithm