@neutrinoparticles/bloom-v1.1-pixi8

HDR-glow bloom add-on for the PIXI v8 NeutrinoParticles runtime (@neutrinoparticles/js-v1.1-pixi8, 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 v7 use @neutrinoparticles/bloom-v1.1-pixi7.

Installation

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

pixi.js@^8 and @neutrinoparticles/js-v1.1-pixi8 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 (universal on desktop, ~95%+ of mobile). PIXI v8 uses WebGL2 by default. 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. You keep control of the render loop and choose what is bloomed.

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

const app = new PIXI.Application();
await app.init({
  width: 800, height: 600,
  autoStart: false,               // we drive the loop so bloom presents each frame
  neutrino: { texturesBasePath: 'textures/' },
});
document.body.appendChild(app.canvas);

// HDR scene target the effect renders into, and the bloom over it.
const sceneRT = NeutrinoBloomPixi8.createSceneTarget(app.renderer, app.renderer.width, app.renderer.height);
const bloom = new NeutrinoBloomPixi8(app.renderer, sceneRT, { intensity: 1.0 });

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] });

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

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

Turn bloom off by rendering scene straight to the screen instead (app.renderer.render({ container: 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 | |---|---| | NeutrinoBloomPixi8.createSceneTarget(renderer, width, height) | Create the HDR (RGBA16F) RenderTexture the effect renders into. | | new NeutrinoBloomPixi8(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. Keep PIXI's default (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. Render into createSceneTarget's RT, and give the effect HDR colour in the editor.
• Upside-down / mirrored: you presented into a top-left target while the add-on flips for the screen. present() targets the screen (bottom-left) 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 (as in Quick Start), calling present() last.

Documentation

Full documentation at neutrinoparticles.com.

License

Copyright (c) Yurii Miroshnyk. All rights reserved.