Mapping

The Mapping tab drives a modifier’s parameters from live particle data, so a setting changes per particle and over the course of the simulation instead of holding one fixed value.

Every full NeXus modifier carries a Mapping tab in Properties ▸ Physics, alongside Object Properties, Groups Affected and Falloff. The forces (nxGravity, nxWind, nxTurbulence and the rest) all have it, as do the simulation modifiers, the nxMesher generator and nxUpres. The lighter object-type modifiers do not: nxEmitter, nxCollider, nxGroup, nxGenerator, nxTrail, nxCache and nxFalloff have no Mapping tab.

Each entry in the tab is a layer. A layer routes one particle-data source into one or more modifier parameters: it reads the chosen particle property and uses it to modulate the chosen settings. The Mapping curve then shapes exactly how the source value maps onto the parameter value.

If a modifier has no mappable parameters the tab reads No mappable parameters and there is nothing to add.

The Mapping tab on nxGravity, with one Age layer added

The Mapping tab on nxGravity. One layer has been added, keyed to the particle Age. The top half is the Mapping Layers list. The box below holds the selected layer’s settings.

Mapping Layers

The top of the tab is the Mapping Layers list. Add, select, reorder and remove your layers here.

Add a layer

Click the + button to open the Add Mapping Layer menu, then pick the particle-data source the new layer is keyed by. The layer is created reading that source. You can change the source later from the layer’s settings.

There are twenty basic particle-data sources, available on every Mapping tab:

Age, Color (Brightness), Color R, Color G, Color B, Distance, Document Time, Fluid Density, Fuel, Granular, Group, ID, Life, Mass, Radius, Scale, Smoke, Speed, Temperature and Vertex Weight.

The beta adds five more: Solver Blend, Solver Damage, Solver Material, Solver Speed and Solver Stretch. They read the per-particle state that a solver such as nxMPM writes. Beta

Some modifiers add their own sources to the bottom of this menu, grouped under their own headings, so the exact list depends on which modifier you are mapping.

The list

You can have as many layers as you wish. Each row shows a summary of the layer: its source, an arrow, the parameters it drives, then its weight, range and clamp mode. The check box at the start of each row is the layer’s Enabled toggle. Turn a layer off to suspend it without deleting it.

Select a layer to open its full settings in the box below.

Reorder and remove

The buttons beside the list remove the selected layer (-) and move it up or down. Order the layers to control how stacked mappings on the same parameter combine.

Display Channel Beta

Below the list. Sets which of the emitter’s Display Channels the Color sources read. Set as None, by default, which reads the particles’ own color. The other entries are the Display Channels set up on the emitter’s Display tab, listed by name. The choice applies to every emitter in the scene. With no Display Channels set up, the menu reads No Display Channels and is grayed out.

Layer settings

Selecting a layer opens its settings. The heading restates the routing as source → parameter so you can see at a glance what the layer does.

Source

The particle data this layer reads. It defaults to the source you picked when adding the layer. Open the menu to change it to any of the available particle-data types.

For example, set the source to Age to drive a parameter from how old each particle is or to Speed to drive it from how fast the particle is moving.

Layer

On the layer-stack modifiers (nxTurbulence, nxScale, nxSpeed, nxSpin, nxDirection, nxLimit and nxColor) an extra Layer menu appears. These modifiers hold their own stack of layers, so this menu picks which of those layers the mapping targets. Modifiers without a stack do not show this control.

nxMPM shows the Layer menu too, with a Domain entry for the solver’s own settings followed by one entry per material layer. Beta

Destinations Beta

The modifier parameters this layer modulates. One layer can drive several parameters at once, all from the same source, range, weight and curve.

Click the + button beside the Destinations list to add a parameter and the - button to remove the selected one. The available parameters depend on which modifier you are mapping. On some modifiers they are grouped under headings. On a layered modifier, the menu offers only the parameters the targeted layer actually uses. A destination that no longer applies, for example after you change that layer’s type, is shown in red with a warning icon.

Until you add a destination the layer does nothing.

Range Min, Range Max

These set the span of source values the mapping reacts to. The Mapping curve is applied across this range: a source value at Range Min sits at the left of the curve and a source value at Range Max sits at the right.

For a source such as Age, a Range Min of 40 and a Range Max of 50 means the curve affects each particle only while it is between 40 and 50 frames old.

For the time-based sources (Age, Life and Document Time) the range is entered in the NeXus time system, with a per-field frames or seconds toggle (the f or s button beside each field). It defaults to a Range Min of 0 and a Range Max of 2. For every other source the range is a plain value pair, defaulting to 0 to 1.

Weight

The blend strength of this layer, as a percentage. Defaults to 100%, applying the mapping in full. Lower it to blend the mapped value back toward the parameter’s own fixed value, so at 50% the parameter lands halfway between its base setting and the fully mapped result.

Clamp

Controls what happens when a particle’s source value falls outside the Range Min to Range Max span. Set as Clamp, by default. The alternatives are Cycle and Continue.

Clamp: hold the mapping at the start or end value once the source passes the edge of the range.
Cycle: wrap the source back through the range and repeat it in a continuous loop.
Continue: pass source values outside the range through unmodified, instead of clamping them to the edge.

Mapping

The curve that defines how the source value maps onto the parameter. It is the heart of the tab.

The horizontal X axis is the chosen source, with 0.0 at Range Min and 1.0 at Range Max. The vertical Y axis is a multiplier on the parameter, so at 1.0 the parameter takes its full value and at 0.0 it takes none of it.

With the default straight line the parameter rises evenly across the range. Edit the curve to shape that response. A downward line makes the parameter fall off across the range. A curve that rises then falls makes it grow and then shrink.

Because the curve is a static graph, you can read off how a parameter behaves at any point in the range without playing the scene. Halfway along an Age range, a curve value of 0.5 means the particle gets half the parameter’s value at that age.

Once the source, parameter and range are set, editing this one curve is enough to build very different behaviors from the same layer.

Worked example: a surface-tension field

Mapping is easiest to understand from a real setup. This example drives an nxFluids liquid’s Surface Tension per particle from a spatial field, so the tension is zero at the center of an influence sphere and rises smoothly to full at its edge. Download the scene and open it in Blender 5.1 to follow along.

The scene playing in the viewport: a fluid body whose per-particle surface tension is set by the mapped field.

Download: surface_tension_field.blend

The Surface Tension slider cannot read an object directly, so the value is routed through particle Color:

An empty, ST_Field_Center, marks the middle of the field. Move it to relocate the field.
An nxColor modifier with a single Distance from Object layer, keyed to ST_Field_Center over a distance of 0 to 1.2m, writes a radial 0 to 1 value into each particle’s Color: black at the center, white at the edge.
nxFluids runs a FLIP solve with a base Surface Tension of 60%. On its Mapping tab, one layer reads Color (Brightness) and drives Surface Tension across a range of 0 to 1. The effective per-particle tension becomes 60% of the radial value, so it is 0 at the center and about 60% at the edge.

The modifier order matters. nxColor must run before nxFluids so the mapped tension reads the current frame’s color.

To adapt it, match the emitter radius and the nxColor distance to resize the influence, raise the nxFluids Surface Tension slider to change the maximum and edit the Mapping curve or the color ramp to reshape the falloff.