Meta Developers

Spatial SDK apps leverage an Entity-Component-System (ECS) design pattern. This design pattern enhances data organization on an entity through components and drives behavior with systems that process this data.

Add components to an object

To add a component to an object:

Select the desired object in the Composition panel or the Viewport.
Note: Adding components from the Object tab is not supported.
Navigate to the Properties panel and click the + button adjacent to Components.
A menu displaying available components will appear. Select the desired component to add it to your object, provided it doesn’t already include that component.

It’s important to remember that adding components from the Object tab is not supported. Attributes such as map attributes, tuple attributes, and entity attributes are not supported either.

Reload components

In the upper right corner of the Component menu, you can see a Reload button that allows you to instantly reload the changes you make in the component XMLs. If you modify component attributes in XML, clicking this button will refresh the list of available components. However, if you change the name of your component, you’ll need to rebuild your app in Android Studio and then click the Reload button.

Built-in components

Spatial Editor includes several predefined components tailored for frequent use cases, which you can add to your objects just like custom components. For built-in components to be available in the Spatial Editor, you need to open and build your project in Android Studio once.

Component name	Description	Properties
Animated	Plays an animation for a glTF asset. Also configures different settings for animation.	pausedTime — Paused location/time (sec) within animation track playbackState — State of the animation (playing or paused) playbackType — The type of animation playback to be used startTime — World time at which animation started (ms since epoch) track — which animation track of the glTF to play
Audio	Plays audio “from” an entity	audioInternal — The Uri String of the audio file to be used volume — Volume of audio
AvatarAttachment	Defines the type of an Avatar the entity is meant to represent.	type — Which part of the avatar the entity is meant to represent (i.e. “head”, “body”, “right_hand”, “left_controller”)
Box	Defines the dimensions of a box shape by the relative offset of two opposite corners. A box with max=Vector3(1,1,1) and min=Vector3(-1,-1,-1) will result in a 2 by 2 by 2 box	max — The relative offset of the top corner of the box from the center min — The relative offset of the bottom corner of the box from the center
Controller	Represents Controller Data and properties that can be used to facilitate input	buttonState — The current state of the buttons being pressed represented by integer bits changedButtons — Which buttons (represented by integer bits) have been changed (pressed or unpressed since the last frame) directTouchButtonState — The state of the direct touch buttons directTouchEnabled — Whether direct touch is enabled for this controller or not type — What type of controller it is. 0 for controller, 1 for hands, 2 for eye.
CreatorVisibility	Use this Component to hide an Entity from every user except for the creator of the Entity or hide the entity from only the creator. This MUST be used with dynamically created Entities. This Component is currently only designed for simple use like having an object or panel that only the creator can see. If you need more complex visibility logic, you will need to write your own Visibility Component and System. Feel free to use this one as a reference.	state — Different states of CreatorVisibility, such as only visible to the creator, or only invisible to the creator
Dome	Defines the dimensions of a dome shape by a radius.	radius — The radius of the dome in meters
Grabbable	Grabbable is a component that allows an object to be grabbed by a controller. It requires the Mesh Component to be present.	enabled — Defines whether the object can be grabbed or not. isGrabbed — Whether the object is currently grabbed or not maxHeight — the maximum height an object can be held when grabbed minHeight — the minimum height an object can be held when grabbed type — The type of behavior an object has when grabbed (faces user, pivots on y axis, etc.)
Hittable	Defines whether an object is hittable or not	hittable — The type of behavior the object can be hit using
Plane	Defines the dimensions of a horizontal plane	depth — The full length of the plane along the z axis width — The full length of the plane along the x axis
Quad	Dimensions for a Quad.	max — The offset of the top right? corner of the quad from the center of the quad min — The offset of the bottom left? corner of the quad from the center of the quad
RoundedBox	Defines the dimensions of a box shape with rounded corners by the relative offset of two opposite corners and a Vector3 of radii to modify the roundedness	max — The relative offset of the top corner of the box from the center min — The relative offset of the bottom corner of the box from the center radius — Vector3 representing the roundedness (follow up on exact modification)
Sphere	Defines the dimensions of a sphere by the radius	radius — The radius of the sphere in meters
SupportsLocomotion	When added to an entity with a mesh, allows for default locomotion on the mesh	N/A
TrackedBody	Maps joints found in BodyJoint to a Pose in world space. If a bone is not present in the map, it means that the tracking is not currently valid for that pose. Will be present locally if the XR_FB_body_tracking is able to be loaded.	jointPoses — This is an experimental attribute and not settable in Cosmo
Visible	Gives the ability to change mesh between being visible and invisible.	isVisible — The Mesh’s current state.

Create custom components

Spatial SDK allows for the creation of custom components, acting as data containers within your application. Once integrated into a Spatial SDK project, these custom components become selectable and applicable to objects via the Properties panel.

While XML is the recommended way to define components, you can still use Kotlin. See the details here, but keep in mind that Kotlin usage is deprecated.

Find out more about the Spatial SDK Gradle extension

Did you find this page helpful?