NixieFX Editor Manual

Getting started

Browser requirements

The editor runs at nixiefx.com/editor/ with no install and no account. It reads and writes real folders on your computer through the browser's File System Access API, which today ships in Chromium-based browsers: Chrome, Edge, Arc, Brave, or Opera. In Safari or Firefox the editor shows a full-screen notice ("Reading and writing local folders needs the File System Access API, which this browser does not support yet") instead of the launcher.

Nothing is uploaded. Projects are ordinary folders; the browser asks for read/write permission per folder, and the launcher footer states it plainly: "Your folders stay on your computer · nothing is uploaded."

The launcher

When no project is open, the launcher offers:

The playground

The playground is a real project folder on disk, not a browser sandbox, so everything you author there is saved as normal files a game can load. The first click walks you through setup:

1. A dialog explains the plan ("Set up your playground") and asks you to pick an empty folder. The playground project is copied into it, and the browser asks permission to access the folder.
2. If the folder you pick is not empty, the editor refuses — "The playground needs an empty folder so it can never overwrite anything of yours." — and offers to pick another.
3. If the folder already contains a VFX project, the editor offers to adopt it as your playground instead ("Project found — use it as your playground?").

After setup the playground folder is remembered. On later visits the same card reopens it directly. Two recovery flows are built in:

• Permission expired — browsers periodically drop folder permissions. The editor shows "Folder access needed" and re-asks until you grant access or cancel.
• Folder deleted or emptied — if the remembered folder no longer contains a project, setup starts over from step 1.

If you used an older NixieFX build whose playground lived purely in browser storage, its contents are copied into the disk folder you pick, so nothing you authored is lost.

Interface tour

Top bar

Tool tabs: VFX and Materials

Below the top bar, two tool tabs switch the whole workspace: VFX (the particle editor) and Materials (the shader graph editor). A dot appears on the Materials tab while the open material has unsaved changes. Switching into Materials while the current effect is dirty prompts to discard; switching back never prompts, because material work is continuously auto-preserved in a per-project scratch slot. The chosen tab is remembered between sessions.

Viewport toolbar

Viewport footer

The strip under the viewport shows live readouts and playback controls:

• particles — active particle count over total capacity; time — preview time in seconds; timing — simulation milliseconds (hover for frame / update / draw ms and fps).
• Play/Pause and Restart — pause freezes the simulation; Restart replays from time 0. By default each restart picks a fresh random seed; see lock seed below.
• Reset view — restores the default camera (double-clicking the viewport does the same).
• Zoom slider — camera zoom, 0.45×–2.5×.
• ortho — orthographic camera toggle (on by default).
• auto-loop — when a one-shot effect finishes (all emitters done, all particles gone), the preview automatically restarts. On by default.
• lock seed — keep the same random seed on every replay for bit-identical repetition. Off by default, so replays vary. Scrubbing and seeking never reseed regardless of this toggle.
• FOV slider — perspective field of view, 8–65 degrees; disabled while the camera is orthographic.

Bottom workspace and inspector

The bottom panel has two tabs — Assets and Timeline — that share a single toolbar row. Both stay mounted, so switching tabs never loses state. Drag the handle above the panel to resize it (220–520 px; double-click resets). The right-hand inspector panel hosts the emitter modules and the Validation & Export panel; its width is also draggable (320–640 px).

Projects and files

A NixieFX project is any folder containing a vfx-editor.prj settings file. Effects are plain JSON files — the editable source of truth — and everything the editor writes stays inside the project folder:

Project Settings dialog

Top bar → Settings. Each row shows a Default/Custom pill; paths are project-relative.

With the default settings (Effect Data and Asset Root both .) the Assets browser shows two roots — Project Files and Export Output. When the two paths differ it shows three: Particle Effects, Assets, and Export Output. Export Output is always read-only.

The Assets browser

The Assets tab is a three-pane file manager: a folder tree on the left, the file view in the middle (with breadcrumbs and a status bar), and a details inspector on the right.

Toolbar

• Create menu — New Folder, New Particle Effect, New Material, and a "From Template" section with the effect templates Impact Burst, Ambient Sparks, and Smoke Puff. New effects and folders drop straight into inline rename; new effects open in the editor immediately.
• Import menu — Import Texture, Import Mesh, Import Effect JSON (multi-select file dialogs).
• File actions — Copy, Paste, Move, Duplicate, Rename, Delete, Reveal in Finder (desktop dev build only), Refresh.
• A recursive search box ("Search project...") that matches names and paths across the whole current root.
• Sort menu — Name, Type, Size, Date modified; Ascending / Descending. Folders always list first.
• List view / Grid view toggle. Both persist across sessions.

Navigation and selection

• Back / Forward buttons walk a real history stack; "Up one folder" and clickable breadcrumbs move within the tree.
• Multi-select with Ctrl/Cmd + click (toggle), Shift + click (range), or a rubber-band marquee drag on empty space. Arrow keys, Home/End, PageUp/PageDown and type-ahead work in the file view — see Keyboard shortcuts.
• Double-click behavior by type: folders navigate; particle effects open in the VFX editor; materials open in the Material editor; textures and meshes just select.
• Texture files show live image thumbnails in both views; effects show a spark icon, materials a palette icon, meshes a box icon.

Drag and drop

• Move — drag entries onto a folder card, a tree row, or a breadcrumb. Invalid drops (same folder, folder into itself) are refused with a reason. The Move... action opens a destination-picker dialog for the same operation.
• Import from the OS — drop files anywhere on the browser: images become textures, .glb/.gltf become meshes, and .json imports as an effect (or a mesh when dropped in the assets root). The overlay reads "Drop textures, meshes, or effect JSON to import".
• Dragging a single texture or mesh onto a texture/mesh field in the inspector assigns it there.

Context menu

Right-click an entry (or empty space) for: New Folder, New Particle Effect, New Material, Import Texture / Mesh / Effect JSON, Open, Export Game VFX (on effect files — exports just that effect), Rename, Copy, Paste, Move..., Duplicate, Delete, Reveal in Finder (desktop only), and Refresh.

Details pane and missing references

• Textures — preview, path, type, size, modified date, a reference count, and a "Referenced by" list of the effects and emitters using the texture ("Unused by saved effects" when none).
• Effects — file, emitter count, modified date, and a validation pill. The open effect shows its live validation summary ("Valid" or "N errors, N warnings") plus an open / open (unsaved) badge; other effects show "Open to validate".
• Materials — file, node count, modified date.
• The status bar shows the current location, the item and selection counts, and — when any saved effect references a file that no longer resolves — a warning counter like "2 missing asset refs".

Authoring particle effects

An effect is a set of emitters; each emitter is configured through a fixed stack of modules in the right-hand inspector. Select an emitter by clicking its track in the timeline; add one with the + button in the timeline toolbar (or the "Add emitter" button shown when an effect has none). The inspector starts with a locked Effect section (effect Id and Name), then the emitter modules in two groups: "Runtime-bound emitter modules" and "Extended emitter modules", and ends with Validation & Export.

Module conventions

• Every module is a collapsible section. Optional modules have an enable checkbox in the header; structural modules (Initialize Particle, Shape, Renderer, Emission) are always on. Collapse state is remembered per module. There is no "add module" picker — the stack is fixed, and modules are turned on with their checkbox. The one exception is Shader Custom Data, which hides behind a + Shader Custom Data (advanced) button until enabled.
• Some modules have a recipe menu (sparkles button, "Apply a module recipe") with one-click presets; recipes may adjust related modules too (an Emission recipe also sets duration, shape, and start speed).
• Number fields are Blender-style: drag to scrub, click to type, arrow keys nudge by one step, hold Shift while dragging for 0.1× fine control. Bounded values render as filled sliders; unbounded ones as steppers with ‹ › arrows. Booleans are On/Off toggles.
• Backend-specific behavior is called out in inline notes under the affected field (for example "Three pins the alignment axis in 3D. Pixi uses a projected 2.5D approximation.").

Value modes

Most scalar fields accept more than a constant. The chevron next to the field ("Value mode") opens a menu:

The same menu always ends with a Curve Range row — two numbers setting the curve editor's vertical range for this field.

Module reference

• Main
• Emission
• Initialize Particle
• Shape
• Forces (Gravity & Drag)
• Velocity over Lifetime
• Color over Lifetime
• Size over Lifetime
• Rotation over Lifetime
• Renderer
• Limit Velocity over Lifetime
• Inherit Velocity
• Lifetime by Emitter Speed
• Force over Lifetime
• Color by Speed
• Size by Speed
• Rotation by Speed
• External Forces
• Noise
• Plane Collision
• Triggers
• Sub Emitters
• Texture Sheet Animation
• Particle History Trails
• Shader Custom Data

Main

The module checkbox here enables or disables the whole emitter.

Emission

Always on (dims with the emitter). Recipes: Steady, Burst, Aura, Trail.

Initialize Particle

Always on. The single source of every particle's initial state.

Shape

Always on. Fields appear per shape.

Forces (Gravity & Drag)

Optional. Initial velocity is set in Initialize Particle; this module applies gravity and drag over the particle's age.

Velocity over Lifetime

Optional. Adds linear, orbital, and radial velocity over the particle's age — computed analytically, so motion is deterministic and identical on both backends.

Color over Lifetime

Optional. Recipes: White, Fire, Smoke, Magic.

Size over Lifetime

Optional. Recipes: Constant, Shrink, Grow, Pop.

Rotation over Lifetime

Optional. Controls only over-life spin — Start Rotation (from Initialize Particle) always sets the initial angle. Recipes: Still, Random, Spin, Tumble.

Renderer

Always on; starts collapsed. Recipes: Glow, Sprite, Smoke, Shards. The badge reads "textured" once a texture is assigned, otherwise "<mode> / <blend>".

The texture picker — texture slots open a searchable grid of the project's images with a None card ("No texture (procedural shape)") that falls back to the built-in procedural billboard. You can import from the picker (button or drag-and-drop); accepted formats are .png, .jpg, .jpeg, .gif, .webp, .bmp, .svg and .avif. Mesh slots work the same way for .glb, .gltf and mesh .json files.

Limit Velocity over Lifetime

Inherit Velocity

Lifetime by Emitter Speed

Force over Lifetime

Color by Speed

Size by Speed

Rotation by Speed

External Forces

Noise

Plane Collision

Triggers

Named runtime events your game code can listen for. Event names are free-form strings.

Sub Emitters

Three fixed slots — Birth, Collision, and Death — each spawning another effect file from this project:

Sub-emitters currently run on the Pixi backend; enabling the module reports a blocker on the Three backend.

Texture Sheet Animation

Flipbook animation over a uniform sprite-sheet grid.

Particle History Trails

Per-particle ribbons. Three renders a camera-facing world-space ribbon from particle centers; Pixi renders a screen-space particle-history approximation.

Shader Custom Data

Four per-particle scalar channels (each supporting constant / random / curve, range −1…1) plus a label. When the emitter is bound to a material with a DynamicParameter node, the channels take that node's names and feed it directly — see Materials. Until then the channels are named Param1–Param4. Pixi delivers the channels as one emitter-level representative value; Three evaluates random and curve channels per particle.

Curves and gradients

The curve editor

Clicking any curve thumbnail opens Particle System Curves — a draggable floating panel (Escape closes it; its position is remembered). The toolbar shows the value axis with the field's unit, a Multiplier ("Multiplies the graph output after the curve is evaluated"), and the X axis: Particle Lifetime (normalized particle age, the default) or Loop Age (the emitter's normalized loop time). In Random Between Two Curves mode, Curve A / Curve B tabs switch the edited side; both curves stay visible with the band between them filled.

• Add a point — double-click the canvas. Remove — select and press Delete / Backspace, or the Remove button. Curves keep at least 2 and at most 8 points. The first and last points are locked to x = 0 and x = 1.
• Select — click a point; Shift + click toggles; drag on empty canvas draws a marquee. With two or more points selected, a transform box appears with eight scale handles — drag the body to move the group, drag a handle to scale it.
• Tangents — the primary point shows draggable in/out Bezier handles (dragging sets slope and weight together). The point row exposes numeric T, V, In, Out, Win, Wout fields and the tangent mode buttons Auto (shape-preserving), Flat (slope 0 — stops overshoot), Linear (through neighbouring keys), Break (independent sides) and Unify (one symmetric slope).
• Value range — double-click the top or bottom axis label to type a new bound (the top label adjusts the multiplier; the bottom sets the minimum), or use the Curve Range row in the value-mode menu.
• Optimize — simplifies the curve by removing redundant points at the chosen tolerance (Tol 0.001 / 0.005 / 0.01 / 0.025), preserving endpoints and sharp spikes.
• Presets — built-ins Hold, Rise, Warm Up, Snap In, Pulse, Fade, Soft Fade, Late Pop, S-Curve, and Blink, remapped into the field's current range. The Saved row saves and loads your own named presets per project; saving under an existing name overwrites it.

The drawn stroke is sampled by the same runtime curve evaluator the game uses, so what you see is exactly what plays back.

The gradient editor

Gradient swatches (Color over Lifetime, Color by Speed, material Gradient Ramp nodes) open the Gradient floating panel:

• Blend / Fixed — smooth interpolation between stops, or hard stepping where each stop holds until the next.
• Two stop tracks around the gradient bar: alpha stops on top, color stops below. Double-click a track to add a stop; double-click a stop (or use the trash button) to remove it; drag to move. Up to 8 stops of each kind; the last one of a kind cannot be deleted.
• A selected color stop shows its Color, a Location percentage, a duplicate-stop button, and an embedded color picker. A selected alpha stop shows an alpha slider plus a 0–255 value and its Location.
• Presets: White Fade, Ember, Smoke, Magic, Poison, Ice.

The color picker

Color swatches open a compact picker: a saturation/value square, a vertical hue strip, a 6-digit HEX field, and R / G / B inputs (0–255). The picker is RGB-only — alpha is edited through gradient alpha stops or the Initial Alpha field, and HDR brightness through Emissive Intensity.

The timeline

The Timeline tab shows one track per emitter. Clicking a track selects that emitter in the inspector.

Tracks and clips

• Per-track buttons: Loop (emitter looping), Solo (preview only this emitter — an editor-side preview state, not saved into the effect), Lock (protects the track from edits), and Mute (disables the emitter — this one is saved into the effect JSON).
• Drag the clip body to change the emitter's start delay. Drag the left edge to move the start while pinning the end (changes delay and duration). Drag the right edge to change the duration. Dragging past the end of the timeline grows the effect duration. Minimum duration is 0.05 s.
• Double-click a track or clip name to rename inline (Enter commits, Escape cancels). Reorder emitters with Move up / Move down in the context menu.
• Groups — effects whose JSON defines timeline groups show group rows with collapse, group-lock, and group-hide controls (hide toggles every member emitter). The editor does not currently create groups itself.
• Right-click a track for the full context menu: Rename, Copy, Paste, Duplicate, Enable/Disable loop, Lock/Unlock, Mute/Unmute, Solo/Unsolo, Move up/down, Delete. Right-clicking empty space offers Paste at playhead.

Transport and tools

The tab strip hosts a single toolbar row: emitter tools (add emitter at playhead, snap magnet, copy / paste / duplicate, loop, lock, mute, delete), then the transport — jump to start, step back one frame, play/pause, step forward one frame, jump to end, Loop playback range, and Restart effect — followed by the playhead readout, a Frames / Seconds unit toggle, an FPS field (1–240, presets 24, 25, 29.97, 30, 50, 60, 120 — display-only: it changes labels and the snap grid, never playback speed), and zoom controls with a Fit button.

• Scrubbing — drag the ruler or playhead. Seeks are deterministic: scrubbing backward re-simulates from time 0 with the same seed, so the state you land on is exactly what playback would have produced. Scrubbing never reseeds and never toggles play/pause.
• Loop range — with "Loop playback range" on, a bracket appears on the ruler; drag its ends or middle to set the range. Each loop wrap picks a fresh seed unless lock seed is on.
• Snap — the magnet toggles snapping to the frame grid (or the visible seconds grid in Seconds mode); off allows subframe drags.
• Zoom — the slider or Ctrl/Cmd + wheel over the lanes (0.1×–12×).

Preview, camera and backends

Pixi and Three backends

The preview renders through the same nixie-fx runtime games embed, with two switchable backends. The Pixi / Three toggle in the viewport toolbar also sets the effect's target profile, which is saved in the effect JSON: Pixi ⇒ pixi-ui-2d, Three ⇒ three-world-3d. New effects and all bundled templates default to three-world-3d. (A third profile, portable, means "must satisfy both backends"; the editor previews portable effects through Pixi.)

Each toggle button carries a support dot — supported, partial, or blocked — computed live from the current effect, and the tooltip names the first blocker or warning (for example, mesh particle assets are Three-only, sub-emitters are currently Pixi-only, lit shading warns on Pixi). The same per-backend reports are written into every export.

Camera

Bindings are identical on both backends, and the camera state is remembered per project. The navigation gizmo in the viewport corner shows the current orientation: click an axis ball (+X, −X, +Y, −Y, +Z, −Z) to snap to that view (snapping forces orthographic on), click the center to toggle perspective/orthographic, drag the disc to orbit, or wheel over it to zoom. The camera starts orthographic; the ortho checkbox and the FOV slider (8–65°, perspective only) live in the viewport footer.

Gizmos

The Gizmos menu lists what applies to the selected emitter, each with its own visibility checkbox:

• Shape outlines (Circle / Box / Cone / Sphere / Hemisphere shape) — wireframes with draggable handles that edit the module values directly: radius, box width/height/depth, cone radius/length/angle. Visible by default.
• Move origin — a translate gizmo on the emitter origin with X/Y/Z arrows, plane handles, and a ground-plane center handle. It edits Initialize Particle → Emitter Position. Visible by default.
• Particle pivots and Particle wireframes — per-particle debug overlays (pivot crosses and quad outlines for the selected emitter). Hidden by default.

Preview bloom

The Bloom button opens the preview bloom popover. Bloom is a preview aid only — it is stored in browser storage per project and never saved into effects or exports. Your game applies its own bloom; the editor's exists so HDR emissive values can be judged visually.

The reset button restores the balanced defaults above.

Materials and the shader graph

The Materials tool tab is a node-based shader graph editor in the spirit of Unreal's material editor. A material is a graph that outputs baseColor, emissive, opacity, and opacityMask; any output left unwired shows a (fixed) tag and falls back to the built-in Sprite Master fixed-function behavior. Materials are saved as .material JSON files in the project's materials folder.

Creating and saving materials

• + New Material in the sidebar creates an in-memory draft; the Assets browser's Create menu and context menu create the file immediately and open it. Double-clicking a .material in the Assets browser opens it too.
• New materials seed with the Sprite Master parameter set — MainTex (texture), Tint (color), Emissive (float), and Opacity (float) — plus an Output node.
• Save lives in the graph toolbar (a name prompt appears for unsaved drafts). Work in progress is also auto-preserved per project, so switching tabs or reloading never loses the graph. Note: Ctrl/Cmd + S saves only in the VFX view — in the Materials view use the Save button.

Working the graph

• Add nodes — click a palette entry (drops at the view center), drag it onto the canvas, or right-click empty canvas for a searchable "Add node…" menu.
• Connect — drag from an output pin to an input pin. Inputs take one connection; outputs fan out. Texture pins only connect to texture pins; float and vector types inter-connect freely (floats broadcast). Invalid connections flash the reason (incompatible types, cycles, occupied input).
• Rewire / disconnect — Alt + click a pin breaks its connections; Alt + click an edge deletes it; dragging from a wired input pin picks the wire up to re-drop elsewhere; hold Ctrl/Cmd to grab an existing edge end.
• Edit — Ctrl/Cmd + C / V / D copy, paste and duplicate selected nodes; Delete removes them (the Output node cannot be deleted); undo/redo with Ctrl/Cmd + Z / Ctrl/Cmd + Shift + Z. Pan with middle- or right-drag; left-drag box-selects.
• Previews — the right-hand Preview panel renders the material; select a node and press Start Previewing Node to inspect any intermediate output (with a pin selector for multi-output nodes). Selected nodes with animated inputs also draw a live inline preview, and Noise nodes always show their baked swatch. Right-clicking a Constant offers Promote to Parameter.

Node catalog

Texture-like nodes expose Unreal-style RGB / R / G / B / A output pins; most math nodes have a single Out pin.

Material settings

Parameters and material instances

The inspector's Parameters section declares typed inputs — float, vec2, vec3, color, texture, bool — with a display group, a Per-material or Global scope, an optional slider range (floats), and an optional Per-particle flag (floats; feeds DynamicParameter).

An emitter binds a material through the Renderer module's Surface row. What the emitter stores is a material instance: the graph reference plus per-instance parameter overrides and an optional MainTex override — so one graph can drive many emitters with different textures and settings. Overridden rows get a reset button ("Reset to default") that returns them to the graph's live default.

Tiers: how materials run on each backend

The meter strip under the graph reports the compiled Tier, the texture-tap count (warns above 3), the shader program count, and any per-particle inputs:

Exporting for games

The inspector's Validation & Export module shows the current effect's validation summary (blockers, errors, warnings) and the Export Game VFX button, which exports the whole project. Right-clicking an effect file in the Assets browser offers a single-effect Export Game VFX as well.

Export writes the project's output folder (default out/vfx):

• Every compiled effect (and its manifest entry) carries a support report per backend — supported, partial, or blocked — with warnings and blockers, so a game can fail fast on effects its renderer cannot honor.
• If validation blocks the export, the editor writes export-diagnostics.json instead of a bundle and lists the diagnostics in the panel.
• The output folder is emptied and rewritten on every export — never keep hand-made files in it.
• The result panel reports the outcome ("Exported N effects to out/vfx.", "…with partial-support warnings.", or "Export blocked for N effects.") with the written files and any diagnostics.

Loading the bundle in a game is covered by the runtime feature reference and the Three.js runtime guide: install nixie-fx with your renderer, load the bundle, and drive update() from your frame loop.

Keyboard shortcuts

There is no spacebar play/pause and no export shortcut. The save shortcut applies only in the VFX view — materials save with their toolbar button.

Troubleshooting & FAQ

Resources

• Open the editor free, browser-based, your files stay local
• Feature reference capability overview of the editor and runtime
• Three.js runtime guide loading exported effects in a Three.js game
• Runtime repository github.com/azakhary/nixie-fx — runtime, CLI, and skills (MIT)
• Agent skills nixie-fx-authoring + nixie-fx-runtime install guide

This manual is maintained by the team behind NixieFX, the browser-based particle editor for PixiJS and Three.js. A machine-readable version is available at /editor-manual.md, and a site index for LLMs at /llms.txt.