Create custom systems

• A basic understanding of Entity-Component-System (ECS) architecture and systems.
• The LookAt component defined in your project (see Creating custom components).
• Meta Horizon Android Studio plugin.

• Implement unique gameplay mechanics
• Create custom animations or transitions
• Process user input in specialized ways
• Optimize performance for specific use cases

• target: Entity - The entity to look at (alternative to lookAtHead)
• lookAtHead: Boolean - Whether to look at the viewer’s head (default: false)

• Component queries: How to find entities that have specific components.
• Transform manipulation: How to modify object rotations in 3D space using quaternions.
• Component lifecycle: The pattern of read → process → write that most systems follow.
• Look-at mathematics: How to calculate rotations to face targets using quaternion operations.

1. Right-click on \app\src\main\java\your\project\folder.
2. Select New > File.
3. Create a new Kotlin file named LookAtSystem.kt.

class CustomSystem : SystemBase() {

    override fun execute() {
        // System logic executes every frame

    }
}

• Always extend SystemBase from com.meta.spatial.core.SystemBase.
• Import all necessary components and utilities.
• Use proper package naming conventions.
• Override the execute() method for frame-by-frame logic.

import com.meta.spatial.core.Pose
import com.meta.spatial.core.Quaternion
import com.meta.spatial.core.Query
import com.meta.spatial.core.SystemBase
import com.meta.spatial.toolkit.Transform

class LookAtSystem : SystemBase() {
    override fun execute() {
        // 1. Query: Find entities that need to look at something
        val query = Query.where { has(LookAt.id, Transform.id) }

        // 2. Process: Calculate new rotation for each entity
        for (entity in query.eval()) {
            val lookAt = entity.getComponent<LookAt>()
            val transform = entity.getComponent<Transform>()

            // Get target position (could be head or another entity)
            var targetPose: Pose = if (lookAt.lookAtHead) {
                getScene()!!.getViewerPose()
            } else {
                lookAt.target.getComponent<Transform>().transform
            }

            // Calculate rotation to look toward target
            var eyePose: Pose = transform.transform
            val direction = (targetPose.t - eyePose.t)
            val newRotation = Quaternion.lookRotation(direction)

            // Note: This calculation creates a vector pointing toward the target.
            // Use rotational offsets (like Vector3(0f, 180f, 0f)) to achieve the desired facing direction.
            // See CustomComponentsSample for examples of using offsets to control final orientation.

            // Apply the new rotation
            eyePose.q = newRotation

            // 3. Update: Save changes back to entity
            entity.setComponent(Transform(eyePose))
        }
    }
}

• Query pattern: Uses Query.where { has(LookAt.id, Transform.id) } to find all entities with both components needed for look-at behavior.
• Component retrieval: Gets the current LookAt and Transform components from each entity using getComponent<ComponentType>().
• Target determination: Chooses between looking at the viewer’s head (getScene()!!.getViewerPose()) or another entity (lookAt.target.getComponent<Transform>().transform).
• Direction calculation: Computes the direction vector by subtracting target position from entity position: (eyePose.t - targetPose.t). This creates a vector pointing away from the target, which is why rotational offsets are often needed.
• Rotation calculation: Uses Quaternion.lookRotation(direction) to convert the direction vector into a rotation quaternion.
• Transform update: Saves the new rotation back to the entity with entity.setComponent(Transform(eyePose)).

class MainActivity : AppSystemActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Register custom components
        componentManager.registerComponent<LookAt>(LookAt.Companion)

        // Register custom systems
        systemManager.registerSystem(LookAtSystem())

    }
}

1. Register components first.
2. Register systems second.
3. Load and setup scenes last.

• Smooth rotation: Uses interpolation for natural movement instead of instant snapping
• Axis constraints: Can restrict rotation to specific axes (like Y-axis only for characters)
• Rotation offsets: Applies directional corrections to achieve proper facing orientation
• Speed control: Configurable rotation speed for different entity types

• Queries
• SpatialFeatures