npm package: @nkduy/scenejs
Description: Particle effect renderer based on three.js and the Minecraft Bedrock particle format
Author: NKDuy
Latest version: 1.2.1

# SceneJS

Particle effect renderer based on [three.js](https://threejs.org) and the [Minecraft Bedrock particle format](https://bedrock.dev/docs/stable/Particles).

# Installation

`npm i scenejs`

# Usage

This is the simplest possible implementation of a SceneJS emitter into your scene

```javascript
// Import scenejs
import SceneJS from "scenejs";
// Load JSON File
import RainbowParticle from "./rainbow.particle.json";

// Setup SceneJS Scene
const scenejs_scene = new SceneJS.Scene();
// Setup Emitter
const emitter = new SceneJS.Emitter(scenejs_scene, RainbowParticle);
// Add emitter into Three.JS scene
threejs_scene.add(scenejs_scene.space);
// Play Effect
emitter.playLoop();

// Update particle rotation in your app's rendering loop
scenejs_scene.updateFacingRotation(camera);
```

# Development

- `npm i`: Install dependencies
- `npm run watch`: Activate compiler
- `npm run build`: Build for production

# API

## Scene

### `new SceneJS.Scene(options?)`

Creates a new scene, which can hold multiple emitters

- `options: Object`:
  - `fetchTexture: Function`

### Properties

- `emitters: Array` List of all emitters
- `space: three.js Object3D` Global particle space. Add this to your three.js scene.
- `global_options: Object`
  - `max_emitter_particles: Number` Maximum amount of particles per emitter
  - `tick_rate: Number` Emitter tick rate per second.
  - `loop_mode: String` Default emitter loop mode
  - `parent_mode: String` Default emitter parent mode
  - `scale: Number` Emitter scale. The default is 1 for block space. Set to 16 to run in a pixel space environment like Pixel Studio.

### `SceneJSScene#updateFacingRotation(camera)`

Updates the particle facing rotation for all emitters

- `camera: Camera` three.js camera to orient the particle towards

### `SceneJSScene#fetchTexture( config )`

Method to provide visuals for a texture. Null by default. Gets called by configs if the texture is updated. Should return a data URL, or a promise resulting in a data URL.

- `config: Config` Particle config that is requesting the texture

&nbsp;

## Emitter

### `new SceneJS.Emitter(scene, config?, options?)`

Creates a new particle emitter

- `scene: SceneJS Scene`: SceneJS scene to add this emitter to
- `config: Config`: Config instance
- `scene: Scene`: SceneJS Scene
- `options: Object`:
  - `loop_mode: String` How the emitter loops: `auto`, `once` or `looping`. Default: `auto`
  - `loop_mode: String` How the emitter is located in the world: `world`, `entity` or `locator`. Default: `world`

### `Emitter#updateFacingRotation(camera)`

Updates the particle facing rotation

- `camera: Camera` three.js camera to orient the particle towards

### `Emitter#delete()`

Deletes the emitter

&nbsp;

## Default Playback Loop

### `Emitter#playLoop()`

Starts to play the particle effect using the default play loop

### `Emitter#toggleLoop()`

Pause/resume the default playback loop

### `Emitter#stopLoop()`

Stops the default playback loop

&nbsp;

## Control Emitter

### `Emitter#start()`

Starts the emitter, setting the time to 0 and initializing all variables

### `Emitter#tick()`

Runs an emitter tick

### `Emitter#stop(clear_particles)`

Stops the emitter

### `Emitter#jumpTo(second)`

Jumps to a specific time in the emitter. This is optimited to run as few operations as possible so you can use it to hook the emitter to a custom playback loop

&nbsp;

## Config

Configs store the configuration of an emitter. All emitters have a config by default.

### `new SceneJS.Config(scene, config, options)`

Creates a new emitter config instance

- `scene: SceneJS Scene`: SceneJS scene
- `config: Config`: Config instance
- `options: Object`:
  - `path: String` Location of the particle file that the config is based on.

### Config#reset()

Resets the config to default values

### Config#set(key, value)

Sets a property of the config to a specific value

- `key: String` Key of the value to change
- `value: Any` Value to set

### Config#setFromJSON(data)

Loads the configuration from a JSON particle file

- `json: Object` Particle file content

### Config#onTextureUpdate()

Method that runs when the texture of the config is updated. Null by default