ManipulationComponent
A component that adds fluid and immersive interactive behaviors and effects.
Declaration
struct ManipulationComponentOverview
ManipulationComponent enables rich interaction on entities in 3D space, including gesture-based movement, and audio feedback. When you apply this to an entity, the system enables intuitive manipulation using hands or input devices like a trackpad.
Interaction Features
Gestures:
Single-hand or trackpad gestures allow translation of the entity.
Rotating the hand changes the orientation of the object.
Two-hand gestures allow intuitive scaling and rotation.
The system supports handoff between hands for seamless manipulation.
Audio Feedback:
The system plays audio cues at key interaction moments (e.g., pinch, handoff, release).
To disable system audio or use custom sounds, set audioConfiguration to
.none, and use component events to trigger your own audio responses.
Component Events:
ManipulationComponentpublishes events through the entity’sSceneto notify you of key stages in the interaction lifecycle.See ManipulationEvents for details on available events.
When you add this component to an entity, the system modifies the entity’s transform directly. If you need to apply your own transforms, consider applying them to a subentity instead, or listening to component events and responding accordingly.
Interaction Lifecycle
During a typical interaction, the system transitions through several stages, each stage has a specific event in ManipulationEvents. You can subscribe to these events to implement custom behaviors, audio feedback, analytics, or visual responses:
Interaction Will Begin: ManipulationEvents.WillBegin You can use this to add additional feedback, which lets someone know they have begun manipulating the entity.
Object Handed Off: ManipulationEvents.DidHandOff You can use this to provide visual or auditory confirmation of transfer.
Transform Updated: ManipulationEvents.DidUpdateTransform You can use this to drive effects like trails, dynamic shadows, or visual feedback.
Interaction Will Release: ManipulationEvents.WillRelease You can use this to run a final visual cue that the person’s manipulation of the entity is about to end.
Interaction Will End: ManipulationEvents.WillEnd You can use this event to remove visual cues to show that neither the person nor the app are actively manipulating the entity’s transform anymore.
Topics
Creating a manipulation component
Configuring the manipulation
configureEntity(_:hoverEffect:allowedInputTypes:collisionShapes:)audioConfigurationdynamicsreleaseBehavior