Effectors

For scalars, Natsura uses Mappings: a general mechanism for turning attributes into parameter controls, so users can build their own sliders instead of relying on fixed UIs.

Effectors exist to provide the same general mechanism for vectors:
a way to carry directional and spatial information per point, without needing new parameters or node types every time someone wants a new type of control.

What Effectors Do

Effectors provide reusable vector channels that other nodes can read.

They can be used to:

• Shape growth directions and bending.
• Represent world-space influences such as gravity, light direction, wind, curve attraction, magnets, or noise fields.
• Build higher-level controls by combining multiple effectors and mappings.
• Encapsulate commonly needed shaping behaviours into reusable nodes without special-casing them inside the core simulation.

They carry information; behaviour comes from how that information is read and mapped into parameters.

What Effectors Are

At the technical level, an effector is:

• A vector attribute on points (for example: v@eff_dir, v@eff_curve, v@eff_wind).
• Written somewhere in the graph (Simulate, an effector node, a Natsura Wrangle, etc.).
• Read later by nodes that are configured to use that attribute.

There is no special effector data type.
Effectors are ordinary attributes that the system treats as directional / influence channels by convention.

How Effectors Are Used

In a typical setup:

1. An effector is computed and written per point
   (by the simulation, an effector node, or a custom wrangle).
2. A node such as Grow is configured to read a specific effector via a weight parameter.
3. The parameter can be replaced by a Mapping chain to how much influence each effector has per point.

Effectors provide raw vectors; mappings and node logic define how that data shapes growth.

Sources of Effectors

Effectors can come from several places:

• Simulation output
  Some vectors are produced naturally by the simulation and exposed as attributes, for example:
  • Gravity-related directions.
  • Light-oriented directions.
  • Contact / “thigmotropism”-style directions.
  • Other internal guidance vectors.
  
  These attributes can be treated as effectors and reused throughout the graph.
• Library effector nodes
  To avoid repeating the same vector math, Natsura provides a growing library of effector nodes that:
  • Take inputs such as curves, lights, wind settings, noise fields, or nearby geometry.
  • Compute a vector per point.
  • Write it to a known attribute name.
  
  Examples (existing / planned) include gravitropism, phototropism, thigmotropism, curve attraction, attractors/magnets, noise fields, and wind fields.
  Internally, they all follow the same pattern: compute a vector → write a vector attribute.
• Custom effectors via Natsura Wrangle
  Any vectors defined in code can be turned into an effector:

  // Natsura Wrangle example
  vector up    = {0,1,0};
  vector noise = snoise(@P * ch("freq"));
  v@eff_custom = normalize(up + noise * ch("amp"));
  

  
  This creates a custom effector eff_custom.
  From the system’s point of view, it is equivalent to any built-in effector.

Per-Point Values and Inheritance

Effectors are stored per point:

• Each point can have its own effector vector.
• When a new point is created during growth, if no new value is written for a given effector, it inherits its parent’s effector value.

This inheritance is simple but important.

Example:

• A curve-based effector is computed for the trunk only.
• Branch points are created from trunk points, but the effector is not recomputed for them.
• Those branch points inherit whatever effector value the trunk had when they were created.

Result: branches follow the trunk’s direction instead of having their own curve-relative vectors.
To give branches their own behaviour, the effector must be computed explicitly on those branch points as well.

Flow in the Graph

Natsura evaluates graphs in a deferred way: you build an engine that runs later, instead of a strictly top-to-bottom SOP chain.

Effectors follow the normal attribute flow:

• Nodes lower in the graph define or modify effector attributes on points.
• Nodes higher in the graph read the attribute values that exist on those points at evaluation time.
• If a lower node overwrites an effector attribute, nodes above it see the updated value.

Effectors do not use a separate data path; they are part of the standard attribute system.

Ancestor Access

Sometimes it is useful to read an effector not only from the current point but from its ancestors in the growth hierarchy.

Natsura provides tools to:

• Read the effector on the current point.
• Read the effector from the parent, grandparent, and further up the chain.

This enables:

• Multi-scale direction (trunk → branch → twig).
• Local variation that still respects a larger, inherited direction.
• More stable shapes or motion by referencing higher-level effectors.

This is still based on attributes; ancestor access simply chooses which point’s attribute to read.

Troubleshooting Checklist

When an effector appears to have no effect, it is usually an attribute or mapping issue. Check:

1. Does the effector attribute exist on these points?
2. Is it computed for all relevant generations (trunk, branches, twigs)?
3. Are new points given fresh values, or only inheriting from parents?
4. Is any node actually reading this attribute at the stage where it should matter?
5. Is the mapping from vector to parameter producing sensible ranges and values?

If all of the above are correct, the effector is behaving as designed; further adjustments belong in how it is read or mapped.