pins

Declaration

@MainActor @preconcurrency var pins: EntityGeometricPins { get }

Discussion

You can look up, add, and remove a GeometricPin for the owning entity through this EntityGeometricPins instance. The entity’s GeometricPinsComponent stores any added geometric pins.

Other Component types on an Entity may also provide GeometricPin instances, such as for skeletal pose joints. There is no distinction between these two when GeometricPin instances are accessed.

Geometric pins for skeletal pose joints

Pins for skeletal pose joints are not predefined, they need to be set in entity’s GeometricPinsComponent before you can access them. When associating a pin with a skeletal pose joint, you need to pass in the correct joint names either in full pose joint name or with its leaf joint name:

let fullNamePin = skeletalPoseEntity.pins.set(named: "fullName", skeletalJointName: "root/hips_joint/spine_1_joint/spine_2_joint")
let shortNamePin = skeletalPoseEntity.pins.set(named: "shortName", skeletalJointName: "spine_2_joint")

The pose (position and orientation) of the GeometricPin is the current pose of the joint in the coordinate frame of the Entity (i.e. not relative to the parent joint). While the skeletal pose is animated, the GeometricPin pose change on every frame.

To print all the pins, you can loop over pins.

for pin in skeletalPoseEntity.pins {
    print("joint   name: \(pin.name)")        // Full joint path name.
    print("    position: \(pin.position)")    // In coordinate frame of skeletalPoseEntity.
    print(" orientation: \(pin.orientation)") // In coordinate frame of skeletalPoseEntity.
}

In skeletal pose joint names, prefix the characters ., [, ] and \ with an escaping character (\).

For example, to access a skeletal pose joint named "my.joint":

// To include a literal backslash in a string,
// escape it with an additional backslash.
let myJointPinEscaped = skeletalPoseEntity.pins.set(named: "myJointPinEscaped", skeletalJointName: "my\\.joint")
// Alternatively, use Swift's raw string feature
// by enclosing the string in # symbols.
let myJointPinRaw = skeletalPoseEntity.pins.set(named: "myJointPinEscaped", skeletalJointName: #"my\.joint"#)