# NixieFX editor & runtime feature reference

> Documentation · Updated August 2026 · https://nixiefx.com/vfx-runtime-docs/

An overview of everything the NixieFX particle system can do — the emitter and
module system, the node-based material editor, the PixiJS and Three.js
rendering backends, the export bundle, and runtime integration.

## TL;DR — what NixieFX is

**NixieFX** is two things: a free browser-based HTML5 particle VFX editor
(https://nixiefx.com/editor/) and an open-source (MIT) runtime, `nixie-fx` on
npm. Effects are authored as **plain JSON files** in your project folder and
exported to a self-contained `out/vfx` bundle. Games load that bundle through
**one shared, deterministic simulation** with renderer adapters for **PixiJS**
(2D scenes, HUD, UI effects) and **Three.js** (3D world effects). The editor
covers Unity-style emitter modules — emission shapes, curves and gradients,
velocity and forces, noise, trails, flipbooks, sub-emitters — plus a node-based
material editor, and every exported effect carries a per-backend support
report.

## Core concepts

| Concept | What it is |
| --- | --- |
| Project folder | A NixieFX project is any folder containing a `vfx-editor.prj` settings file. Open it in the editor or drive it from the `nixie-fx` CLI. |
| Effects as JSON | Authoring effects are plain JSON files under `particle-data/effects/` — the editable source of truth, diffable in git and readable by AI agents. |
| Export bundle | Export writes a self-contained `out/vfx` directory: `manifest.json`, compiled effect JSON, and byte-copies of every referenced asset. Games load only this bundle, never the authoring files. |
| Target profiles | Effects target `pixi-ui-2d`, `three-world-3d`, or `portable` (must satisfy both backends). |
| Support reports | Every exported effect carries per-backend status — `supported`, `partial`, or `blocked` — with warnings and the list of approximated modules, so integration can fail fast. |
| The editor | Free at https://nixiefx.com/editor/. Runs entirely in the browser, no install or account; your effects stay in your local project folder. |

## What does the NixieFX editor include?

| Editor feature | What it does |
| --- | --- |
| Live viewport | Previews the effect through the same runtime games embed, switchable between the PixiJS and Three.js backends, with live per-backend support diagnostics. |
| Timeline | Multi-emitter timeline with start-delay clips, per-emitter loop, enable, solo and lock, plus collapsible groups and playback transport with scrubbing. |
| Curve editor | Multi-point curves with per-point Bezier tangents and weights, editable ranges, and savable curve presets. |
| Gradient editor | Color + alpha stop gradients with blend or fixed stepping, used by color-over-lifetime, trails, and material ramps. |
| Material editor | Node-based shader-graph editor with live node-output previews (see Materials below). |
| Viewport helpers | Floor grid (Three.js backend), emitter origin gizmos, a navigation gizmo, and a particle wireframe debug overlay. |
| Preview bloom | HDR-style bloom preview with threshold, intensity, exposure, scatter, quality, and downscale controls — preview-only, never serialized into exports. |
| Effect templates | Starter templates (Impact Burst, Ambient Sparks, Smoke Puff, Starter Cone) for new effects. |

## Emission & emitter shapes

| Feature | What it does |
| --- | --- |
| Rate over time | Continuous emission from a constant, random-range, or curve value, sampled every update. |
| Rate over distance | Emits proportionally to how far the effect has moved — for trails behind moving objects. |
| Bursts & schedules | A single start burst plus a burst schedule table: time, count, cycles, interval, and per-burst probability. |
| Emitter shapes | Point, circle, box, cone, sphere, hemisphere, and mesh — with radius and radius thickness, box size, cone angle and length, base-or-volume emission, and per-shape position, rotation, and scale. |
| Arc control | Emission arc modes: random, loop, ping-pong, and burst-spread, plus an arc speed value. |
| Mesh emission | Spawns particles from mesh geometry — area-weighted surface sampling or vertices — using interpolated normals as the spawn direction. Three.js backend only. |
| Simulation space | World-space or local-space simulation per emitter. |
| Duration & capacity | Per-emitter duration, looping, max-particle cap, and a timeline start delay. |

## Particle values over lifetime

| Feature | What it does |
| --- | --- |
| Initialize Particle | Single source of initial values: lifetime, color, size, rotation, angular velocity, and start velocity (a speed along the shape direction, or a per-axis vector range). Mesh emitters add 3D size and rotation. |
| Color over lifetime | Gradient sampled over normalized age, multiplied onto the initial color. Initial color itself can be constant, random-between-two, a gradient, or random-between-two gradients, with independent alpha modes. |
| Size over lifetime | Curve multiplier over start size; billboards can use separate X/Y curves. |
| Rotation over lifetime | Spin as a scalar or Unity-style separate X/Y/Z axes; start rotation always applies independently of the spin toggle. |
| HDR emissive intensity | Unity-style intensity stops on particle color, preserved linearly in export for the game's own bloom/HDR pipeline. |
| Curves & gradients | Nearly every scalar accepts constant, random-between-two-constants, curve, or random-between-two-curves; curves can sample particle lifetime or emitter loop age. |

## Velocity, forces & noise

| Feature | What it does |
| --- | --- |
| Gravity & drag | Base forces applied over particle age. |
| Velocity over lifetime | Unity-style linear (local or world axes), orbital (per-axis angular velocity around an offsettable center), and radial velocity with a speed modifier — computed analytically, so motion is deterministic and identical across renderers, events, trails, and sub-emitters. |
| Limit velocity | Speed clamping with dampen and drag controls. |
| Inherit velocity | Particles inherit the emitter's movement velocity. |
| Force over lifetime | Constant or randomized directional force over age. |
| External forces | Wind, gravity multiplier, drag, and vortex. |
| Noise / turbulence | Two modes: per-axis sine jitter, or a coherent, divergence-free 3D curl-noise field shared by all particles — with a spawn ramp (particles are born exactly on the shape) and a strength-over-life curve. |
| Plane collision | Analytic plane bounce with bounce and dampen factors, supporting multiple decaying bounces and firing collision events. |
| Lifetime by emitter speed | Scales start lifetime by particle speed. |

## Trails, flipbooks, sub-emitters & events

| Feature | What it does |
| --- | --- |
| Trails | Per-particle history trails: emit ratio, trail-point lifetime, base width plus a width-over-trail curve, stretch or tile texture modes, a dedicated trail texture (or the particle's), gradient or inherited color, and a world-space toggle. |
| Flipbooks | Texture-sheet animation over uniform grids: tile counts, start/end frame range, frame-over-time curve, cycles, and random start frame. |
| Sub-emitters | Birth, collision, and death slots that spawn other effect files, with probability, property inheritance, spawn budgets, and recursion guards. |
| Events / triggers | Deterministic per-frame events for particle birth, death, normalized-time crossings, and collisions — drained from the runtime instance by game code. |
| Custom data | Four per-particle scalar channels (constant, random, or curve) with a label, feeding material Dynamic Parameters or game-specific consumers. |

## Rendering & sorting

| Feature | What it does |
| --- | --- |
| Blend modes | Alpha, additive, and premultiplied — premultiplied lets a single authored atlas mix additive glow and translucent smoke in one emitter. |
| Material blends | Masked (alpha cutout with a clip value) and opaque materials override the emitter blend for cutout and no-blending passes. |
| Shading | Unlit by default; lit shading on the Three.js backend makes mesh/world particles react to scene lighting. |
| Orientation | Face camera, spawn direction, current velocity, or a fixed vector — with camera-facing modes for aligned billboards. |
| Particle sorting | Per-emitter sort mode: none, distance far-first (alpha-correct painter order), distance near-first, oldest-first, or youngest-first. |
| Draw-order layers | Integer "order in layer" (−1024..1024) sorts emitters within an effect. |
| Opacity source | Alpha can come from the texture's alpha channel, a R/G/B channel, luminance, inverse luminance, or a constant, with an invert toggle — so RGB-only textures can alpha-blend without resorting to additive. |
| Textures | Project-relative texture refs with procedural circle or square billboards as fallback. |
| Mesh particles | PixiJS renders flat 2D shards (grass, triangle, and quad templates with thickness and pivot); Three.js renders prepared 3D mesh assets with flip-winding and recompute-normals options. |
| Depth | Real GPU depth test/write on Three.js; deterministic 2.5D draw ordering with a depth-ink option on PixiJS. |
| Two-sided rendering | Materials choose the rendered face on the 3D backend: double-sided (default), front, or back. |
| Pivots | Signed pivot offsets for billboards and mesh particles, including negative values. |

## Materials & the shader graph

The material editor is a node-based shader graph in the spirit of Unreal's
material editor. A graph outputs **base color, emissive, opacity, and opacity
mask**; texture-like nodes expose Unreal-style `RGB / R / G / B / A` output
pins, and graphs declare typed parameters (float, vec2, vec3, color, texture,
bool) with groups, slider and clamp ranges. Each emitter is assigned a
**material instance** — a reference to a shared graph plus per-instance
parameter overrides and a **MainTex override** — so one graph can drive many
emitters with different textures and settings.

| Node category | Nodes |
| --- | --- |
| Particles | Particle Color, Relative Time, Speed, Random, Size, Direction, Position, Macro UV, and DynamicParameter (four per-particle channels fed by the Custom Data module) |
| Constants | Constant, Time, Gradient Ramp |
| Coordinates | Texture Coordinate, Tiling & Offset, Rotator, Panner |
| Texture | Texture Sample and ParticleSubUV (flipbook-aware sampling) |
| Math | Add, Subtract, Multiply, Divide, Lerp, One Minus, Clamp, Step, Smoothstep, Power, Min, Max, Remap, Desaturate, Fresnel (radial), Sphere Mask, Split, Combine, Swizzle, Abs, Frac, Floor, Ceil, Round, Sign, Square Root, Length, Normalize, Dot Product, Sine, Cosine, If |
| Utility | Noise (Perlin-style, with turbulence, octave levels, tiling, and seed — baked to textures), Vector Noise (curl), Antialiased Texture Mask, Spherical Particle Opacity |
| Parameters | Parameter, Subgraph |
| Output | Base Color, Emissive, Opacity, Opacity Mask |

Material blend modes are `normal`, `add`, `masked`, and `opaque`. Procedural
noise nodes are **baked to textures** at compile time so they stay cheap at
runtime. Compilation is backend-aware: on PixiJS, graphs resolve to baked
textures and per-particle color channels so particles stay batch-friendly; on
Three.js, graphs compile to real shaders, which is where fully dynamic
per-pixel material features belong.

## How do the PixiJS and Three.js backends compare?

| Capability | PixiJS backend | Three.js backend |
| --- | --- | --- |
| Intended use | 2D games, HUD and UI effects | 3D world effects |
| Simulation | One shared deterministic core | Same core — same seeds, same motion |
| Billboards | Screen-space quads (batched particle containers) | Camera-facing world quads with an instanced fast path |
| Mesh particles | 2D shard approximation | Prepared 3D mesh assets |
| Mesh-surface emission | Not supported (falls back to point) | Supported |
| Lit shading | Not supported (exports with a warning) | Supported |
| Depth | Deterministic 2.5D ordering + depth ink | GPU depth test / depth write |
| Materials | Baked textures + per-particle channels | Compiled shaders |
| Trails | Supported | Supported |
| Support report key | `support.backends.pixi2d` | `support.backends.three3d` |

Where a feature is approximated or unsupported on a backend, the export says so
explicitly — a blocked effect must not be silently treated as supported, and a
partial effect can contain deliberate backend approximations.

## What does the export bundle look like?

```text
project/
  vfx-editor.prj          # project settings
  particle-data/effects/  # authoring JSON (source of truth)
  assets/                 # raw textures, materials, meshes
  out/vfx/                # exported game bundle
    manifest.json         # effect + asset index, validation status
    effects/*.json        # compiled effects with support reports
    ...                   # byte-copied referenced assets
```

The manifest indexes every compiled effect and deduped asset ref (textures,
materials, prepared meshes). Compiled effects carry source hashes for cache
invalidation, and a `support` object with the overall status, per-backend
reports, warnings, and the authoring paths of any approximated modules. If
validation blocks an export, the writer emits `export-diagnostics.json`
instead of a game-loadable bundle.

## How do games integrate the runtime?

Install `nixie-fx` with the renderer your game already uses (both are optional
peer dependencies), load the exported bundle, and advance the renderer once
per host frame in seconds:

```sh
npm install nixie-fx pixi.js   # or: npm install nixie-fx three
```

```ts
import { loadVfxExportBundle } from "nixie-fx/export";
import { PixiVfxRenderer } from "nixie-fx/pixi";
// Three.js: import { ThreeVfxRenderer } from "nixie-fx/three";

const bundle = loadVfxExportBundle(
  { manifest, effectsByPath, assetPaths },
  { requiredBackend: "pixi2d", requireEveryAsset: true },
);

const runtime = new PixiVfxRenderer({ parent: app.stage, textureProvider });
runtime.createEffect(bundle.effectsById.get("spark-burst"), { seed: 12345 });

app.ticker.add((t) => runtime.update(t.deltaMS / 1000));
// On scene teardown:
runtime.destroy();
```

Effect instances expose `spawn`, `reset`, `stop`, `setPosition`, and
`destroy`. The Three.js adapter follows the same lifecycle, constructed with a
scene and camera plus texture and mesh providers. The package also installs a
CLI — `npx nixie-fx effect create`, `validate`, and `export` — for scripted
and agent-driven workflows.

## Agent skills

NixieFX ships two official LLM agent skills from the same repository:
`nixie-fx-authoring` (project layout, effect creation, validation, export,
visual review) and `nixie-fx-runtime` (loading bundles, wiring providers, host
lifecycle). One command installs both for Claude Code, Cursor, Codex, Grok,
Copilot, Gemini CLI, and 40+ other agents:

```sh
npx skills add https://github.com/azakhary/nixie-fx
```

More at https://nixiefx.com/skills/.

## Frequently asked questions

### Which renderers does the NixieFX runtime support?

PixiJS (2D scenes, HUD and UI effects) and Three.js (3D world effects),
through one shared, deterministic simulation with renderer adapters. Install
`nixie-fx` from npm together with the renderer your game already uses — both
renderers are optional peer dependencies.

### What file format are NixieFX effects stored in?

Plain JSON. Authoring effects live next to a `vfx-editor.prj` project file and
diff like source code. Games never read those — they load the exported
`out/vfx` bundle: a `manifest.json`, compiled effect JSON, and byte-copies of
every referenced asset.

### Can the same effect run on both PixiJS and Three.js?

Yes, when authored against the `portable` target profile. Every exported
effect carries per-backend support reports (`supported` / `partial` /
`blocked`). Some features — prepared 3D mesh particles, mesh-surface emission,
lit shading, GPU depth — are Three.js-only, and the report states exactly
which apply.

### Is the NixieFX editor free?

Yes. It runs entirely in the browser at https://nixiefx.com/editor/ with no
install and no account, and effects stay in your local project folder. The
runtime, export pipeline, CLI, and agent skills are open source under the MIT
license.

## Resources

- **Runtime repository** — https://github.com/azakhary/nixie-fx (runtime, CLI, and skills, MIT)
- **npm package** — https://www.npmjs.com/package/nixie-fx
- **NixieFX editor** — https://nixiefx.com/editor/ (free, browser-based, files stay local)
- **Agent skills** — https://nixiefx.com/skills/
- **The web-native mobile game stack** — https://nixiefx.com/mobile-game-stack/

---

*This reference is maintained by the team behind NixieFX
(https://nixiefx.com/), the browser-based HTML5 particle editor for PixiJS and
Three.js. The HTML version lives at https://nixiefx.com/vfx-runtime-docs/,
and a site index for LLMs at https://nixiefx.com/llms.txt.*