# Group Collision Checker (Pro)

## Overview

The **GroupCollisionChecker** detects runtime collisions between named realvirtual groups. Objects within the same group never collide with each other (self-collision is suppressed), while objects from different groups trigger collision events automatically.

This is useful for monitoring whether a robot arm collides with machine fixtures, or a gripper penetrates a workpiece holder — without false alarms from joints within the same kinematic chain.

<figure><img src="/files/4nf2pw5UgqKD3rejbf4Q" alt="Group Collision Checker detecting a robot colliding with the machine door"><figcaption><p>Collision between the robot group and the machine door is detected and highlighted in real time</p></figcaption></figure>

{% hint style="info" %}
This feature was added in realvirtual **6.3.0** (Professional)
{% endhint %}

## How It Works

The system uses a single dedicated physics layer (`rvCollissionCheck`) that is isolated from all other realvirtual layers (sensors, transport surfaces, sinks). Within that layer:

* **Same-group** collider pairs are suppressed via `Physics.IgnoreCollision`
* **Cross-group** collider pairs trigger collision events automatically
* Only **one** physics layer is consumed regardless of how many groups you define

This design avoids layer exhaustion and prevents side effects on sensors or transport systems.

## Quick Start

1. Add a **GroupCollisionChecker** component to any GameObject in your scene
2. Add entries to **Collision Groups** — each entry is a realvirtual Group name plus a collider mode
3. Optionally assign a **MultiObjectOverlayRendererFeature** reference for GPU-based highlighting
4. Press Play — collisions are detected and reported via signals, events, and Inspector status

## Properties

### Collision Groups

**Collision Groups** (list) The groups to monitor. Each entry defines:

* **Group Name** — the realvirtual Group name (as assigned via the Group component)
* **Collider Mode** — how colliders are created for objects in this group:
  * **BoxApproximation** — creates a BoxCollider from the renderer bounds. Fast and safe, but coarse.
  * **MeshCollider** — creates a convex MeshCollider. More accurate, uses the convex hull (max 255 vertices).
  * **ExistingOnly** — uses only already-present colliders. Objects without a collider are skipped.

### Settings

**Auto Setup On Start** (boolean) When enabled, the collision system initializes automatically when the simulation starts. Disable this to call `SetupCollisionSystem()` manually from script.

### Highlight

**Highlight On Collision** (boolean) Enables GPU-accelerated visual highlighting of colliding objects via the URP Overlay Renderer Feature.

**Overlay Feature** (reference) Assign a dedicated `MultiObjectOverlayRendererFeature` instance from your URP Renderer Asset. This must be a separate instance from the one used by the Selection system.

**Highlight Color** (Color) The highlight overlay color applied to colliding objects. Default: red.

**Overlay Mode** (enum) The rendering style for the highlight: Default, XRay, or Blink.

**Blink Speed** (float) Blink frequency in cycles per second when Overlay Mode is set to Blink.

**Reset Mode** (enum) Controls when highlights are removed:

* **WhileColliding** — highlight disappears automatically when collision ends
* **OnEnterPersistent** — highlight stays until manually reset via the ResetHighlight signal

### Interface Connection (PLC Signals)

**CollisionActive** (PLCInputBool) Output to PLC — true when at least one cross-group collision is active.

**CollisionCount** (PLCInputInt) Output to PLC — number of currently active collision pairs.

**ResetHighlight** (PLCOutputBool) Input from PLC — a rising edge clears all collision highlights.

**ResetCollisions** (PLCOutputBool) Input from PLC — a rising edge resets all collision tracking.

### Events

**OnCollisionEnterEvent** (UnityEvent) Fired when a cross-group collision begins. Provides both GameObjects involved.

**OnCollisionExitEvent** (UnityEvent) Fired when a cross-group collision ends. Provides both GameObjects involved.

### Advanced

**Excluded Pairs** (list) Specific cross-group pairs to exclude from detection. For example, exclude "Gripper" vs. "Workpiece" if gripper contact is intentional.

### Status (Read-Only)

**Is Colliding** — true when at least one collision is active

**Active Collision Count** — number of active collision pairs

**Total Proxy Count** — total managed collider proxies

**Highlighted Renderer Count** — renderers currently highlighted

**Active Pairs** — human-readable list of current collision pairs

## Collider Mode Recommendations

| Group Type      | Recommended Mode | Reason                                                 |
| --------------- | ---------------- | ------------------------------------------------------ |
| Robot joints    | ExistingOnly     | Manually placed capsule/box colliders are more precise |
| Machine frame   | BoxApproximation | Many parts, coarse detection sufficient                |
| Gripper / tools | MeshCollider     | Accurate shape matters for contact detection           |
| Safety zones    | ExistingOnly     | Manually placed box triggers as zone boundaries        |

## Typical Use Cases

**Robot vs. Machine Frame** — A 6-axis robot arm (Group "RobotArm") moves near a machine frame (Group "MachineFrame"). Self-collision within the robot's joints is suppressed. Any contact between robot and frame triggers a red blinking highlight and sets the PLC signal to stop the robot.

**Gripper vs. Fixture** — A gripper (Group "Gripper") picks parts from a fixture (Group "Fixture"). Gripper-to-workpiece contact is excluded via Excluded Pairs. Only unintended gripper-to-fixture contact triggers an alarm.

**Multiple Robots** — Two robots (Group "Robot1", Group "Robot2") work in overlapping reach zones. Each robot's internal joints don't trigger alarms, but any robot-to-robot contact does.

## Highlight Setup (URP)

To use the highlight feature, you need a second `MultiObjectOverlayRendererFeature` in your URP Renderer:

1. Open your URP Renderer Asset (typically `URP-Default-Renderer.asset`)
2. Click **Add Renderer Feature** and select **Multi Object Overlay Renderer Feature**
3. Name it "CollisionOverlay" to distinguish it from the selection overlay
4. Assign this new feature to the **Overlay Feature** field on the GroupCollisionChecker

The existing overlay feature (used by the Selection system) remains untouched.

## Scripting API

```csharp
// Manual setup (if AutoSetupOnStart is false)
checker.SetupCollisionSystem();

// Clear highlights without resetting tracking
checker.ClearAllHighlights();

// Reset all tracking (highlights + active pairs)
checker.ClearCollisionTracking();

// Subscribe to collision events via C# delegates
checker.OnGroupCollisionEnter += (objA, objB) => {
    Debug.Log($"Collision: {objA.name} <-> {objB.name}");
};

checker.OnGroupCollisionExit += (objA, objB) => {
    Debug.Log($"Collision ended: {objA.name} <-> {objB.name}");
};
```

## See Also

* [Group](/components-and-scripts/motion/group.md) — assigning objects to groups
* [Group Manager](/basics/runtime-ui/group-manager.md) — hiding/showing groups at runtime
* [Selection Window](/basics/user-interface/selection-window.md) — filtering by groups in the editor

\
© 2025 realvirtual GmbH [https://realvirtual.io](https://realvirtual.io/) - All rights reserved. No part of this publication may be reproduced, distributed, or transmitted in any form or by any means, including printing, saving, photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the publisher.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.realvirtual.io/components-and-scripts/collision/group-collision-checker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.