open class Entity : BaseScenePose

kotlin.Any
   ↳ androidx.xr.scenecore.BaseScenePose
     ↳ androidx.xr.scenecore.Entity
Known direct subclasses
ActivitySpace

ActivitySpace is an Entity used to track the system-managed pose and boundary of the volume associated with a spatialized Activity.
AnchorEntity

An AnchorEntity tracks a Pose relative to some position or surface in the "Real World." Children of this Entity will remain positioned relative to that location in the real world, for the purposes of creating Augmented Reality experiences.
GltfModelEntity

GltfModelEntity is a concrete implementation of Entity that hosts a glTF model.
MeshEntity

A renderable entity in the scene graph that renders a CustomMesh.
PanelEntity

PanelEntity contains an arbitrary 2D Android View, within a spatialized XR scene.
SurfaceEntity

SurfaceEntity is an Entity that hosts a Surface, which will be texture mapped onto the Shape.
Known indirect subclasses
ActivityPanelEntity

ActivityPanelEntity creates a spatial panel for embedding an Activity in Android XR.
MainPanelEntity

Represents the main spatialized panel in a Scene.

An Entity is the fundamental building block of a SceneCore Scene. Entities have a parent-child relationship with each other and are used to build a spatial scene graph.

There are several different Entity types with Entity being the base class. The position of most Entity types can be updated within the scene graph by updating their Pose. Additionally, the Entity's scale, and alpha can be updated. Components can be attached to Entities to enable additional behaviors.

There are several subtypes of Entities. These include Entities with special positions, (e.g. ActivitySpace and AnchorEntity) as well as those which are used to render different types of content (e.g. PanelEntity and GltfModelEntity).

Summary

Public companion functions
Entity
create(session: Session, name: String?, pose: Pose, parent: Entity?)

Public factory method for creating an Entity.

Public functions
Unit
addChild(child: Entity)

Sets an Entity to be a child of this Entity in the scene graph.
Boolean
addComponent(component: Component)

Adds a Component to this Entity.
@FloatRange(from = 0.0, to = 1.0) Float
getAlpha(relativeTo: Space)

Returns the alpha transparency set for this Entity, relative to given Space.
List<Component>

Retrieves all components attached to this Entity.
List<T>

Retrieves all Components of the given type T and its subtypes attached to this Entity.
open Pose
getPose(relativeTo: Space)

Returns the Pose for this Entity, relative to the provided Space.
open @FloatRange(from = 0.0) Float
getScale(relativeTo: Space)

Returns the scale of this entity, relative to given space.
Boolean
isEnabled(includeParents: Boolean)

Returns the enabled status of this Entity.
Unit

Remove all components from this Entity.
Unit

Removes the given Component from this Entity.
Unit
setAlpha(alpha: @FloatRange(from = 0.0, to = 1.0) Float)

Sets the alpha transparency of the Entity relative to the parent Space.
Unit
setEnabled(enabled: Boolean)

Sets the local enabled state of this Entity.
open Unit
setPose(pose: Pose, relativeTo: Space)

Sets the Pose for this Entity.
open Unit
setScale(scale: @FloatRange(from = 0.0) Float, relativeTo: Space)

Sets the scale of this Entity relative to the given Space.

Public properties
List<Entity>

Provides the list of all children of this entity.
CharSequence

Alternate text for this Entity to be consumed by Accessibility systems.
Entity?

The parent of this Entity, from which this Entity will inherit most of its properties.

Inherited functions
From androidx.xr.scenecore.BaseScenePose
open suspend HitTestResult?
hitTest(origin: Vector3, direction: Vector3)

Perform a hit test from the specified origin in the specified direction into the Scene.
open suspend HitTestResult?
hitTest(origin: Vector3, direction: Vector3, hitTestFilter: Int)

Creates a hit test from the specified origin in the specified direction into the scene.
open Vector3
transformDirectionTo(direction: Vector3, destination: ScenePose)

Transforms a direction from this ScenePose's local space to the destination ScenePose's local space.
open Pose
transformPoseTo(pose: Pose, destination: ScenePose)

Returns a Pose relative to this ScenePose, transformed into a Pose relative to the destination.
open Vector3
transformPositionTo(position: Vector3, destination: ScenePose)

Transforms a position from this ScenePose's local space to the destination ScenePose's local space.
open Vector3
transformVectorTo(vector: Vector3, destination: ScenePose)

Transforms a vector from this ScenePose's local space to the destination ScenePose's local space.

Inherited properties
From androidx.xr.scenecore.BaseScenePose
open Pose

The current Pose relative to the activity space root.

Public companion functions

create

Added in 1.0.0-alpha16
fun create(
    session: Session,
    name: String? = null,
    pose: Pose = Pose.Identity,
    parent: Entity? = null
): Entity

Public factory method for creating an Entity.

Parameters
session: Session

Session to create the Entity in.
name: String? = null

Name of the entity. This is unset by default.
pose: Pose = Pose.Identity

Initial pose of the entity. The default value is Pose.Identity.
parent: Entity? = null

Parent entity. Defaults to null. If null, the entity is created but not attached to the scene graph, meaning it will be invisible. If a parent entity (e.g., ActivitySpace or any other Entity already present in the scene) is assigned later, the entity will become visible (provided it is enabled). This allows for Entity pre-configuration before making it visible.

Public functions

addChild

Added in 1.0.0-alpha16
fun addChild(child: Entity): Unit

Sets an Entity to be a child of this Entity in the scene graph. The child Entity will inherit properties from the parent, and will be represented in the parent's coordinate space. From a user's perspective, as this Entity moves, the child Entity will move with it.

Parameters
child: Entity

The Entity to be attached.

addComponent

Added in 1.0.0-alpha16
fun addComponent(component: Component): Boolean

Adds a Component to this Entity.

Parameters
component: Component

the Component to be added to the Entity.
Returns
Boolean

True if given Component was successfully added to the Entity. This can be false for certain components if an Entity already has a component of that type or does not support the component type.

getAlpha

Added in 1.0.0-alpha16
fun getAlpha(relativeTo: Space = Space.PARENT): @FloatRange(from = 0.0, to = 1.0) Float

Returns the alpha transparency set for this Entity, relative to given Space.

Parameters
relativeTo: Space = Space.PARENT

Gets alpha relative to given Space. Default value is the parent space.

getComponents

Added in 1.0.0-alpha16
fun getComponents(): List<Component>

Retrieves all components attached to this Entity.

Returns
List<Component>

List attached to this Entity.

getComponentsOfType

Added in 1.0.0-alpha16
fun <T : Component> getComponentsOfType(type: Class<T>): List<T>

Retrieves all Components of the given type T and its subtypes attached to this Entity.

Parameters
type: Class<T>

The type of Component to retrieve.
Returns
List<T>

List of the given type attached to this Entity. This list will be empty if no components of the given type are attached to this Entity.

getPose

Added in 1.0.0-alpha16
open fun getPose(relativeTo: Space = Space.PARENT): Pose

Returns the Pose for this Entity, relative to the provided Space.

Parameters
relativeTo: Space = Space.PARENT

Get the Pose relative to given Space. Default value is the parent space.
Returns
Pose

Current Pose of the Entity relative to the given space.

getScale

Added in 1.0.0-alpha16
open fun getScale(relativeTo: Space = Space.PARENT): @FloatRange(from = 0.0) Float

Returns the scale of this entity, relative to given space.

Parameters
relativeTo: Space = Space.PARENT

Get the scale relative to given Space. Default value is the parent space.
Returns
@FloatRange(from = 0.0) Float

Current uniform scale applied to self and children.

isEnabled

Added in 1.0.0-alpha16
fun isEnabled(includeParents: Boolean = true): Boolean

Returns the enabled status of this Entity.

If includeParents is true, the returned value will be false if this Entity or any of its ancestors is disabled. If includeParents is false, the local enabled state is returned. Regardless of the local enabled state, an Entity will be considered disabled if any of its ancestors are disabled.

Parameters
includeParents: Boolean = true

Whether to include the enabled status of parents in the returned value.
Returns
Boolean

True if this Entity is enabled, possibly including the enabled status of its parents.

removeAllComponents

Added in 1.0.0-alpha16
fun removeAllComponents(): Unit

Remove all components from this Entity.

removeComponent

Added in 1.0.0-alpha16
fun removeComponent(component: Component): Unit

Removes the given Component from this Entity.

setAlpha

Added in 1.0.0-alpha16
fun setAlpha(alpha: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Sets the alpha transparency of the Entity relative to the parent Space. Values are in the range 0, 1 with 0 being fully transparent and 1 being fully opaque.

This value will affect the rendering of this Entity's children. Children of this node will have their alpha levels multiplied by this value and any alpha of this Entity's ancestors. As a result, the effective alpha of a child cannot exceed the effective alpha of its parent.

Parameters
alpha: @FloatRange(from = 0.0, to = 1.0) Float

Alpha transparency level for the Entity.

setEnabled

Added in 1.0.0-alpha16
fun setEnabled(enabled: Boolean): Unit

Sets the local enabled state of this Entity.

When false, this Entity and all descendants will not be rendered in the scene, and the Entity will not respond to input events. If an Entity's local enabled state is true, the Entity will still be considered not enabled if at least one of its ancestors is not enabled.

Parameters
enabled: Boolean

The new local enabled state of this Entity.

setPose

Added in 1.0.0-alpha16
open fun setPose(pose: Pose, relativeTo: Space = Space.PARENT): Unit

Sets the Pose for this Entity. The Pose given is set relative to the Space provided.

Parameters
pose: Pose

The Pose offset from the parent.
relativeTo: Space = Space.PARENT

Set the pose relative to given Space. Default value is the parent space.

setScale

Added in 1.0.0-alpha16
open fun setScale(scale: @FloatRange(from = 0.0) Float, relativeTo: Space = Space.PARENT): Unit

Sets the scale of this Entity relative to the given Space. This value will affect the rendering of this Entity's children. As the scale increases, this will uniformly stretch the content of the Entity.

Parameters
scale: @FloatRange(from = 0.0) Float

The uniform scale factor.
relativeTo: Space = Space.PARENT

Set the scale relative to given Space. Default value is the parent Space.

Public properties

children

Added in 1.0.0-alpha16
val children: List<Entity>

Provides the list of all children of this entity. Adding children can be done using addChild or by setting the parent property of the child Entity. To remove a child, set the child's parent property to another Entity or null.

Returns
List<Entity>

List of all children of this entity.

contentDescription

Added in 1.0.0-alpha16
var contentDescription: CharSequence

Alternate text for this Entity to be consumed by Accessibility systems.

parent

Added in 1.0.0-alpha16
var parent: Entity?

The parent of this Entity, from which this Entity will inherit most of its properties. For example, this Entity's Pose is defined in relation to the parent Entity's coordinate space, so as the parent moves, this Entity will move with it. Setting the parent to null will remove the Entity from the scene graph.