Connecting Spatial Editor to your project

Updated: Mar 4, 2026

Connect using Spatial SDK Plugin

The Spatial SDK Plugin connects your app to Spatial Editor, the spatial composition tool that helps you set up immersive scenes in Spatial SDK. The plugin registers Gradle tasks that streamline your development workflow. This page covers the export task.

Apply the plugin

In the [versions] block of the gradle/libs.versions.toml file, add this code to create a variable for the Spatial SDK version.

 spatialsdk = "0.10.1"

All Spatial SDK dependencies reference this variable. Update all versions by changing this single line when new releases become available.

In the [plugins] block, add this code to apply the Spatial SDK Plugin.

 meta-spatial-plugin = { id = "com.meta.spatial.plugin", version.ref = "spatialsdk" }

In app/build.gradle.kts, apply the Spatial SDK plugin.

 plugins {
     alias(libs.plugins.meta.spatial.plugin)
 }

Using the export task

The export task uses the Spatial Editor CLI to export your Spatial Editor project to glXF format compositions for your Spatial SDK app. These glXF files can be inflated into a Spatial SDK app to create a scene.

You can add export configuration to your app-level build.gradle.kts file. You can export the entire project or individual compositions and objects. Define which metaspatial file to export and its destination in the assets directory.

You can also set a custom path to the Spatial Editor CLI. The export task uses a default location if you don’t specify one.

Setting up exports

The configuration below demonstrates three common export scenarios:

Full project export: Exports your entire Spatial Editor project, including all compositions and objects, to a single destination folder. This is the most common setup for simple projects.

Composition-specific export: Exports only a specific composition and its dependencies. Use this when you want to modularize your assets or only include certain parts of your project.

Individual object export: Exports just a single object. This is useful for reusable assets that you want to place in specific locations within your app’s asset structure.

Each export item defines a projectPath (your main .metaspatial file) and an outputPath (where the exported assets go in your app). The optional compositionPath and spatialEditorObjectPath parameters allow you to target specific parts of your project for export.

val projectDir = layout.projectDirectory
val sceneDirectory = projectDir.dir("scenes")
spatial {
  scenes {
    // If Meta Spatial Editor is installed in a non-default location, set the CLI path:
    // Mac:
    // cliPath.set("/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI")
    // Windows:
    // cliPath.set("C:/Program Files/Meta Spatial Editor/v8/Resources/CLI.exe")
    exportItems {
        // Export your entire project, including all compositions and objects
        item {
            projectPath.set(sceneDirectory.file("Main.metaspatial"))
            outputPath.set(projectDir.dir("src/main/assets/scenes"))
        }
        // Export only a specific composition and its contents
        item {
            projectPath.set(sceneDirectory.file("Main.metaspatial"))
            outputPath.set(projectDir.dir("src/main/assets/composition/comp"))
            compositionPath.set(sceneDirectory.file("Comp1/Main.metaspatialcomp"))
        }
        // Export only a specific object
        item {
            projectPath.set(sceneDirectory.file("Main.metaspatial"))
            outputPath.set(projectDir.dir("src/main/assets/obj1"))
            spatialEditorObjectPath.set(sceneDirectory.file("duck/Main.metaspatialobj"))
        }
    }
  }
}

Running the export task

Once you have the export task set up, you can run it like any other Gradle task.

Android Studio Gradle panel showing export task location under spatial tasks

If you’re unable to locate them, ensure that Settings > Experimental > Gradle > Configure all Gradle tasks during Gradle Sync is enabled in your Android Studio settings.

Android Studio Settings dialog showing Experimental Gradle option to configure all Gradle tasks during sync

Automated exporting

The export task can be run automatically during the app build process.

Working with components in exported scenes

When the export task converts your Spatial Editor project to glXF format, it exports more than just 3D models and materials. It also preserves component data that defines object behavior and properties. Components are what transform static 3D assets into interactive, functional objects in your Spatial SDK app.

For example, a sphere in Spatial Editor might have a Grabbable component that makes it pickable, or a Visible component that controls whether it appears in the scene. These components become part of the exported glXF file and are automatically applied to entities when you inflate the scene in your app.

Understanding how to work with components is essential for creating dynamic experiences, as they bridge the gap between what you design visually in Spatial Editor and what you control programmatically in your Spatial SDK code.

Using components in Spatial Editor

Spatial Editor includes built-in components from the Spatial SDK toolkit. Components are the data containers in Spatial SDK’s Entity-Component-System (ECS) architecture. They store all the information that defines what your spatial objects are and what properties they have. You can also define additional components using XML.

Define components in XML

Add a component XML file in app/src/main/components. The Spatial Editor will read the XML defined in the folder and display your custom components in UI. If you prefer to use another directory, refer to Specify the custom components folder.

Using components in Spatial Editor

Open your Spatial Editor project file in Spatial Editor. Select the object that you want to add a component to. All available components from your app appear when you add a component.

Spatial Editor Properties panel with Add Component dialog showing custom LookAt component option

Learn more about using components in Spatial Editor.

Next steps

Set up hot reload to see changes from Spatial Editor instantly in your headset without rebuilding your app.

(Removed) Define components in Kotlin

:::caution The generateComponents Gradle task was removed in v0.10.1. Component generation from XML definitions is now automatic at build time. If you are using SDK v0.10.1 or later, you do not need to configure or run any component generation tasks. :::

For SDK versions prior to 0.10.1, XML was the recommended method for defining components since v0.5.5. The generateComponents task was used for Kotlin-defined components but is no longer available.

Did you find this page helpful?