Usage Guide

This is a reference-style walkthrough of all major Octoputs systems. For hands-on step-by-step instructions, see the tutorials.

Creating an Attachable Object

Any GameObject that should be pickable, draggable, or movable between slots needs an AttachableObject component. This marks the object as something Octoputs can manage.

Menu path: Octoputs / Core / Attachable Object

The component is organized into sections:

Filtering

Controls which slots this object can be placed into.

• Tags - Assign one or more AttachmentTag ScriptableObjects to categorize this object (e.g., "Red", "Heavy", "Fragile"). Tags are checked by filters on slots to accept or reject objects.
• Point Filter - An optional list of AttachmentPointFilter implementations. When set, this object only accepts slots that pass all filters. Useful for restricting where an object can be placed.

Drag Configuration

• Transform To Attach - Optional override for which transform is moved during attachment. Defaults to the object's own transform if left empty.

Phase Tabs

Each phase of the object's lifecycle (arriving at a slot, staying there, or leaving) has its own tab with conditions, a process, and events:

Phase	Fields
Attaching	Conditions (all must pass to begin), Process (runs during transition), OnAttachStarted event
Attached	Process (runs while attached), OnAttached event, OnTargetReached event
Detaching	Conditions (all must pass to begin), Process (runs during transition), OnDetachStarted event, OnDetached event

Conditions use [SerializeReference] with the Jungle condition system - select any Condition implementation from the dropdown. Processes use IProcess, which can be a single command, a command list, a transform pipeline, or any other process type.

Default processes

A freshly added AttachableObject has CommandList as the default attaching and detaching process. This is an empty command list you can populate, or swap for a different process type entirely.

Creating an Attachment Point

A slot that can hold objects is represented by an AttachmentPoint component. Add it to any GameObject that should accept attachable objects - a shelf position, a socket, a hand, etc.

Menu path: Octoputs / Core / Attachment Point

Filtering

Controls which objects this slot accepts.

• Tags - Tags that describe this slot. Used by AttachmentTagFilter on objects or transfer processes to match compatible pairs.
• Attachable Filters - List of AttachableFilter implementations. Only objects passing all filters can attach here.

Phase Tabs

Phase	Fields
Attaching	Conditions, Cancellation Strategy (Pause or Revert), Process, OnAttachStarted event
Attached	Process, OnAttached event
Detaching	Conditions, Allow Instant Steal toggle, Cancellation Strategy, Process, OnDetachStarted/OnDetached events

Default attaching process

New AttachmentPoints default to an EntryCommandProcess containing AttachedObjectCommands (reparent, physics, layer setup) followed by a HeldAttachableTransformPipeline. This gives you working attach behavior out of the box.

Cancellation Strategies

What happens if an attach or detach is interrupted mid-transition:

• Pause - The object freezes in place.
• Revert - The object transitions back to the previous phase (attach reverts to idle, detach reverts to attached).

Allow Instant Steal

When enabled on the Detaching tab, another slot can immediately grab the held object without waiting for the full detach sequence to complete.

Detection

Detectors answer the question "which objects or slots are available right now?" They scan the scene (using triggers, raycasts, or manual lists) and push results into storage containers that other systems can read from.

AttachableDetector

Finds movable objects and pushes them into an AttachableObjectStorage.

Add the component, then configure its Detection Strategy:

Strategy	How it works
Trigger	Uses a trigger collider on the same GameObject. Objects entering/exiting the trigger are detected/lost.
Raycast	Casts rays each frame to find objects under the cursor or at a given origin.
Reference List	Manually assigned list of objects. Useful for pre-wired setups.
Held Attachable	Detects the object currently held by a specific AttachmentPoint.

Each strategy has its own configuration fields that appear when selected.

Resolution settings control how the detector finds the AttachableObject component on detected GameObjects (search self, parent, children) and whether to deduce from an AttachmentPoint if the hit object is a point rather than an attachable.

AttachmentPointDetector

Same pattern as AttachableDetector, but finds slots (AttachmentPoint components) and pushes them into AttachmentPointStorage.

Pair detectors with storages

A detector without a storage does nothing persistent. Always assign a storage reference so detected objects are available to transfer processes.

For a hands-on setup walkthrough, see Tutorial: Your First Drag and Drop.

Transfer

Transfer is the system that actually moves objects between slots. It reads from a source (detected objects) and writes to a destination (available slots).

AttachableTransferProcess

Reads objects from a source AttachableObjectStorage and attaches them to slots from a destination AttachmentPointStorage.

Key settings:

Setting	Options	Description
Transfer Amount	OneAtOnce, AllAtOnce, CustomAmount	How many objects to move per trigger
Selection Mode	First, Last, Random	Which object to pick when transferring one at a time
Transfer Conditions	List of Condition	All must pass for the transfer to proceed
Attachable Filters	List of AttachableFilter	Filters applied to source objects
Attachment Point Filters	List of AttachmentPointFilter	Filters applied to destination slots
Detach If No Destination	Toggle	If true, detaches the object even when no valid destination exists

AttachableTransferProcess implements IProcess, so it can be used anywhere the Jungle process system expects a process - inside a ProcessLauncher, as part of a command list, or wired to an event.

AttachingAgent

A complete grab-hold-drop workflow as a single component. Instead of wiring detectors, storages, and transfer processes separately, you configure one component that handles the entire pick-up, carry, and put-down cycle.

Sections:

1. Grab Trigger - When to grab: an IEvent that starts the grab, plus conditions and an optional preparation process (e.g., reach animation).
2. Grab Object - What to grab: source storage, filters, and selection mode. Option to use instant detach from source.
3. Holding - Where to hold: reference to the AttachmentPoint where the agent holds grabbed objects during transport.
4. Drop Trigger - When to drop: an IEvent that starts the drop (defaults to toggling with grab if unset), conditions, and preparation process.
5. Drop Destination - Where to place: optional destination storage, filters, and selection mode. DetachIfNoDestination controls whether the agent releases the object when no valid slot exists.
6. Automation - Continuous operation: AutoRepeat restarts the cycle automatically. BufferRequests queues grab/drop events that arrive during the wrong state.

Agent states: Idle, PreparingGrab, Grabbing, Holding, PreparingDrop, Dropping.

Events: OnGrabStarted, OnGrabComplete, OnDropStarted, OnDropComplete.

For a step-by-step setup, see Tutorial: AttachingAgent Workflow.

Transform Pipelines

Transform pipelines control how objects move when they attach to a slot. Instead of just teleporting, an object can bounce, slide, follow a curve, or use physics forces - all configured without code.

Each pipeline is an IProcess with three internal stages: Target (where to go), Modifiers (adjustments along the way), and Applier (how to write the final position).

Pipeline Types

Pipeline	What it does	Best for
DirectTransformPipeline	Sets position/rotation directly each frame	UI, strategy games, editors
PhysicsTransformPipeline	Applies forces via Rigidbody	Physics puzzles, VR, immersive sims
JointTransformPipeline	Uses ConfigurableJoint constraints	Cranes, ropes, tethered objects
Direct2DPipeline	Direct position for 2D rigidbodies	2D games without physics
Rigidbody2DPipeline	Physics forces for 2D rigidbodies	2D physics games
HeldAttachableTransformPipeline	Auto-resolves the held object from an AttachmentPoint	Default on AttachmentPoint

Targets

The target computes the destination - where the object should end up:

• TransformTarget - Follow a static transform reference
• RayHitTransformTarget - Follow a raycast hit point on a surface
• BlendedTransformTarget - Interpolate between two targets based on a weight
• LerpedTransformTarget - Lerp from current position to a destination over time
• CurveTransformTarget - Follow an animation curve path
• SequenceTransformTarget - Step through a sequence of targets
• CompositeTransformTarget - Combine position from one target and rotation from another
• ConditionalTransformTransformTarget - Switch targets based on a condition

Modifiers

Modifiers form a chain that adjusts the target before the applier writes it. They execute top to bottom, and order matters - a constraint placed after a spring will lock the axis after the bounce, while placing it before would let the spring override the lock.

See the API Reference for the full list of 33+ modifiers organized by category.

For a hands-on modifier tutorial, see Tutorial: Transform Pipelines.

Tag-Based Filtering

Tags let you control which objects fit which slots. A "Red" cube only fits a "Red" socket; a "Heavy" crate is rejected by a "Light Only" shelf. Tags are AttachmentTag ScriptableObjects created via Create > Jungle > Octoputs > Attachment Tag.

Assign them to both AttachableObject and AttachmentPoint components, then add filters that enforce the matching rules.

Filter Types

For filtering objects (placed on slots or transfer processes):

Filter	What it checks
AttachableTagFilter	Whether the object's tags match required tags (with configurable matching mode)
AttachableHeldStateFilter	Whether the object is currently attached somewhere
AttachableEligibilityFilter	Whether the object's own conditions allow attachment
AttachableStatFilter	Whether the object's stat values pass a numeric comparison
AttachedToEvaluatedObject	Whether the object is attached to the slot being evaluated

For filtering slots (placed on objects or transfer processes):

Filter	What it checks
AttachmentPointTagFilter	Whether the slot's tags match required tags
AttachmentPointIsHoldingFilter	Whether the slot currently holds an object
AttachmentPointCanAttachFilter	Whether the slot's conditions allow attachment
AttachmentPointPhaseFilter	What lifecycle phase the slot is in
AttachmentPointStatFilter	Whether the slot's stat values pass a numeric comparison
AttachmentPointHoldingObjectWithTagFilter	Whether the held object has a specific tag

Tag Requirement Modes

The AttachmentTagFilter supports four matching modes:

Mode	Behavior
All	Every required tag must be present on the target
Any	At least one required tag must be present
One	Exactly one required tag must match
AnyExcept	The target must have none of the specified tags (inverted match)

For a hands-on tutorial, see Tutorial: Tag-Based Filtering.

Measurement

The ObjectMeasurer component tracks how an object is moving - its speed, acceleration, distance traveled, and more. Add it to any object you want to monitor, then configure which measurements to track.

Available measurements:

Measurement	What it tracks
PositionMeasurement	Current world position
VelocityMeasurement	Velocity vector (position delta / time)
SpeedMeasurement	Scalar speed (magnitude of velocity)
AccelerationMeasurement	Acceleration vector
AngularVelocityMeasurement	Rotation rate
DistanceTraveledMeasurement	Cumulative distance moved
BoundsMeasurement	Object bounds in world space

Measurement values are accessed via MeasurementKey ScriptableObjects, which act as named keys into the measurer's data. The AttachedObjectMeasurer variant automatically measures the object held by a specific AttachmentPoint.

Stats System

Track numeric values on objects and slots - weight, durability, fill count, or any custom metric. The stats system lets you create rules like "only accept objects with weight < 10" or "this slot is full when holdCount >= 3."

• DraggableStatStorage / AttachmentPointStatStorage - Store named numeric values on objects or slots
• DraggableStatMetric / AttachmentPointStatMetric - Define what to measure (ScriptableObject)
• DraggableStatEvaluator / AttachmentPointStatEvaluator - Evaluate stat values against thresholds
• StatComparison - Comparison operators (Equal, NotEqual, Greater, Less, etc.)

Stats integrate with the filtering system via AttachableStatFilter and AttachmentPointStatFilter.