# Groups & Cycles

## Group settings

Each Group's `More` block tunes how its Actions play together:

| Property | Purpose |
|---|---|
| `Gates` | Gate the whole group, it only runs when every entry passes. Same address grammar as everywhere else ({doc}`tag-grammar`), a trailing `:!State` negates that entry. |
| `RepeatPolicy` | Bitmask: `BlockWhenDone` refuses a re-run once at rest at its own end pose, `BlockWhilePlaying` refuses one while mid-play. Both set by default. |
| `ConfirmTime` | Hold-to-confirm duration before the group commits (bind the hold-progress to a UI ring via `OnInteractHoldProgress`). |
| `EasingFunction` / `EasingExponent` | Motion easing across the timeline. |
| `LoopStartTime` | Where `@Loop` sends the group back to. |
| `RampInTime` / `RampOutTime` | Ease a looping motion up to speed and back down: a fan spinning up, an escalator winding down. |
| `StopSpeedFactor` | Multiplier on total duration when stopping mid-play for a smooth landing (non-looping groups only). |
| `bCanBeInterrupted` | Whether a new trigger can cut this group short. |
| `bCarryObjects` / `CarryHeight` | Ferry objects resting on or inside the animated target. See {doc}`carrying`. |
| `OffsetMode` / `OffsetTarget` | Whether poses are relative to the component's start (`ComponentStart`), its most recent play start (`StartPose`), a target, or the raw parent space. |
| `DeltaSpace` | Axis frame the Location/Rotation deltas travel in: `Relative` (parent space), `Local` (this Component's own rotation), or `World` (fixed axes, cancels the Actor's yaw). |

## Carry is decided once, at the start

`bCarryObjects` scans for what to ferry **when the group starts playing**, and that
set is then fixed for the whole motion. Drop something into a drawer that is already
opening and it will **not** be picked up, it rides only if it was there when the
drawer began to move.

This is a tradeoff:

- **Predictable**: what a group carries is decided at one instant you can reason
  about, not on whichever frame something was inside.
- **Cheap**: a continuous re-scan needs an overlap query per moving object per
  frame. A single scan at trigger time does not.

Requirements for a carried object:

- The scan volume is the target's bounds extended upward by `CarryHeight`.
- A carried object's mesh must be **Movable**: a Static mesh is skipped (and says
  so in the log).
- For multiplayer, the carried object must be a **replicated** actor with
  replicated movement, or remote clients will not see it move (see
  {doc}`../guides/multiplayer`).

## Cycles

A **Cycle** is an ordered list of Group names. Each trigger moves it one step:
closed → opening → open → closing → closed, and so on. `StartIndex` seeds where it
begins for actors placed pre-opened, pre-broken, etc.

### Cycle auto-detect

Place a door **half-open** in the level. On `BeginPlay`, the IC reads the actor's
current pose and syncs the cycle index so the *next* press moves **away** from
where you left it, no manual index bookkeeping for hand-placed variety. This also
means a designer can place 10 identical doors at 10 different open states and
each one plays correctly on first press.

### Choosing Cycle vs Group triggering

- Trigger a **Cycle** by name when you want stateful, alternating behavior (press
  = toggle open/closed).
- Trigger a **Group** directly when you want a specific action regardless of
  current state (a "Reset" button that always plays the `Close` group, never
  `Open`).
- Trigger an **Action** directly (rare) for the finest-grained control, bypassing
  Group-level settings like gates and easing.

## See also

- {doc}`model`: how State/KeyFrame/Action/Group/Cycle relate.
- {doc}`gates`: `Gates` and `OnActionRejected` in depth.
- {doc}`carrying`: the carry mechanism in more detail, with multiplayer notes.