# three-base

**Repository Path**: drm/three-base

## Basic Information

- **Project Name**: three-base
- **Description**: 在 three.js 的基础上封装了的 three-base 基类,    统一处理了 鼠标事件,低频渲染, dom离开页面时自动清理显存, 动态视角切换,  已经提供了一个好用的动画库,  等等常用组件,
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://www.npmjs.com/package/three-base
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 1
- **Created**: 2022-07-07
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: three-base-npm

## README

# three-base

一个基于 Three.js 和 React 的 3D 可视化开发框架，提供了丰富的 3D 组件和工具类，简化 3D 应用的开发流程。

## 项目简介

three-base 是一个功能完整的 3D Web 开发框架，集成了 Three.js 的强大功能，并封装了大量实用的 3D 组件和工具。项目使用 React + TypeScript + Vite 构建，支持现代化的开发体验。

## 主要特性

- 🎯 **基于 Three.js 0.167.0** - 使用最新稳定版本的 Three.js
- ⚛️ **React 18 集成** - 完全支持 React 18 的特性
- 📦 **TypeScript 支持** - 完整的类型定义和类型安全
- 🚀 **Vite 构建工具** - 快速的开发和构建体验
- 🎨 **丰富的 3D 组件** - 火焰效果、文字渲染、镜面反射等
- 🎮 **交互控制系统** - 鼠标控制、键盘控制、FPS 控制
- 📱 **移动端适配** - 支持移动设备的触摸交互
- 🔥 **粒子系统** - 高性能的粒子渲染
- 🌿 **后期处理** - 辉光、描边、泛光等视觉效果

## 核心组件

### 基础组件
- **ThreeBase** - 核心渲染类，提供基础的 3D 场景管理
- **ThreeMouse** - 鼠标交互管理，支持点击、悬停、拖拽等事件
- **ThreeLoader** - 3D 模型加载器，支持 GLB、GLTF、FBX 等格式
- **Transition** - 动画过渡系统，支持缓动和关键帧动画

### 视觉效果
- **Fire** - 火焰粒子系统，可调节颜色、高度、半径
- **Mirror** - 镜面反射效果
- **Grass** - 草地渲染系统
- **SpriteText** - 3D 文字精灵渲染
- **ExtrudeMesh** - 挤出几何体生成

### 交互控制
- **FPScontrol** - 第一人称控制器
- **keyContorls** - 键盘控制系统
- **EventMesh** - 可交互的 3D 网格对象

### 实用工具
- **ApngTexture** - APNG 动画纹理支持
- **InstancedMeshBase** - 实例化网格，高性能渲染大量相似对象
- **PlaneWithHtml** - 在 3D 空间中渲染 HTML 内容
- **threeUtils** - 3D 数学工具函数

## 快速开始

### 安装依赖
```bash
npm install
# 或
yarn install
```

### 开发模式
```bash
npm run dev
# 或
yarn dev
```

### 构建项目
```bash
npm run build
# 或
yarn build
```

### 预览构建结果
```bash
npm run preview
# 或
yarn preview
```

## 使用示例

### 创建基本的 3D 场景

```typescript
import { AmbientLight, BoxGeometry, Mesh, MeshLambertMaterial, PointLight, Vector3 } from "three";
import ThreeBase from "three-base";
import Transition from "three-base/Transition";
import Fire from "three-base/Fire";

class HomeRender extends ThreeBase {
    constructor() {
        super();
    }

    init() {
        super.init();
        // 设置相机位置和朝向
        this.resetLookAt({
            center: new Vector3(0, 0, 0),
            position: new Vector3(10.954, 19.452, 39.811)
        });
    }

    // 环境光
    ambientLight = (() => {
        const ambientLight = new AmbientLight("#fff", 0.4);
        this.scene.add(ambientLight);
        return ambientLight;
    })();

    // 点光源
    pointLight = (() => {
        const pointLight = new PointLight("#fff", 0.4);
        pointLight.position.set(50, 40, 50);
        this.scene.add(pointLight);
        return pointLight;
    })();

    // 火焰效果
    fire = (() => {
        const fire = new Fire();
        fire.fireColor = "#ff2200";
        fire.fireScale = 1;
        fire.fireRadius = 0.5;
        fire.fireHeight = 3;
        fire.position.set(0, 5, 0);
        this.scene.add(fire);
        return fire;
    })();

    // 交互立方体
    box = (() => {
        const geometry = new BoxGeometry(10, 10, 10);
        const material = new MeshLambertMaterial({ color: 0xfff });
        const mesh = new Mesh(geometry, material);

        // 创建动画
        const transition = new Transition({ rotationY: 0 });
        transition.onChange(({ rotationY }) => {
            mesh.rotation.y = rotationY;
        });

        mesh.position.set(0, 0, 0);
        mesh.userData = { cursor: "pointer", enableEvent: true };

        // 鼠标事件
        mesh.addEventListener("click", e => { });
        mesh.addEventListener("leftclick", e => {
            transition.set({ rotationY: Math.random() * 5 });
        });
        mesh.addEventListener("mouseenter", e => { });
        mesh.addEventListener("mouseleave", e => { });

        this.scene.add(mesh);
        return mesh;
    })();
}

const homeRenderer = new HomeRender();
export default homeRenderer;
```

### 在 React 组件中使用

```tsx
import React, { useEffect } from 'react';
import homeRenderer from './homeRenderer';

function App() {
    useEffect(() => {
        homeRenderer.setContainer(document.getElementById("three-container"));
        return () => {
            homeRenderer.dispose();
        };
    }, []);

    return <div id="three-container" style={{ width: '100%', height: '100vh' }} />;
}

export default App;
```

## 项目结构

```
three-base/
├── src/                    # 源代码
│   ├── components/         # React 组件
│   ├── views/             # 页面视图
│   │   ├── home/          # 首页示例
│   │   ├── FPSDemo/       # 第一人称演示
│   │   ├── Helix/         # 螺旋动画
│   │   ├── MeshParticles/ # 粒子系统
│   │   └── OctreeDemo/    # 八叉树碰撞检测
│   └── utils/             # 工具函数
├── three-base/            # 核心库
│   ├── Fire/              # 火焰效果
│   ├── Grass/             # 草地系统
│   ├── Ground1/           # 地形系统
│   └── lib/               # 编译输出
├── public/                # 静态资源
└── dist/                  # 构建输出
```

## 技术栈

- **Three.js 0.167.0** - 3D 渲染引擎
- **React 18.2.0** - UI 框架
- **TypeScript 4.7.4** - 类型系统
- **Vite 4.1.1** - 构建工具
- **Ant Design 4.22.6** - UI 组件库
- **MobX 6.6.1** - 状态管理
- **Less 4.1.3** - CSS 预处理器

## 演示页面

项目包含多个演示页面，展示了不同的 3D 功能：

- **首页** - 基础 3D 场景和交互
- **FPS Demo** - 第一人称视角控制
- **Helix** - 螺旋动画效果
- **Mesh Particles** - 网格粒子系统
- **Octree Demo** - 八叉树碰撞检测演示

## 发布和部署

### 发布 NPM 包
```bash
npm run 发包
```

### 部署到服务器
项目支持自动部署到远程服务器，配置信息在 `script/index.js` 中。

## 开发者信息

- **作者**: xiaosihan
- **版本**: 2.0.130
- **许可证**: ISC
- **仓库地址**: https://gitee.com/drm/three-base

## 在线演示

http://www.3dkeshihua.com/three-base/

## 注意事项

- 建议使用 Vite 进行项目构建
- 确保浏览器支持 WebGL
- 移动端使用时注意性能优化
- 大型模型加载时建议使用进度提示