Skip to content

Tutorial: Your First Drag and Drop

Build a working interaction from scratch — a cube that snaps to a slot when you click on it. No scripting required; everything is configured in the Inspector.

By the end you'll press Play, click on the cube, and watch it attach to a chosen slot automatically.

Prerequisites: Octoputs installed (Installation), a new empty scene.

How Octoputs Thinks About a Scene

Before wiring anything, hold this picture:

  • An AttachableObject is a thing that can be picked up.
  • An AttachmentPoint is a slot that can hold one.
  • An AttachingAgent is the actor that moves attachables between points — the player's hand, a robot arm, a cursor.

In this tutorial the agent is the player's mouse click. The whole workflow lives on a single GameObject — the agent finds an attachable through a Detector and snaps it onto a destination point.

1. Scene Setup

Create the following GameObjects:

  1. Cube (GameObject → 3D Object → Cube) — the item that will move. Position it somewhere visible.
  2. DestinationPoint (empty GameObject) — the slot the cube will move to. Move it a few units away from the Cube.
  3. CursorAgent (empty GameObject) — the agent that drives the interaction.

Add a Main Camera if your scene doesn't have one (default new scenes already do).

2. Mark the Cube as Movable

Select the Cube and add the AttachableObject component.

Add Component → Octoputs → Core → Attachable Object

The Inspector shows three tabs — Attaching, Attached, Detaching — plus a Filtering section. The defaults are fine; this object will accept any compatible point.

3. Create the Slot

Select DestinationPoint and add the AttachmentPoint component.

Add Component → Octoputs → Core → Attachment Point

The defaults handle reparenting, physics, and snap-to-position automatically. Out of the box, anything that attaches here is teleported to the point's transform using a direct transform operation.

4. Add a Detector to Pick Targets Under the Mouse

The Cursor Agent needs to know which AttachableObject the player wants to grab. We'll use a Detector that raycasts under the mouse cursor.

Select CursorAgent and add a Detector component.

Add Component → Jungle → Reactions → Detector

Configure it:

  1. Detection Strategy — pick Raycast Detection Strategy (or Camera Mouse Raycast if available). Configure the strategy's ray to come from the main camera through the mouse pointer.
  2. Filters — click + and add Is Attachable. This filter passes only GameObjects that carry an AttachableObject (and rewrites the candidate to that AttachableObject's GameObject when it finds one on a parent).

That's the picker. Whatever's under the mouse pointer that's an Attachable shows up in the detector's Available list.

Why a Detector and not a custom click handler?

Detectors are the unified way to source GameObjects in Octoputs — trigger zones, raycasts, manual lists, all behave the same way. The same Detector pattern feeds AttachingAgents, Reactors, and any other consumer.

5. Add the AttachingAgent

Still on CursorAgent, add the AttachingAgent component.

Add Component → Octoputs → Transfer → Attaching Agent

Now wire it.

Grab Trigger

  • Grab Event — pick Mouse Button Event. Set the button to Left and the trigger to On Press.

Grab

  • Grab Source — this is a SmartAttachableObject. Set the mode to Dynamic (the default), then in the Source Object picker choose From Detector and drag the Detector you added on this same GameObject into it. Leave selection mode as First.
  • Leave Instant Detach Source Attachable off.

Holding

This agent doesn't carry the cube — it just sends it straight from the hover to the destination. We still need a holding point because the agent uses it internally during transitions. Create a child of CursorAgent named HoldPoint, add an AttachmentPoint to it, and drag it into the agent's Holding Point field.

Drop Trigger

Leave Drop Event empty — that means the grab event toggles between grab and drop. One click grabs from the source, the next click drops to the destination.

Drop Destination

  • Drop Destination — set this SmartAttachmentPoint to Local mode and drag the DestinationPoint GameObject's AttachmentPoint component into the Direct Value field.

Leave the other fields at their defaults.

6. Test in Play Mode

Press Play. Hover the mouse over the Cube and click. The Cube snaps to the Cursor's HoldPoint. Click again anywhere — it snaps to DestinationPoint.

sequenceDiagram
    participant Player
    participant Agent as AttachingAgent
    participant Det as Detector
    participant Cube as AttachableObject
    participant Hold as HoldPoint
    participant Dest as DestinationPoint

    Player->>Agent: Click (grab event)
    Agent->>Det: ResolveAll() → list of detected attachables
    Det-->>Agent: [Cube]
    Agent->>Cube: Attach to HoldPoint
    Cube-->>Hold: Held
    Player->>Agent: Click again (toggles to drop)
    Agent->>Dest: Attach Cube
    Cube-->>Dest: Attached

What Just Happened?

Three independent pieces collaborated:

  1. Detector answered "which Attachable is under the cursor?"
  2. AttachingAgent ran the grab → hold → drop state machine.
  3. AttachmentPoint ran the attaching process on each transition — the default process reparents, kills physics on the rigidbody if any, and runs a DirectTransformOperation that snaps the cube to the point.

Each piece is independent. Swap the Raycast strategy for a Trigger Volume and the agent now grabs anything that walks into a zone. Swap the DestinationPoint reference for a GameObjectFromDetector on a second Detector and the agent picks the closest slot dynamically. Add modifiers to the AttachmentPoint's attaching process and the cube bounces in instead of snapping.

Next Steps