Skip to content

Octoputs Overview

Octoputs is a modular Unity framework for building spatial interactions — dragging, attaching, detaching, snapping, transferring, and arranging objects in your scene. Whether you're making an inventory system, a card game hand, an Astroneer-style resource management interface, a VR object grabber, or a physics-based crane, Octoputs gives you the building blocks to compose the behavior you need — without writing movement code.

What Can You Build?

  • Inventory and storage systems — drag items between grid slots, stacks, or categorized containers
  • Card games — fan cards in hand, drag to play, snap to board positions
  • 3D object manipulation — pick up, carry, and place objects with mouse, touch, or VR controllers
  • Automated workflows — robot arms, conveyor belts, delivery drones that grab and drop on their own
  • Physics-based interactions — objects with weight, inertia, and collision that feel real
  • Snap-to-grid editors — level editors, furniture placement, building tools
  • Character carrying — third-person characters that pick up and carry objects

Core Concepts

Octoputs is built around a few simple ideas:

Attachable Objects and Attachment Points

Any object in your scene can become attachable — something that can be picked up, moved, and placed. Any other object can become an attachment point — a slot, target, or destination that accepts attachable objects. The relationship between them drives everything else.

Both objects and points go through a lifecycle: idle, attaching, attached, detaching. Each phase can have its own conditions, animations, and behaviors — all configurable in the Inspector.

Detection and Filtering

Octoputs can automatically detect when objects enter a zone, get hit by a raycast, or appear in a reference list. Detection supports triggers, raycasts, and manual assignment, so it works with mouse input, VR hand tracking, third-person character interactions, or fully automated systems.

Attachment can be filtered and restricted — only certain objects fit certain slots. You can filter by tags, by state, by stats, or by custom conditions, keeping your logic clean without writing if-statements.

Movement and Feel

When an object moves toward its target, the movement passes through a pipeline with three stages:

  1. Where should it go? — The target: follow a transform, track a raycast hit on a surface, blend between multiple destinations, or follow a curve
  2. How should the movement feel? — Modifiers adjust the path: add spring physics for bouncy movement, snap to a grid, avoid collisions, align to surfaces, add tilt based on velocity, or apply smoothing. Over 30 modifiers can be stacked and combined.
  3. How does it physically move? — The applier: set the position directly for snappy response, apply physics forces for weighted feel, or use joints for rope-like trailing

Each piece is independent. Swap the target without changing the feel. Add a modifier without touching anything else. The same object can feel completely different just by changing pipeline settings.

Transfer and Automation

Objects can be transferred between storages and attachment points, either manually (drag and drop) or automatically. The transfer system handles selection (which object to pick), amount (one at a time or all at once), and destination (where to place it).

For fully automated workflows, the AttachingAgent orchestrates complete grab-hold-drop sequences driven by events — press a button, detect a collision, or wait for a timer. Agents can auto-repeat, buffer requests, and run preparation animations before each action.

Layout and Arrangement

Attached objects can be automatically arranged using layout strategies — grids for inventories, fans for card hands, circles for radial menus, lines for shelves, or stacks for piles. Layouts update dynamically as objects are added or removed.

Tracking and Stats

Objects can track their own metrics — position, velocity, speed, distance traveled — and expose them to other systems. A per-object stat system lets you attach numeric values (weight, durability, value) that can be read by filters and conditions, enabling rules like "only accept objects lighter than 10kg" or "this slot is full when it holds 3 items."

High-Performance Mode

For demanding scenarios — resource management games with hundreds of simultaneous objects, or large-scale simulations — Octoputs provides batch pipeline processing using Unity's Job system. The same pipeline configuration scales from a single dragged object to hundreds running in parallel.

Architecture Overview

Under the hood, Octoputs follows a pipeline architecture where each stage is independently swappable:

flowchart LR
    D[Detector] -->|pushes into| S[Storage]
    S -->|read by| T[Transfer Process]
    T -->|attaches to| AP[Attachment Point]
    AP -->|runs| P[Transform Pipeline]
    P -->|Target| M[Modifiers]
    M -->|Applier| O[Object Transform]

Detection finds objects or points (via trigger colliders, raycasts, or manual references) and pushes them into Storage containers. A Transfer Process reads from source storage and moves objects to destination Attachment Points. Each attachment point runs a Transform Pipeline that computes the target position, applies a chain of modifiers, and writes the result to the object's transform.

The Transform Pipeline

The pipeline has three stages:

  1. Target — Computes WHERE the object should be (position, rotation, scale)
  2. Modifier chain — Adjusts the target (smoothing, constraints, snapping, collision avoidance)
  3. Applier — Controls HOW the object moves (direct set, physics forces, joint constraints)

Each stage has multiple implementations. Swap any piece without affecting the others.

Built on Jungle

Octoputs is built on the Jungle framework, which provides shared infrastructure used across all Jungle plugins:

  • Value Providers — Configurable data sources that decouple "where data comes from" from "what uses it." A speed value can come from a constant, an animation curve, or a ScriptableObject — your setup doesn't change.
  • Processes — A universal model for operations, whether instant or over time. Attach sequences, animations, and pipelines all share the same lifecycle.
  • Conditions — Boolean evaluators that gate actions: is the slot available? Does the object have the right tag? Is the distance close enough?
  • Events — Observable triggers that connect gameplay moments to behavior: a button press starts a grab, a timer fires a drop.
  • Class Selection — The Inspector UI that lets you browse, search, and select implementations from a categorized popup — no code required.

You do not need to learn Jungle separately to use Octoputs — the Inspector handles all wiring. But understanding these concepts helps when building advanced setups.

Next Steps