@anov/3d-cross-engine-api

核心设计理念

• 无框架依赖：原生 JS/TS 编写，可集成到任意 Web 框架。
• 模块化与插件机制：所有功能均模块化，支持插件式扩展。
• 多引擎适配：通过适配器模式，统一对接 Three.js、Unity、Unreal、Zorro 等主流 3D 引擎。
• 统一 API：对外暴露统一的 API，极大简化 3D 项目开发难度。
• 高扩展性：支持自定义实体、功能模块和引擎适配器。

安装

npm install @anov/3d-cross-engine-api

快速开始

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]
})

使用示例

相机控制

// 设置相机
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]
})

实体操作

// 创建模型
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 | 代码重构，优化代码逻辑、删除冗余代码等 |

License

MIT