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 IAttachmentPointCheck checks (e.g. AttachmentPointTagCheck, IsHoldingCheck) added directly — the slot already knows it is filtering points, so no umbrella wrapper is needed. When set, this object only accepts slots that pass every check. Per Jungle convention these fields are allowlists — null = all allowed. Use Object Filter (AttachmentPointGameObjectFilterCheck) if you need to run a generic GameObject filter here.

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 a ProcessList (Parallel mode) as the default attaching and detaching process. This is an empty process container 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. Matched by AttachmentPointTagCheck (on objects, agents, or transfer operations) to pair compatible objects and slots.
• Attachable Filters - List of IAttachableObjectCheck checks (e.g. AttachableTagCheck, HeldStateCheck) added directly — the slot already knows it is filtering attachables, so no umbrella wrapper is needed. Only objects passing every check can attach here. Use Object Filter (AttachableGameObjectFilterCheck) if you need to run a generic GameObject filter 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 a sequence containing an AttachmentPointCommand (reparenting, physics, layer setup) and a transform operation targeting the held object. This gives you working attach behaviour 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 and expose results through IItemSource<GameObject>. Consumers (commands, agents, reactors) resolve typed components on the fly via SmartAttachableObject / SmartAttachmentPoint in Dynamic mode.

Detector (Jungle Core)

Octoputs uses Jungle Core's generic Detector component. Configure it with:

1. A detection strategy — Trigger, Raycast, Proxy, Reference List, etc.
2. A filter chain — for example AttachableObjectFilterGroup with AttachableTagCheck + EligibilityCheck, or AttachmentPointFilterGroup with AttachmentPointTagCheck + CanAttachCheck. The umbrella filters also rewrite the candidate (e.g. a child collider rewrites to the parent AttachableObject).
3. Optional processes that begin/end on detection edges (anyAvailableProcess, noneAvailableProcess, onAddedProcess, onRemovedProcess) and UnityEvents on add/remove.

The same Detector type works for attachable detection and attachment-point detection — the filter chain decides what gets accepted.

For "mirror this detection into a container that another command can read", drop a DetectorToContainerRelay next to the Detector.

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

Transfer

Transfer is the system that actually moves objects between slots. The two targeted commands are:

AttachmentPointCommand

Targets a single AttachmentPoint (resolved from a SmartAttachmentPoint) and runs a list of IAttachmentPointOperation items in parallel:

Operation	What it does
AttachToPointOperation	Attaches a configured attachable to this point.
DetachPointOperation	Detaches whatever this point is currently holding.
TransferAttachableOperation	Moves an attachable from one point to this one.

AttachableObjectCommand

Targets a single AttachableObject (resolved from a SmartAttachableObject) and runs a list of IAttachableObjectOperation items in parallel:

Operation	What it does
DetachAttachableOperation	Detaches this attachable from wherever it is currently held.

Both commands implement IProcess (via the Command base class), so they can be used anywhere the Jungle process system expects a process — inside a ProcessComponent, as a phase process on an AttachmentPoint/AttachableObject, or wired to a Reactor body.

AttachingAgent

A complete grab-hold-drop workflow as a single component. Instead of wiring detectors, containers, 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 Source - What to grab: a SmartAttachableObject (Dynamic mode wired to a Detector is the typical setup) plus filter chain.
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: a SmartAttachmentPoint (Dynamic mode for live detection, or a static reference) plus filter chain. 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.

Events: OnGrabStarted, OnGrabComplete, OnDropStarted, OnDropComplete.

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

Transform Operations

Transform operations 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 transform operation is an IProcess with three internal stages: Target (where to go), Modifiers (adjustments along the way), and Applier (how to write the final position). Compose multiple operations on a single subject using ParallelTransformOperation or SequenceTransformOperation. To group several subjects under one execution frame, use the Transformer component.

Operation Types

Operation	What it does	Best for
DirectTransformOperation	Sets position/rotation directly each frame	UI, strategy games, editors
PhysicsTransformOperation	Applies forces via Rigidbody	Physics puzzles, VR, immersive sims
JointTransformOperation	Uses a ConfigurableJoint	Cranes, ropes, tethered objects
Direct2DTransformOperation	Direct position for 2D rigidbodies	2D games without physics
Rigidbody2DTransformOperation	Physics forces for 2D rigidbodies	2D physics games
ParallelTransformOperation	Run multiple child transform operations on the same subject at once	Layered effects (target + shake)
SequenceTransformOperation	Run multiple child transform operations on the same subject in order	Scripted moves (scale up, then translate, then scale back)
BatchTransformOperation	Submit a subject to the Jobs-based batch pipeline	Many simultaneous draggables

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
• ShapeTraversalTransformTarget - Travel along a shape (Line, Arc, Circle, or a 3D curve via Curve Shape) at a set speed
• 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

Context-known slots (attachableFilters, pointFilter, agent grab/drop filters, transfer point filters) take typed checks directly — the picker shows only the relevant IAttachableObjectCheck / IAttachmentPointCheck (plus the Object Filter escape hatch). Detector filter chains still take IGameObjectFilter and use the AttachableObjectFilterGroup / AttachmentPointFilterGroup umbrellas.

For filtering objects (placed on slots, agents, or commands):

Filter	What it checks
AttachableTagCheck	Whether the object's tags match required tags (with configurable matching mode)
HeldStateCheck	Whether the object is currently attached somewhere
EligibilityCheck	Whether the object's own conditions allow attachment

For filtering slots (placed on objects, agents, or commands):

Filter	What it checks
AttachmentPointTagCheck	Whether the slot's tags match required tags
IsHoldingCheck	Whether the slot currently holds an object
CanAttachCheck	Whether the slot's conditions allow attaching a specific object
PhaseCheck	What lifecycle phase the slot is in
OnAttachedObjectCheck	Delegates to nested attachable checks evaluated on the currently held object
NotJustDetachedCheck	Suppresses the slot briefly after a detach while the detached object stays nearby

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

Measurements track how an object is moving — its speed, acceleration, distance traveled, and more. They plug into the Setter system as sub-setters inside a DataStorageSetter entry. Use the preset menu (GameObject > Jungle > Setting > Setter (Measurement Preset)) to create a pre-configured Setter + DataStorageComponent in one click.

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 stored via Key ScriptableObjects (shared Jungle.Data type) into a DataStorage. The TargetedMeasurer base class resolves a target — a GameObject, AttachmentPoint, or AttachableObject — and dispatches to its list of typed measurements. Each measurement reads from the target and writes a keyed value into the storage.