FreighterHead

The locomotive of a snake-style freighter convoy — the escort target your mission keeps alive. The cars behind it trace the exact arc it drew a few seconds ago.

What it does

FreighterHeadComponent is pure data. Each tick the FreighterChainSystem (which ships with the FreighterChain component) records the head's pose into a ring buffer — sized to capacity — so trailing FreighterCar entities can sample the buffer at increasing time offsets and follow the head's historic path exactly, snake-style. FreighterHelmSystem steers the head: toward the current waypoint gate when a track is set (advancing currentWaypointIndex as it enters each gate's sphere), or a gentle sinusoidal drift when there's no mission, phased off the head's clock.

The head has no System of its own — the classes and both systems live in FreighterChain, which this component pulls in as a dependency. Killing the head is mission failure: the shared destroyShip path emits wingman.freighter.killed, which MissionDirector treats as an instant loss.

Use it in a scene

A head plus two trailing cars, steering down +Z:

{
  "FreighterHead": {
    "tags": ["freighter-head"],
    "components": {
      "Transform6DOF": { "x": 0, "y": 0, "z": 100 },
      "Velocity6DOF": {},
      "FreighterHead": { "carSpacingSeconds": 0.7 },
      "Renderable": { "shape": "freighter-head", "sx": 6, "sy": 5, "sz": 16 },
      "ShipLoadout": { "loadout": "freighter-head" }
    }
  },
  "FreighterCar0": {
    "tags": ["freighter-car"],
    "components": {
      "Transform6DOF": { "x": 0, "y": 0, "z": 65 },
      "FreighterCar": { "index": 0, "headEntityId": "FreighterHead" },
      "Renderable": { "shape": "freighter-car", "sx": 5, "sy": 4, "sz": 10 },
      "ShipLoadout": { "loadout": "freighter-car" }
    }
  }
}

Each car names its head with headEntityId; the chain system resolves it each tick to sample the pose history.

Props

• carSpacingSeconds (number, default 0.7) — per-car age offset in seconds. Car i samples the head's pose at clock − (i+1)·carSpacingSeconds, so a bigger value stretches the convoy out.
• capacity (number, default 480) — ring-buffer length in samples the chain system allocates for this head's pose history. Must cover the furthest car's age offset at the tick rate.
• clock (number, default 0) — wall-clock seconds the head has been alive. Advanced by the chain system; also the phase source for the helm's drift weave. Runtime state, not a tuning knob.
• currentWaypointIndex (number, default 0) — the waypoint the helm is steering toward. Advanced by FreighterHelmSystem; -1 falls back to sinusoidal drift.

Dependencies

• FreighterChain — defines FreighterHeadComponent + FreighterCarComponent and the two systems (FreighterChainSystem, FreighterHelmSystem) that record the pose history and steer the head. The head is inert data without it.

Notes

• The head and cars are one system, two scene keys. FreighterHead and FreighterCar are split only so a scene can place the locomotive and each car as separate entities; both classes and all the motion live in FreighterChain, downloaded as a dependency of either.
• The chain isn't compacted on death. A destroyed car leaves its index gap — surviving cars keep their original offsets, so damage shows as visible holes in the convoy rather than the tail sliding forward.
• Head death ends the run. destroyShip distinguishes the freighter-head tag and emits wingman.freighter.killed (instant mission loss) rather than the incidental wingman.freighter.car.lost a car emits.