# Carrying: ferrying objects on a moving target

`bCarryObjects` lets a Group attach whatever is resting on or inside its moving
target for the duration of the motion: a platform lift carries the player up
with it, a drawer carries its contents as it slides open. The mechanism is
simple: one scan, one instant, fixed for the whole run.

## Decided once, at group start

`bCarryObjects` scans for what to ferry **when the group starts playing**, and
that set is then fixed for the whole motion:

```{mermaid}
graph LR
    Start[Group.StartPlayback] --> Scan[Scan bounds + CarryHeight ONCE]
    Scan --> Attach[Attach whatever overlapped]
    Attach --> Play[Play timeline: set is now fixed]
    Play --> End[Group ends]
    End --> Detach[Detach all carried objects]
```

Drop something into a drawer that is **already opening** and it will **not** be
picked up, it only rides if it was there the instant the drawer began to move.
Need a late passenger? Retrigger the group; `StartPlayback` re-runs the scan
from scratch.

## Why once, not continuous

The reasons:

- **Predictable**: what a group carries is decided at one instant you can
  reason about and reproduce, not on whichever frame something drifted
  inside the volume mid-animation.
- **Cheap**: a continuous re-scan needs an overlap query per moving object,
  per frame. A single scan at trigger time doesn't, and most games never need
  the continuous version anyway.

The scan volume itself is the target's bounds extended upward by
`CarryHeight` (cm): tall enough to pick up a standing player or a stack of
loose props, not so tall it catches the ceiling above.

## Requirements for a carried object

| Requirement | Why |
|---|---|
| Mesh must be **Movable** | A Static mesh's transform can't be driven at runtime: carrying one is skipped and the log says so, instead of doing nothing. |
| Replicated actor + replicated movement (multiplayer) | Without both, the object attaches correctly on the server but **remote clients never see it move**: the two must agree on where the carried object ends up. |

See {doc}`../guides/multiplayer` for the full replication story. The short
version: `bCarryObjects` doesn't replicate the *attach decision*
separately from the actor's own movement replication, so the carried actor has
to be able to replicate itself.

## Use cases

| Scenario | What's carried |
|---|---|
| Lift carries the player | Whoever is standing on the platform when it starts rising, including a pawn. |
| Drawer carries its contents | Any loose Movable prop resting inside the drawer's bounds when it starts sliding open. |
| Elevator floor carries a crate | A pushed-in crate rides up with the elevator, as long as it was inside the scan volume at trigger time. |
| Turntable carries a display prop | The prop turns with the platform instead of sliding off as it spins. |

## Worked example

```text
Group "Rise":
  bCarryObjects: true
  CarryHeight: 20.0
```

A player standing on the lift's platform mesh when `Rise` starts is caught by
the bounds-plus-20cm scan, attached for the whole ascent, and detached the
instant the group ends, so they land on the platform at its new height instead
of staying attached to a component that has finished moving.

## See also

- {doc}`groups-and-cycles`: where `bCarryObjects`/`CarryHeight` sit among the
  rest of a Group's settings (easing, ramps, gates).
- {doc}`../guides/multiplayer`: replication requirements for a carried actor
  in more depth.
- {doc}`gates`: gating a `Rise` group so the lift only carries when it's
  actually allowed to move.
- {cpp:class}`FMovaIxActionGroupMore` (`bCarryObjects`, `CarryHeight`) in the
  API reference.