orientation

 

 

The Orientation operator rotates a particle so that its local Up axis (local Z) points along a specified direction, and optionally its local Forward axis (local X) points along a second specified direction. The resulting frame is written to the particle's orientation matrix each frame.

 

Typical uses include:

  • Making particle shapes stand upright on a surface (UpType = surface normal).
  • Aligning the long axis of a particle shape to its direction of travel (Up UpType = Velocity).
  • Aiming particle shapes at a target point or object (Forward UpType = Position).
  • Billboard-like setups where both axes are pinned to specific directions.

 

 

Axis convention

Local axis convention used by the Orientation node.

 

The Orientation node builds a right-handed frame in which:

  • Up ??? local Z
  • Forward ??? local X
  • Local Y = Z ?? X (computed automatically)

 

If the shape attached to the particle was modelled with a different convention (for example Y-up), use the Shape Rotation parameter to reorient it instead of modifying the shape's geometry.

 

 

How it works

The node operates in one of two modes, chosen implicitly by the value of Forward Type:

 

Single-axis mode (Forward Type = Projected up or Particle)

Only the Up axis is pinned; rotation around Up is left free. The two modes differ in how the frame is computed:

  • Projected Up: The frame is rebuilt from scratch each step, with Forward derived from the horizontal projection of Up vector. The shape never rolls or banks, but any upstream spin is overwritten.
  • Particle: The frame is updated incrementally ??? the particle is rotated by the minimum rotation that takes its current local Z toward the target Up, scaled by the Blend percentage. Spin around local Z survives, but the shape may bank when Up changes direction.

 

Fully-pinned mode (Forward Type = Velocity / Position / Custom)

Both Up and Forward are pinned. The node builds a complete target frame using Gram-Schmidt orthogonalization (Forward is projected onto the plane perpendicular to Up), then smoothly blends the particle's current orientation toward it using slerp. This produces a fully deterministic frame.

 

Note:

Zero-length targets. If a target direction or position resolves to zero length (for example, a stationary particle with Up = Velocity), the node skips this frame for that particle rather than producing an undefined frame.

- 180?? flips. When the particle's current Up is pointing exactly opposite to the target Up, the rotation axis is ambiguous. The node picks a deterministic perpendicular axis so the flip happens smoothly over several frames (at low Blend) rather than through a random jitter.

- Interaction with spin operators. In single-axis mode (Forward = Particle), only the Up axis is corrected each frame. Rotation around Up is free, so a spin around the Up axis is preserved. To drive a continuous roll around Up, either use a spin operator with axis parallel to Up, or animate the Z component of Shape Rotation. In fully-pinned mode, both axes are constrained each frame and any spin is gradually damped by the blend ??? avoid combining fully-pinned alignment with spin operators.

- Both types set to velocity: If Up Type is Velocity and Forward Type is Velocity, both vectors resolve to the same direction and the frame cannot be built. The node silently falls back to single-axis mode (as if Forward Type were Auto) so the particle is never left with a degenerate orientation.

 

 

[Inputs]

 

#Particle Stream - This pin requires a particle stream to be connected.

 

Enabled - Enable or disable node evaluation.

 

Up Type - Selects where the Up vector comes from.

  • Custom: Uses the vector supplied in the Up Vector pin (world space).
  • World X / Y / Z: Uses one of the world-space axis directions, (1,0,0) / (0,1,0) / (0,0,1).
  • Velocity: Uses the particle's own velocity vector.

 

Up Vector - The world-space vector the particle's Up axis will align to. Only active when Up Type is Custom. The vector does not need to be unit length ??? the node normalizes it internally. A zero-length vector is treated as "no target" and the particle is left unchanged for that frame..

 

Forward Type - Selects where the Forward vector comes from, and implicitly selects between single-axis and fully-pinned mode.

  • Projected Up: Single-axis mode. Only Up is pinned; rotation around Up is left free. Forward is derived from the horizontal projection of Up so the shape never rolls or banks, but the frame is rebuilt each step ??? any upstream spin is overwritten.
  • Particle: Single-axis mode. Only Up is pinned; rotation around Up is left free. The frame is updated incrementally from the particle's current matrix, so spin around local Z survives ??? at the cost of possible banking when Up changes direction.
  • Velocity: Forward is the particle's velocity vector. Ideal for "nose along travel direction" setups.
  • Position: Forward points from the particle's position toward a world-space target point (supplied via the Forward Position pin). The direction is recomputed each frame as the particle or target moves, so the particle continually aims at the target.
  • Custom: Uses the direction supplied in the Forward Vector pin (world space).

 

Forward Vector/Position - Align vector/position in world space you want to align particle to.

 

Shape Rotation - An additional rotation (as Euler angles in degrees, X ??? Y ??? Z order) applied after the alignment step, in the particle's local frame. Use this to:

  • Compensate for shape meshes that weren't modelled with the Z-up / X-forward convention.
  • Add a fixed bank, pitch, or yaw offset to every particle.
  • Drive a continuous roll by animating the Z component over time.

 

Because it is applied in local space, the same rotation value produces the same visual offset regardless of which direction the particle currently faces.

 

Blend % - Controls how fast the particle's orientation catches up to the target frame each simulation step.