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, magnets, curve attraction, 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.

The primary use of effectors is to give artists direct modelling control over how a tree grows. Beyond direct control, the framework supports several broader categories of behaviour:

• Tropic responses. Growth toward or away from a direction: gravity (gravitropism), magnetism, or an arbitrary directional bias. Phototropism (response to light) is also a tropic response, but in Natsura it comes from plugging an environment into the Simulate, not from a dedicated light effector. See Intrinsic effectors.
• Self-aware growth. Following attributes from a parent, grandparent, or further-back ancestor. The ancestor effector covers this case, letting a branch respond to the tree's own history, a powerful way to produce self-similar rhythm.
• User control in the viewport. Direct manipulation via handles. The magnet effector is the first of these; curve-influence vectors and other localised viewport controls are planned.
• Awareness of the tree's own shape. Branches reacting to each other to avoid overcrowding. The deflection effector covers this case. (Response to the surrounding environment is separate: it comes from plugging an environment into the Simulate.)

The Effector Catalogue

The current built-in effector types:

Gravity

A uniform up-vector across the entire tree. Drives the gravitropic response, including how much the plant grows toward up. Easy to reason about because the vector is constant everywhere on the tree: the same effector produces the same influence regardless of where it is sampled on the trunk. The full gravitropic response in nature can be more complex than growing straight up, and the response-mode and strength parameters cover that range. One of the most important effectors for shaping both the grow and the assembly decoration.

Ancestor

Follow a direction vector stored on the parent, grandparent, great-grandparent, or further-back ancestor. The attribute followed can be any direction vector on the ancestor, not just the ancestor's own direction of growth: for instance, a noise vector stored on the parent can be followed by the child instead of the child's own noise vector. A branch can copy the parent's own shape, and also copy the influences that shaped the parent, producing self-similar rhythm through the tree. This is one of the most expressive effectors.

Magnet

A user-placed sphere of influence in the viewport, and the first of Natsura's localised user controls. A magnet pulls or pushes branches within the sphere's radius, letting you place spheres of influence in the scene to steer growth in specific directions. Multiple magnets can be placed, each with its own radius and strength. Branches outside the radius are unaffected.

Direction

A constant directional vector, an arbitrary directional bias. Where the gravity effector is locked to world up and drives the gravitropic response specifically, the direction effector takes any vector, useful for a custom bias such as a prevailing/dominant wind direction. It is not a light effector: Natsura has no light effector today; light response (phototropism) comes from the environment input, not this node (see Intrinsic effectors).

Deflection

Awareness of the tree's own shape. The deflection effector reacts to the tree's own geometry so a branch becomes aware of its neighbours and avoids overcrowding. It does not read the surrounding terrain or environment; that response comes from plugging an environment into the Simulate. Object-based effectors that react to scene geometry are planned.

Noise

A vector that varies by position on the tree, so the influence the effector applies differs at every point on the skeleton. The noise can also be made to vary over time, so the same position can carry a different noise vector frame to frame. This enables both static spatial variation and dynamic temporal variation across the tree's growth.

Custom

Write an arbitrary effector in VEX. The custom effector exposes the core effector mechanism directly, intended for artists familiar with Houdini and VEX who need a response that the built-in effectors don't cover. See Custom Effectors via Wrangle below.

Intrinsic effectors

Not every effector is one you add. Intrinsic effectors are vectors that already exist in the simulation, either produced from an environment you plug into the Simulate, or made intrinsic by the system. When you plug in an environment, Natsura bakes it into an optimised format carrying occlusion and lighting information and exposes a phototropism vector the plant can grow with respect to. This is how light-aware growth works today, in place of a dedicated light effector. Other intrinsics include thigmotropism (contact response), and increasingly gravity.

You read an intrinsic effector exactly like any effector you author. Light, occlusion, and dominant-light effectors that you place yourself are planned; until then, the environment input is the route to light-aware growth.

Any effector, intrinsic or authored, can be driven by Mapping: you can scale phototropic response by proximity to a surface, or vary an influence by height up the tree. Mapping is the primary mechanism for attribute-driven growth.

Response Modes

For each effector assigned to a node, the response mode is chosen:

• Attract. Grow in the direction of the effector vector.
• Repel. Grow in the opposite direction.
• Flatten. Grow at a plane perpendicular to the effector.
• Align (up). Twist the local up vector of the growth frame to point toward the effector.
• Level (up). Twist the local up vector to be flat to the effector.
• Orbit. Orbit around the effector vector to produce spiral growth patterns.

The up-vector controls (align, level) influence the spiral of growth, and therefore the phyllotactic arrangement of children spawning on this growth. Modifying the up vector is the path to controlling spiral and phyllotaxy from an effector.

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 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 and a chosen response mode.
3. The parameter can be replaced by a Mapping chain to control how much influence each effector has per point.

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

Effectors are added to nodes that accept directional input. The primary node is the grow, and the framework is being rolled out to other nodes where directional control is useful. Multiple effectors can be added to a single node.

On the grow node (or any node that accepts effectors), use the add effector button. The dropdown lists effectors that Natsura has discovered in the project; any effector containing a core effector inside is auto-discovered, including custom effectors once they are saved. Once assigned, the response mode is chosen from the list above.

A custom icon can be set per effector to make effector instances easier to identify in the UI.

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 (phototropism) directions, produced when an environment is plugged in.
  • 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.
  
  The current set is the catalogue above (gravity, noise, magnet, direction, deflection, ancestor, plus the custom base). Internally, they all follow the same pattern: compute a vector, write a vector attribute.
• Custom effectors via Wrangle. Any vectors defined in code can be turned into an effector:

  // 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.

Custom Effectors via Wrangle

The custom effector is the core effector mechanism exposed for direct VEX scripting. Every built-in effector contains a core effector inside, so the custom effector is what to reach for when a needed response isn't already covered by a built-in. Typical use cases include arbitrary mathematical fields, project-specific tropisms, and prototyping new effector behaviours before they get rolled into a proper built-in.

To write a custom effector, three conventions apply:

1. Group lookup on input 2. All effector streams are merged downstream into a single pass, so each effector must scope its lookups to its own points. Without scoping, the effector would act on points belonging to other effectors. The convention is to read the point group named geo from the second input, and to scope any geometry lookups (primuv, xyzdist, and so on) against that group. The standard snippet for this lives inside every built-in effector; open one and copy the pattern.
2. Second input is the geometry / parameter input. Input 2 (blue) accepts geometry or points. Beyond geometry, it can also be used to pass parameters through into the Natsura Cook framework. This is conceptually akin to mapping, and serves as a workaround until mapping is added directly to effectors.
3. Output vector name matches the node name. The output vector attribute written by the effector must have the same name as the effector node itself.

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.

Cookbook

For practical effector recipes (common force combinations and the response modes and mapped strengths that produce them), see the Effectors Cookbook.

Notes

• The effector framework is being rolled out beyond the grow to other nodes where directional control is useful.
• More effector types are planned. The space of possible effectors is large; most additions will target giving artists more direct controls in the viewport.
• A wind effector is planned. Simulating wind over the timescale of a tree's growth is conceptually unusual, since Natsura's simulation is of growth itself rather than of a moment in time; a wind effector would likely mimic prevailing wind direction changes or obstructions over the tree's life, useful for cases like a tree adapting to a forest that evolves around it.
• The current output-vector naming convention (effector output attribute name matches the node name) is planned to be replaced with a constant attribute name so that renames become automatic.
• Mapping is planned to be added directly to effectors. This will make the current "input 2 as parameter passthrough" workaround unnecessary.