Warning

This library is (extremely!) work-in-progress; meaning that it is not done, or ready for use in any other capacity. Please don't use this and assume that anything will work; it probably won't. And when you find something that does work, be ready for it to break in the next release. Please don't open Issues or PRs for things that are broken; I am most likely aware of them. Use this library at your own risk.

If you're interested in using this library and want to keep up to date, please follow me on Twitter, and/or click the Watch button for this repository.

Introduction 👋

three-vfx is a visual effects library for Three.js and react-three-fiber. It aims to be highly performant (with effects almost entirely simulated on the GPU) and easy to extend.

Status ⚠️

This library is currently under heavy development, and is most definitely not ready for any sort of production use whatsoever. If you're interested in giving it a try, you are, however, invited to play with any of the example sandboxes listed below!

Examples & Demos 🎓

• Official Examples Suite
• Official Starter Sandbox (fork it!)
• Space Nebulae

Where is the Documentation?

I'm afraid there's currently no documentation available outside of the sandboxes linked to above. As much as I would like to provide documentation, the library is still too much in flux, with breaking changes landing on main on almost a daily basis. There will be extensiv documentation as soon as things start to settle down -- until then, if you want to play around with the library, please feel free to use/fork one of the available sandboxes.

How this Library Works 🥳

This library aims to be a game-ready library for realtime visual effects in react-three-fiber projects.

It has a focus on performance, while still striving to keep the codebase maintainable and easy to reason about. For this reason, there are certain advanced techniques for particle simulations in WebGL2 that it deliberately chooses not to do, including keeping per-particle state in Frame Buffer Objects; this is why certain features, like particle collisions, are currently not possible.

However, it will happily power most of your game VFX, and it will be very fast doing so!

So, a quick list of things you should know about this library:

• All effects are particle based, using mesh instancing to render any mesh you throw at them. This allows you to have both simple and complex particles, and have them integrated with your scene's lighting, including shadows. (Support for gl.POINTS particles may be added in the future.)
• Since we're using mesh instancing, each effect uses a single draw call, no matter how many particles it is composed of.
• Effects scale from a couple of particles to several hundreds of thousands, or even more. (But for realtime VFX, you rarely need that many.)
• All particles are fully animated on the GPU, through some custom shader code. Your CPU is not concerned with the animations in any manner and will be free to do other stuff.
• Particle spawning is controlled from your code, though. Spawning new particles is the only thing where the CPU gets involved. Newly spawned particles are configured by writing values into buffer attributes; only the parts of these buffers that represent newly spawned particles are uploaded to the GPU that frame.
• You can currently animate velocity, acceleration, scale, color and opacity per particle. At the moment, these are hard-coded in the library's custom shader code, and attributes like color or scale that change over time only animate through linear interpolation (ie. they linearly mutate from a start value to an end value), but there are plans to make these shaders (and the buffers that configure them) composable through code, which will also allow the selection of different easing functions and animation curves.

Hacking & Development 🏗

But if you want to give the thing a whirl and do some hacking on it, clone this repository and run:

yarn && yarn examples

Alternatively, you can launch the examples app on StackBlitz, or just view them on Vercel.

Resources

A couple of links to (possibly free) resources that will help you build cool visual effects.

• Kenney's Particle Pack
• Kenney's Smoke Particles
• Unity's Free VFX Flipbooks

Questions? 💬

Find me on Twitter or the Poimandres Discord.