Introduction

Particle systems are a technique for simulating the behavior and motion of a large number of particles. These particles can represent virtual objects such as dust, fire, water droplets, or abstract elements like sparkles, stars, snowflakes, etc. Particle systems simulate the movement, appearance, and interactions of each particle to generate various realistic dynamic effects.

Installation

The particle system is provided as an independent plugin module. We can import the particle system plugin using two methods: NPM and CDN links.

1. Installation via NPM

npm install @orillusion/core --save
npm install @orillusion/particle --save

import { Engine3D } from "@orillusion/core"
import { ParticleSystem } from "@orillusion/particle"

2. Importing via CDN

We recommend using the ESModule build version.

<script type="module">
  import { Engine3D } from "https://unpkg.com/@orillusion/core/dist/orillusion.es.js" 
  import { ParticleSystem } from "https://unpkg.com/@orillusion/particle/dist/particle.es.js" 
</script>

Alternatively, you can load the UMD build version via <script> and access the ParticleSystem module through the global Orillusion module through the global

<script src="https://unpkg.com/@orillusion/core/dist/orillusion.umd.js"></script>
<script src="https://unpkg.com/@orillusion/particle/dist/particle.umd.js"></script>
<script>
  const {Engine3D, ParticleSystem} = Orillusion
</script>

Usage

1. Adding the Particle System Component

First, create an entity object and add the particle system component:

let obj = new Object3D();
let ps = obj.addComponent(ParticleSystem);
scene.addChild(obj);

2. Setting the Individual Particle's Geometry

Set the geometry shape of the individual particle, for example, using a PlaneGeometry:

ps.geometry = new PlaneGeometry(1, 1, 1, 1, Vector3.Z_AXIS);

3. Setting the Particle Material

Set the particle material and load the required texture map:

let material = new ParticleMaterial();
material.baseMap = await Engine3D.res.loadTexture('particle/fx_a_glow_003.png');
ps.material = material;

4. Selecting the Simulator

Specify the simulator to be used by the ParticleSystem component. Currently, only the ParticleStandSimulator simulator is available:

let simulator = ps.useSimulator(ParticleStandSimulator);

5. Adding the Emitter Module

Add a required emitter module to the ParticleStandSimulator and set the emission parameters:

let emitter = simulator.addModule(ParticleEmitterModule);
// Set the maximum number of particles
emitter.maxParticle = 10000;
// Set the duration of emission
emitter.duration = 10;
// Set the emission rate (number of particles per second)
emitter.emissionRate = 1000;
// Set the particle's lifecycle size
emitter.startLifecycle.setScalar(1);
// Set the emitter's shape type
emitter.shapeType = ShapeType.Sphere;
// Set the radius of the emitter's shape
emitter.radius = 10;
// Set the emission location on the shape
emitter.emitLocation = EmitLocation.Shell;

6. Play

Start playing the particle animation:

ps.play();

WebGPU is not supported in your browser
Please upgrade to latest Chrome/Edge

<

import { Engine3D, AtmosphericComponent, Vector3, View3D, HoverCameraController, Object3D, PlaneGeometry, Scene3D, CameraUtil, webGPUContext } from '@orillusion/core';

import { ParticleSystem, ParticleMaterial, ParticleStandardSimulator, ParticleEmitterModule, ShapeType, EmitLocation } from '@orillusion/particle';

class Sample_ParticleSystem {
    async run() {
        await Engine3D.init();

        let scene = new Scene3D();
        scene.addComponent(AtmosphericComponent).sunY = 0.6;

        let camera = CameraUtil.createCamera3DObject(scene);
        camera.perspective(60, webGPUContext.aspect, 0.1, 5000.0);

        let ctrl = camera.object3D.addComponent(HoverCameraController);
        ctrl.setCamera(45, -15, 30);

        await this.initScene(scene);

        let view = new View3D();
        view.scene = scene;
        view.camera = camera;
        Engine3D.startRenderView(view);
    }

    async initScene(scene: Scene3D) {
        // 创建实体对象
        let obj = new Object3D();
        scene.addChild(obj);

        // 添加粒子系统组件
        let particleSystem = obj.addComponent(ParticleSystem);

        // 设置粒子材质
        let material = new ParticleMaterial();
        material.baseMap = await Engine3D.res.loadTexture('https://cdn.orillusion.com/particle/fx_a_glow_003.png');

        // 设置粒子形状
        particleSystem.geometry = new PlaneGeometry(1, 1, 1, 1, Vector3.Z_AXIS);
        particleSystem.material = material;

        // 使用指定仿真器
        let simulator = particleSystem.useSimulator(ParticleStandardSimulator);

        // 添加发射器模块
        let emitter = simulator.addModule(ParticleEmitterModule);
        emitter.maxParticle = 1 * 10000;
        emitter.duration = 10;
        emitter.emissionRate = 1000;
        emitter.startLifecycle.setScalar(1);
        emitter.shapeType = ShapeType.Sphere;
        emitter.radius = 10;
        emitter.emitLocation = EmitLocation.Shell;

        // 开始播放
        particleSystem.play();
    }
}

new Sample_ParticleSystem().run();