AttachingAgent¶

An agent that grabs objects, holds them, then places or drops them. Use for robot arms, delivery drones, or any grab-hold-drop workflow.

Namespace: Octoputs.Transfer Inherits: MonoBehaviour Implements: ICycleProvider<AgentCycle>, ITargetedCycleProvider<AgentCycle>

Overview¶

AttachingAgent orchestrates a complete grab-hold-drop cycle driven by events. When a grab event fires, the agent resolves an attachable through a SmartAttachableObject, runs an optional preparation process, detaches the object from its source point, and attaches it to a holding point. A separate drop event (or the same grab event as a toggle) reverses the flow, resolving a destination point through a SmartAttachmentPoint, placing the object there — or detaching in place if no destination is eligible.

Agent state machine: Idle → PreparingGrab → Grabbing → Holding → PreparingDrop → Dropping → Idle.

The agent supports conditions, filter chains, auto-repeat, and request buffering. For diagnosis when grabs/drops fail, the agent retains a ring buffer of the most recent rejection records (queryable via LastRejection, TryGetRejection).

Properties¶

Grab Trigger¶

Property	Type	Description
grabEvent	`IEvent`	Event that triggers the grab.
grabConditions	`List<Condition>`	All must pass for the grab to proceed.
grabFilters	`List<IAttachableObjectCheck>`	Checks a grab candidate must pass (added directly — no umbrella wrapper).

Grab¶

Property	Type	Description
grabPreparationProcess	`IProcess`	Process that runs before the object is attached to the holding point — reach/grab animations.
grabSource	`SmartAttachableObject`	Attachable(s) to grab. Defaults to Dynamic mode for a multi-GameObject source (Detector, container). Configure source selection (first/last/random) on the source itself.
instantDetachSourceAttachable	`bool`	If true, uses instant detach when grabbing from the source (skips state processes).

Holding¶

Property	Type	Description
HoldingPoint	`AttachmentPoint`	The point where the agent holds grabbed objects during transport.

Drop Trigger¶

Property	Type	Description
dropEvent	`IEvent`	Event that triggers the drop. If empty, the grab event toggles.
dropConditions	`List<Condition>`	All must pass for the drop to proceed.
dropFilters	`List<IAttachmentPointCheck>`	Checks a drop candidate point must pass (added directly — no umbrella wrapper).

Drop Destination¶

Property	Type	Description
dropPreparationProcess	`IProcess`	Process that runs before the object is released — place/release animations.
dropDestination	`SmartAttachmentPoint`	Destination point(s). Defaults to Dynamic mode for a multi-GameObject source.
dropOnZoneProcess	`IProcess`	Process that runs after the held object is placed onto an eligible destination point.
instantDetachDestinationPoints	`bool`	If true, uses instant attach/detach when dropping (skips processes).
DetachIfNoDestination	`bool`	If true, simply detaches in place when no destination is available. If false, keeps holding.
noDestinationDetachProcess	`IProcess`	Process that runs when no eligible destination is found and the object is detached in place.

Automation¶

Property	Type	Description
autoRepeat	`bool`	Automatically restart the grab-drop cycle after each completion.
bufferRequests	`bool`	Remember grab/drop events arriving during the wrong state and replay them later.

Events¶

Property	Type	Description
OnGrabStarted	`UnityEvent`	Invoked when a grab begins.
OnGrabComplete	`UnityEvent`	Invoked when the held object reaches the holding point.
OnDropStarted	`UnityEvent`	Invoked when a drop begins.
OnDropComplete	`UnityEvent`	Invoked when the held object is released.

Runtime State¶

Member	Description
`IsIdle` / `IsPreparingGrab` / `IsGrabbing` / `IsHolding` / `IsPreparingDrop` / `IsDropping`	Boolean state probes.
`CurrentAttachable`	The object currently held (or being moved).
`LastDropDestination`	The point most recently chosen as a drop destination.
`GrabAttempts` / `GrabSuccesses` / `DropAttempts` / `DropSuccesses`	Lifetime counters.
`LastRejection` / `LastRejectionDetail` / `LastRejectionTime`	Most recent grab/drop failure.
`RejectionCount` / `RejectionCapacity`	Ring buffer of recent failure records.