Mates

Mates help your user drag-and-drop meshes. Like magnets, mates help meshes align perfectly according to the connectors on the meshes and your business logic.

Mates are based on mesh connectors. Your scene should have at least two separate meshes, each with a connector, before you create a mate.

Overview

When two meshes with connectors are marked as draggable, and they are dragged close enough to each other for the user to see them overlap, then the connectors can automatically align with each other, thanks to the logic of mates.

Specifically, this means both the position and rotation of one connector can be applied to the other. The rest of the dragged mesh follows along. This makes the drag-and-drop experience easy for the user, as they see the object “snap” into the correct position according to both your business rules expressed in the mate, and to the spatial math of the 3D space.

For example, a pressure dial has a male input port on the bottom. A pipe fitting has three female ports on the sides and top. Using these ports in the real world, it’s easy to connect these two objects together.

In the virtual world of the 3D scene, invisible connectors must be added to meshes to mark these special points on each mesh. And then mates can define which connectors align with each other, and which connectors ignore each other. For example, adding connectors to the dial and the pipe fitting objects in the 3D space, and defining mates that specify these connectors are compatible, can help ensure the pressure dial aligns correctly to one of the three locations on the pipe fitting when dragged near them. But it does not align to other, incompatible connectors, such as a connector on the end of an electrical cable.

Aligning meshes within one scene

Mate Types

Mates can help align draggable meshes within one scene.

1. In a scene, create two or more meshes.

2. In each mesh, create at least one connector. Ensure the connector is positioned and rotated correctly to define the position and rotation of the connection point.

3. Optionally, you can fix one of the meshes. Select the mesh, click the context menu and choose “fix”. An anchor icon appears next to the mesh. Repeat the process to “unfix” the mesh, and the anchor disappears.

4. In the explorer, select the mates category and click the context menu to create a new mate.

5. Give the mate a name, specify its type, and select the two connectors that define this mate.

6. Optionally, you can adjust the mate's properties to flip direction, swap the connector, or align with only specific other mates with matching metadata to ensure it behaves as expected.

What is “fixing” a mesh?

When a mate aligns two meshes by their connectors, one of them will stay still and the other will move to complete the mate. Usually, the one that will move is the one your user is dragging. To control exactly which mesh moves and which stays in place, turn on the “fix” property on one of the two meshes. The anchor symbol will appear next to the name of the mesh, and the “fix” will ensure that mesh will not move to complete the mate. All movement will be from the other mesh.

Assign a type to a mate to control how the two meshes can be moved after they are mated together.

Type	Position	Rotation	Real-World Example
Fastened	fixed (cannot be moved)	fixed (cannot be rotated)	A stamp glued to an envelope cannot be moved or rotated.
Revolute	fixed	flexible (can be rotated)	The handle on a water faucet can be turned, but not moved to another location.
Slider	fixed along one dimension	fixed (cannot be rotated)	An elevator can move up or down the elevator shaft, but cannot rotate within it.
Planar	fixed along two dimensions	fixed (cannot be rotated)	A table can slide around a room.
Cylindrical	fixed along the circumference of a cylinder	fixed (cannot be rotated)	A flag can blow in any direction away from a flagpole, and can move up and down the flagpole, but it cannot be rotated upside down.
Ball	fixed along the surface of a sphere	fixed (cannot be rotated)	The carrot nose can be placed anywhere on a snowman’s spherical head.
Parallel

Using Mates in Snap rules

Mates define how mesh connectors can align two meshes. However, the logic to control and implement this logic comes from Snap rules and the mate properties.

Mating meshes within one scene

In a scene rule, you can create a new Mate. Mates appear in the scene graph as children of the scene node itself, so do the same when creating a mate via Snap: make it a child of the scene node. For example, in the scene “Connector test” we have two connectors, called “connector1” and “connector2”. This would create a mate between those two connectors:

Mating meshes from different child scenes

As you know, when nesting configurators, you can nest the scenes as well. Meshes from all child scenes appear in the parent scene as though the origins of all scenes are aligned.

Creating connectors as needed

The meshes may appear all in the same space, but logically they remain organized in a hierarchy. The parent configurator/scene is at the top, with the child configurators/scenes treated as an array. Any children of those children are again an array, and so on to make a tree structure.

What does this have to do with creating Mates?

Any connectors on any meshes in any child scenes can be mated to another connector from another child scene. But the mating must occur at the parent scene level, because only the parent scene has visibility to all children.

In a parent scene, use Snap code to create a mate between two meshes from two child scenes. Here, for example, we have

• A configurator called “Connector Test” with 2 nested configurators.

• Each configurator has a scene of the same name.

• The child scenes have at least one mesh with at least one connector.

To mate the two child meshes by their connector, write code in the parent scene: create a new mate node as a child of the scene node.

If your child scenes do not have connectors, you can also create connectors at the parent level for each child scene:

(Note how we use the modulo ( % ) function to alternate the variable dir back and forth from +1 to -1 as we loop through the children. This creates connectors that face in a direction opposite to the previous one, so they can be mated together to make a long line, like beads on a string. You may use this or other techniques to ensure the position and direction of your connectors are correct.)