@neutrinoparticles/js-v1.1-phaser

Phaser 3 integration for NeutrinoParticles real-time particle effects (format v1.1).

Installation

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

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

Peer dependency: Phaser 3.60+

Requirements

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

• WebGL2 — the primary path;
• WebGL1 (the Phaser 3 default) — 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, a plain new Phaser.Game({ type: Phaser.WEBGL }) works out of the box.

On a WebGL1 context missing those capabilities, the plugin's init 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).

Phaser 3 creates a WebGL1 context by default. To run on the faster WebGL2 path, create a WebGL2 context yourself and hand it to the game via the context option — WebGL2 is a superset of WebGL1, so Phaser's own rendering keeps working:

const canvas = document.createElement('canvas');
canvas.width = 800;
canvas.height = 600;
document.body.appendChild(canvas);
const gl2 = canvas.getContext('webgl2');

new Phaser.Game({
  type: Phaser.WEBGL,
  canvas: canvas,
  context: gl2, // hand the WebGL2 context to Phaser
  width: 800,
  height: 600,
  // ...
});

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 Phaser from 'phaser'
import { GamePlugin } from '@neutrinoparticles/js-v1.1-phaser'

class GameScene extends Phaser.Scene {
  constructor() {
    super({ key: 'GameScene' });
  }

  preload() {
    // Load exported effect (must be exported "For XHR Request")
    this.load.neutrino('myEffect', 'export_js/my_effect.js');
  }

  create() {
    // Get effect model from cache (created by the loader)
    const effectModel = this.cache.binary.get('myEffect');

    // Create effect instance
    this.effect = this.add.neutrino(effectModel, {
      position: [this.cameras.main.centerX, this.cameras.main.centerY, 0]
    });
  }
}

new Phaser.Game({
  type: Phaser.WEBGL, // Phaser's default WebGL1 context works out of the box;
                      // see "WebGL2 vs WebGL1" above for the faster WebGL2 setup
  width: 800,
  height: 600,
  scene: GameScene,
  plugins: {
    global: [{
      key: 'neutrino',
      plugin: GamePlugin,
      start: true,
      data: {
        texturesBasePath: 'textures/',
        generateNoise: true
      }
    }]
  }
});

For plain <script> tags (no bundler), reference the plugin as PhaserNeutrino.GamePlugin and include the UMD builds of both @neutrinoparticles/js-v1.1 and @neutrinoparticles/js-v1.1-phaser.

How It Works

scene.load.neutrino(key, url) fetches the exported .js file via XHR and creates an effect model internally. The model is then available via this.cache.binary.get(key). Use this.add.neutrino(model, options) to create an effect instance that auto-updates and renders as part of the Phaser scene.

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({ position: [newX, newY, 0] });

// With new angle
effect.resetPosition({ position: [newX, newY, 0], angle: 45 }); // degrees

Restart

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

effect.restart({ position: [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:

import { Pause } from '@neutrinoparticles/js-v1.1-phaser'

const effect = this.add.neutrino(effectModel, {
  position: [400, 300, 0],
  pause: 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.

effect.setPropertyInAllEmitters('MyParticlesPerSecond', 100);
effect.setPropertyInAllEmitters('MyColor', [1.0, 0.5, 0.2]);

Number of Particles

const numParticles = effect.getNumParticles();

Common Issues

• Error: ... WebGL1 context lacks <capability> at startup: the (rare) WebGL1 context does not support the render technique — see Requirements. Running on a WebGL2 context (the context game option) lifts the requirement.
• No particles visible: Make sure the export target in the editor is set to JavaScript v1.1. Verify texturesBasePath points to the correct textures directory.
• Turbulence not working: Set generateNoise: true in the plugin config, or call the plugin's generateNoise() before creating effects that use noise.

Documentation

Full documentation at neutrinoparticles.com.

License

Copyright (c) Yurii Miroshnyk. All rights reserved.