OPAL: Open Physics Abstraction Layer

Tutorial 8: Contact Groups

Usually all Solid/Solid collisions generate physical contacts that keep them from interpenetrating. Sometimes this is not desired, either for performance reasons (fewer constraints means faster simulation) or for special effects. Contact groups can be used to enable forcefields that repel only a subset of objects, efficient ray casts that only collide with certain objects, invisible “trigger volumes” that generate collision events but don’t make physical contacts with anything, etc.

It is important to note the difference between “collision events” and “contacts” the way OPAL defines them. Collision events occur whenever two Solids collide (but are only handled if at least one of the two Solids uses a collision event handler). Contacts are physical constraints that keep Solids from penetrating one another. Solids can use collision events and/or contacts. By default, every collision group generates contacts, and every Shape starts in group 0.

Every OPAL Shape is in one (and only one) contact group. A contact group can be set to enable or disable contacts with other contact groups, including itself. For example, if groups 5 and 8 are set not to generate contacts, object A is in group 5, and object B is in group 8, objects A and B will pass through one another when they collide. OPAL can use up to 32 different contact groups. Contact groups always work both ways between two groups: if group X makes contacts with group Y, group Y will make contacts with group X.

Warning: Because the contact group interactions are always two-way, be careful about the order in which you setup the groups. If you set group 3 not to make contacts with group 5, then set group 5 to make contacts with group 3, the two groups will make contacts.

Here is an example that shows how to create three objects: object A, object B, and object C. We will generate contacts only between objects A and B and objects B and C, but not between objects B and C:

opal::Simulator* sim = opal::createSimulator();

// Create three Solids, each with a Shape in a different contact group.

opal::SphereShapeData sphereData;

opal::Solid* objectA = sim->createSolid();

sphereData.contactGroup = 1;

objectA->addShape(sphereData);

opal::Solid* objectB = sim->createSolid();

sphereData.contactGroup = 2;

objectB->addShape(sphereData);

opal::Solid* objectC = sim->createSolid();

sphereData.contactGroup = 3;

objectC->addShape(sphereData);

// Setup the contact groups.

sim->setupContactGroups(1, 2, true);

sim->setupContactGroups(2, 3, true);

sim->setupContactGroups(1, 3, false);

To setup an object that doesn’t make contacts with anything else, do the following:

opal::Simulator* sim = opal::createSimulator();

opal::BoxShapeData boxData;

boxData.contactGroup = 15;

opal::Solid* trigger = sim->createSolid();

trigger->addShape(boxData);

sim->setupContactGroup(15, false);

The “setupContactGroup” function sets up the interaction between a contact group and every other contact group at once, making it easy to create a trigger volume object that doesn’t affect anything else physically but can still generate collision events.

When using the RaycastSensor and VolumeSensor, keep in mind that contact groups can be used to make more efficient collision queries. Remember, the VolumeSensor takes a pointer to a “volume” Solid and checks which other Solids collide with that Solid. Simply use a contact group on the volume Solid’s Shape(s). The RaycastSensor has an explicit contact group that can be setup to limit which other groups it collides with.