babylon.quarks 1.0.0

Unity-style particle effects for Babylon.js

A GPU-batched particle system with Shuriken's modules, one BatchedRenderer per scene, WebGL 2 and WebGPU. Build effects in the browser editor, export them from Unity, or write them in TypeScript.

npm i babylon.quarks
engine — particles — fps — All demos
Render modes
7
Behaviors
25
Emitter shapes
11
Shaders
GLSL + WGSL
Peer
@babylonjs/core ^9.24
License
MIT
Version
1.0.0

What the Vortex is made of

Seven systems under one renderer, around 400 particles alive, a handful of instanced draws. Move the pointer over the window: the dust leans toward it and the last layer sheds trails along its path.

Source: examples/src/landing/vortex.ts. “Open in editor” loads the same seven systems.

  1. 0 Nebula Billboard · alpha blend · SphereEmitter r 22 ColorOverLife, RotationOverLife, Noise
  2. 1 Core glow Billboard · additive · PointEmitter ColorOverLife, SizeOverLife
  3. 2 Core heart Billboard · additive · PointEmitter ColorOverLife, SizeOverLife
  4. 3 Accretion disk Billboard · additive · DonutEmitter r 7 ColorOverLife, OrbitOverLife, GravityForce
  5. 4 Comet ribbons Trail, 60 segments · additive · DonutEmitter r 10.3 ColorOverLife, OrbitOverLife, GravityForce, WidthOverLength
  6. 5 Stardust Stretched billboard · additive · SphereEmitter r 18 ColorOverLife, TurbulenceField, LimitSpeedOverLife, ApplyForce toward the pointer
  7. 6 Cursor comets Trail, 40 segments · additive · PointEmitter at the pointer InheritVelocity, GravityForce, OrbitOverLife, LimitSpeedOverLife, WidthOverLength; emission rate from pointer speed

The modules, in Shuriken's order

A system is the same stack as Unity's inspector: main settings, emission, shape, behaviors over life and by speed, forces, collision, sub-emitters, texture sheet, trails, renderer. The parity checklist lists what is shipped and what is not.

  1. One batched renderer per scene

    Systems that share a material are drawn together, so a screen full of muzzle flashes, hits and auras costs a handful of draw calls instead of one per system. The simulation runs on a column store with compiled behavior passes; on a CPU-only NullEngine, 100 000 particles over 16 emitters step in 9 ms where Babylon's built-in ParticleSystem takes 58 ms.

    Run the benchmark in your browser
    Dozens of muzzle flashes rendered at once
  2. Trails, ribbons and beams

    RenderMode.Trail draws a ribbon through a particle's past positions, with WidthOverLength, texture modes (stretch, tile, repeat per segment), curve tension and world-space history. RenderMode.Beam is for lightning, tethers and lasers. Trails can be shed from the surface of a mesh through MeshSurfaceEmitter, and a teleporting emitter clears its history with clearTrails().

    A sword trail and a flickering beam
  3. 25 behaviors

    Each is a class you add to a system; curves are PiecewiseBezier, gradients are Gradient, and any of them can be random between two. Your own behaviors register through the plugin API and save in the same JSON.

    • ColorOverLife
    • SizeOverLife
    • RotationOverLife
    • FrameOverLife
    • VelocityOverLife
    • OrbitOverLife
    • LimitSpeedOverLife
    • ColorBySpeed
    • SizeBySpeed
    • Noise
    • TurbulenceField
    • GravityForce
    • ApplyForce
    • InheritVelocity
    • ApplyCollision
    • WidthOverLength
    • EmitSubParticleSystem
    Particles bent by a noise field
  4. Texture effects inside the particle shader

    Flipbooks with frame blending, gradient maps, alpha erosion, UV distortion, soft particles, per-texture tiling, offset and scroll, and blend modes that treat alpha as coverage the way Unity's particle shaders do. Each one is off until you set it and compiles nothing when unused.

    Gradient-mapped fire and an eroding smoke cloud
  • Mesh particles

    Any mesh as a particle, lit or unlit, with vertex colours, a rotation axis per particle and rim lighting; or emission from a mesh's surface with MeshSurfaceEmitter.

  • Sub-emitters

    EmitSubParticleSystem spawns a whole system when a particle is born or dies, or for every frame it lives, inheriting what you choose from the parent.

  • Pools and timelines

    EffectPool keeps copies of a one-shot effect ready so playing one allocates nothing. QuarksPrefab sequences systems on a timeline.

  • GLSL and WGSL, both hand-written

    Every shader has a WGSL twin, so WebGPU never loads a transpiler. CI compiles every variant of both languages on each change.

  • A documented JSON format

    Versioned JSON with a published schema. The same file round-trips through QuarksLoader, the editor and the Unity exporter; files from quarks.art load too.

    Format specification

Running in a few lines

Load an effect file from the editor or the Unity exporter, build a system in code, or embed the editor itself.

import {BatchedRenderer, QuarksLoader, QuarksUtil} from 'babylon.quarks';

// One renderer per scene batches every system added to it.
const renderer = new BatchedRenderer('vfx', scene);

const effect = await new QuarksLoader(scene).load('effects/explosion.json');
QuarksUtil.addToBatchRenderer(effect, renderer);
QuarksUtil.play(effect);

scene.onBeforeRenderObservable.add(() => {
    renderer.update(scene.getEngine().getDeltaTime() / 1000);
});

Every demo runs live in your browser

Open any of them full screen, read its source, or send it to the editor and change it.

A Shuriken-style editor that runs in the browser

Hierarchy, viewport with gizmos, a module inspector with curves and gradients, a timeline, undo. Use it on this site, embed it in your own tools as a React component, or drive its headless session API without any UI.

  1. 1 Scene: the effect's systems, shown and hidden with the eye.
  2. 2 Viewport, with the gizmo of the selected emitter.
  3. 3 Inspector: the module stack with curves and gradients.
  4. 4 Timeline: every system's duration on one time axis, with playback controls.
The effect editor with a hierarchy, viewport, module inspector and timeline
The editor with the Vortex loaded from the stage above.

Export effects from Unity

Select a Particle System in Unity and choose Tools › Quarks › Export Selected Effect to JSON. Sub-emitters, grouped systems and textures come along; anything Shuriken has that babylon.quarks does not is reported by name. Unity 2020.3 and newer, installed as a .unitypackage, through UPM, or copied in.

{
  "metadata": {
    "generator": "babylon.quarks Unity exporter 1.0.0",
    "quarksFormat": 1
  },
  "object": {
    "type": "ParticleEmitter",
    "name": "Rocket",
    "ps": { "looping": true, "renderMode": 1, … },
    "children": [
      { "name": "Smoke", … },
      { "name": "TrailSparks", … }
    ]
  }
}
The exporter's menu in Unity, and the start of the file it writes for a rocket with two sub-emitters.