Driving from code

There are two refs. Each value lives on one of them:

what changes	where it lives	how to change it per frame
throttle	the nozzle	`handle.throttle = …`
where it sits, which way it points	the nozzle	`handle.setOffset`, `setDirection`
the engine (radius, Mach, soot…)	the nozzle's params	`handle.updateParams` (not every frame)
altitude, airspeed, the day, exposure	the batch's profile	`batch.updateProfile`
step counts	the batch's quality	`batch.setQuality`

The nozzle handle

import {
  Afterburner,
  type AfterburnerHandle,
} from "@aeronautic/afterburner/react";

const engine = useRef<AfterburnerHandle>(null);

<Afterburner ref={engine} preset="afterburner" />;

member	what it does
`throttle`	Read or write, 0 to 1 dry, to 1.1 with reheat. Cheap enough to write every frame.
`updateParams(partial)`	Merges into the current params. Rewrites this one instance.
`setParams(params)`	Replaces the params over the preset.
`setOffset(offset)`	Moves or turns the nozzle in the frame it sits in.
`setDirection([x,y,z])`	Points the exhaust.
`params`	The resolved params, or `null` before the nozzle is in a batch.
`object`	The nozzle's `Group`.
`nozzle`	The core `AfterburnerNozzle`, for anything else.
`batch`	The `AfterburnerBatchHandle` it draws with.

The handle is stable for the component's life. It's safe to use before the nozzle has joined a batch.

The plume doesn't jump to a throttle you write: it eases toward it over the batch's responseS, a quarter of a second by default, as a real engine spools and a burner lights. handle.nozzle.drawnThrottle is where it has got to. Set responseS={0} on <AfterburnerBatch> to follow at once.

throttle-ref.tsx

Starting…

import { useFrame } from "@react-three/fiber";
import {
  Afterburner,
  type AfterburnerHandle,
} from "@aeronautic/afterburner/react";
import { type FC, type RefObject, useRef } from "react";
import { Nozzle, Stage } from "./stage";

/**
 * Spool up and down, writing the throttle through a ref.
 * @returns Nothing
 */
const Spool: FC<{ engine: RefObject<AfterburnerHandle | null> }> = ({
  engine,
}) => {
  useFrame(({ clock }) => {
    if (!engine.current) return;

    // From most of military power through the burner's light-off to full
    // reheat and back, every few seconds: in reheat about two fifths of it
    engine.current.throttle = 0.95 + 0.15 * Math.sin(clock.elapsedTime * 0.9);

    // A wobble of the nozzle's aim, as a vectoring nozzle would
    const pitch = 0.08 * Math.sin(clock.elapsedTime * 0.6);
    engine.current.setDirection([0, pitch, 1]);
  });

  return null;
};

/**
 * Throttle and aim changed every frame without a React render.
 * @returns The example
 */
export const ThrottleRef: FC = () => {
  const engine = useRef<AfterburnerHandle>(null);

  return (
    <Stage>
      <Spool engine={engine} />
      <Nozzle />
      <Afterburner ref={engine} preset="afterburner" />
    </Stage>
  );
};

export default ThrottleRef;

The batch ref

<AfterburnerBatch ref> is the AfterburnerBatchHandle itself:

import {
  AfterburnerBatch,
  type AfterburnerBatchHandle,
} from "@aeronautic/afterburner/react";

const batch = useRef<AfterburnerBatchHandle>(null);

useFrame(() => {
  batch.current?.updateProfile({ altitudeM: aircraft.position.y });
});

<AfterburnerBatch ref={batch} preset="afterburner">
  <Afterburner />
  <Afterburner position={[0, 0, 1.2]} />
</AfterburnerBatch>;

updateProfile merges the fields you give and only writes uniforms. Calling it every frame is fine. batch.stats() returns { nozzles, near, mid, far, culled }, handy for an overlay.

Without an <AfterburnerBatch> you can still reach the shared batch through any nozzle's handle.batch. Inside one, useAfterburnerBatch() returns the nearest.

Props versus refs

A prop is applied when it changes, and wins when it does. If something writes updateParams({ sootPerM }) and the params prop later changes, the prop's value replaces it. The same goes for profile and updateProfile. Let one owner set each field: props for settings, refs for what a simulation drives.

The nozzle handleCopy Anchor Link

The batch refCopy Anchor Link

Props versus refsCopy Anchor Link

On this page

The nozzle handle

The batch ref

Props versus refs