wintersky v1.3.0
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);
Three.js up to version r134 is currently supported. Newer versions of three.js have an issue with updating textures on the fly if their size has changed. A workaround would be required to solve this.
Development
npm i
: Install dependenciesnpm run watch
: Activate compilernpm 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 emittersspace: 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 emittertick_rate: Number
Emitter tick rate per second.loop_mode: String
Default emitter loop modeparent_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 toconfig: Config
: Config instancescene: Scene
: Wintersky Sceneoptions: Object
:loop_mode: String
How the emitter loops:auto
,once
orlooping
. Default:auto
loop_mode: String
How the emitter is located in the world:world
,entity
orlocator
. 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 sceneconfig: Config
: Config instanceoptions: 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 changevalue: 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