Skip to content

Tutorial: Tag-Based Filtering

Make red objects only fit red slots, and blue objects only fit blue slots. By the end of this tutorial, mismatched objects will be silently rejected — no code required.

Prerequisites: Complete Tutorial: Your First Drag and Drop, or have an equivalent scene with at least two AttachableObjects and two AttachmentPoints.

1. Starting Point

You should have a working scene with:

  • At least two movable objects (e.g. RedCube and BlueCube, each with an AttachableObject component).
  • At least two slots (e.g. RedSlot and BlueSlot, each with an AttachmentPoint component).
  • A way to attempt attaching them — the CursorAgent from the basic tutorial works, or any other agent / command setup.

If you only have one of each from the basic tutorial, duplicate them now and re-wire the agent's drop destination to a Detector that finds both slots, so the agent picks whichever is closer / first.

2. Create Color Tags

Tags are tiny label assets. They carry no logic; they're just identifiers that the filtering system matches against.

In the Project window:

  1. Right-click in your Assets folder.
  2. Select Create → Jungle → Attachment → Attachment Tag.
  3. Name it Red.
  4. Repeat to create a Blue tag.

Tags are identities, not data

AttachmentTag assets carry no data beyond their identity (and an optional description). Two tags are "different" if they are different ScriptableObject assets. The asset name is for your reference.

3. Label Your Objects

Tell each cube which color it is.

Select RedCube. In its AttachableObject component, find the Filtering section and add the Red tag to the Tags list.

Select BlueCube. Add the Blue tag.

4. Label Your Slots

Do the same for the receiving slots.

Select RedSlot. In its AttachmentPoint component, find the Filtering section and add the Red tag to the Attachment Tags list.

Select BlueSlot. Add the Blue tag.

Objects and slots can carry multiple tags

A single object or slot can have many tags. A PurpleCube could carry both Red and Blue, and a UniversalSlot could too.

5. Add a Filter That Enforces the Tags

Tags alone are just labels — they don't block anything yet. You need a filter that checks whether an incoming object's tags match the slot's requirements.

Select RedSlot. In its AttachmentPoint, scroll to the Attachable Filters list inside the Filtering section. Click + and pick Tag (the AttachableTagCheck) — the slot already knows it is filtering attachables, so checks are added directly with no umbrella wrapper.

Configure it:

Field Value
Required Tags Red
Requirement Any

Repeat for BlueSlot with the Blue tag.

Where to put the filter

Filters can live in three places:

  1. On the slot's Attachable Filters — the slot decides which objects it accepts.
  2. On the object's Point Filter — the object decides which slots it tolerates.
  3. On the agent's Grab Filters / Drop Filters — the agent enforces a global rule during a transfer.

Slot-side is the most intuitive — each slot owns its acceptance rule.

6. Test the Filtering

Press Play. Have the agent attempt every combination:

  • RedCube → RedSlot — succeeds. The red tag satisfies the filter.
  • RedCube → BlueSlot — rejected. The red tag does not satisfy the blue filter.
  • BlueCube → BlueSlot — succeeds.
  • BlueCube → RedSlot — rejected.

When a transfer is rejected, the agent silently picks the next eligible candidate (or fails the drop if none are valid). No exceptions thrown.

Why the rejection was silent

The AttachingAgent buffers rejection reasons internally — open the agent's Debug panel in the Editor to see exactly which filter or condition rejected each candidate. See the AttachingAgent reference for the rejection record API.

7. Filter Requirement Modes

AttachableTagCheck and AttachmentPointTagCheck both expose a Requirement mode that controls how the required tag list is evaluated.

All — "must have every tag"

Filter requires: [Red, Heavy]
Object has: [Red, Heavy, Fragile]   → PASS
Object has: [Red]                   → FAIL (missing Heavy)

Any — "must have at least one"

Filter requires: [Red, Blue]
Object has: [Red]    → PASS
Object has: [Green]  → FAIL

One — "must match exactly one"

Filter requires: [Red, Blue, Green]
Object has: [Red]        → PASS
Object has: [Red, Blue]  → FAIL (two matches)

AnyExcept — "must have none of these"

Filter requires: [Fragile]
Object has: [Heavy, Red]      → PASS (no Fragile)
Object has: [Fragile, Red]    → FAIL

AnyExcept in practice

A Trash Bin slot with an AnyExcept filter for [Valuable] accepts any object except those tagged as valuable.

8. Combining Multiple Filters

You can add multiple filters to the same list. All filters must pass — the chain is AND-evaluated.

For example, on a single slot's Attachable Filters list:

  1. Tag Filter — requires the Red tag.
  2. Held State Filter — requires the object to not be currently attached elsewhere.

The result: a slot that only accepts free, red-tagged objects.

Filter chains are always allowlists

A filter slot in Octoputs always means allow only what passes. To express "reject these", invert at the leaf — for tags, use the AnyExcept mode. There is no top-level denylist.

9. Object-Side Filters: When the Object Picks Slots

The flip side: an object that's choosy about which slots it accepts. On the AttachableObject's Point Filter list, add a Tag check directly requiring, say, Heavy Duty Slot. Now this specific object will refuse any slot that doesn't carry that tag — useful for objects that need infrastructure (a battery requires a charging dock, a key requires a keyhole).

The other AttachmentPoint checks available:

Check What it tests
AttachmentPointTagCheck Tag match (with All/Any/One/AnyExcept).
IsHoldingCheck Whether the slot currently holds anything.
CanAttachCheck Whether the slot's own conditions allow attaching a specific object.
PhaseCheck Current lifecycle phase (Idle / Attaching / Attached / Detaching).
OnAttachedObjectCheck Delegates to nested attachable checks evaluated on whatever the point currently holds.
NotJustDetachedCheck Hides a point briefly after a detach to avoid immediate re-highlight.

Next Steps