Skip to content

Tutorial: AttachingAgent Workflow

Automate grab-and-drop without player input - build a robot arm, a conveyor belt sorter, or an NPC that carries objects between locations. A single component handles the entire pick-up, hold, and put-down cycle.

By the end of this tutorial you will have an agent that grabs objects from a source, holds them at a point, and places them at a destination - either on command or in a continuous loop.

Prerequisites: Octoputs installed (Installation), a scene with at least one movable object, two slots, and their respective storages configured. If you have not set those up yet, complete Your First Drag and Drop first.

1. Create the Agent GameObject

Create an empty GameObject in your scene and name it Agent.

GameObject > Create Empty, then rename to Agent.

Add the AttachingAgent component:

Add Component > Octoputs > Transfer > Attaching Agent

The Inspector shows six collapsible sections: Grab Trigger, Grab Object, Holding, Drop Trigger, Drop Destination, and Automation. We will configure each one.

2. Set When to Grab

The Grab Trigger section controls when the agent attempts to grab an object.

  • Grab Event - The signal that tells the agent "start grabbing now." For a player-driven setup, choose an input event (mouse click, key press). For automation, use a timer event or a custom script.

  • Grab Conditions - Optional extra checks. All must pass before the grab proceeds. For example, a cooldown timer or a distance check.

  • Grab Preparation Process - An optional step that runs before the actual grab (e.g., a reach animation). The grab waits for this to finish.

Start simple

Leave Grab Conditions and Grab Preparation Process empty for your first setup. Add them later once the basic workflow is running.

3. Set What to Grab

The Grab Object section controls which objects the agent can pick up.

  • Grab Source - Point this to an AttachableObjectStorage - a list of available objects. This storage is typically populated by a detector (trigger zone, raycast, or manual list).

  • Grab Filters - Optional filters to narrow the selection. For example, add an AttachableTagFilter to only grab objects with a specific tag.

  • Grab Selection Mode - How to choose when multiple objects are available:

    Mode Behavior
    First Grabs the first eligible object in the list
    Last Grabs the most recently added eligible object
    Random Grabs a random eligible object

  • Instant Detach Source Attachable - When enabled, the object is instantly removed from its current slot (skipping detach animations). When disabled, the agent waits for the full detach sequence.

Where does the object list come from?

The AttachableObjectStorage is typically populated by an AttachableDetector - a trigger zone, raycast, or reference list that finds objects and pushes them into the storage. See Usage: Detection for details.

4. Set Where to Hold

The Holding section has one field:

  • Holding Point - An AttachmentPoint where grabbed objects are held during transport.

Create a child GameObject under your Agent, name it HoldPoint, and add an AttachmentPoint component to it. Position it where you want objects to appear while the agent holds them (e.g., at the end of a robot arm, above a character's head, or on a tray).

Drag the HoldPoint into the Holding Point field on the AttachingAgent.

Required field

The Holding Point is mandatory. The agent cannot function without it. The Inspector shows a validation warning if this field is empty.

The AttachmentPoint on the holding point controls how the object transitions when grabbed. The default processes work well for most setups. Customize the attaching/detaching processes on this point to control grab and release animations.

5. Set When to Drop

The Drop Trigger section controls when the agent releases the held object.

  • Drop Event - The signal for dropping. If left empty, the grab event toggles between grab and drop - one click grabs, the next click drops.

    To use separate triggers (e.g., left-click to grab, right-click to drop), assign a different event here.

  • Drop Conditions - Optional conditions that must pass before the drop proceeds.

  • Drop Preparation Process - An optional step before release (e.g., a place animation).

Toggle mode

For the simplest setup, leave Drop Event empty. The grab event will toggle: first trigger grabs, second trigger drops. This works well for click-to-grab, click-to-place interactions.

6. Set Where to Drop

The Drop Destination section controls where the object goes when dropped.

  • Detach If No Destination - When enabled, the agent releases the object even if no valid slot exists (the object is simply let go). When disabled, the agent keeps holding the object.

  • Drop Destination - An optional AttachmentPointStorage - a list of slots the agent can place objects into. The agent picks an eligible slot from this list.

    If left empty, the agent always lets go in place (useful for "throw" or "release" behaviors).

  • Drop Filters - Optional filters for destination slots.

  • Drop Point Selection Mode - Same options as grab: First, Last, or Random.

  • Instant Detach Destination Points - When enabled, if the selected slot already holds an object, that object is instantly removed to make room.

Drop without a destination

If Drop Destination is empty and Detach If No Destination is true, the agent simply lets go of the object wherever it is. This is useful for tossing items or releasing them to fall with gravity.

7. Test the Workflow

Press Play and trigger the grab event. You should see:

  1. The agent picks an object from the source list.
  2. The grab preparation runs (if configured).
  3. The object detaches from its current slot (if any).
  4. The object appears at the HoldPoint position.
  5. The agent enters the Holding state.

Now trigger the drop event (or the grab event again in toggle mode):

  1. The drop preparation runs (if configured).
  2. The object detaches from the holding point.
  3. The object moves to an eligible destination slot, or is released in place.
  4. The agent returns to Idle.

Debugging

The AttachingAgent tracks rejection reasons and attempt counts. Check LastRejection and LastRejectionDetail in the Inspector debug view if the grab or drop does not trigger as expected.

8. Understanding the Agent's Lifecycle

Under the hood, the agent moves through six states in a fixed cycle:

stateDiagram-v2
    [*] --> Idle
    Idle --> PreparingGrab : Grab triggered
    PreparingGrab --> Grabbing : Preparation complete
    Grabbing --> Holding : Object attached to holding point
    Holding --> PreparingDrop : Drop triggered
    PreparingDrop --> Dropping : Preparation complete
    Dropping --> Idle : Object placed or released
    Holding --> Idle : Drop triggered (grab cancelled mid-detach)
State What happens
Idle Waiting for a grab trigger.
PreparingGrab Running the grab preparation (e.g., reach animation).
Grabbing Moving the object from its source to the holding point.
Holding Object is held. Waiting for a drop trigger.
PreparingDrop Running the drop preparation (e.g., place animation).
Dropping Moving the object from the holding point to a destination (or releasing).

The agent exposes boolean properties for each state (IsIdle, IsHolding, etc.) that you can query from scripts or conditions.

Events fire at key transitions:

Event When it fires
OnGrabStarted Grab trigger accepted, entering PreparingGrab
OnGrabComplete Object successfully attached to holding point
OnDropStarted Drop trigger accepted, entering PreparingDrop
OnDropComplete Object placed or released, returning to Idle

9. Running on Autopilot

The Automation section lets the agent work without continuous input:

  • Auto Repeat - The agent automatically starts a new grab as soon as a drop completes, creating a continuous pick-and-place loop. The cycle stops when the source runs out of eligible objects or all destination slots are full.

  • Buffer Requests - Grab or drop events that arrive during the wrong state are remembered and processed when the agent is ready. Without buffering, events that arrive at the wrong time are silently lost.

Conveyor belt sorter

Enable Auto Repeat on an agent with a trigger-based source storage. The agent continuously grabs objects as they arrive on the conveyor and places them at destination slots. No player input needed.

Responsive player controls

Enable Buffer Requests for player-driven agents. If the player clicks "drop" while the agent is still in the grab animation, the drop executes as soon as the hold state is reached instead of being lost.

10. Practical Example: Robot Arm

Here is a concrete setup for a robot arm that picks items from a conveyor belt and places them on shelves.

Scene hierarchy:

RobotArm (AttachingAgent)
  +-- GripperPoint (AttachmentPoint)  <- holding point
ConveyorZone (AttachableDetector + AttachableObjectStorage)
  +-- TriggerCollider (BoxCollider, Is Trigger)
ShelfPoints (AttachmentPointStorage)
  +-- ShelfSlot1 (AttachmentPoint)
  +-- ShelfSlot2 (AttachmentPoint)
  +-- ShelfSlot3 (AttachmentPoint)
Items
  +-- Box1 (AttachableObject)
  +-- Box2 (AttachableObject)
  +-- Box3 (AttachableObject)

AttachingAgent configuration on RobotArm:

Section Setting Value
Grab Trigger Grab Event Timer event (e.g., every 3 seconds)
Grab Object Grab Source ConveyorZone's AttachableObjectStorage
Grab Object Selection Mode First
Holding Holding Point GripperPoint
Drop Trigger Drop Event (empty - toggles with grab)
Drop Destination Drop Destination ShelfPoints's AttachmentPointStorage
Drop Destination Drop Point Selection Mode First
Drop Destination Detach If No Destination false
Automation Auto Repeat true

With this setup, the robot arm:

  1. Grabs the first box detected on the conveyor.
  2. Holds it at the GripperPoint.
  3. Immediately drops it at the first available shelf slot.
  4. Repeats until no boxes remain or all shelves are full.

Adding animations

Assign a process to Grab Preparation Process that animates the arm reaching toward the conveyor, and a process to Drop Preparation Process that animates the arm extending toward the shelf. The agent waits for each process to complete before proceeding.

Next Steps