# three-fx

**Repository Path**: gsang/three-fx

## Basic Information

- **Project Name**: three-fx
- **Description**: three常用特效库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ✨ Three.js FX

> 数字孪生场景视觉特效库 - 粒子/辉光/材质/后处理/动画

[![npm version](https://img.shields.io/npm/v/threejs-fx)](https://www.npmjs.com/package/threejs-fx)
[![license](https://img.shields.io/npm/l/threejs-fx)](LICENSE)

## 🎯 特性

- 🎨 **开箱即用** - 预设多种数字孪生常用特效
- ⚡ **TypeScript** - 完整类型支持
- 📦 **Tree-shakable** - 按需引入
- 🔧 **参数可配置** - 灵活定制
- 🎮 **实时预览** - 内置 Demo 可热更新开发

## 📦 安装

```bash
npm install threejs-fx three
# 或
yarn add threejs-fx three
# 或
pnpm add threejs-fx three
```

## 🚀 快速开始

```typescript
import * as THREE from 'three'
import { ParticleSystem, BloomEffect, EffectManager } from 'threejs-fx'

// 创建场景
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
const renderer = new THREE.WebGLRenderer({ antialias: true })
renderer.setSize(window.innerWidth, window.innerHeight)
document.body.appendChild(renderer.domElement)

// 创建特效管理器
const effects = new EffectManager(scene, camera, renderer)

// 添加星光粒子
const stars = new ParticleSystem(scene, {
  type: 'stars',
  count: 1000,
  area: 200,
  twinkle: true
})
effects.add('stars', stars)

// 添加辉光效果
const bloom = new BloomEffect(scene, camera, renderer, {
  strength: 1.5,
  radius: 0.4,
  threshold: 0.85
})
effects.add('bloom', bloom)

// 动画循环
const clock = new THREE.Clock()
function animate() {
  requestAnimationFrame(animate)
  
  const time = clock.getElapsedTime()
  const deltaTime = clock.getDelta()
  
  effects.update(time, deltaTime)
  bloom.render()
}
animate()
```

## 🎮 本地开发

```bash
# 克隆项目
git clone https://github.com/yourname/threejs-fx.git
cd threejs-fx

# 安装依赖
npm install

# 启动开发服务器（带热更新）
npm run dev

# 构建库
npm run build
```

访问 http://localhost:3000 查看 Demo

## 📚 特效组件

### 粒子系统 ParticleSystem

```typescript
import { ParticleSystem } from 'threejs-fx'

// 星光
const stars = new ParticleSystem(scene, {
  type: 'stars',
  count: 1000,
  area: 200,
  color: 0xffffff,
  twinkle: true
})

// 火花
const sparks = new ParticleSystem(scene, {
  type: 'sparks',
  count: 200,
  color: 0xffaa00,
  size: 0.5
})

// 雪花
const snow = new ParticleSystem(scene, {
  type: 'snow',
  count: 2000,
  area: 150,
  speed: 5
})

// 雨滴
const rain = new ParticleSystem(scene, {
  type: 'rain',
  count: 3000,
  speed: 15
})
```

**参数说明：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| type | `'stars' \| 'sparks' \| 'snow' \| 'rain' \| 'dust' \| 'fireflies'` | `'stars'` | 粒子类型 |
| count | number | 1000 | 粒子数量 |
| area | number | 100 | 分布区域大小 |
| size | number | 0.5 | 粒子大小 |
| color | number | 自动 | 粒子颜色 |
| opacity | number | 0.8 | 透明度 |
| speed | number | 1 | 运动速度 |
| twinkle | boolean | false | 是否闪烁 |
| loop | boolean | true | 是否循环 |

### 辉光效果 BloomEffect

```typescript
import { BloomEffect } from 'threejs-fx'

const bloom = new BloomEffect(scene, camera, renderer, {
  strength: 1.5,    // 辉光强度
  radius: 0.4,      // 辉光半径
  threshold: 0.85,  // 阈值
  resolutionScale: 0.5  // 分辨率缩放
})

// 渲染
bloom.render()

// 调整参数
bloom.setStrength(2.0)
bloom.setRadius(0.5)
bloom.setThreshold(0.9)
```

### 网格地面 GridFloor

```typescript
import { GridFloor } from 'threejs-fx'

const grid = new GridFloor(scene, {
  size: 200,
  divisions: 50,
  primaryColor: 0x00ffff,    // 青色
  secondaryColor: 0x004444,  // 深青色
  fadeDistance: 80
})
```

### 雷达扫描 RadarScan

```typescript
import { RadarScan } from 'threejs-fx'

const radar = new RadarScan(scene, {
  radius: 30,
  color: 0x00ff88,  // 翠绿色
  speed: 1.5,
  ringCount: 3
})
```

### 脉冲光环 RingPulse

```typescript
import { RingPulse } from 'threejs-fx'

const pulse = new RingPulse(scene, {
  radius: 5,
  color: 0x00ffff,
  ringCount: 3,
  expansionSpeed: 3,
  maxRadius: 40
})

// 手动触发脉冲
pulse.pulse()
```

## 🎨 特效管理器 EffectManager

统一管理多个特效：

```typescript
import { EffectManager, ParticleSystem, BloomEffect } from 'threejs-fx'

const manager = new EffectManager(scene, camera, renderer)

// 添加特效
manager.add('particles', new ParticleSystem(scene))
manager.add('bloom', new BloomEffect(scene, camera, renderer))

// 批量更新
manager.update(time, deltaTime)

// 控制可见性
manager.setVisible(false)  // 隐藏所有
manager.get('particles')?.setVisible(true)  // 显示单个

// 获取特效
const particles = manager.get<ParticleSystem>('particles')

// 移除特效
manager.remove('particles')

// 清空所有
manager.clear()
```

## 🎨 配色方案

推荐配色：

```typescript
// 赛博朋克
const cyberpunk = {
  primary: 0x00ffff,   // 青色
  secondary: 0xff00ff, // 紫色
  accent: 0x00ff88     // 绿色
}

// 科技蓝
const techBlue = {
  primary: 0x0088ff,
  secondary: 0x00ffff,
  accent: 0x0044aa
}

// 暗夜绿
const darkGreen = {
  primary: 0x00ff88,
  secondary: 0x00ffff,
  accent: 0x004422
}
```

## 📁 项目结构

```
threejs-fx/
├── src/
│   ├── effects/          # 特效组件
│   │   ├── ParticleSystem.ts
│   │   ├── GridFloor.ts
│   │   ├── RadarScan.ts
│   │   └── RingPulse.ts
│   ├── postprocessing/   # 后处理
│   │   └── BloomEffect.ts
│   ├── utils/            # 工具类
│   │   └── EffectManager.ts
│   └── index.ts          # 入口
├── demo/                 # 演示项目
│   ├── index.html
│   └── src/
│       └── main.ts
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
```

## 📝 更新日志

### v1.0.0
- ✨ 初始版本
- 🎨 粒子系统（星光/火花/雪花/雨滴/灰尘/萤火虫）
- 💡 辉光效果（Bloom）
- 📐 网格地面
- 🎯 雷达扫描
- 💫 脉冲光环
- 🛠️ 特效管理器

## 📄 License

MIT © [Your Name](https://github.com/yourname)

---

Made with ❤️ for Three.js developers