Template project walkthrough

• 3D scene composition: Unlike mobile apps that work on flat screens, spatial apps exist in three-dimensional space around users. You need to understand how to create environments that feel natural and comfortable.
• Asset management: 3D assets are more complex than images - they have geometry, materials, animations, and physics. Understanding how to efficiently load and manage these assets is crucial for app performance.
• Panel integration: Users still need familiar UI elements (buttons, text, videos), but now these can float in 3D space or attach to surfaces. This is your bridge between traditional app development and spatial experiences.
• VR features: Your app’s virtual content can understand and respond to the real world. Imagine apps that can place virtual furniture in real rooms or overlay information on real objects.

• Install Android Studio⁠ so you can develop and launch Android applications.
• Install Spatial SDK’s Android Studio Plugin⁠.
• Install Meta Spatial Editor for either Windows or Mac, which already includes the CLI needed to export projects.
• Install Meta Quest Developer Hub.
• A Meta Quest device (Quest 2, Quest Pro, or Quest 3) for testing.

1. On your mobile device, open the Meta Horizon app.
2. In the app, tap the headset icon in the toolbar.
   
3. Your paired headset should appear at the top of the screen. Tap the headset item, which displays the model and status of your paired headset.
   
4. Tap Headset Settings beneath the image of your headset.
   
5. Tap Developer Mode.
   
6. Toggle Developer Mode to the on position.
   
7. Use a USB-C data cable to connect the headset to your computer.
8. Put on the headset.
9. In the headset, open the Quick Control menu item.
10. Select Open Settings, displayed as a gear icon. Then, open the Developer tab and toggle MTP Notification on.
11. When asked to allow USB debugging, select Always allow from this computer.
    

• Basic knowledge of Android development⁠ and Kotlin⁠.
• Activity lifecycle in Android⁠.
• Jetpack Compose⁠ basics (for panel UI).
• 3D coordinate systems⁠ and transforms⁠.

1. The environment: Your 3D environment (like a stage or room)
2. Objects: 3D models, interactive elements (like props on the stage)
3. UIs: Traditional interfaces that float in 3D space (like holographic screens)
4. The user: Hand tracking, gaze, controller input (how users interact)

• Depth: Objects can be near or far from the user
• Scale: A button might be small up close or too large far away
• Comfort: Users move their heads, so your app needs to respond appropriately

Project/
├── app/
│   ├── build.gradle.kts                # Build configuration with Spatial SDK
│   ├── scenes/                         # Meta Spatial Editor project files
│   │   ├── Main.metaspatial            # Main scene project
│   │   ├── Composition/                # Exported scene composition
│   │   └── environment/                # 3D assets (models, textures, materials)
│   └── src/main/
│       ├── AndroidManifest.xml         # VR app permissions & configuration
│       ├── assets/                     # Runtime assets (IBL, licenses)
│       ├── java/.../                   # Kotlin source code
│       │   ├── ImmersiveActivity.kt    # Main VR activity
│       │   └── PanelActivity.kt        # Compose-based panel
│       └── res/                        # Android resources (layouts, drawables)
├── gradle/
│   └── libs.versions.toml              # Dependency versions
└── build.gradle.kts                    # Project-level build configuration

• Contains your spatial scenes.
• Use Meta Spatial Editor for drag-and-drop 3D scene composition, real-time preview, and automatic optimization.
• .metaspatial files are the project files for your spatial scenes.
• Composition/ contains the exported, optimized data your app actually loads.
• environment/ holds all your 3D assets organized by type.

• Contains your app’s Kotlin source code.
• In Spatial SDK, you manage immersive 3D environments and spatial interactions instead of activities and fragments.
• ImmersiveActivity.kt: Your main function for VR. It sets up the 3D environment, manages user positioning, and handles spatial experiences.
• PanelActivity.kt: Familiar Android UI development, but these UIs now float in 3D space as panels.

• Contains your app’s runtime assets like shaders and textures.
• 3D environments need lighting, textures, and environmental effects that don’t exist in 2D mobile apps.
• environment.env: Image-based lighting files that make your 3D content look realistic by simulating how light bounces in real environments.

• Contains your app’s permissions and capabilities.
• VR apps need access to cameras (for Passthrough), hand tracking, spatial positioning, and other sensors that regular mobile apps don’t use.
• This is where you enable features like hand tracking, mixed reality features, and spatial audio.
• Immersive activities must declare android:configChanges to prevent activity restarts during device configuration changes. For details, see Handling configuration changes.

• meta-spatial-sdk: The foundation package required by all spatial apps.
• meta-spatial-sdk-vr: Adds VR-specific features essential for immersive experiences.
• meta-spatial-sdk-toolkit: Pre-built components and systems for common spatial app needs like lighting, audio, and user interactions.

// Main VR Activity - manages the immersive 3D environment
class ImmersiveActivity : AppSystemActivity() {
    // Registers VR features and manages the 3D scene
    override fun registerFeatures(): List<SpatialFeature>
    override fun onSceneReady()
    override fun registerPanels(): List<PanelRegistration>
}

// Panel Activity - manages panels and UIs within the immersive world
class PanelActivity : ComponentActivity() {
    // Uses Jetpack Compose for rich 2D UI
    override fun onCreate(savedInstanceState: Bundle?)
}

• Separation of concerns: 3D environment logic stays separate from UI logic.
• Familiar tools: You can use Jetpack Compose for UI while learning spatial concepts.
• Gradual adoption: Existing Android developers can focus on spatial-specific concepts first.

• Pre-configured project structure with scenes/ directory.
• Build pipeline that exports your Spatial Editor project to optimized runtime assets.
• Example code showing how to load these exported scenes.

1. Open app/scenes/Main.metaspatial in Meta Spatial Editor.
2. Follow the Connecting Spatial Editor to your project guide for complete setup and export configuration.
3. Set up hot reload to see changes instantly in your headset.

private fun loadGLXF(): Job {
    gltfxEntity = Entity.create()
    return activityScope.launch {
        glXFManager.inflateGLXF(
            Uri.parse("apk:///scenes/Composition.glxf"),   // Your exported scene
            rootEntity = gltfxEntity!!,                    // Where to attach it
            keyName = "example_key_name"                   // Reference name for later
        )
    }
}

• URI: Points to your exported scene file (automatically created by the build pipeline).
• rootEntity: The “parent” object that contains your entire scene.
• keyName: A name you can use later to find specific objects in the scene.

// Create a skybox entity - demonstrates entity creation with multiple components
val skyboxEntity = Entity.create(
    listOf(
        Mesh(Uri.parse("mesh://skybox")),     // Geometry component
        Material().apply {                     // Material component
            baseTextureAndroidResourceId = R.drawable.skydome
            unlit = true  // Template shows shader overrides
        },
        Transform(Pose(Vector3(0f, 0f, 0f)))  // Position component
    )
)

1. Start with the template and get it running.
2. Modify the 3D scene in Meta Spatial Editor.
3. Add your UI panels using familiar Compose patterns.
4. Implement interactions and business logic.
5. Optimize performance and comfort.

• Hot reload: See changes instantly without rebuilding.
• Data Model Inspector: Debug ECS component states in real-time.
• OVRMetrics: Monitor performance metrics.
• Input forwarding: Test with desktop mouse/keyboard.

• Spatial SDK Architecture
• Spatial SDK activity lifecycle
• Entity-Component-System (ECS)
• Components in Spatial SDK
• Systems in Spatial SDK
• Use queries to access entities

• Adding Interactions: See Object3DSample⁠ for grabbable objects.
• Mixed Reality Features: Check MixedRealitySample⁠ for Passthrough.
• Physics: Explore PhysicsSample⁠ for realistic object behavior.
• Animation: Try AnimationsSample⁠ for moving objects.
• Media: Look at MediaPlayerSample⁠ for videos in 3D space.