@neutrinoparticles/bloom-v1.1-pixi7

HDR-glow bloom add-on for the PIXI v7 NeutrinoParticles runtime (@neutrinoparticles/js-v1.1-pixi7, JS export format v1.1). Particles whose colour exceeds 1.0 glow with true HDR energy — the exact algorithm the editor preview shows, so the editor matches the game.

For PIXI v8 use @neutrinoparticles/bloom-v1.1-pixi8.

Installation

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

pixi.js@^7 and @neutrinoparticles/js-v1.1-pixi7 are peer dependencies. The version-agnostic core (@neutrinoparticles/bloom-v1.1) is installed automatically.

Requirements

WebGL2 only. Bloom renders into a float (RGBA16F) target so colour > 1 survives; that needs a WebGL2 context with a renderable float colour buffer. On WebGL1 the add-on throws a clear error at construction — render without it there.

Export Target in Editor

Set the export target to JavaScript v1.1 (same as the base runtime). Bloom only affects rendering — no bloom-specific export setting. For particles to glow, the effect must produce colour above 1.0 (HDR colour in the editor); colour ≤ 1 is preserved untouched.

Quick Start

Render your effect into the add-on's HDR scene target, then present() composites the bloom to the screen.

import * as PIXI from 'pixi.js';
import * as PIXINeutrino from '@neutrinoparticles/js-v1.1-pixi7';
import { NeutrinoBloomPixi7 } from '@neutrinoparticles/bloom-v1.1-pixi7';

const app = new PIXI.Application({
  width: 800, height: 600,
  autoStart: false,               // we drive the loop so bloom presents each frame
  preferWebGLVersion: 2,          // bloom needs WebGL2
  neutrinoV11: { texturesBasePath: 'textures/' },
});
document.body.appendChild(app.view);

const sceneRT = NeutrinoBloomPixi7.createSceneTarget(app.renderer, app.renderer.width, app.renderer.height);
const bloom = new NeutrinoBloomPixi7(app.renderer, sceneRT, { intensity: 1.0 });

PIXI.Assets.add({ alias: 'effectModel', src: 'export_js/my_effect.js', data: app.neutrinoV11.loadData });
const effectModel = await PIXI.Assets.load('effectModel');
const effect = new PIXINeutrino.Effect(effectModel, { position: [400, 300, 0] });

const scene = new PIXI.Container();
scene.addChild(effect);

app.ticker.add(() => {
  const sec = Math.min(app.ticker.deltaMS / 1000, 1.0);
  effect.update(sec);
  app.renderer.render(scene, { renderTexture: sceneRT, clear: true }); // scene -> HDR target
  bloom.present();                                                      // scene + bloom -> screen
});
app.start();

Turn bloom off by rendering scene straight to the screen instead (app.renderer.render(scene)). The preview-without-bloom then matches game-without-bloom.

Options

| Option | Default | Notes | |---|---|---| | intensity | 1.0 | Additive glow strength, baked into the combine at construction (editor value). |

The glow threshold is fixed at luminance 1.0 (scene ≤ 1 is preserved) and the white-core present tuning is baked to match the editor exactly.

API

| Member | Description | |---|---| | NeutrinoBloomPixi7.createSceneTarget(renderer, width, height) | Create the HDR (RGBA16F) RenderTexture the effect renders into. | | new NeutrinoBloomPixi7(renderer, sceneRT, options?) | Create the bloom over a scene target. Throws on a WebGL1 context. | | present() | Run the bloom over the scene RT and composite to the screen. Call once per frame after rendering the scene into the RT. | | destroy() | Release the bloom's GL resources. |

Algorithm

Soft-knee prefilter at half-res (only luminance > 1 glows) → 4-tap downsample down a 4-level pyramid → dual-Kawase 8-tap upsample → composite scene + additive bloom into a full-res HDR target → hue-preserving + white-core present. All targets are RGBA16F. A raw-WebGL2 port of the editor's BloomNeutrino via @neutrinoparticles/bloom-v1.1; the PIXI Filter API cannot express a mip pyramid, so bloom runs on raw WebGL2, bracketed by PIXI GL-state save/restore so it coexists with normal PIXI rendering (sprites, blend modes, masks, filters, and render textures).

Common Issues

• requires a WebGL2 context error at construction: bloom needs WebGL2 float targets. Set preferWebGLVersion: 2; do not force WebGL1.
• No glow: the effect's colour never exceeds 1.0, or the scene is not rendered into the HDR sceneRT. Bloom is scene-preserving — only HDR colour > 1 glows.
• Upside-down / mirrored: present() targets the screen and flips accordingly; render your scene into the provided sceneRT, not a hand-made top-left one.
• Black frame / bloom flashes then disappears: PIXI's autoStart cleared the canvas after present(). Use autoStart: false and drive the loop yourself, calling present() last.

Documentation

Full documentation at neutrinoparticles.com.

License

Copyright (c) Yurii Miroshnyk. All rights reserved.