# 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

A **Vue 3 + TypeScript + Three.js + Vite** 3D digital twin framework. Features a modular engine architecture, multi-format model loading (GLTF/FBX/OBJ), six core subsystems (lighting, materials, animation, interaction, labels, post-processing), a plugin system, and 10+ Vue Composables for deep integration — ready out of the box.

[中文文档](./README.md)

## Screenshots

### Overview

3D viewport with a right-side control panel supporting camera, lighting, materials, post-processing, animation, and helper tools.

![Overview](./docs/images/demo-overview.png)

### Material Modes

Switch between four display modes for different observation and analysis scenarios:

| Default Rendering | Wireframe |
|:---:|:---:|
| ![Default](./docs/images/Material-1.png) | ![Wireframe](./docs/images/Material-2.png) |
| Standard PBR material with realistic textures | Green wireframe revealing mesh topology |

| X-Ray | Transparent |
|:---:|:---:|
| ![X-Ray](./docs/images/Material-3.png) | ![Transparent](./docs/images/Material-4.png) |
| Blue glow see-through effect for internal inspection | Semi-transparent view showing layer relationships |

### Post-Processing Effects

Bloom, Outline, SSAO, and FXAA effects that can be dynamically combined and toggled.

![Post-Processing](./docs/images/feature-postprocess.png)

## Features

- **Modular Engine Architecture** — Core engine with a subsystem registry; each module can be independently registered or removed
- **Multi-Format Model Loading** — GLTF/GLB, FBX, OBJ support with built-in Draco decoder
- **Lighting System** — 5 light types (Ambient, Directional, Point, Spot, Hemisphere) with built-in presets
- **Material System** — One-click wireframe, transparent, X-Ray display modes with preset management and original material restoration
- **Animation System** — Three.js AnimationMixer integration + Tween animation management
- **Raycasting** — Click, hover, and box-select interaction events
- **Label System** — CSS2D / CSS3D label adapters
- **Post-Processing** — Bloom, Outline, SSAO, FXAA effects with dynamic enable/disable
- **Plugin System** — Unified plugin interface for extensibility
- **Deep Vue Integration** — 10+ composable functions wrapping engine capabilities with reactive data binding
- **Full TypeScript Types** — Strict mode enabled, complete type definitions for all APIs

## Tech Stack

| Category | Technology |
|----------|-----------|
| Framework | Vue 3.5 (Composition API + `<script setup>`) |
| 3D Engine | Three.js 0.175 |
| State Management | Pinia 3 |
| UI Library | Element Plus 2.9 |
| Build Tool | Vite 6 |
| Language | TypeScript 5.7 (strict) |
| Styling | SCSS + CSS Variables |
| HTTP | Axios |
| Utilities | VueUse, @tweenjs/tween.js |
| Code Quality | ESLint 9 + Prettier + Stylelint + Commitlint + Husky |

## Architecture

### Engine Architecture

```
Engine (Main Class)
├── EventBus          — Inter-subsystem communication
├── Clock             — High-precision timer driving frame updates
├── RendererManager   — WebGL rendering management
├── SceneManager      — Multi-scene support with switching
├── CameraSystem      — Perspective/Orthographic + OrbitControls
└── Systems Map       — Subsystem registry
    ├── modelLoader       Model loader
    ├── lights            Lighting system
    ├── materials         Material system
    ├── animation         Animation system
    ├── tween             Tween animations
    ├── raycaster         Raycasting
    ├── labels            Label system
    ├── postProcessing    Post-processing pipeline
    └── plugins           Plugin manager
```

### Project Structure

```
src/
├── engine/                    # 3D Engine Core
│   ├── core/                  # Core subsystems
│   │   ├── Engine.ts          #   Main engine class (lifecycle, render loop)
│   │   ├── RendererManager.ts #   WebGL renderer management
│   │   ├── SceneManager.ts    #   Multi-scene management
│   │   ├── CameraSystem.ts    #   Camera system (perspective/orthographic + controls)
│   │   └── Clock.ts           #   High-precision timer
│   ├── loaders/               # Model loading
│   │   ├── ModelLoader.ts     #   Model loading manager
│   │   ├── LoaderCache.ts     #   Load result cache
│   │   ├── GLTFLoaderAdapter.ts #  GLTF/GLB adapter (Draco support)
│   │   ├── FBXLoaderAdapter.ts  #  FBX adapter
│   │   ├── OBJLoaderAdapter.ts  #  OBJ adapter
│   │   └── TextureLoader.ts   #   Texture loading manager
│   ├── lights/                # Lighting system
│   ├── materials/             # Material system
│   ├── animation/             # Animation system
│   ├── interaction/           # Interaction system
│   ├── labels/                # Label system
│   ├── postprocessing/        # Post-processing pipeline
│   ├── plugins/               # Plugin system
│   ├── helpers/               # Debug helpers
│   ├── events/                # Event system
│   ├── utils/                 # Utilities
│   ├── types/                 # TypeScript type definitions
│   └── index.ts               # Unified engine exports
├── composables/               # Vue composables
├── stores/                    # Pinia state management
├── components/                # Vue components
├── views/                     # Page views
├── layouts/                   # Layouts
├── services/                  # Service layer
├── styles/                    # Global styles
├── router/                    # Route configuration
├── App.vue                    # Root component
└── main.ts                    # Application entry
```

## Getting Started

### Prerequisites

- Node.js >= 18
- pnpm (recommended), npm, or yarn

### Installation

```bash
# Clone the repository
git clone https://gitee.com/your-username/TwinForge.git
cd TwinForge

# Install dependencies
pnpm install

# Start the dev server
pnpm dev

# Production build
pnpm build

# Preview production build
pnpm preview
```

## Usage

### Basic — ThreeCanvas Component

```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) {
  // Engine is ready — create scenes, load models, etc.
  const scene = engine.sceneManager.createScene('main')
  const loader = engine.getSystem('modelLoader')
  // ...
}
</script>
```

### Using Composables in Child Components

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

### Custom Plugins

Create custom plugins by implementing the `IEnginePlugin` interface:

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

const myPlugin: IEnginePlugin = {
  name: 'my-plugin',
  install(engine) {
    engine.eventBus.on('object:click', ({ object }) => {
      console.log('Clicked:', object.name)
    })
  },
  dispose() {
    // Clean up resources
  },
}
```

### Engine Options

```ts
interface EngineOptions {
  antialias?: boolean          // Anti-aliasing (default: true)
  alpha?: boolean              // Transparent background (default: false)
  shadowMap?: boolean          // Shadow maps (default: true)
  pixelRatio?: number | 'auto' // Pixel ratio (default: 'auto')
  toneMapping?: ToneMapping    // Tone mapping (default: ACESFilmicToneMapping)
  toneMappingExposure?: number // Exposure (default: 1.0)
  renderQuality?: 'high' | 'medium' | 'low' // Render quality
  enablePostProcessing?: boolean // Post-processing (default: true)
  enableLabels?: boolean       // Label system (default: true)
  debug?: boolean              // Debug mode (default: false)
}
```

### Model Placement

Place 3D model files in the `public/models/` directory. Supported formats:

| Format | Extension | Notes |
|--------|-----------|-------|
| glTF / GLB | `.gltf` `.glb` | Recommended; supports Draco compression |
| FBX | `.fbx` | Supports skeletal animations |
| OBJ | `.obj` | Basic mesh format |

## Available Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start dev server |
| `pnpm build` | Type check + production build |
| `pnpm preview` | Preview production build |
| `pnpm type-check` | Run TypeScript type checking only |
| `pnpm lint` | ESLint check with auto-fix |
| `pnpm lint:style` | Stylelint check with auto-fix |
| `pnpm format` | Prettier formatting |

## Browser Compatibility

Requires modern browsers with WebGL 2.0 support:

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

## Contributing

1. Fork the repository
2. Create a `feat/xxx` branch
3. Commit your code (following [Conventional Commits](https://www.conventionalcommits.org/))
4. Create a Pull Request

## License

[MIT](./LICENSE)