@neutrinoparticles/js-v1.1-pixi8

PIXI.js v8 integration for NeutrinoParticles real-time particle effects (format v1.1).

Installation

npm install @neutrinoparticles/js-v1.1-pixi8

The core runtime (@neutrinoparticles/js-v1.1) is installed automatically as a dependency.

Peer dependency: PIXI.js v8

Requirements

The v1.1 renderer reconstructs particle geometry on the GPU. It works on:

• WebGL2 (the PIXI v8 default) — the primary path;
• WebGL1 — supported automatically on contexts that provide OES_texture_float, at least 2 vertex texture image units, highp float in fragment shaders, and pass a one-time vertex-float-texture smoke test at startup. The renderer detects the context version and picks the path by itself — no configuration needed.

On a WebGL1 context missing those capabilities, creating the plugin context throws an Error naming the missing capability (for example NeutrinoParticles (js-v1.1): WebGL1 context lacks OES_texture_float; WebGL2 or WebGL1 with vertex float textures is required.).

WebGL2 vs WebGL1: which to use

Prefer WebGL2 whenever it is available — it is the faster and leaner path. WebGL1 is a compatibility fallback for devices and embeds that cannot create a WebGL2 context. Rough comparison of the same effect on the two paths:

• Rendering speed: identical at typical particle counts (up to ~20k live particles the difference is not measurable); on very heavy effects (~100k live particles) WebGL1 costs roughly 10% more render time per frame — the vertex shader does almost twice as many texture reads and extra math to unpack data that WebGL2 reads directly.
• GPU memory: WebGL1 uses about 25% more per effect (an extra byte texture carries the data WebGL1 shaders cannot decode from the float texture).
• Features/visuals: identical — both paths render the same effects with full parity (quads and ribbons).

In practice: keep PIXI's default (preferWebGLVersion: 2) so WebGL1 engages automatically only where WebGL2 truly is not available — set preferWebGLVersion: 1 in app.init only when you deliberately need to test or target the legacy path.

Export Target in Editor

In the NeutrinoParticles Editor, set the export target to JavaScript v1.1.

After export you get a .js file (e.g. my_effect.js) containing the effect model.

Quick Start

HTML + Dynamic loading

In the editor's project settings, select For XHR Request export format, then load the effect at runtime via PIXI.Assets. Pass app.neutrino.loadData so the loader parses the file as a NeutrinoParticles effect.

<script src="path/to/pixi.js"></script>
<script src="path/to/@neutrinoparticles/js-v1.1/dist/neutrinoparticles.js-v1.1.umd.js"></script>
<script src="path/to/@neutrinoparticles/js-v1.1-pixi8/dist/neutrinoparticles.js-v1.1-pixi8.umd.js"></script>
<script>

(async () => {
  const app = new PIXI.Application();

  await app.init({
    width: 800,
    height: 600,
    neutrino: { // options for PIXINeutrino.Context
      texturesBasePath: 'textures/' // Prefix for loading textures. Slash at the end!
    }
  });

  document.body.appendChild(app.canvas);

  // Generate turbulence if your effects use it
  // app.neutrino.generateNoise();

  PIXI.Assets.add({
    alias: 'effectModel',
    src: 'export_js/my_effect.js',
    data: app.neutrino.loadData
  });
  const effectModel = await PIXI.Assets.load('effectModel');

  const effect = new PIXINeutrino.Effect(effectModel, {
    position: [400, 300, 0]
  });
  app.stage.addChild(effect);

  app.ticker.add((time) => {
    const sec = time.deltaMS / 1000;
    effect.update(sec > 1.0 ? 1.0 : sec);
  });
})();

</script>

ES6 + Bundler

import * as PIXI from 'pixi.js'
import * as PIXINeutrino from '@neutrinoparticles/js-v1.1-pixi8'

const app = new PIXI.Application();
await app.init({
  width: 800,
  height: 600,
  neutrino: { texturesBasePath: 'textures/' }
});
document.body.appendChild(app.canvas);

PIXI.Assets.add({ alias: 'effectModel', src: 'export_js/my_effect.js', data: app.neutrino.loadData });
const effectModel = await PIXI.Assets.load('effectModel');

const effect = new PIXINeutrino.Effect(effectModel, { position: [400, 300, 0] });
app.stage.addChild(effect);

app.ticker.add((time) => {
  const sec = time.deltaMS / 1000;
  effect.update(sec > 1.0 ? 1.0 : sec);
});

3D Perspective Projection

Effects can place particles in 3D (Z position/velocity set up in the editor). By default the renderer is orthographic: Z is ignored. Pass a PerspectiveProjection to make particles scale with depth (same behavior and API as the JS v1.0 runtimes): particles farther away shrink toward the screen center, particles behind the camera are discarded.

const projection = new PIXINeutrino.PerspectiveProjection(60.0); // horizontal FOV, degrees

const effect = new PIXINeutrino.Effect(effectModel, {
  position: [400, 300, 0],
  projection // can be shared between effects
});

For the angle use the same value as in the NeutrinoParticles Editor project (Project Settings > Preview > Perspective) to match the editor preview. The projection has no camera rotation — only depth scaling around the screen center.

Instant Position Change (Teleporting)

Moving the effect via position creates a smooth trail of particles. To instantly teleport the effect without a trail:

effect.resetPosition([newX, newY, 0]);

// With new rotation (radians)
effect.resetPosition([newX, newY, 0], newRotationRadians);

Restart

Restart destroys all existing particles and starts the effect from scratch:

effect.restart([newX, newY, 0]);

Pause

Full pause — all particles freeze, nothing is generated:

effect.pause();
effect.unpause();

Generators pause — existing particles continue to live, but no new particles are created:

effect.pauseGenerators();
effect.unpauseGenerators();

Set the initial pause state in the constructor:

const effect = new PIXINeutrino.Effect(effectModel, {
  position: [400, 300, 0],
  pause: PIXINeutrino.Pause.YES // starts paused
});
// ...later:
effect.unpause();

Emitter Properties

Control exposed emitter properties at runtime. Properties are defined in Emitter Guide or Emitter Scheme in the Editor.

// Write to every emitter that declares the property...
effect.setPropertyInAllEmitters('MyParticlesPerSecond', 100);
effect.setPropertyInAllEmitters('MyColor', [1.0, 0.5, 0.2]);

// ...or address a single emitter by name.
effect.setPropertyInEmitter('Sparks', 'MyColor', [1.0, 0.5, 0.2]);

Read the current values back. A scalar property returns a number, a vector property returns a number[], and an unknown property returns undefined:

effect.getEmitterPropertyValue('Sparks', 'MyColor');  // [1.0, 0.5, 0.2]
effect.getEmitterPropertyValue('MyParticlesPerSecond');  // 100 — first emitter with it

effect.hasEmitterProperty('Sparks', 'MyColor');  // true
effect.hasEmitterProperty('NoSuchProperty');     // false

Discover what an effect exposes without knowing the names up front:

for (const p of effect.getEmitterProperties()) {
    // { emitterName: 'Sparks', name: 'MyColor', arity: 3, value: [1, 0.5, 0.2] }
    console.log(p.emitterName, p.name, p.arity, p.value);
}

Values are read live from the simulation buffer at call time.

Use only the documented methods above. Exported effects are minified, and the internal property names/objects they contain (_globParamMeta, or whatever short name it was mangled to) are not a stable API — they change between editor versions and differ between commercial and non-commercial exports.

Number of Particles

const numParticles = effect.getNumParticles();

Common Issues

• a WebGL2 renderer is required error: The v1.1 renderer needs WebGL2. PIXI v8 uses WebGL2 by default; make sure you are not forcing a WebGL1 renderer.
• No particles visible: Check that the export target in the editor is set to JavaScript v1.1. Verify texturesBasePath points to the correct textures directory.
• Turbulence not working: Call app.neutrino.generateNoise() before creating effects that use noise/turbulence.

HDR Bloom (optional add-on)

Add a scene-preserving HDR glow that matches the editor preview with @neutrinoparticles/bloom-v1.1-pixi8: render the effect into an HDR scene target and present() the bloom to the screen. Only particle colour above 1.0 glows; the rest of the scene is untouched. WebGL2 only.

Documentation

Full documentation at neutrinoparticles.com.

License

Copyright (c) Yurii Miroshnyk. All rights reserved.