Develop
Develop
Select your platform
Attributes
Updated: Feb 7, 2025
Overview
Attributes are at the core of Spatial SDK’s data model. They represent serializable data units that can be stored and used inside of your components.
A component can contain many attributes. For example, the
Grabbable component contains:<BooleanAttribute
name="enabled"
defaultValue="true"
description="Defines whether the object can be grabbed or not."
/>
<EnumAttribute
name="type"
defaultValue="GrabbableType.FACE"
description="The type of behavior an object has when grabbed (faces user, pivots on y axis, etc.)"
/>
<BooleanAttribute
name="isGrabbed"
defaultValue="false"
description="Whether the object is currently grabbed or not"
/>
<FloatAttribute
name="minHeight"
defaultValue="-Float.MAX_VALUE"
description="the minimum height an object can be held when grabbed"
/>
<FloatAttribute
name="maxHeight"
defaultValue="Float.MAX_VALUE"
description="the maximum height an object can be held when grabbed"
/>
The build process will generate Kotlin code and Android resources based on the XML inputs.
Supported attributes
Spatial SDK currently support 13 attributes:
BooleanAttributeEntityAttributeEnumAttributeExperimentalMapAttributeFloatAttributeIntAttributeLongAttributePoseAttributeTimeAttributeUUIDAttributeVector2AttributeVector3AttributeVector4Attribute
Some attributes are self-explanatory by name. For example,
IntAttribute is a 32 bit integer. Other attributes require more explanation. This document describes the available attributes one-by-one.EntityAttributeEntityAttribute represents a reference to another entity in Spatial SDK’s ECS. The Entity is represented by a long integer under-the-hood and is recontructed on creation for use. All entity attribute will have a default value of Entity.nullEntity().<EntityAttribute name="target" description="Target Entity to follow" />
EnumAttributeYou must specify a valid Kotlin enum value to the
defaultValue XML property of EnumAttribute. The enum value can be defined in XML or Kotlin.<Enum
name="GrabbableType"
description="GrabbableType is an enum that defines the type of behavior an object has when grabbed. "
>
<EnumValue
value="FACE"
description="The object faces the user when grabbed."
/>
<EnumValue
value="PIVOT_Y"
description="The object will be pivoted in Y dimension."
/>
</Enum>
<Component name="Grabbable">
<EnumAttribute
name="type"
defaultValue="GrabbableType.FACE"
description="The type of behavior an object has when grabbed (faces user, pivots on y axis, etc.)"
/>
</Component>
Enum attributes can be set and retrieved as the enums they represent. Here is an example:
Grabbable(type = GrabbableType.PIVOT_Y ...
ExperimentalMapAttribute<ExperimentalMapAttribute name="lines" keyType="Int" valueType="Vector3" description="Represents the lines on a whiteboard" />
ExperimentalMapAttribute is a Kotlin map with a limited API. Currently our maps support get, set, contains, and remove.Valid key types include
Int, Long, and String. Valid value types include Int, Long, Float, String, UUID, Vector2, Vector3, Vector4, Quaternion, and Pose.ExperimentalMapAttribute supports about 30 elements (depending on your app load) before performance slows. If you need to improve performance, APIs are available on the entity for direct data access and modification. inline fun <reified T, reified V> getMap(attribute: Int): HashMap<T, V>
inline fun <reified T, reified V> tryGetMapValue(attribute: Int, key: T): V?
inline fun <reified T, reified V> trySetMapValue(attribute: Int, key: T, value: T): Boolean
fun setMap(attribute: Int, value: HashMap<*, *>)
fun addToMap(attribute: Int, value: HashMap<*, *>)
FloatAttribute, BooleanAttribute, IntAttribute, LongAttributeThese are all native Kotlin objects. The names all indicate the types you you can expect:
Float, Boolean, Int, Long.<FloatAttribute
name="tolerance"
defaultValue=".2f"
description="This is the change in distance needed to start moving"
/>
<BooleanAttribute
name="active"
defaultValue="true"
description="Whether entity is actively following or not"
/>
<IntAttribute
name="track"
defaultValue="0"
description="which animation track of the glTF to play"
/>
<LongAttribute
name="startTime"
defaultValue="-1L"
description="World time at which animation started (ms since epoch)"
/>
FloatAttribute
You have to set a valid Kotlin float value to the
defaultValue property of a FloatAttribute. In Kotlin, 1.1 is a Double, not a Float. If no defaultValue is specified, it will fall back to 0.0f.<FloatAttribute name="floatAttr" defaultValue="-.1f" />
<FloatAttribute name="floatAttr1" description="no defaultValue provided, this attribute will have a default value of 0.0f" />
IntAttribute
You have to set a valid Kotlin Int value to the
defaultValue property of an IntAttribute. If no defaultValue is specified, it will fall back to 0.<IntAttribute name="intAttr" defaultValue="1" />
<IntAttribute name="intAttr1" description="no defaultValue provided, this attribute will have a default value of 0" />
LongAttribute
You have to set a valid Kotlin Long value to the
defaultValue property of a LongAttribute. If no defaultValue is specified, it will fall back to 0L.<LongAttribute name="longAttr" defaultValue="1L" />
<LongAttribute name="longAttr1" description="no defaultValue provided, this attribute will have a default value of 0L" />
PoseAttributePoseAttribute is a commonly used attribute to represent a 3D position and orientation. The transform component only has one attribute, a pose. These are stored and created as Spatial SDK poses (com.meta.spatial.core.Pose).<PoseAttribute name="transform" description="Represents the position and orientation of an object" />
For a
PoseAttribute, you must specify a valid pose as the defaultValue. A pose contains position and orientation data.<PoseAttribute name="poseAttr" defaultValue="1f,2f,3f,4f,5f,6f,7f" />
As shown above, the first three floats,
1f,2f,3f, represent the position of a pose in the form of a Vector3. The the last four digits, 4f,5f,6f,7f, represent the orientation in the form of a quaternion. If no defaultValue is specified, it will fall back to 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f.UUIDAttributeUUIDAttribute can be used to store a Java UUID (java.util.UUID). UUIDs are 128 bit data stores that are commonly used for database keys, transaction ids, and more.For a
UUIDAttribute, you can provide a valid UUID string as the defaultValue. If no defaultValue is provided, a random UUID will be used.<UUIDAttribute name="uuidAttr" defaultValue="123e4567-e89b-12d3-a456-426614174000" />
You can also specify the most significant bit (MSB) and the least significant bit (LSB) of a UUID.
<UUIDAttribute name="uuidAttr" defaultValue="-2, 1L" />
The above
UUIDAttribute has a UUID default value of java.util.UUID(-2L, 1L).Vector2Attribute, Vector3Attribute, Vector4AttributeThese store Spatial SDK’s
Vector2Attribute, Vector3Attribute, and Vector4Attribute (com.meta.spatial.core.VectorNAttribute). The API documentation provides details on these types, including built-in functions for multiplication and addition.<Vector2Attribute
name="dimensions"
defaultValue="0.75f, 1.0f"
description="used to store the panel dimensions" />
<Vector3Attribute
name="followOffset"
defaultValue="0f, 0f, 0f"
description="used to define the location that the followable tracks to" />
/** */
<Vector4Attribute
name="baseColorInternal"
defaultValue=".5f, .5f, .5f, 1.0f"
description="holds material base colors, accessed through a getter" />
Vector2Attribute
The
defaultValue for a Vector2Attribute should be a pair of float values representing a 2D vector. If you don’t set the defaultValue, it will fall back to 0.0f, 0.0f.<Vector2Attribute name="vector2Attr" defaultValue="0.1f,0.0f" />
Vector3Attribute
For a
Vector3Attribute, the defaultValue should be three float values representing a 3D vector. If you don’t set the defaultValue, it will fall back to 0.0f,0.0f,0.0f.<Vector3Attribute name="vector3Attr" defaultValue="0.0f,0.0f,1.0f" />
Vector4Attribute
The
defaultValue for a Vector4Attribute must be four float values representing a 4D vector. If you don’t set the defaultValue, it will fall back to 0.0f,0.0f,0.0f,0.0f.<Vector4Attribute name="vector4Attr" defaultValue="0.0f,0.0f,0.0f,1.0f" />
Did you find this page helpful?
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
English (US)
© 2025 Meta