Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marginalhours/dom-particles
Particle effects in the DOM
https://github.com/marginalhours/dom-particles
dom gamedev incremental-game javascript-library particles
Last synced: 3 months ago
JSON representation
Particle effects in the DOM
- Host: GitHub
- URL: https://github.com/marginalhours/dom-particles
- Owner: marginalhours
- License: mit
- Created: 2019-01-01T16:48:55.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-08T07:07:38.000Z (about 2 years ago)
- Last Synced: 2024-10-12T03:24:51.963Z (4 months ago)
- Topics: dom, gamedev, incremental-game, javascript-library, particles
- Language: JavaScript
- Homepage: https://marginalhours.github.io/dom-particles/
- Size: 3.12 MB
- Stars: 24
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# dom-particles
[](https://circleci.com/gh/marginalhours/dom-particles) [](https://www.npmjs.com/package/dom-particles)
A small JS library to provide particle-style effects within the DOM, without leveraging `` or other techniques.
[Demo Page](http://marginalhours.github.io/dom-particles)
## Quickstart
Include this `` tag in the `<head>` of your page:
`<script type="text/javascript" src='https://unpkg.com/dom-particles'>`
Then somewhere in the `` include the following script:
```
const t = new DomParticles();
const c = { x: document.body.clientWidth / 2 , y: document.body.clientHeight / 2 };
t.addEmitter({
position: { x: c.x, y: c.y },
particleOptions: {
velocity: { y: -50 },
contents: 'Hello world'
}
});
```
## Alternative installation via NPM
`npm install --save dom-particles`
then in your code:
```
import DomParticles from 'dom-particles'
const d = new DomParticles();
...
```
## Development
`git clone` this repository, then:
```
cd dom-particles
npm i
# Uses parcel to start a hot-reloading playground on port 1234
npm run dev
# Builds dom-particles.js to lib/
npm run build
# Runs unit tests with Mocha
npm run test
```
# API Reference
## DomParticles object
The DomParticles object is the chief way of creating particles and emitters.
By default, a DomParticles only uses the `requestAnimationFrame` API to update itself
while a particle or emitter is extant. After the last particle or emitter reaches the end of its
lifespan, the DomParticles will unregister itself and stop updating until the next `add` or `addEmitter` call.
### Options
| Name | Default | Remarks |
| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `max` | `100` | Maximum number of particles on screen at any one time. Global across all emitters |
| `preallocate` | `10` | How many particle elements to create by default and add to the DOM. More will be created on-demand, up to the `max` amount. |
| `tagName` | `span` | Tag to use for particle elements |
| `container` | document `body` tag | Parent container for all particles. Will have `position:relative` applied to the styles. |
| `autostart` | `true` | If `false`, particles will not be animated until `.start()` is called on the parent `DomParticles` instance |
### Methods
- `.addParticle(options)` - Create a particle from the provided `options` object (see below for particle options)
- `.addEmitter(options)` - Create a particle emitter from the provided `options` object (see below for emitter options)
- `.start()` - If `autostart: false` was passed to this instance, call this function manually to begin animation.
- `.reset()` - Removes all particles and emitters.
- `.clearEmitters()` - Removes all emitters. Existing particles will remain until the end of their lifespan.
## Particles
Particles are created (and returned) by the `add` function on a `DomParticles` object.
By default they have a finite lifespan, after which they disappear from the DOM.
At each frame, the following default update is applied to a particle:
```
velocity += acceleration;
position += velocity;
```
There are also three update hooks which can be provided in the particle options: `onCreate`, `onUpdate`, and `onDestroy`. All of these are called with the particle object as the first argument. For `onUpdate`, the second argument is the elapsed time (in fractions of a second, so `1.0` is one second) since the last `onUpdate` call.
Velocity and acceleration are specified in units of pixels per second. For example, a particle with a `ttl` of `1000` milliseconds and a velocity of `{ x: 10 }` will travel ten pixels to the right during its lifespan.
### Options
| Name | Default | Remarks |
| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contents` | `'.'` | innerHTML of the particle element |
| `ttl` | `1000` | Set to an integer to destroy this particle after that many milliseconds have elapsed. |
| `onCreate` | N/A | Callback function on particle creation - called with the particle object as its first argument |
| `onUpdate` | N/A | Callback function on particle update - called with the particle object as its first argument, and elapsed time since last `onUpdate` call as the second argument |
| `onDestroy` | N/A | Callback function on particle destruction - called with the particle object as its first argument |
| `style` | `{}` | object of styles to be applied to the particle. Style values can be arrays, for animation purposes - see section **Styling Particles** below. |
| `heading` | `false` | Set to a number in range `0`...`2 * Math.PI` to manually control the particle heading in an `onUpdate` handler, otherwise animate using the `rotation` style. |
| `grid` | `false` | Set to a number to snap the particle's position to a grid of that size |
| `position` | `{x : 0, y: 0}` | Particle position. If particle is created by an emitter, this is taken to be relative to the emitter's position; if not, it's taken to be relative to the container element of the parent `DomParticles` object. For convenience, components which are zero need not be specified: `{x: 1}` and `{y: 1}` are both valid vectors. |
| `velocity` | `{x : 0, y: 0}` | Particle velocity |
| `acceleration` | `{x : 0, y: 0}` | Particle acceleration |
### Methods
- `setText(text)`: Sets the `innerText` of the particle element to `text`
- `setContents(html)`: Sets the `innerHTML` of the particle element to `html`
- `updateStyle(styleObject)`: Update particle element styles
### Styling particles
The `style` property of a particle options object, or a `particleOptions` object passed to an `Emitter`, is not limited to static properties or getters. You can pass an array of values for a specific property, like so:
```
t.add({
style: {
'backgroundColor': ['#fff', '#000']
}
});
```
Over the lifetime (`ttl` property) of the particle, the values in this array will be linearly interpolated between
for the purpose of the particle's actual style at a particular moment in time. In the above example, a particle with a `ttl` of `500` milliseconds will begin life at `t = 0` with a white background but end it at `t = 500` with a black one.
The array of values can be any length. Most simple CSS properties (colours; unit + value eg `1px`, `2em` etc) are supported. Compound properties have to be manipulated component-by-component.
There are also some CSS transform properties which are included as separate arguments for ease-of-use. These are as follows:
- `scale` (or just `scaleX` or `scaleY`) - scale the element. This is the _transform_ version of scale, not the general CSS property.
- `rotation` - rotate the element, but takes lower precedence than the `heading` property.
- `skew` (or just `skewX` or `skewY`) - skew the element
## Emitters
Emitters are created (and returned) by the `addEmitter` function on a `DomParticles` object. They provide a convenient way to create multiple particles with similar properties.
### Options
| Name | Default | Remarks |
| ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxEmissions` | `false` | Maximum particles to emit. Set to a integer to destroy this emitter after that many have been created. |
| `ttl` | `false` | Set to an integer to destroy this emitter after that many milliseconds have elapsed. |
| `emitEvery` | `500` | Number of milliseconds between particle emissions |
| `onCreate` | N/A | Callback function on emitter creation - called with the particle object as its first argument |
| `onUpdate` | N/A | Callback function on emitter update - called with the emitter object as its first argument, and elapsed time since last `onUpdate` call as the second argument |
| `onDestroy` | N/A | Callback function on emitter destruction - called with the emitter object as its first argument |
| `heading` | `0` | Set to a number in range `0`...`2 * Math.PI` to rotate the direction from which particles are emitted. |
| `position` | `{x : 0, y: 0}` | Emitter position. Particles emitted from this emitter will have a position relative to the emitter's position, not the origin. |
| `velocity` | `{x : 0, y: 0}` | Emitter velocity |
| `acceleration` | `{x : 0, y: 0}` | Emitter acceleration |
| `particleOptions` | default particle options | See subsection "Options" of the "Particle" section. |