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: JungleBehaviour → 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, typed checks, 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).
noDestinationPolicy	`NoDestinationPolicy`	What happens when no point is eligible: Detach In Place drops the object where it is, Let Go drops it where it is even over a point that refuses it (for hands), Keep Holding puts it back on the holding point, Return To Origin sends it back to the point it was picked up from (falls back to Detach In Place when picked up loose or refused there).
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.

Triggering an Agent from code

AttachingAgent is event-driven — there is no public Grab() or Drop() method. To trigger an agent from a script, raise the same IEvent the agent listens to in its Grab Event or Drop Event field. See Scripting API Examples for the pattern.