Develop
Develop
Select your platform

Attributes

Updated: May 22, 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 supports the following attributes:
- `BooleanAttribute`
- `Color4Attribute`
- `EntityAttribute`
- `EnumAttribute`
- `ExperimentalMapAttribute`
- `FloatAttribute`
- `IntAttribute`
- `LongAttribute`
- `PoseAttribute`
- `TimeAttribute`
- `UUIDAttribute`
- `URIAttribute`
- `Vector2Attribute`
- `Vector3Attribute`
- `Vector4Attribute`
Some attributes are self-explanatory by name. For example, IntAttribute is a 32 bit integer. Other attributes require more explanation. Every attribute is described below.

Color4Attribute

Color4Attribute can be used to store colors. You can use either a hex string or a comma-separated list of four floats(r, g, b, a) to define the color.
<Color4Attribute name="color" defaultValue="1.0f, 0.0f, 0.0f, 1.0f" />
<Color4Attribute name="colorHex" defaultValue="#112233FF" />

EntityAttribute

EntityAttribute 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" />

EnumAttribute

You 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. (Note: UUID, Pose and Quaternion are not supported by the Spatial Editor to display and edit.)
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, LongAttribute

These 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.
You can also specify a range for the FloatAttribute using the Constraints tag. The Min and Max tags are required. The Min tag must be less than or equal to the Max tag.
<FloatAttribute name="floatAttr" defaultValue="-.1f" />
<FloatAttribute name="floatAttr1" description="no defaultValue provided, this attribute will have a default value of 0.0f" />
<FloatAttribute name="floatAttrWithRange" defaultValue="0.0f">
  <Constraints>
    <Min>-10.0f</Min>
    <Max>10.0f</Max>
  </Constraints>
</FloatAttribute>

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.
You can also specify a range for the IntAttribute using the Constraints tag. The Min and Max tags are required. The Min tag must be less than or equal to the Max tag.
<IntAttribute name="intAttr" defaultValue="1" />
<IntAttribute name="intAttr1" description="no defaultValue provided, this attribute will have a default value of 0" />
<IntAttribute name="intAttrWithRange" defaultValue="0">
  <Constraints>
    <Min>-10</Min>
    <Max>10</Max>
  </Constraints>
</IntAttribute>

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.
You can also specify a range for the LongAttribute using the Constraints tag. The Min and Max tags are required. The Min tag must be less than or equal to the Max tag.
<LongAttribute name="longAttr" defaultValue="1L" />
<LongAttribute name="longAttr1" description="no defaultValue provided, this attribute will have a default value of 0L" />
<LongAttribute name="LongAttrRange" defaultValue="100">
  <Constraints>
    <Min>-10</Min>
    <Max>10</Max>
  </Constraints>
</LongAttribute>

PoseAttribute

PoseAttribute 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.

UUIDAttribute

UUIDAttribute 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).

URIAttribute

URIAttribute can be used to store a URI (android.net.Uri). A URI is a string that represents a resource. The given URI must be a valid URI otherwise Spatial SDK project build will fail with an IllegalArgumentException.
<URIAttribute name="uriAttr" defaultValue="http://www.meta.com" description="URI attribute"/>

Vector2Attribute, Vector3Attribute, Vector4Attribute

These 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?
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2026 Meta