@neutrinoparticles/js-v1.1-pixi7

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

Installation

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

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

Peer dependency: PIXI.js v7 (7.4.2+)

Requirements

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

• WebGL2 (the PIXI v7 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: do not force the legacy environment (PIXI v7 uses WebGL2 by default) — WebGL1 then engages automatically only where WebGL2 truly is not available, which is exactly where you want it.

Export Target in Editor

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

Export the effect with "For XHR Request" format. After export you get a .js file (e.g. my_effect.js) containing the effect model.

Quick Start

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

// Register plugins before creating PIXI.Application
PIXINeutrino.registerPlugins(PIXI.extensions);

const app = new PIXI.Application({
  width: 800,
  height: 600,
  neutrinoV11: {
    texturesBasePath: 'textures/' // Prefix for loading textures. Slash at the end!
  }
});

document.body.appendChild(app.view);

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

// Load an exported v1.1 effect. Pass app.neutrinoV11.loadData so the loader
// parses it as a NeutrinoParticles effect.
PIXI.Assets.add({ alias: 'effectModel', src: 'export_js/my_effect.js', data: app.neutrinoV11.loadData });

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

  app.ticker.add((delta) => {
    const sec = (delta / PIXI.settings.TARGET_FPMS) / 1000.0;
    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

• Context creation throws about WebGL1 capabilities: the device's WebGL1 context lacks float vertex textures (see Requirements). Use a WebGL2-capable browser/device.
• Plugins not registered: PIXINeutrino.registerPlugins(PIXI.extensions) must be called before creating PIXI.Application.
• 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.neutrinoV11.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-pixi7: 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.