Wintersky

Particle effect renderer based on three.js and the Minecraft Bedrock particle format.

Demo: Wintersky Rainbow Demo

Installation

npm i wintersky

Usage

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

// Import wintersky
import Wintersky from 'wintersky';
// Load JSON File
import RainbowParticle from './rainbow.particle.json';

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

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

Development

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

API

Scene

`new Wintersky.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 Blockbench.

`WinterskyScene#updateFacingRotation(camera)`

Updates the particle facing rotation for all emitters

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

`WinterskyScene#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

Emitter

`new Wintersky.Emitter(scene, config?, options?)`

Creates a new particle emitter

scene: Wintersky Scene: Wintersky scene to add this emitter to
config: Config: Config instance
scene: Scene: Wintersky 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

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

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

Config

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

`new Wintersky.Config(scene, config, options)`

Creates a new emitter config instance

scene: Wintersky Scene: Wintersky 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

rtm516 / wintersky