<!--
{
  "availability" : [
    "visionOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "TabletopKit",
  "identifier" : "/documentation/TabletopKit/TabletopInteraction",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "TabletopKit"
    ],
    "preciseIdentifier" : "s:11TabletopKit0A11InteractionC"
  },
  "title" : "TabletopInteraction"
}
-->

# TabletopInteraction

A protocol for objects that manage the entire flow of players interacting with equipment.

```
class TabletopInteraction
```

## Overview

Conform to the [`TabletopInteraction.Delegate`](/documentation/TabletopKit/TabletopInteraction/Delegate) protocol to take an appropriate action, depending on the equipment and the phase of the interaction. For example, move equipment or toss a die when a gesture ends.

```swift
struct MoveInteraction: TabletopInteraction.Delegate {
    func update(interaction: TabletopKit.TabletopInteraction) {
        let equipment = interaction.value.controlledEquipmentID
        guard let destination = interaction.value.proposedDestination else {
            return
        }
        
        if interaction.value.phase == .ended {
            interaction.addAction(.moveEquipment(matching: equipment, childOf: destination.equipmentID, pose: destination.pose))
        }
    }
}
```

To get information about the equipment that the interaction applies to, use the [`value`](/documentation/TabletopKit/TabletopInteraction/value-swift.property) property. To get the phase of the interaction or gesture, use the `Value` [`gesturePhase`](/documentation/TabletopKit/TabletopInteraction/Value-swift.struct/gesturePhase) or [`phase`](/documentation/TabletopKit/TabletopInteraction/Value-swift.struct/phase-swift.property) properties.

Then execute actions — for example, move equipment when the phase ends — using the [`addAction(_:)`](/documentation/TabletopKit/TabletopInteraction/addAction(_:)-1cety) or [`addActions(_:)`](/documentation/TabletopKit/TabletopInteraction/addActions(_:)) method.

To start an interaction programmatically, use the `TabletopGame` [`startInteraction(onEquipmentID:)`](/documentation/TabletopKit/TabletopGame/startInteraction(onEquipmentID:)) method.

## Topics

### Performing actions

[`protocol Delegate`](/documentation/TabletopKit/TabletopInteraction/Delegate)

A protocol for objects that manage the entire flow of players interacting with equipment.

[`struct TossOutcome`](/documentation/TabletopKit/TabletopInteraction/TossOutcome)

An object representing the final outcome of tossing one equipment, as it appears at the end of its simulation.

[`func addAction(some TabletopAction)`](/documentation/TabletopKit/TabletopInteraction/addAction(_:)-1cety)

Submit an action tied to this interaction. If the interaction gets canceled, all the associated actions will be automatically rolled back.

[`func addAction(some CustomAction)`](/documentation/TabletopKit/TabletopInteraction/addAction(_:)-4rx16)

Submit a custom action tied to this interaction. If the interaction gets canceled, all the associated actions will be automatically rolled back.

[`func addActions(some Sequence<any TabletopAction>)`](/documentation/TabletopKit/TabletopInteraction/addActions(_:))

Submit a collection of actions tied to this interaction. If the interaction gets canceled, all the associated actions will be automatically rolled back.

[`func toss(equipmentID: EquipmentIdentifier, as: TossableRepresentation, linearVelocity: Vector3D?, angularVelocity: Vector3D?)`](/documentation/TabletopKit/TabletopInteraction/toss(equipmentID:as:linearVelocity:angularVelocity:))

Begins a simulation of a toss of the equipment with the specificied parameters. Equipment that begins a toss in the same TabletopInteraction may interact with each other as well as the game’s boundary.

[`func end()`](/documentation/TabletopKit/TabletopInteraction/end())

Ends the current interaction.

[`func cancel()`](/documentation/TabletopKit/TabletopInteraction/cancel())

Cancels the current interaction. All actions added to the interaction will also be cancelled.

### Getting the value of the interaction

[`var value: TabletopInteraction.Value`](/documentation/TabletopKit/TabletopInteraction/value-swift.property)

The current value belonging to this interaction.

[`struct Value`](/documentation/TabletopKit/TabletopInteraction/Value-swift.struct)

A structure that provides the details about an interaction, such as the phase of the gesture and position of the equipment.

### Setting information about the equipment and pose

[`func setControlledEquipment(matching: EquipmentIdentifier)`](/documentation/TabletopKit/TabletopInteraction/setControlledEquipment(matching:))

Replace the current controlled equipment with a different one

[`func setPose(Pose3D)`](/documentation/TabletopKit/TabletopInteraction/setPose(_:))

Sets the pose of the controlled `Equipment`.

### Managing the interaction destination

[`func setConfiguration(TabletopInteraction.Configuration)`](/documentation/TabletopKit/TabletopInteraction/setConfiguration(_:))

Sets the configuration of this interaction.

[`struct Configuration`](/documentation/TabletopKit/TabletopInteraction/Configuration)

[`enum AllowedDestinations`](/documentation/TabletopKit/TabletopInteraction/AllowedDestinations)

The possible destinations of equipment in an interaction.

[`struct Destination`](/documentation/TabletopKit/TabletopInteraction/Destination)

An object that represents the destination position and orientation of equipment in an interaction.

[`func setAllowedDestinations(TabletopInteraction.AllowedDestinations)`](/documentation/TabletopKit/TabletopInteraction/setAllowedDestinations(_:))

Sets which equipment the interaction can target.

### Getting the interaction identifier

[`struct Identifier`](/documentation/TabletopKit/TabletopInteraction/Identifier)

A unique identifier for interactions.

### Determining the dead zone

[`enum DeadZone`](/documentation/TabletopKit/TabletopInteraction/DeadZone)

The dead zone allows to specify how much the input device should move or rotate from its initial pose
to start moving the object.

### Handling collision behavior

[`enum Constants`](/documentation/TabletopKit/TabletopInteraction/Constants)

[`struct CollisionTargets`](/documentation/TabletopKit/TabletopInteraction/CollisionTargets)

A set of targets for collision behaviors during an interaction

[`struct DirectPickupBehavior`](/documentation/TabletopKit/TabletopInteraction/DirectPickupBehavior)

An object that represents the behavior of the pickup phase of the direct interaction.
The pickup phase describes how the object moves from its initial pose to the pose it
will have when moving rigidly with the input device.

[`struct DirectInteractionConstants`](/documentation/TabletopKit/TabletopInteraction/DirectInteractionConstants)

An object that represents the parameters of a direct interaction that cannot be changed while
the interaction is active.

[`enum IndirectRotationAlignmentBehavior`](/documentation/TabletopKit/TabletopInteraction/IndirectRotationAlignmentBehavior)

An object that represents how the equipment’s orientation should be automatically aligned
during the course of the interaction.

[`struct IndirectInteractionConstants`](/documentation/TabletopKit/TabletopInteraction/IndirectInteractionConstants)

An object that represents the parameters of an indirect interaction that cannot be changed while
the interaction is active.

[`enum HoverAlignmentBehavior`](/documentation/TabletopKit/TabletopInteraction/HoverAlignmentBehavior)

An object that describes how the controlled equipment should behave when approaching a target.

[`enum HoverAlignmentSource`](/documentation/TabletopKit/TabletopInteraction/HoverAlignmentSource)

An object representing the types of features that can be auto aligned by the
`HoverAlignmentBehavior`

[`struct ProgrammaticInteractionConstants`](/documentation/TabletopKit/TabletopInteraction/ProgrammaticInteractionConstants)

An object that represents the parameters of a programmatic interaction that cannot be changed while
the interaction is active.

### Handling interaction intents

[`enum NewInteractionIntent`](/documentation/TabletopKit/TabletopInteraction/NewInteractionIntent)

[`struct NewDirectInteractionIntent`](/documentation/TabletopKit/TabletopInteraction/NewDirectInteractionIntent)

An object that represent the developer’s intent when a new direct interaction is proposed by the system

[`struct NewIndirectInteractionIntent`](/documentation/TabletopKit/TabletopInteraction/NewIndirectInteractionIntent)

An object that represent the developer’s intent when a new indirect interaction is proposed by the system


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)