Components in Spatial SDK

Updated: Sep 15, 2025

Overview

Components are data containers in Spatial SDK’s Entity-Component-System (ECS) architecture. They define what your spatial objects are and what properties they have.

For an overview of how components fit into the broader ECS architecture, see Entity-Component-System (ECS).

What components do

In spatial applications, your entities need to track different types of information:

Positional data: Where is this object in 3D space? How is it oriented?

Visual properties: What does it look like? What color is it? Does it have a texture?

Interactive state: Can users grab it? Is it currently selected? Is a button being pressed?

Behavioral data: How fast does it move? What sound does it make? Who is it following?

Instead of storing everything in single entities, components organize data by purpose. A Transform component handles position and rotation. A Material component manages appearance. This separation makes your code modular, testable, and reusable.

Component lifecycle and purpose

Components have a simple lifecycle:

Creation: Components start with default values when entities are created.

Use by systems: Systems read and update component data during your application.

Cleanup: Components are automatically removed when entities are destroyed.

Example: `UpAndDown` component

Here’s a simple component from the PhysicsSample that demonstrates these concepts:

<?xml version="1.0" ?>
<ComponentSchema packageName="com.meta.spatial.samples.physicssample">
  <Component name="UpAndDown">
    <Description>
A Component that stores data for up-and-down animation.
    </Description>
    <FloatAttribute name="amount" defaultValue="0.1f" />
    <FloatAttribute name="speed" defaultValue="0.5f" />
    <FloatAttribute name="offset" defaultValue="0.0f" />
    <Vector3Attribute name="startPosition" defaultValue="0f, 0f, 0f" />
  </Component>
</ComponentSchema>

This component demonstrates:

Single responsibility: It stores only up-and-down animation data, nothing else.

Meaningful names: UpAndDown clearly describes the data it contains, and attributes like amount and speed are self-explanatory.

Right attribute types: Uses FloatAttribute for numbers like speed and Vector3Attribute for the 3D position.

Good defaults: Objects start with sensible animation values.

When attached to an entity, this component gives it the data needed for smooth up-and-down motion. A corresponding system reads these values and updates the entity’s position over time.

Component design fundamentals

Understanding the core principles behind effective component design helps you create maintainable, reusable components that work with Spatial SDK’s systems. This section covers essential design patterns and implementation strategies.

Key design principles

Components follow two essential principles:

Components store data, not behavior: The UpAndDown component stores animation values like speed and amount, but it doesn’t contain the animation logic. That logic lives in systems that read the component data.

Build complex objects from simple components: Want a moving, grabbable object? Combine Transform, UpAndDown, and Grabbable components on the same entity rather than creating one complex component.

Attribute types as building blocks

Components store data using strongly-typed attributes. Common types are:

IntAttribute - Whole numbers (health points, score, count)

StringAttribute - Text data (names, descriptions, URLs)

BooleanAttribute - True/false values (visible, enabled, active)

Vector3Attribute - 3D coordinates (position, velocity, direction)

These four types handle most common use cases. Choose the right type for type safety. Physics systems expect Vector3Attribute for velocity, UI systems expect StringAttribute for displayed text.

Common component patterns

Most components fall into two main categories:

Changing data: Health, score, position - values that systems update frequently during gameplay. Like the UpAndDown component’s offset that changes as the object moves.

Configuration data: Movement speed, maximum health, colors - settings that rarely change but control how systems behave. Like the UpAndDown component’s amount and speed that control the animation style.

Best practices and implementation

When creating your first components, keep them simple and focused:

Start small: Create components that handle just one thing well. A Health component should only track health-related data, not also handle movement or appearance.

Choose meaningful names: Use clear, descriptive names that make it obvious what data the component stores. PlayerScore is better than GameData.

Pick the right attribute type: Use IntAttribute for numbers, StringAttribute for text, BooleanAttribute for true/false values, and Vector3Attribute for positions.

As you gain experience, you can explore more advanced considerations like performance optimization and complex relationships between components.

Now that you understand component design principles and implementation patterns, you can:

Analyze your spatial application’s data needs: What information do your objects need to store? How does this data change over time?

Design focused components: Break complex data into single-responsibility components that systems can query efficiently.

Implement with appropriate attribute types: Choose attribute types that match your data’s semantics and usage patterns.

Test component lifecycle: Verify that your components work correctly during creation, modification, and cleanup.

Integrate with systems: Design components that provide the data your systems need to implement application logic.