Placing plumes

The one rule

A plume leaves its nozzle's origin along the nozzle's local +Z. That is aft of a model that flies along -Z with +Y up, the convention the other packages share. Every way of placing one just decides where that origin is and which way +Z points.

In JSX

<Afterburner> takes every <group> prop. position is the exit plane's centre. Turn it with rotation, or point it with direction:

// On a model built facing +X: exit 7 m behind its origin, exhaust towards −X
<Afterburner position={[-7, 0, 0]} direction={[-1, 0, 0]} />

// The same, as a rotation: a quarter turn about Y takes +Z to −X
<Afterburner position={[-7, 0, 0]} rotation={[0, -Math.PI / 2, 0]} />

direction is any vector in the parent's frame, normalised for you. When both are given, it wins over rotation.

The group's scale scales the plume, look and all. Usually you want params={{ nozzleRadiusM }} instead: it rescales every length of the jet, the way a bigger engine would.

On a node you don't own

For a node of a loaded model, or anything else outside your JSX, pass it as target. The plume is portalled into it, and position, rotation and direction are then in its frame:

const { nodes } = useGLTF("/fighter.glb");

<Afterburner
  target={nodes.FX_Exhaust_L}
  position={[0, 0, 0.08]}
  direction={[0, 0, -1]}
/>;

target takes any Object3D: a mesh, a group, a bone. If it comes from a ref, keep it in state so the plume re-renders once it exists. See the tutorial.

on-a-model.tsx

Starting…

import { useAnimations, useGLTF } from "@react-three/drei";
import { useFrame } from "@react-three/fiber";
import { Afterburner } from "@aeronautic/afterburner/react";
import { type FC, useEffect, useRef } from "react";
import { type Group, LoopOnce } from "three";
import { base_path } from "@/lib/shared";
import { Stage } from "./stage";

// A glTF exported from Blender. Each nozzle has an empty node on its exit,
// FX_Exhaust_L and FX_Exhaust_R, riding its vectoring gimbal with its -Z
// pointing aft: those are what the plumes sit on, from outside the model's tree
const MODEL = `${base_path}/fighter.glb`;

/**
 * A twin-engined fighter flying a lazy figure of eight, burners lit.
 * @returns The model and its two plumes
 */
const Fighter: FC = () => {
  const { scene, nodes, animations } = useGLTF(MODEL);
  const body = useRef<Group>(null);
  const { actions } = useAnimations(animations, body);

  useEffect(() => {
    // The afterburner cones and the pylons are meant hidden, flagged so in
    // their extras, which three hands over as userData
    scene.traverse((node) => {
      if (node.userData.visible_default === false) node.visible = false;
    });

    // It's modelled on its wheels: fold them away once it's on screen
    const retract = actions.ANIM_Gear_Retract;

    if (!retract) return;

    retract.setLoop(LoopOnce, 1);
    retract.clampWhenFinished = true;
    retract.play();
  }, [scene, actions]);

  useFrame(({ clock }) => {
    const t = clock.elapsedTime * 0.5;

    if (!body.current) return;

    body.current.rotation.set(
      Math.sin(t * 0.5) * 0.2,
      Math.sin(t) * 0.25,
      Math.sin(t) * 0.5,
    );
    body.current.position.y = Math.sin(t * 1.3) * 0.6;
  });

  return (
    <group ref={body}>
      <primitive object={scene} />
      {[nodes.FX_Exhaust_L, nodes.FX_Exhaust_R].map((exhaust, index) => (
        <Afterburner
          key={index}
          target={exhaust}
          preset="afterburner"
          // At the petals' trailing edge, in the anchor's frame
          position={[0, 0, 0.08]}
          // The exhaust streams down the anchor's -Z: aft
          direction={[0, 0, -1]}
          // The exit as modelled, inside the petals: an oval 0.76 m wide and 0.45 m high, sized
          // as the round exit of its area
          params={{ nozzleRadiusM: 0.29, nozzleAspect: 1.67 }}
        />
      ))}
    </group>
  );
};

/**
 * Two plumes on two nodes of a loaded, moving model, placed with `target`.
 * @returns The example
 */
export const OnAModel: FC = () => (
  <Stage camera={[17, 6, 24]} target={[0, 0, 9]} floor={-5} reflections>
    <Fighter />
  </Stage>
);

export default OnAModel;

Moving it from code

Through the handle, without a render:

// Move and aim it, in the frame it sits in
engine.current?.setOffset({
  position: [0, 0.2, -4.2],
  direction: [0, -0.1, -1],
});

// Just aim it
engine.current?.setDirection([0, -0.1, -1]);

// Or write the group directly: it is a plain three.js Group
engine.current?.object?.position.set(0, 0.2, -4.2);

setOffset takes an AfterburnerOffset:

field	type
`position`	`[x, y, z]` or any `{ x, y, z }`
`rotation`	an `Euler`, a `Quaternion`, `[x, y, z]` or `[x, y, z, w]`
`direction`	`[x, y, z]` or any `{ x, y, z }`; wins over `rotation`

Fields you leave out are kept.

Without React

A core nozzle follows an object's world matrix, at an optional offset in its frame. attach switches which object it follows:

const tail = batch.add({
  object: engine_node,
  offset: { position: [0, 0, -4.2], direction: [0, 0, -1] },
});

tail.setOffset({ position: [0, 0.1, -4.2] });
tail.attach(other_engine); // follow something else
tail.attach(null); // stop following, and hold where it is now

Detaching folds the last world pose into the nozzle's matrix, so the plume doesn't jump. More in Without React.

The one ruleCopy Anchor Link

In JSXCopy Anchor Link

On a node you don't ownCopy Anchor Link

Moving it from codeCopy Anchor Link

Without ReactCopy Anchor Link

On this page

The one rule

In JSX

On a node you don't own

Moving it from code

Without React