shader-particle-system

基于 Three.js 的 GPU Shader 粒子系统，支持 Points 和 Instanced Plane 两种渲染模式。

安装

npm install shader-particle-system

需要 three >= 0.158.0 作为 peer dependency。

基本用法

import * as THREE from 'three';
import { Group, Emitter, Constants } from 'shader-particle-system';

// 1. 创建粒子组
const group = new Group({
    texture: { value: yourTexture },
    maxParticleCount: 1000,
});

// 2. 创建发射器
const emitter = new Emitter({
    maxAge: { value: 2 },
    position: {
        value: new THREE.Vector3(0, 0, 0),
        spread: new THREE.Vector3(5, 5, 5),
    },
    velocity: {
        value: new THREE.Vector3(0, 10, 0),
        spread: new THREE.Vector3(2, 2, 2),
    },
    color: {
        value: [new THREE.Color(0xff0000), new THREE.Color(0xffff00)],
    },
    opacity: { value: [1, 0] },
    size: { value: [2, 0.5] },
    particleCount: 500,
});

// 3. 添加到场景
group.addEmitter(emitter);
scene.add(group.mesh);

// 4. 每帧更新
function animate() {
    requestAnimationFrame(animate);
    group.update(deltaTime);
    renderer.render(scene, camera);
}

渲染模式

Points 模式（默认）

每个粒子是一个 Point Sprite，始终面向相机，适用于火焰、烟雾、星光等效果。

const group = new Group({
    texture: { value: texture },
    maxParticleCount: 1000,
    // renderMode 默认为 'points'
});

Instanced Plane 模式

每个粒子是一个四边形面片（Instanced Mesh），支持自定义朝向，适用于雨滴、雪花、落叶等需要三维方向感的效果。

const group = new Group({
    texture: { value: texture },
    maxParticleCount: 1000,
    renderMode: 'instanced',
    orientMode: 'velocity', // 或 'billboard'
});

// update 时传入 renderer，自动适配 DPR 变化
group.update(deltaTime, renderer);

orientMode 选项：

| 值 | 效果 | |---|---| | 'billboard' | 面片完全面向相机（默认） | | 'velocity' | 面片保持竖直，绕 Y 轴朝向相机，俯视可见窄边，平视可见完整面片，增强三维立体感 |

API

Group

new Group(options)

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | texture.value | THREE.Texture | null | 粒子纹理 | | texture.frames | THREE.Vector2 | (1,1) | 精灵图帧数 | | texture.frameCount | Number | frames.x * frames.y | 总帧数 | | texture.loop | Number | 1 | 动画循环次数 | | maxParticleCount | Number | null | 最大粒子数（建议设置） | | renderMode | String | 'points' | 渲染模式：'points' 或 'instanced' | | orientMode | String | 'billboard' | 朝向模式：'billboard' 或 'velocity' | | blending | Number | AdditiveBlending | 混合模式 | | hasPerspective | Boolean | true | 是否启用透视缩放 | | colorize | Boolean | true | 是否启用颜色 | | transparent | Boolean | true | 是否透明 | | alphaTest | Number | 0.0 | Alpha 测试阈值 | | depthWrite | Boolean | false | 是否写入深度 | | depthTest | Boolean | true | 是否深度测试 | | fog | Boolean | true | 是否受雾影响 | | scale | Number | 300 | 透视缩放系数 | | fixedTimeStep | Number | 0.0167 | 默认时间步长 |

方法：

| 方法 | 说明 | |---|---| | addEmitter(emitter) | 添加发射器 | | removeEmitter(emitter) | 移除发射器 | | update(dt, renderer?) | 更新粒子系统。instanced 模式下传入 renderer 可自动适配 viewport | | addPool(count, options, createNew) | 创建发射器对象池 | | triggerPoolEmitter(count, position) | 触发对象池中的发射器 | | setViewportSize(width, height) | 手动设置 viewport 尺寸（设备像素） | | setPositionRotationMatrix(matrix) | 设置粒子位置旋转矩阵 | | dispose() | 释放资源 |

Emitter

new Emitter(options)

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | type | Number | BOX | 分布类型 | | particleCount | Number | 100 | 粒子数量 | | maxAge.value | Number | 2 | 粒子最大生命（秒） | | maxAge.spread | Number | 0 | 生命随机偏差 | | position.value | Vector3 | (0,0,0) | 发射位置 | | position.spread | Vector3 | (0,0,0) | 位置随机偏差 | | position.radius | Number | 10 | 球形/圆盘分布半径 | | velocity.value | Vector3 | (0,0,0) | 初速度 | | velocity.spread | Vector3 | (0,0,0) | 速度随机偏差 | | acceleration.value | Vector3 | (0,0,0) | 加速度 | | acceleration.spread | Vector3 | (0,0,0) | 加速度随机偏差 | | drag.value | Number | 0 | 阻力 (0-1) | | color.value | Color[] | [Color()] | 生命周期颜色（最多 4 个） | | opacity.value | Number[] | [1] | 生命周期透明度（最多 4 个） | | size.value | Number[] | [1] | 生命周期尺寸（最多 4 个） | | angle.value | Number[] | [0] | 生命周期旋转角（最多 4 个） | | wiggle.value | Number | 0 | 摆动幅度 | | rotation.axis | Vector3 | (0,1,0) | 旋转轴 | | rotation.angle | Number | 0 | 旋转角度 | | duration | Number | null | 发射器持续时间（null 为无限） | | alive | Boolean | true | 是否激活 | | isStatic | Boolean | false | 是否静态粒子 | | direction | Number | 1 | 时间方向（1 正向，-1 反向） |

方法：

| 方法 | 说明 | |---|---| | enable() | 启用发射器 | | disable() | 停止发射（已有粒子继续生命周期） | | remove() | 从组中移除 | | reset(force?) | 重置发射器 |

Constants

// 分布类型
Constants.distributions.BOX     // 1 - 盒状分布
Constants.distributions.SPHERE  // 2 - 球面分布
Constants.distributions.DISC    // 3 - 圆盘分布
Constants.distributions.LINE    // 4 - 线性分布

// 渲染模式
Constants.renderModes.POINTS    // 'points'
Constants.renderModes.INSTANCED // 'instanced'

// 朝向模式
Constants.orientModes.BILLBOARD // 'billboard'
Constants.orientModes.VELOCITY  // 'velocity'

开发

# 开发模式（watch + 本地服务器）
npm start

# 构建生产版本
npm run build

# 发布
npm publish

License

MIT