NWN Aurora Emitter → rollnw Particle System Map

This document is a companion to particle_system.md. It maps every Aurora Emitter field to its rollnw equivalent, states the expected visual outcome for common configurations, and documents known gaps.

How to use this document: Given an MDL emitter node, look up each field in the tables below to find the rollnw authoring IR field it maps to, then consult the visual outcomes sections to predict what should appear on screen.

Status legend: ✅ Implemented · ⚠️ Partial (parsed but not fully applied) · ❌ Not in renderer (simulation only or no-op) · 🚫 Deferred

Field Mapping

Emitter Style

Note: Non-targeted additive Linked emitters with broad rectangular spawn regions are lowered to billboard_world_z when their authored data matches the soft-volume policy described below.

Emitter Parameters

Emitter Particles

Texture / Chunk

Emitter Advanced

Expected Visual Outcomes

Update × Render Matrix

What you should see on screen for each combination:

Blend Mode

Practical heuristic: If the texture has a black background and uses lightness to define shape (fire, sparks, magic), use lighten. If the texture has an explicit alpha channel (smoke puff, debris), use normal. For leaves or hard-edged decals, use punch-through.

P2P Reference Node Direction Convention

P2P reference node offsets are inverted relative to intuition. The engine pulls particles toward the reference position but defines "toward" backward:

• A reference at offset (0 0 0.63) above the emitter pulls particles downward (toward –Z in world space).
• A reference at offset (0 0 -0.63) pulls particles upward.

When debugging P2P effects, always verify the observed direction of particle flow against the sign of the reference node's offset. This is a NWN engine convention, not a rollnw quirk.

Common Pattern Cookbook

For each of MerricksDad's canonical emitter patterns, the key fields and expected screen result:

Basic Puff (e.g., vim_magblue — magic missile impact)

update    Explosion
render    Normal
blend     Lighten
texture   fxpa_flare    (single frame: xgrid 1, ygrid 1)
xsize 0   ysize 0       (point emitter)
colorStart 1 1 1 → colorEnd 0.36 0.76 1.0
alphaStart 1 → alphaEnd 0
sizeStart 0.5 → sizeEnd 0.07
birthrate 70   lifeExp 1

Expected: On detonate event — camera-facing colored flash that shrinks and fades over 1 second. Additive blending means the center appears brightest; edges fall off. Nothing visible between detonate events.

Animated Puff / Flame (e.g., vim_exp2flame)

update    Fountain
render    Normal
blend     Lighten
texture   fxpa_firebb   (xgrid 4, ygrid 4, frameStart 0, frameEnd 15, fps 16)
xsize 60  ysize 50
inherit 1
birthrate 30   lifeExp 1
mass (negative or zero)

Expected: Continuous animated quads rising from a 60×50 cm base; each quad cycles through the 4×4 sprite sheet over its lifetime. inherit 1 makes the flames follow the emitter when it moves. Particles always face camera.

Chunks (e.g., vim_destruct — gore/debris)

update    Fountain
render    Normal
blend     Normal
texture   NULL
chunkName Red_M_Giblet
spread    6.28          (360°, all directions)
velocity  5   randvel 1
particleRot 1.5
birthrate (driven by animation keys, bursts near 100 then drops to 0)
lifeExp   4

Expected: 3D mesh instances launched in every direction from a point. Each chunk has a random-ish trajectory and tumbles (particleRot). Normal blend because they are opaque lit geometry.

Trail of Smoke (e.g., it_torch_000)

update    Fountain
render    Normal
blend     Normal
texture   fxpa_smoke01  (xgrid 4, ygrid 4, random 1, fps 30)
mass      -0.2          (rises)
velocity  0   randVel 0.2
sizeStart 0 → sizeEnd 2
alphaStart X → alphaEnd 0

Expected: Expanding, fading puffs that rise from the emitter. random 1 means each puff shows a different noise frame. mass < 0 gives upward buoyancy; randVel adds subtle variance. Puffs diffuse visually as they scale up and fade out. twosidedtex is parsed but not yet GPU-applied — if the puff rotates edge-on it may vanish (currently not a practical issue since these are camera-facing).

Local-Z Ripple / Swirl (e.g., wmgst_t_051 spin02)

update      Fountain
render      billboard_to_local_z
blend       Lighten
texture     fxpa_ripple      (xgrid 2, ygrid 2)
inherit     1
xsize 4     ysize 4          (small local XY spawn region)
birthrate   10
lifeExp     2
velocity    0   randvel 0.04
particleRot 5
blurlength  10
mass        0

Runtime mapping: The emitter's local XY axes define the quad plane and local Z is the plane normal. Attached/local particles keep the authored local rect spawn and velocity motion; particleRot rotates each sprite in that local plane. For wmgst_t_051 spin02, the visible spiral comes from absolute atlas frame 1 of fxpa_ripple on large 0.6m quads, not from rewriting particle centers into a synthetic spiral. blurlength is parsed but does not resize billboard_to_local_z effects.

Expected: A circular additive ripple disk that stays anchored to the item/socket orientation. The ripple texture spins in the authored local plane; particles should not grow into a wide cloud or orbit as independent center points.

Detonation Burst

update    Explosion
event     <time> detonate    (in the animation sequence)

Expected: All Explosion-mode emitters in the model fire simultaneously when the detonate animation event fires. Using multiple detonate entries in one sequence triggers multiple bursts. Set birthrate = 0 on specific emitters to suppress them on a given detonate pass.

Lightning (P2P Beam)

update    Lightning
lightningDelay    (re-randomize interval)
lightningRadius   (lateral jitter amplitude)
subdivision       (number of segments)
lightningScale    (per-segment max offset)
node reference <name>    (child of the emitter node)

Expected: Animated jittered polyline from the emitter to the reference child node. Shape re-randomizes at each lightningDelay interval. More subdivisions = more jagged. Larger lightningRadius = more chaotic spread. End-fade applied via sine function.

P2P Gravity Vortex (e.g., vff_comvortex — Implosion)

update    Fountain
render    Normal
blend     Normal
p2p 1     p2p_sel 0     (gravity type)
xsize 1000  ysize 1000  (wide spawn plane)
chunkName Fx_Rockchunksml
grav      2             (pull acceleration)
drag      1             (slingshot past then return)
threshold 1.5           (destroy within 1.5m of reference)
spread    0.175         (≈10°, mostly perpendicular to plane)
node reference <name>   (target singularity)

Expected: Chunks spawn across the wide plane, drift toward the reference node with increasing speed, overshoot slightly (drag), curve back, and are destroyed when they enter the threshold radius. The reference node's position is inverted — if offset is (0 0 0.63), particles converge downward.

Linked Chain / Lightning Curtain (e.g., T_Door21 ground_lightning, vps_tentacle)

render    Linked
p2p 1     p2p_sel 1     (Bezier)
combinetime               controls kink traversal speed (see below)
lifeExp                   particle lifetime; kink travels (lifeExp/combinetime) fraction of path
xsize / ysize             spawn region; lateral spread provides initial kink displacement
sizeStart / sizeEnd       ribbon width over particle lifetime

Rendering model: The ribbon is drawn source (emitter position, fixed) → particle (animated kink) → target (reference node, fixed). Both endpoints are anchors. The kink is a per-particle waypoint that starts at the particle's spawn position and traverses toward the target at rate path_t = age / combinetime. Because xsize/ysize give each spawn a lateral offset within the emitter's local XY plane, the kink starts off the emitter→target axis and converges toward the target as the particle ages. This off-axis starting position is the source of the visible V-kink and zigzag character. When the particle dies, a new one spawns at a fresh random position, instantly resetting the kink shape.

xsize and ysize on linked-chain emitters define the spawn region that provides the initial kink displacement — they are not the ribbon width (that is sizeStart). Large values give extreme initial kinks; zero gives a point spawn at the emitter with no off-axis bend. The emitter's local orientation determines which world axis the spread falls on.

combinetime effect on kink convergence: - Small combinetime relative to lifeExp (e.g., combinetime 0.11, lifeExp 0.1): kink reaches 91% of path before death → spends most of its life near the target end, nearly converged. Bolt starts wide/kinked and snaps toward straight quickly. - Large combinetime relative to lifeExp (e.g., combinetime 1.0, lifeExp 0.1): kink only travels 10% of path before death → stays close to its spawn position the whole time. - In both cases the bolt spans full height end-to-end (source → kink → target). combinetime does not affect bolt height, only how far the kink has converged when the particle dies.

Expected: Full-height ribbon spanning from emitter to reference node. The kink shape changes each spawn due to random lateral spawn offset. random 1 on the sprite sheet gives each new particle a different texture frame → flickering lightning character. Additive blend (Lighten) makes it glow. Bolt reshapes every lifeExp seconds.

Linked Broad Rect / Ground Mist (e.g., tnp_gmist)

update    Fountain
render    Linked
blend     Lighten
p2p 0
xsize / ysize             broad rectangular spawn region
lifeExp                   >= 1 second
velocity + randvel        <= 1 m/s

Import model: This legacy NWN pattern uses Linked, but the authored intent is a volume of soft cards, not a ribbon. rollnw lowers it to billboard_world_z when the emitter is non-targeted, non-lightning, additive, broad rectangular, continuous, long-lived, and low-speed. Targeted Linked emitters (p2p 1) still use the linked-chain renderer.

Expected: Low, soft additive ground mist with overlapping horizontal cards. It should not draw connected ribbons between particles.

Wind Burst (e.g., vff_pulswind)

update    Explosion
texture   NULL
blastRadius 15
blastLength 1.2

Expected: Invisible emitter — no particles drawn. On detonate, pushes a force event outward in blastRadius. Affects particles with affectedByWind = 1 and animesh dangly objects. No visual representation in mudl; only observable through secondary effects on other particles.

Ground Aura / Flat Ring

render    billboard_to_world_z    (quads lie flat, face up)
   or
render    aligned_to_world_z      (quads face sideways, ring-like)
spread    180–360                 (wide horizontal emission)
mass      0                       (no gravity drift)
velocity  (low, or 0 for static)

Expected: billboard_to_world_z — quads flat on the ground plane with stable world-space axes; circular disc appearance when spread = 360. aligned_to_world_z — quads perpendicular to ground with world Z locked as the vertical axis; suitable for vertical shaft/ring/halo effects.

Known Gaps Summary