MovableComponent

fun createAnchorable(
    session: Session,
    anchorPlacement: Set<AnchorPlacement> = setOf(AnchorPlacement.createForPlanes()),
    disposeParentOnReAnchor: Boolean = true
): MovableComponent

Public factory function for creating a MovableComponent.

This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.

When created with this function the MovableComponent will move and potentially Anchor the Entity. When anchored a new AnchorEntity will be created and set as the parent of the Entity. If the entity is moved off of a created AnchorEntity it will be reparented to the ActivitySpace. An EntityMoveListener can be attached to receive callbacks when the Entity is being moved and to see if it was reparented to an AnchorEntity.

This component cannot be attached to an AnchorEntity or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.

This functionality requires Session to be called with androidx.xr.runtime.PlaneTrackingMode.HORIZONTAL_AND_VERTICAL. This configuration requires that the SCENE_UNDERSTANDING_COARSE Android permission is granted. If not granted, the anchorable functionality will be disabled, and the element will behave as if the anchoring functionality was not applied.

fun createCustomMovable(
    session: Session,
    scaleInZ: Boolean,
    executor: Executor?,
    entityMoveListener: EntityMoveListener
): MovableComponent

Public factory function for creating a MovableComponent.

This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.

When created with this function the MovableComponent will not move or rescale the Entity, but it could be done using the EntityMoveListener.onMoveUpdate callback.

This component cannot be attached to an AnchorEntity or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.

fun createSystemMovable(session: Session, scaleInZ: Boolean = true): MovableComponent

Public factory function for creating a MovableComponent.

This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.

When created with this function the MovableComponent will move and rescale the Entity. EntityMoveListener can be attached to received callbacks when the Entity is being moved.

This component cannot be attached to an AnchorEntity or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.

fun <T : Trackable.State> createTrackingMovable(
    session: Session,
    trackable: Trackable<T>,
    poseExtractor: Function<T, Pose?> = Function { state ->
                when (state) {
                    is AugmentedObject.State -> {
                        state.centerPose
                    }
                    is Eye.State -> {
                        state.pose
                    }
                    is Hand.State -> {
                        state.handJoints[HandJointType.PALM]
                    }
                    is Plane.State -> {
                        state.centerPose
                    }
                    else -> {
                        null
                    }
                }
            }
): MovableComponent

Creates a MovableComponent that allows an entity's pose to be driven by an external ARCore Trackable.

This factory is designed for scenarios where an entity needs to continuously track a pose provided by an ARCore data source, such as the user's hand joint from Hand.

Once this component is created and attached to an entity, it will automatically start collecting pose updates. The collection operation is internally managed and tied to the component's attachment lifecycle. The provided poseExtractor function is invoked on the main thread during the frame update loop whenever the underlying Trackable emits a new state. This invocation begins when the component is attached to an Entity and stops when it is detached.

If the poseExtractor returns null (e.g., if a valid pose cannot be extracted from the current state), the system silently does nothing and the entity's pose remains unchanged. Note that any exceptions thrown by the poseExtractor are not caught by the runtime and will propagate, potentially crashing the application.

The default implementation of poseExtractor extracts a pose from the following states: AugmentedObject.State (using centerPose), Eye.State (using pose), Plane.State (using centerPose), and Hand.State (using the pose of the HandJointType.PALM joint). For any other state types, the default implementation returns null, resulting in no pose updates. You must provide a custom poseExtractor for unlisted types.

fun addMoveListener(entityMoveListener: EntityMoveListener): Unit

Adds a listener to the set of active listeners for the move events. The listener will be invoked regardless of whether the Entity is being moved by the system or the user.

The listener is invoked on the main thread.

fun addMoveListener(
    executor: Executor,
    entityMoveListener: EntityMoveListener
): Unit

Adds a listener to the set of active listeners for the move events. The listener will be invoked regardless of whether the Entity is being moved by the system or the user.

The listener is invoked on the provided Executor. If the app intends to modify the UI elements/views during the callback, the app should provide the thread executor that is appropriate for the UI operations. For example, if the app is using the main thread to render the UI, the app should provide the main thread (Looper.getMainLooper()) executor. If the app is using a separate thread to render the UI, the app should provide the executor for that thread.

fun removeMoveListener(entityMoveListener: EntityMoveListener): Unit

Removes a listener from the set of active listeners for the move events.

protected open fun onAttach(entity: Entity): Boolean

Called by the framework when this component is being added to an Entity.

This method is triggered when Entity.addComponent is invoked. Implementations should override this method to perform setup logic or to validate if the component is compatible with the provided entity.

protected open fun onDetach(entity: Entity): Unit

Called by the framework when this component is being removed from an Entity.

This method is triggered when Entity.removeComponent is invoked. Implementations should override this method to release resources or undo any changes made during onAttach.

var size: FloatSize3d

The size of the move affordance in local space virtual meters. This property determines the size of the bounding box that is used to draw the draggable move affordances around the Entity. This property can be modified if the move affordance needs to be larger or smaller than the Entity itself.

When attaching this component to an entity, the apps may update this value to appropriate new value, such as the size of the entity this component is being added to. If apps don't set this value, the component will try to use the entity's dimensions as value for this property where applicable, or default to (1 x 1 x 1).