A PixiJS healing glow with a readable health bar and explicit cleanup

A heal button has two jobs: change the player's health, then acknowledge the change. The second job should never make the first harder to read. This NixieFX tutorial builds a small PixiJS health-bar cue with particles behind the bar, an immediate numeric update, and explicit teardown.

Disclosure: an AI agent prepared this original tutorial and demo for a NixieFX linkbuilding assignment. The screenshots and results below come from the running fixture. They are not performance benchmarks or claims from a production game.

What this fixture does

The starting health is 35/100. Heal +25 updates it immediately and plays one green burst. Health clamps at 100. Damage −25 and Reset to 35 stop the current cue. A test-only button holds the burst at 0.20 seconds, using seed 61, so a screenshot can show a reproducible state.

The particle container is added before the bar graphic. Pixi's draw order therefore keeps the bar in front. The numeric label is HTML outside the canvas, with a progressbar role and current value; neither color nor animation carries the health value alone.

Real held frame: health 60/100, 32 active and 32 visible particles, t=0.20 s. The green dots rise from a narrow box surrounding the bar.

Export a small, bounded effect

The fixture pins nixie-fx 0.1.20 and PixiJS 8.19.0. Its effect targets pixi-ui-2d, uses one burst of 32 procedural billboards, and has a 0.65-second particle lifetime. It uses additive blending and unlit rendering, with depth settings disabled. No texture provider or external image asset is needed for this effect.

The spawn field is box, with dimensions [4, 0.18, 0] in effect units. At 100 pixels per unit, that spans 400 pixels around the bar's center. With the projection's Y axis pointing down, negative Y velocity sends particles upward. Resetting the existing effect instance restarts the cue; a click does not create a new renderer or instance.

For the broader authoring and integration context, the NixieFX PixiJS particle-effects documentation is the assigned reference. The source below includes the exact procedural authoring fixture used here.

Run it from the complete source

Create a directory containing the three files below: make-effect.mjs, index.html, and main.js. Then run:

npm init -y
npm pkg set type=module
npm install --save-exact nixie-fx@0.1.20 pixi.js@8.19.0 vite@7.1.9
node make-effect.mjs
npx vite --host 127.0.0.1

Open the local URL printed by Vite. The builder validates the authoring project, exports it, and copies the exported bundle into public/vfx. Vite serves those files as /vfx. Serving unbundled main.js with a plain static server will not resolve its npm imports; use Vite for this source version.

Trigger and cleanup

The health update happens before start(). The animation branch checks both the demo's Reduce motion checkbox and the operating-system preference. Reduced motion still updates the health value, without starting particles. Changing that preference while the cue is active stops the cue.

The runtime uses a manually driven animation loop, with Pixi's ticker stopped. The loop advances the effect, renders the stage, and stops updating after the cue window. This is a UI example, so elapsed frame steps are capped at 0.05 seconds. It is not a simulation clock for gameplay logic.

Dispose demo cancels the animation frame, removes motion listeners, destroys the NixieFX renderer and Pixi application, removes the canvas, and disables controls. A pagehide listener uses the same guarded disposal path. Reload the page to create a fresh instance.

What was actually checked

The export validator reported 0 errors and 0 warnings. The loaded effect's PixiJS backend support report was supported. In Chromium, the following UI actions were checked:

Action	Observed result
Hold the first heal at 0.20 s	Health 35 → 60; active 32, visible 32
Hold a second heal	Health 60 → 85; still active 32, visible 32
Advance the held effect by 1 s	Active 0, visible 0
Enable Reduce motion, then heal	Health 85 → 100; active 0, visible 0
Dispose	Canvas removed; buttons and motion checkbox disabled

Limits worth keeping visible

This fixture exercises a fixed 560×300 WebGL canvas and one assetless PixiJS effect. It does not establish mobile performance, screen-reader compatibility across browsers, or a frame-rate budget. The canvas can scroll horizontally on a narrow viewport; a real responsive HUD should fit its own layout and recalculate the effect origin when that layout changes.

Mesh rendering, lit materials, GPU depth behavior, textured effects, and Three.js are outside this example's tested scope. Do not assume a different export is supported because this one is: inspect its target report and add required asset providers. The held-frame and advance buttons are debugging controls, not player-facing features.

The useful pattern is small: update state immediately, make the cue decorative, reuse one bounded effect instance, and destroy the resources when the UI leaves.

Complete authoring and runtime source

The code blocks contain the full files, including the HTML controls. No omitted helper or private repository is required.

make-effect.mjs

import { mkdir, writeFile, cp } from 'node:fs/promises';
import { execFileSync } from 'node:child_process';
import { createDefaultParticleEffect, createConstantParticleScalar as scalar, normalizeParticleEffect } from 'nixie-fx';
import { normalizeEditorProjectFile } from 'nixie-fx/project';
const stamp='2026-10-13T00:00:00.000Z';
await mkdir('authoring',{recursive:true});
const project=normalizeEditorProjectFile({app:'vfx-editor',kind:'project',version:1,id:'n308-health-glow',name:'Healing glow',createdAt:stamp,updatedAt:stamp,settings:{effectDataPath:'.',outputPath:'out/vfx',assetRootPath:'.',allowExternalOutput:false}});
await writeFile('authoring/vfx-editor.prj',JSON.stringify(project,null,2));
const effect=createDefaultParticleEffect('healing-glow','Healing glow');
effect.targetProfile='pixi-ui-2d';effect.timeline.duration=0.8;effect.timeline.loop.enabled=false;
const e=effect.emitters[0];
e.maxParticles=32;e.duration=0.05;e.loop=false;
e.spawn.shape='box';e.spawn.box=[4,0.18,0];e.spawn.rate=0;e.spawn.rateValue=scalar(0);
e.spawn.bursts=[{time:0,count:32,cycles:1,interval:0,probability:1}];
e.initializeParticle.lifetime=scalar(0.65);
e.initializeParticle.size=scalar(0.09);e.billboard.sizeValue=scalar(0.09);e.billboard.softness=0.5;
e.modules.velocity=true;e.initializeParticle.velocity.mode='vector';
e.initializeParticle.velocity.min=[-0.12,-0.8,0];e.initializeParticle.velocity.max=[0.12,-0.35,0];
e.initializeParticle.color.color=[0.25,1,0.45,1];e.initializeParticle.color.intensity=scalar(1);
e.initializeParticle.color.intensity.editorMin=0;e.initializeParticle.color.intensity.editorMax=16;
e.modules.color=true;e.color.gradient.alphaStops=[{position:0,alpha:1},{position:0.6,alpha:0.75},{position:1,alpha:0}];
e.render.blend='additive';e.render.shading='unlit';e.render.depthTest=false;e.render.depthWrite=false;e.render.depthInk=false;
await writeFile('authoring/healing-glow.json',JSON.stringify(normalizeParticleEffect(effect),null,2));
const cli=new URL('./node_modules/nixie-fx/dist/cli.js',import.meta.url).pathname;
execFileSync(process.execPath,[cli,'validate','./authoring'],{stdio:'inherit'});
execFileSync(process.execPath,[cli,'export','./authoring'],{stdio:'inherit'});
await mkdir('public/vfx',{recursive:true});await cp('authoring/out/vfx','public/vfx',{recursive:true});

index.html

<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Healing glow — PixiJS / NixieFX</title><style>body{margin:32px auto;max-width:760px;padding:0 20px;background:#091515;color:#e9fff1;font:16px/1.5 system-ui}h1{font-size:30px;margin-bottom:6px}p{color:#b4c9bf}#stage{width:560px;max-width:100%;overflow:auto;border:1px solid #375b48;border-radius:12px}#health{font-size:24px;font-weight:700;margin:18px 0 8px}button{background:#215c3f;color:white;border:1px solid #65b28b;padding:10px 14px;border-radius:6px;margin:6px 5px 6px 0;cursor:pointer}button:disabled{opacity:.5}pre{white-space:pre-wrap;background:#183027;padding:12px;border-radius:6px}label{display:block;margin:12px 0}</style><h1>A healing cue that leaves the health value readable</h1><p>PixiJS 8.19.0 · nixie-fx 0.1.20 · one 32-particle burst · procedural, assetless fixture</p><div id="health" role="progressbar" aria-label="Health" aria-valuemin="0" aria-valuemax="100" aria-valuenow="35">Health 35 / 100</div><div id="stage"></div><div><button id="heal" disabled>Heal +25</button><button id="hold" disabled>Heal +25 · hold at 0.20 s</button><button id="damage" disabled>Damage −25</button><button id="reset" disabled>Reset to 35</button><button id="finish" disabled>Advance 1 second</button><button id="dispose" disabled>Dispose demo</button></div><label><input id="reduce" type="checkbox"> Reduce motion (also respects OS preference)</label><pre id="report">Loading runtime and export…</pre><p>The health value changes immediately. Particles are decorative and sit behind the bar. Holding a frame is a test control; disposal removes the canvas and disables controls. Reload to restart.</p><script type="module" src="./main.js"></script></html>

main.js

import {Application, Container, Graphics} from 'pixi.js';
import {PixiVfxRenderer, createPixiVfx2dProjection} from 'nixie-fx/pixi';
import {loadVfxExportBundle} from 'nixie-fx/export';
const report=document.querySelector('#report'),stage=document.querySelector('#stage');
try {
 const app=new Application(); await app.init({width:560,height:300,resolution:1,background:'#102020',preference:'webgl',antialias:true});app.ticker.stop();stage.append(app.canvas);
 app.canvas.setAttribute('role','img');app.canvas.setAttribute('aria-label','Green healing particles behind a health bar');
 async function json(path){const r=await fetch(path);if(!r.ok)throw Error(`Load failed: ${path}`);return r.json();}
 const manifest=await json('./vfx/manifest.json');
 const effectsByPath=Object.fromEntries(await Promise.all(manifest.effects.map(async e=>[e.path,await json('./vfx/'+e.path)])));
 const bundle=loadVfxExportBundle({manifest,effectsByPath},{requiredBackend:'pixi2d',requiredEffectIds:['healing-glow']});
 const effect=bundle.effectsById.get('healing-glow');if(effect.assets.length)throw Error('This fixture requires an assetless effect.');
 const layer=new Container();app.stage.addChild(layer);
 const runtime=new PixiVfxRenderer({parent:layer,projection:createPixiVfx2dProjection({pixelsPerUnit:100,yAxis:'down'})});
 const pulse=runtime.createEffect(effect,{autoStart:false});
 const bar=new Graphics();app.stage.addChild(bar);
 const reduce=document.querySelector('#reduce'),pref=matchMedia('(prefers-reduced-motion: reduce)'),value=document.querySelector('#health');
 let health=35,running=false,t=0,last=0,raf=0,disposed=false;
 function draw(){bar.clear().roundRect(60,140,440,30,8).fill(0x304343);if(health>0)bar.roundRect(63,143,434*health/100,24,6).fill(0x57dc8b);app.renderer.render(app.stage);value.textContent=`Health ${health} / 100`;value.setAttribute('aria-valuenow',health);report.textContent=`PixiJS export: ${effect.support.backends.pixi2d.status} · active ${pulse.stats.activeParticles} · visible ${pulse.stats.visibleParticles} · t=${t.toFixed(2)} s · seed 61`;} 
 function stop(){running=false;pulse.stop();t=0;}
 function start(hold=false){stop();if(reduce.checked||pref.matches){draw();return;}pulse.reset({position:[2.8,1.55,0],seed:61});if(hold){for(let i=0;i<24;i++)runtime.update(1/120);t=.2;}else{running=true;last=performance.now();}draw();}
 document.querySelector('#heal').onclick=()=>{health=Math.min(100,health+25);start();};
 document.querySelector('#hold').onclick=()=>{health=Math.min(100,health+25);start(true);};
 document.querySelector('#damage').onclick=()=>{health=Math.max(0,health-25);stop();draw();};
 document.querySelector('#reset').onclick=()=>{health=35;stop();draw();};
 document.querySelector('#finish').onclick=()=>{running=false;for(let i=0;i<120;i++)runtime.update(1/120);t+=1;draw();};
 function motion(){stop();draw();}reduce.addEventListener('change',motion);pref.addEventListener('change',motion);
 function dispose(){if(disposed)return;disposed=true;running=false;cancelAnimationFrame(raf);reduce.removeEventListener('change',motion);pref.removeEventListener('change',motion);window.removeEventListener('pagehide',dispose);runtime.destroy();app.destroy(true,{children:true});for(const b of document.querySelectorAll('button'))b.disabled=true;reduce.disabled=true;report.textContent='Disposed: RAF cancelled, runtime and Pixi application destroyed.';}
 document.querySelector('#dispose').onclick=dispose;window.addEventListener('pagehide',dispose);
 function frame(now){if(disposed)return;if(running){const dt=Math.min((now-last)/1000,.05);runtime.update(dt);t+=dt;if(t>.8)running=false;draw();}last=now;raf=requestAnimationFrame(frame);}raf=requestAnimationFrame(frame);
 for(const b of document.querySelectorAll('button'))b.disabled=false;draw();
}catch(e){report.textContent=e.message;console.error(e);}