3D跨引擎API
npm install @anov/3d-cross-engine-api- 无框架依赖：原生 JS/TS 编写，可集成到任意 Web 框架。
- 模块化与插件机制：所有功能均模块化，支持插件式扩展。
- 多引擎适配：通过适配器模式，统一对接 Three.js、Unity、Unreal、Zorro 等主流 3D 引擎。
- 统一 API：对外暴露统一的 API，极大简化 3D 项目开发难度。
- 高扩展性：支持自定义实体、功能模块和引擎适配器。
``bash`
npm install @anov/3d-cross-engine-api
`javascript
import { CrossEngineApi, engineThree, engineUnreal, engineUnity, engineZorro } from '@anov/3d-cross-engine-api'
CrossEngineApi.registerEngine(engineThree, {})
CrossEngineApi.registerEngine(engineUnreal, {})
CrossEngineApi.registerEngine(engineUnity, {})
CrossEngineApi.registerEngine(engineZorro, {})
// 创建API实例
const api = await CrossEngineApi.createInstance({
engine: 'three', // 使用的引擎: 'three'/'unity'/'unreal'/'zorro'
el: document.getElementById('container'),
scc: {
/ 场景配置 /
}
custom: {
/ 自定义配置 /
}
})
// 相机操作
await api.camera.set({
position: [0, 10, 20],
target: [0, 0, 0]
})
// 创建POI
const poi = await api.poi.create({
position: [0, 0, 0],
name: '测试POI'
})
await poi.update({
position: [10, 0, 0]
})
`
`javascript
// 设置相机
await api.camera.set({
position: [0, 10, 20],
target: [0, 0, 0]
})
// 相机聚焦
await api.camera.focus({
position: [10, 0, 0],
distance: 20
})
// 相机跟随
await api.camera.follow({
target: 'model_1',
offset: [0, 5, 10]
})
`
`javascript
// 创建模型
const model = await api.model.create({
url: 'models/car.glb',
position: [0, 0, 0],
scale: [1, 1, 1],
rotation: [0, 0, 0]
})
// 创建POI
const poi = await api.poi.create({
position: [10, 0, 0],
name: '测试点位',
icon: 'icons/marker.png'
})
// 添加事件
poi.$on('click', res => {
console.log('点击了POI')
})
// 创建图层
const layer = await api.layer.create({
name: '建筑图层',
visible: true
})
// 批量操作
await api.batch.create({
type: 'poi',
data: [
{ position: [10, 0, 0], name: 'POI 1' },
{ position: [20, 0, 0], name: 'POI 2' },
{ position: [30, 0, 0], name: 'POI 3' }
]
})
`
`
src/
├── index.ts # API 入口
├── api/ # API 核心模块
│ ├── core/ # 基础模块与接口（BaseModule、EntityModule、ModuleManager 等）
│ ├── entities/ # 各类实体（poi、model、area、layer、group、batch、flyline、spline、heatMap、bar、mark、pointLight、realismTraffic、streamerTraffic）
│ ├── modules/ # 功能模块（scene、camera、environment、animation、material、tools）
│ ├── types/ # 类型定义（实体、模块、全局配置等）
│ ├── interfaces/ # API/实体/模块接口定义
│ ├── error/ # 错误处理
│ └── index.ts # API 模块入口
├── engines/ # 引擎适配器
│ ├── EngineAccess.ts # 引擎访问统一入口
│ ├── interface/ # 引擎接口定义
│ ├── types/ # 引擎相关类型
│ ├── three/ # Three.js 适配器
│ ├── unity/ # Unity 适配器
│ ├── unreal/ # Unreal 适配器
│ └── zorro/ # Zorro 适配器
├── Server/ # 消息通信与引擎管理
│ ├── msgManagement.ts # 消息管理
│ ├── mitt.ts # 事件总线
│ ├── utils.ts # 工具函数
│ ├── interfaces/ # 服务端接口
│ ├── types/ # 服务端类型
│ ├── EngineManagement/ # 引擎注册、实例管理、插件管理等
│ └── index.ts # 服务端入口
- api/core/：基础模块、实体/功能模块基类、模块管理器。
- api/entities/：所有 3D 场景中的实体类型。
- api/modules/：场景、相机、环境、动画、材质、工具等功能模块。
- api/types/、api/interfaces/：类型和接口定义，便于类型安全和 IDE 智能提示。
- engines/：各类 3D 引擎的适配器及接口。
- Server/：消息通信、引擎管理、事件分发等后端逻辑。
- BaseModule：所有模块的基类，内置事件机制（$on/$off/$once/$emit）。
- EntityModule：实体模块基类，封装实体的创建、更新、销毁等通用逻辑。
- EntityManager：统一管理所有实体，支持批量操作和层级关系。
- ModuleManager：统一管理所有功能模块。
- EngineAccess：引擎访问入口，屏蔽底层差异。
- Server：消息通信、引擎注册与实例管理。
`
BaseModule (基础模块)
├── EntityModule (实体模块基类)
│ ├── Poi
│ ├── Model
│ ├── Area
│ ├── Layer
│ ├── Group
│ ├── Batch
│ ├── FlyLine
│ ├── Spline
│ ├── HeatMap
│ ├── Bar
│ ├── Mark
│ ├── PointLight
│ ├── RealismTraffic
│ └── StreamerTraffic
└── Modules (功能模块基类)
├── Scene
├── Camera
├── Environment
├── Animation
├── Material
└── Tools
`
EntityManager (实体管理器)
├── 负责创建和管理所有实体
├── 提供实体查询和批量操作能力
└── 处理实体间的层级关系
跨引擎 API 支持多种 3D 引擎，通过适配器模式实现统一接口：
- Three.js 适配器
- Unity 适配器
- Unreal 适配器
- Zorro 适配器
`
Server (服务端)
├── MsgManagement (消息管理)
├── EngineManagement (引擎管理)
└── Utils (工具函数)
1. CrossEngineApi.createInstance(config) 创建 API 实例。
2. 加载所选引擎适配器，初始化 Server 消息系统。
3. 注册功能模块（scene、camera 等）和实体模块（poi、model 等）。
4. 初始化实体管理器，建立引擎通信。
5. 通过统一 API 进行场景、实体、相机等操作。
`
// 创建实体
1. api.poi.create(config)
→ 调用EntityModule实例方法
→ 通过消息系统发送创建请求
→ 引擎适配器接收并处理请求
→ 引擎执行实际创建操作
→ 返回实体引用ID和数据
→ 创建实体对象并添加到管理器
→ 返回实体对象给用户
// 更新实体
2. api.poi.update(config)
→ 获取目标实体
→ 通过消息系统发送更新请求
→ 引擎适配器处理更新
→ 更新本地实体数据
→ 返回更新结果
`
所有模块都继承了 BaseModule 中的事件机制：
- $on：注册事件监听器$off
- ：取消注册事件监听器$once
- ：注册一次性事件监听器$emit`：触发事件
-
- 自定义实体/模块：继承 EntityModule/BaseModule，实现自定义逻辑后注册到 EntityManager/ModuleManager。
- 适配新引擎：实现引擎接口，注册到 EngineAccess。
- 插件开发：通过插件注册机制扩展 API 能力。
| 实体类型 | 描述 |
| ------------------- | -------------------------------- |
| POI | 点位标注，用于标记地图上的兴趣点 |
| Model | 3D 模型，支持 gltf、glb 等格式 |
| Area | 区域，用于定义特定区域和边界 |
| Layer | 图层，用于组织和管理实体 |
| Group | 分组，用于组织相关实体 |
| Batch | 批量操作，提高大量实体操作性能 |
| FlyLine | 飞线，用于展示点到点的动态连接 |
| Spline | 曲线，用于创建平滑曲线 |
| HeatMap | 热力图，用于展示数据密度分布 |
| Bar | 柱状图，用于三维数据可视化 |
| Mark | 标记，简单的标记点 |
| PointLight | 点光源，增强场景光照效果 |
| RealismTraffic | 真实交通流，模拟真实交通流量 |
| StreamerTraffic | 流动交通，简化的交通流动效果 |
| 类型 | 描述 |
| ------------ | ------------------------------------------------- |
| feature | 新功能开发，例如添加新模块、新接口等 |
| fix | 修复 bug，代码错误修正或问题修复 |
| style | 代码风格调整，例如代码格式化、空格修复等 |
| docs | 文档相关的修改，例如更新 README、API 文档、注释等 |
| perf | 提升性能的改动，例如优化算法、改进查询速度等 |
| test | 添加或修改测试代码 |
| refactor | 代码重构，优化代码逻辑、删除冗余代码等 |
MIT