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.

• Point Filter - An optional list of IAttachmentPointCheck checks (e.g. GameObjectFilterAttachmentPointCheck, 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.

To tag this object, add a Tagger component and assign Key assets. Receiving slots can then use a GameObjectFilterAttachableCheck with a JungleTagFilter to enforce tag matching.

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
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.

• Attachable Filters - List of IAttachableObjectCheck checks (e.g. GameObjectFilterAttachableCheck, 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.

To tag this slot, add a Tagger component and assign Key assets. Objects or agents can then use a GameObjectFilterAttachmentPointCheck with a JungleTagFilter to enforce tag matching.

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 selection step — for example AttachableObjectFilterGroup with GameObjectFilterAttachableCheck (containing a JungleTagFilter) + EligibilityCheck, or AttachmentPointFilterGroup with GameObjectFilterAttachmentPointCheck + CanAttachCheck. The umbrella filters also redirect the candidate (e.g. a child collider redirects to the parent AttachableObject). Use a Sequence to compose multiple steps.
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 selection step decides what gets accepted.

For "mirror this detection into a container that another command can read", put a Reactor next to it with a Detector Membership cycle reaction: its On Begin process runs a ContainerCommand with a StoreValueOperation, its On End process a RemoveValueOperation. The detector stays pure; the reaction does the side effect.

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's process.

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 typed checks.
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 typed checks. No Destination Policy decides what happens when no valid slot exists: drop in place, keep holding, or return to the origin point.
6. Automation - Continuous operation: Auto Repeat restarts the cycle automatically. Buffer Requests 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 run a move on its own, or move several objects together, use a Transformer.

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, in a straight line or along an arc
• ShapeTraversalTransformTarget - Travel a route across any shape at a set speed, along either axis or on a route you draw
• SequenceTransformTarget - Step through a sequence of targets
• CompositeTransformTarget - Combine position, rotation and scale, each from its own target
• ConditionalTransformTransformTarget - Switch targets based on a condition; each slot holds a full target that starts over when picked

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 Key ScriptableObjects — shared Jungle Core assets created via Create > Jungle > Data > Key.

Add a Tagger component to each GameObject (attachable or slot) and assign the appropriate tags. Then add filter checks 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. The Detector's selection step takes IObjectSelection — use AttachableObjectFilterGroup / AttachmentPointFilterGroup as umbrella steps that resolve the component and run inner typed checks.

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

Filter	What it checks
GameObjectFilterAttachableCheck	Runs any IGameObjectFilter (e.g. a JungleTagFilter) against the attachable's GameObject
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
GameObjectFilterAttachmentPointCheck	Runs any IGameObjectFilter (e.g. a JungleTagFilter) against the point's GameObject
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	Hides the slot after a watched attachable detaches from it, until the configured reset (distance, time, or detector focus) fires

Tag Requirement Modes

The JungleTagFilter 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. Add a Process Component, pick Measurement Command as its process, set the target, and add measurements. For attach counts and hold times, use Attachable Object Measurement Command or Attachment Point Measurement Command instead. See Tutorial: Measuring Motion.

Available measurements:

Measurement	What it tracks
Position	Current world position
Velocity	Velocity vector (position delta / time)
Speed	Scalar speed (magnitude of velocity)
Acceleration	How fast the speed is changing
Angular Velocity	Rotation rate
Accumulated Twist	Total degrees turned around an axis
Distance Traveled	Cumulative distance moved
Distance To Object	Distance between the target and another object
Bounds	Renderer bounds in world space

Each measurement writes into its own Sink. To store results in a Data Storage, pick Float From Data Storage (or the matching type) as the sink and set its storage and key. Anything that reads that key, such as a Reactor or a condition, then sees the live value.