---
name: vjmap3d
description: Use when building 3D map/scene applications with vjmap3d (唯杰地图三维引擎, based on three.js, v2 supports WebGL/WebGPU dual engines) — creating App, Service and MapViewEntity (CAD drawing as ground), entities (MeshEntity / FillExtrusionsEntity / PolygonsEntity / PolylinesEntity / GlLinesEntity / sprites / SymbolEntity), coordinate transforms (CAD↔world↔screen, mapToWorld, toDist), camera/control, events and picking, particles, post-processing, Marker2D/3D, Popup2D, plugins (3D Tiles / physics / loaders), and embedding as a 3D layer in vjmap 2D. Keywords vjmap3d three 三维 MapViewEntity FillExtrusionsEntity WebGPU mapToWorld toDist Marker3D. Peer three per published package (npm vjmap3d@2.0.0 declares three >=0.185). Excludes vjmap 2D base map (use vjmap skill), vjcad, vjvp.
metadata:
  product: map3d
  package: vjmap3d
  packageVersion: "2.0.0"
  peerPackage: three
  docsMcp: https://vjmap.com/server/aimcp/mcp?products=map3d
---

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

```yaml
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 示例为准**：

| 来源 | 入口 |
|---|---|
| 官方文档/示例 MCP | `https://vjmap.com/server/aimcp/mcp?products=map3d`（工具：`list_docs` / `search_docs` / `get_doc_content`）。路径前缀：`map3d/docs/...`（官方文档）、`map3d/example/...`（示例源码，15 个子目录：animation/entity/particle/threejs/ui 等）；类型定义 `vjmap3d.d.ts` 约 1.7MB，按需指定行范围读取 |
| npm 包类型定义 | `npm i vjmap3d` 后看 `node_modules/vjmap3d/dist/vjmap3d.d.ts` |
| 离线参考 | 本目录 `references/`（产品介绍 [references/README.md](references/README.md)，分类见下方速查表） |

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

## 安装与模板

```bash
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](templates/vite-app/README.md)）
- **纯 HTML / CDN 模板** → `templates/cdn/`（importmap 引 three 与 vjmap3d，无构建）

```js
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](references/graphics/coordTransform.md)）。`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 地图操作习惯一致。

## 按场景速查

| 要做什么 | 去读 |
|---|---|
| 创建应用、App 模块（渲染/场景/相机/控制/事件/坐标/统计） | [core/app](references/core/app.md) · [guide/createapp](references/guide/createapp.md) · [guide/quickstart](references/guide/quickstart.md) |
| WebGL / WebGPU 切换与差异 | [advance/webgpu](references/advance/webgpu.md) |
| 实体/模块/Object3D 关系、自定义模块 | [core/entity](references/core/entity.md) · [core/module](references/core/module.md) · [guide/concept](references/guide/concept.md) · [guide/design](references/guide/design.md) |
| 事件与响应式（hover / click / 状态） | [core/event](references/core/event.md) · [entity/entityModule](references/entity/entityModule.md) |
| CAD 图作地面、多图、地形、坐标转换 | [entity/mapViewEntity](references/entity/mapViewEntity.md) · [graphics/service](references/graphics/service.md) · [graphics/coordTransform](references/graphics/coordTransform.md) |
| 相机控制、视角指示器、限制范围 | [graphics/camera](references/graphics/camera.md) |
| 多边形 / 折线 / GL 宽线 / 拉伸体（建筑白模） | [entity/polygonsEntity](references/entity/polygonsEntity.md) · [entity/polylinesEntity](references/entity/polylinesEntity.md) · [entity/glLinesEntity](references/entity/glLinesEntity.md) · [entity/fillExtrusionsEntity](references/entity/fillExtrusionsEntity.md) |
| 实例化 / 精灵图片 / 文字 / 标记 / 序列帧 / 符号 | [entity/instancedMeshEntity](references/entity/instancedMeshEntity.md) · [entity/spriteImagesEntity](references/entity/spriteImagesEntity.md) · [entity/spriteTextsEntity](references/entity/spriteTextsEntity.md) · [entity/spriteMarkerEntity](references/entity/spriteMarkerEntity.md) · [entity/spriteAnimatorEntity](references/entity/spriteAnimatorEntity.md) · [entity/symbolEntity](references/entity/symbolEntity.md) |
| Mesh 实体、内置几何体/材质/对象（天空盒/水面/光源） | [entity/meshEntity](references/entity/meshEntity.md) · [builtin/geometry](references/builtin/geometry.md) · [builtin/material](references/builtin/material.md) · [builtin/objects](references/builtin/objects.md) |
| 资源加载（GLTF / OBJ / 纹理）、加载器插件 | [graphics/resource](references/graphics/resource.md) · [plugin/loader](references/plugin/loader.md) |
| Marker2D/3D、Popup2D、右键菜单、控件、UI 配置 | [ui/marker2D](references/ui/marker2D.md) · [ui/marker3D](references/ui/marker3D.md) · [ui/popup2D](references/ui/popup2D.md) · [ui/contextMenu](references/ui/contextMenu.md) · [ui/control](references/ui/control.md) · [ui/uiconfig](references/ui/uiconfig.md) |
| 动画（补间/路径/关键帧）、行为、常用函数 | [advance/animation](references/advance/animation.md) · [advance/behavior](references/advance/behavior.md) · [advance/functions](references/advance/functions.md) |
| 粒子特效（火焰/烟/雨雪/流动） | [particle/useguide](references/particle/useguide.md) · [particle/particlesystem](references/particle/particlesystem.md) · [particle/particleemitter](references/particle/particleemitter.md) · [particle/simulation](references/particle/simulation.md) · [particle/particle](references/particle/particle.md) |
| 后处理（辉光/景深/描边/抗锯齿） | [postprocessing/postprocessing](references/postprocessing/postprocessing.md) |
| 拾取编辑、命令、键鼠输入 | [interaction/editor](references/interaction/editor.md) · [interaction/command](references/interaction/command.md) · [interaction/input](references/interaction/input.md) |
| 3D Tiles / 物理 / 几何算法插件 | [plugin/3dtiles](references/plugin/3dtiles.md) · [plugin/physics](references/plugin/physics.md) · [plugin/algorithm](references/plugin/algorithm.md) |
| 作为 vjmap 二维地图的 3D 图层 | [guide/createapp §做为唯杰地图的三维图层](references/guide/createapp.md) |
| Canvas2D 绘图转三维纹理材质（render2d 命名空间） | [advance/render2d](references/advance/render2d.md) |

## 红旗

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
```