Connectors

Connectors are connection interfaces which allow you to snap assets or entities together. Connectors are commonly used with assets, allowing you to reposition and snap parts easily without requiring manual positioning. There are two types of connectors used in ProtoTwin:

• Point Connectors: Define a position and rotation for attaching an entity to another at a point, such as mounting an industrial robot arm on a robot pedestal or attaching end-of-arm tooling to a robot flange.
• Curve Connectors: Define a curve and rotation for attaching an entity to another along a path, such as mounting a bracket on the side of a straight or curved conveyor.

Included are a PointConnectorComponent and CurveConnectorComponent which can be added to entities to configure how they snap together. Connectors can also be configured programmatically using the TypeScript API.

Using Connectors

Connectors can be used to:

• Snap an industrial robot to a pedestal.
• Snap a gripper to a robot flange.
• Connect the start of one conveyor to the end of another conveyor.
• Mount brackets, stands, guide rails or end stops along a conveyor.
• Position attachments along either straight or curved equipment.

Point connectors can snap to other point connectors when the connection has a fixed mounting location. A point connector can also snap to a curve connector, allowing an attachment to be positioned anywhere along the curve. Many assets in the asset library are already preconfigured with connectors, allowing you to position and align parts easily.

It is possible to configure point connectors to snap to other point connectors, or configure point connectors to snap to curve connectors, but it’s not possible to configure a curve connector to snap to another curve connector, or a point connector.

Tags and Targets

Connector tags can be used to control the connectors that are compatible. The Tag identifies the type of connection provided by a connector. Point connectors additionally have Targets, which specify the tags they are allowed to snap to.

For example, a robot pedestal could use the built-in tag robot.pedestal, while the point connector on the base of the robot arm targets the robot.pedestal tag. Please see the built-in connector tags used by various assets. For your own connectors, you may use one of these tags or create a tag with a unique name.

Snapping

Snapping refers to the process of dragging the transform gizmo of an entity so that the connectors are connected.

• The Snap Mode controls which parts of the connector pose are aligned. The Position, X Axis, Y Axis and Z axis can be enabled independently. A snap mode is only applied when it is enabled on both connectors.
• The Snap Radius controls the distance between connectors in screen-space before interactive snapping can occur, whereas the Snap Angle limits the angular difference between the axes.
• The Snap Entity optionally specifies the entity to reparent when a connection is created. The snap entity of the source connector specifies the entity to reparent, whereas the snap entity of the target connector specifies the entity that becomes the new parent.

For snapping to occur, the angle between the axes on each connector must be less than the snap angle, the distance between the origin point on each connector must be less than the snap radius, and the target connector’s tag must be compatible with one of the targets on the source connector.

Snapping Example

A robot pedestal asset that has only Position and Z Axis enabled will snap only the position and z-axis. If the robot’s z-axis is facing up, the consequence of not enabling the X Axis or Y Axis is that you can rotate the robot arm after snapping by dragging the gizmo and using the scroll wheel on your mouse.

The point connector attached to the base entity of the robot will have its snap entity set to the robot entity itself, and the connector on the pedestal will have its snap entity set to itself. This will cause the robot to become a child of the pedestal when both connectors are connected.

Disconnecting

You can disconnect two connectors by dragging the transform gizmo of the snapped entity away from the connected point. This will also reparent the snapped entity to the world.

TypeScript API

Connectors can be snapped programmatically through the world.connectors manager. The following example show how to snap a robot onto a pedestal:

import { type Handle, type World, Tool, PointConnectorComponent } from "prototwin";

export class Snap extends Tool<World> {
    public robot: Handle<PointConnectorComponent> = this.handle(PointConnectorComponent);
    public pedestal: Handle<PointConnectorComponent> = this.handle(PointConnectorComponent);

    override valid(world: World): boolean {
        return true;
    }

    override execute(world: World): void {
        const robot = this.robot.value;
        const pedestal = this.pedestal.value;
        if (robot !== null && pedestal !== null && robot.connector !== null && pedestal.connector !== null) {
            world.connectors.snapPointPoint(robot.connector, pedestal.connector);
        }
    }
}

The first connector is the source that is snapped to the target connector. A point connector can also be snapped to a curve connector:

return world.connectors.snapPointCurve(bracket, conveyorSide, { t: 0.5 });

The t option specifies a normalized position along the curve between 0 and 1. The s option can instead specify the arc-length distance along the curve.

The connector manager can also be used to inspect connections, disconnect connectors and create point or curve connectors programmatically. Please see the Connectors API documentation for more information.

Rendering

You can render all the connectors by clicking the Show Connectors button in the infobar underneath the viewport. Click the button again to disable rendering the connectors. The meaning of the color used to render the connector is described below:

• Curve connectors are always rendered in orange.
• Point connectors with an orange sphere tell you the point connector is not connected.
• Point connectors with a black sphere tell you the point connector is connected.
• The x-axis of the point/curve connector frame is rendered in red.
• The y-axis of the point/curve connector frame is rendered in green.
• The z-axis of the point/curve connector frame is rendered in blue.
• An axis is not rendered if its not enabled in the snap mode of the connector.