# TwinForge

**Repository Path**: mic-HAO/twin-forge

## Basic Information

- **Project Name**: TwinForge
- **Description**: TwinForge — 基于 Vue3 + TypeScript + Three.js + Vite 的 3D 数字孪生基础框架。提供模块化引擎架构、多格式模型加载（GLTF/FBX/OBJ）、灯光/材质/动画/交互/标注/后处理六大子系统、插件机制，以及 10+ Vue Composables 深度集成，开箱即用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 2
- **Created**: 2026-04-30
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TwinForge

基于 **Vue 3 + TypeScript + Three.js + Vite** 的 3D 数字孪生基础框架。提供模块化引擎架构、多格式模型加载（GLTF/FBX/OBJ）、灯光/材质/动画/交互/标注/后处理六大子系统、插件机制，以及 10+ Vue Composables 深度集成，开箱即用。

[English](./README.en.md)

## 效果展示

### 整体界面

3D 视口 + 右侧控制面板，支持相机、灯光、材质、后处理、动画、辅助工具等全方位控制。

![整体界面](./docs/images/demo-overview.png)

### 材质模式切换

一键切换四种显示模式，适用于不同的观察与分析场景：

| 默认渲染 | 线框模式 |
|:---:|:---:|
| ![默认](./docs/images/Material-1.png) | ![线框](./docs/images/Material-2.png) |
| 标准 PBR 材质渲染，还原真实质感 | 绿色线框显示，清晰展示模型网格结构 |

| X-Ray 透视 | 透明模式 |
|:---:|:---:|
| ![X-Ray](./docs/images/Material-3.png) | ![透明](./docs/images/Material-4.png) |
| 蓝色辉光透视效果，可观察内部结构 | 半透明显示，查看模型层叠关系 |

### 后处理效果

支持 Bloom 辉光、Outline 轮廓描边、SSAO 环境光遮蔽、FXAA 抗锯齿，可动态组合启停。

![后处理效果](./docs/images/feature-postprocess.png)

## 特性

- **模块化引擎架构** — 核心引擎 + 子系统注册机制，各功能模块可独立装卸
- **多格式模型加载** — 支持 GLTF/GLB、FBX、OBJ 格式，内置 Draco 压缩解码
- **灯光系统** — 支持 5 种灯光类型（环境光、方向光、点光源、聚光灯、半球光），内置多套灯光预设
- **材质系统** — 一键切换线框、透明、X-Ray 等显示模式，支持材质预设与原始材质恢复
- **动画系统** — AnimationMixer 集成 + Tween 补间动画管理
- **射线拾取** — 支持点击、悬停、框选等交互事件
- **标注系统** — CSS2D / CSS3D 两种标注适配器
- **后处理效果** — Bloom、Outline、SSAO、FXAA 四种效果，支持动态启停
- **插件机制** — 统一的插件接口，便于功能扩展
- **Vue 深度集成** — 10+ 组合式函数（Composables）封装引擎功能，响应式数据驱动
- **TypeScript 全量类型** — 严格模式，所有 API 均有完整类型定义

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Vue 3.5（Composition API + `<script setup>`） |
| 3D 引擎 | Three.js 0.175 |
| 状态管理 | Pinia 3 |
| UI 组件库 | Element Plus 2.9 |
| 构建工具 | Vite 6 |
| 语言 | TypeScript 5.7（strict） |
| 样式 | SCSS + CSS Variables |
| HTTP | Axios |
| 工具库 | VueUse、@tweenjs/tween.js |
| 代码规范 | ESLint 9 + Prettier + Stylelint + Commitlint + Husky |

## 软件架构

### 引擎架构

```
Engine（引擎主类）
├── EventBus          事件总线 — 子系统间通信
├── Clock             高精度计时器 — 驱动帧更新
├── RendererManager   渲染器 — WebGL 渲染管理
├── SceneManager      场景管理 — 支持多场景切换
├── CameraSystem      相机系统 — 透视/正交 + OrbitControls
└── Systems Map       子系统注册表
    ├── modelLoader       模型加载器
    ├── lights            灯光系统
    ├── materials         材质系统
    ├── animation         动画系统
    ├── tween             补间动画
    ├── raycaster         射线拾取
    ├── labels            标注系统
    ├── postProcessing    后处理管线
    └── plugins           插件管理器
```

### 项目结构

```
src/
├── engine/                    # 3D 引擎核心
│   ├── core/                  # 核心子系统
│   │   ├── Engine.ts          #   引擎主类（生命周期、渲染循环）
│   │   ├── RendererManager.ts #   WebGL 渲染器管理
│   │   ├── SceneManager.ts    #   多场景管理
│   │   ├── CameraSystem.ts    #   相机系统（透视/正交、控制器）
│   │   └── Clock.ts           #   高精度计时器
│   ├── loaders/               # 模型加载
│   │   ├── ModelLoader.ts     #   模型加载主管理器
│   │   ├── LoaderCache.ts     #   加载结果缓存
│   │   ├── GLTFLoaderAdapter.ts #  GLTF/GLB 适配器（含 Draco）
│   │   ├── FBXLoaderAdapter.ts  #  FBX 适配器
│   │   ├── OBJLoaderAdapter.ts  #  OBJ 适配器
│   │   └── TextureLoader.ts   #   纹理加载管理
│   ├── lights/                # 灯光系统
│   │   ├── LightSystem.ts     #   灯光创建、管理与辅助器
│   │   └── LightPresets.ts    #   内置灯光预设（Studio/Outdoor/Warehouse）
│   ├── materials/             # 材质系统
│   │   ├── MaterialSystem.ts  #   材质切换与原始材质备份/恢复
│   │   └── MaterialPresets.ts #   内置材质预设
│   ├── animation/             # 动画系统
│   │   ├── AnimationSystem.ts #   Three.js AnimationMixer 封装
│   │   └── TweenManager.ts    #   Tween 补间动画管理
│   ├── interaction/           # 交互系统
│   │   └── RaycasterSystem.ts #   射线拾取（点击/悬停/框选）
│   ├── labels/                # 标注系统
│   │   ├── LabelSystem.ts     #   标注管理器
│   │   ├── CSS2DLabelAdapter.ts # CSS2D 标注适配器
│   │   └── CSS3DLabelAdapter.ts # CSS3D 标注适配器
│   ├── postprocessing/        # 后处理管线
│   │   ├── PostProcessingPipeline.ts # 后处理管线管理器
│   │   └── effects/           #   内置效果
│   │       ├── BloomEffect.ts #     辉光
│   │       ├── OutlineEffect.ts #   轮廓描边
│   │       ├── SSAOEffect.ts  #     环境光遮蔽
│   │       └── FXAAEffect.ts  #     快速近似抗锯齿
│   ├── plugins/               # 插件系统
│   │   └── PluginManager.ts   #   插件注册与生命周期管理
│   ├── helpers/               # 辅助工具
│   │   ├── GridHelper.ts      #   网格辅助器
│   │   ├── AxesHelper.ts      #   坐标轴辅助器
│   │   └── StatsPanel.ts      #   性能统计面板
│   ├── events/                # 事件系统
│   │   └── EventBus.ts        #   类型安全的事件总线
│   ├── utils/                 # 工具函数
│   │   ├── dispose.ts         #   GPU 资源深度销毁
│   │   ├── math.ts            #   数学工具（包围盒、角度转换）
│   │   └── logger.ts          #   分级日志器
│   ├── types/                 # TypeScript 类型定义
│   └── index.ts               # 引擎统一导出入口
├── composables/               # Vue 组合式函数
│   ├── useEngine.ts           #   引擎初始化 & provide/inject
│   ├── useScene.ts            #   场景操作
│   ├── useModel.ts            #   模型加载
│   ├── useCamera.ts           #   相机控制
│   ├── useLights.ts           #   灯光控制
│   ├── useMaterial.ts         #   材质切换
│   ├── useAnimation.ts        #   动画播放
│   ├── useRaycaster.ts        #   射线拾取
│   ├── useLabels.ts           #   标注管理
│   ├── usePostProcessing.ts   #   后处理效果
│   └── useEngineEvent.ts      #   事件订阅（自动清理）
├── stores/                    # Pinia 状态管理
│   ├── sceneStore.ts          #   场景状态
│   ├── modelStore.ts          #   模型注册、选中、可见性
│   ├── uiStore.ts             #   UI 面板状态
│   └── settingsStore.ts       #   全局设置
├── components/                # Vue 组件
│   ├── engine/                #   引擎组件
│   │   ├── ThreeCanvas.vue    #     3D 画布容器
│   │   └── LoadingOverlay.vue #     加载进度覆盖层
│   ├── panels/                #   控制面板
│   ├── toolbar/               #   工具栏
│   └── common/                #   通用组件
├── views/                     # 页面视图
│   ├── HomeView.vue           #   首页
│   ├── SceneView.vue          #   场景编辑页
│   └── DemoView.vue           #   功能演示页
├── layouts/
│   └── MainLayout.vue         #   主布局（侧边栏 + 内容区）
├── services/                  # 服务层
│   ├── api/                   #   Axios 请求封装
│   └── ScenePresetService.ts  #   场景预设服务
├── styles/                    # 全局样式
├── router/                    # 路由配置
├── App.vue                    # 根组件
└── main.ts                    # 应用入口
```

## 安装教程

### 环境要求

- Node.js >= 18
- pnpm（推荐）或 npm / yarn

### 安装与运行

```bash
# 1. 克隆仓库
git clone https://gitee.com/your-username/TwinForge.git
cd TwinForge

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器
pnpm dev

# 4. 生产构建
pnpm build

# 5. 预览构建结果
pnpm preview
```

## 使用说明

### 基础用法 — ThreeCanvas 组件

```vue
<template>
  <ThreeCanvas :engine-options="options" @ready="onReady">
    <LoadingOverlay :visible="loading" :percentage="progress" />
  </ThreeCanvas>
</template>

<script setup lang="ts">
import type { Engine } from '@/engine'

const options = { antialias: true, shadowMap: true }

function onReady(engine: Engine) {
  // 引擎已就绪，可操作场景、加载模型等
  const scene = engine.sceneManager.createScene('main')
  const loader = engine.getSystem('modelLoader')
  // ...
}
</script>
```

### 在子组件中使用 Composables

```ts
import { useEngineInstance } from '@/composables/useEngine'
import { useModel } from '@/composables/useModel'

const engine = useEngineInstance()
const { loadModel, progress, isLoading } = useModel()

await loadModel('/models/example.glb', { castShadow: true })
```

### 自定义插件

实现 `IEnginePlugin` 接口即可创建自定义插件：

```ts
import type { IEnginePlugin } from '@/engine'

const myPlugin: IEnginePlugin = {
  name: 'my-plugin',
  install(engine) {
    engine.eventBus.on('object:click', ({ object }) => {
      console.log('点击了:', object.name)
    })
  },
  dispose() {
    // 清理资源
  },
}
```

### 引擎配置项

```ts
interface EngineOptions {
  antialias?: boolean          // 抗锯齿（默认 true）
  alpha?: boolean              // 透明背景（默认 false）
  shadowMap?: boolean          // 阴影贴图（默认 true）
  pixelRatio?: number | 'auto' // 像素比（默认 'auto'）
  toneMapping?: ToneMapping    // 色调映射（默认 ACESFilmicToneMapping）
  toneMappingExposure?: number // 曝光度（默认 1.0）
  renderQuality?: 'high' | 'medium' | 'low' // 渲染质量
  enablePostProcessing?: boolean // 后处理（默认 true）
  enableLabels?: boolean       // 标注系统（默认 true）
  debug?: boolean              // 调试模式（默认 false）
}
```

### 模型放置

将 3D 模型文件放入 `public/models/` 目录，支持以下格式：

| 格式 | 扩展名 | 说明 |
|------|--------|------|
| glTF / GLB | `.gltf` `.glb` | 推荐格式，支持 Draco 压缩 |
| FBX | `.fbx` | 支持骨骼动画 |
| OBJ | `.obj` | 基础网格格式 |

## 可用脚本

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 启动开发服务器 |
| `pnpm build` | 类型检查 + 生产构建 |
| `pnpm preview` | 预览生产构建结果 |
| `pnpm type-check` | 仅运行 TypeScript 类型检查 |
| `pnpm lint` | ESLint 检查并自动修复 |
| `pnpm lint:style` | Stylelint 检查并自动修复 |
| `pnpm format` | Prettier 格式化 |

## 浏览器兼容性

需要支持 WebGL 2.0 的现代浏览器：

- Chrome >= 90
- Firefox >= 90
- Safari >= 15
- Edge >= 90

## 参与贡献

1. Fork 本仓库
2. 新建 `feat/xxx` 分支
3. 提交代码（遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范）
4. 新建 Pull Request

## 开源协议

[MIT](./LICENSE)