Skip to content
A WebGL based 3D particle engine
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build Rebuilt and updated changelog/package.json for v4.0.5 release Jun 26, 2019
docs Rebuilt and updated changelog/package.json for v4.0.5 release Jun 26, 2019
scripts Removed a bunch of unused dev dependencies May 5, 2019
src Done - emitters and behaviours will now instantiate non nullable prop… Jun 26, 2019
test Done - emitters and behaviours will now instantiate non nullable prop… Jun 26, 2019
.babelrc Added config files Nov 21, 2018
.editorconfig
.esdoc.json Added tests to cover errors thrown by the fromJSON flow, next to limi… Dec 16, 2018
.eslintrc
.gitignore Three conflict bug seems to be fixed by adding an internal compatibil… Mar 21, 2019
.npmignore Added docs to npmignore Nov 29, 2018
.prettierrc Fixed formatting issue, added prettierrc and pretter dev dep so this … Feb 16, 2019
.travis.yml Fixed npm security vulnerabilities, removed istanbul-coveralls package Mar 27, 2019
CHANGELOG.md Rebuilt and updated changelog/package.json for v4.0.5 release Jun 26, 2019
LICENSE.md Updated README some more Nov 24, 2018
NOTES.md Added unit tests for Radius initializer. Renamed Initialize class to … Dec 1, 2018
README.md Removed esdoc and related dev dependencies due to unpatched vulnerabi… Jun 22, 2019
package-lock.json Removed esdoc and related dev dependencies due to unpatched vulnerabi… Jun 22, 2019
package.json Rebuilt and updated changelog/package.json for v4.0.5 release Jun 26, 2019
webpack.config.js Had a rethink on the name and have decided to go with three-nebula in… Apr 4, 2019

README.md

Three Nebula

Build Status Coverage Status

Three Nebula is a WebGL based 3D particle engine that has been designed to work alongside three.js. Check out the examples and API reference documentation for more.

Note: Due to an as of yet unpatched security vulnerability in esdoc I've removed this dev dependency from the repo. The API docs might be slightly out of date because of this, They'll be updated as soon as esdoc is patched.

Features

  • Perfect compatibility with three@0.98.0
  • The ability to instantiate three-nebula particle systems from JSON objects using the static System.fromJSON method
  • The ability to create particle systems from sprites as well as 3D meshes
  • Many kinds of particle behaviours and initializers

Installation

npm

npm i --save three-nebula

script

<script type='text/javascript' src='node_modules/three-nebula/build/three-nebula.js'></script>

Usage

Module

import System, {
  Emitter,
  Rate,
  Span,
  Position,
  Mass,
  Radius,
  Life,
  Velocity,
  PointZone,
  Vector3D,
  Alpha,
  Scale,
  Color,
} from 'three-nebula';
import * as THREE from 'three';

const system = new System();
const emitter = new Emitter();
const renderer = new SpriteRenderer(threeScene);

// Set emitter rate (particles per second) as well as the particle initializers and behaviours
emitter
  .setRate(new Rate(new Span(4, 16), new Span(0.01)))
  .setInitializers([
    new Position(new PointZone(0, 0)),
    new Mass(1),
    new Radius(6, 12),
    new Life(3),
    new RadialVelocity(45, new Vector3D(0, 1, 0), 180),
  ])
  .setBehaviours([
    new Alpha(1, 0),
    new Scale(0.1, 1.3),
    new Color(new THREE.Color(), new THREE.Color()),
  ])
  .emit();

// add the emitter and a renderer to your particle system
system.addEmitter(emitter).addRenderer(renderer);

You can also instantiate your system from a JSON object

import System from 'three-nebula';

const json = {
  preParticles: 500,
  integrationType: 'euler',
  emitters: [
    {
      rate: {
        particlesMin: 5,
        particlesMax: 7,
        perSecondMin: 0.01,
        perSecondMax: 0.02,
      },
      position: {
        x: 70,
        y: 0,
      },
      initializers: [
        {
          type: 'Mass',
          properties: {
            min: 1,
            max: 1,
          },
        },
        {
          type: 'Life',
          properties: {
            min: 2,
            max: 2,
          },
        },
        {
          type: 'BodySprite',
          properties: {
            texture: './img/dot.png',
          },
        },
        {
          type: 'Radius',
          properties: {
            width: 80,
            height: 80,
          },
        },
      ],
      behaviours: [
        {
          type: 'Alpha',
          properties: {
            alphaA: 1,
            alphaB: 0,
          },
        },
        {
          type: 'Color',
          properties: {
            colorA: '#4F1500',
            colorB: '#0029FF',
          },
        },
        {
          type: 'Scale',
          properties: {
            scaleA: 1,
            scaleB: 0.5,
          },
        },
        {
          type: 'Force',
          properties: {
            fx: 0,
            fy: 0,
            fz: -20,
          },
        },
      ],
    },
    {
      rate: {
        particlesMin: 5,
        particlesMax: 7,
        perSecondMin: 0.01,
        perSecondMax: 0.02,
      },
      position: {
        x: -70,
        y: 0,
      },
      initializers: [
        {
          type: 'Mass',
          properties: {
            min: 1,
            max: 1,
          },
        },
        {
          type: 'Life',
          properties: {
            min: 2,
            max: 2,
          },
        },
        {
          type: 'BodySprite',
          properties: {
            texture: './img/dot.png',
          },
        },
        {
          type: 'Radius',
          properties: {
            width: 80,
            height: 80,
          },
        },
      ],
      behaviours: [
        {
          type: 'Alpha',
          properties: {
            alphaA: 1,
            alphaB: 0,
          },
        },
        {
          type: 'Color',
          properties: {
            colorA: '#004CFE',
            colorB: '#6600FF',
          },
        },
        {
          type: 'Scale',
          properties: {
            scaleA: 1,
            scaleB: 0.5,
          },
        },
        {
          type: 'Force',
          properties: {
            fx: 0,
            fy: 0,
            fz: -20,
          },
        },
      ],
    },
  ],
};

const system = new System.fromJSON(json);

Script Tag

If you are adding three-nebula to your project in the script tag, the only difference to the above example is how you access the classes you need. You can do that like so

const { System, Emitter, Rate, Span } = window.System;
const system = new System();

Development

Scripts

There are a few NPM scripts in the root package.json:

  • build - Builds the module and writes the code into ./build/three-nebula.js
  • docs - Serves the docs at http://localhost:8080
  • docs:build - Copies the latest build to ./docs/js and builds the API reference docs
  • test - Runs all specs
  • test:only <spec> - Runs a specific spec
  • test:watch - Watches tests
  • test:watch-only <spec> - Watches a specific spec
  • lint - Lints code and circular dependencies in ./src
  • coverage:generate - Generates a code coverage report
  • coverage:view - View the code coverage report
  • coverage:publish - Publishes the coverage report
  • git:publish <commit-message> - Builds the module, adds all changed files commits with the message you supply and pushes to remote

License

MIT

You can’t perform that action at this time.