Develop

Select your platform

Connecting Spatial Editor to your project

Updated: Sep 17, 2025

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 and generateComponents tasks.

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.9.2"

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 you have installed Meta Spatial Editor somewhere else, update the file path.
    // FOR MAC: cliPath.set("/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI")
    // FOR WINDOWS: cliPath.set("C:/Program Files/Meta Spatial Editor/v8/Resources/CLI.exe")
    exportItems {
        // This item exports your entire project
        item {
            projectPath.set(sceneDirectory.file("Main.metaspatial"))
            outputPath.set(projectDir.dir("src/main/assets/scenes"))
        }
        // This item only exports the given composition and its contained compositions
        // and objects
        item {
            projectPath.set(sceneDirectory.file("Main.metaspatial"))
            outputPath.set(projectDir.dir("src/main/assets/composition/comp"))
            compositionPath.set(sceneDirectory.file("Comp1/Main.metaspatialcomp"))
        }
        // This item only exports the given 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.

(Deprecated) Define components in Kotlin

XML is the recommended method for defining components on Spatial SDK version 0.5.5+. However, you can still use Kotlin by running the generateComponents task. This task generates a JSON file with component information for your app. Place this JSON file next to your main metaspatial file.

Note: Certain attributes such as Entity and ExperimentalMap are not currently supported in the Spatial Editor.

Start by setting up the config needed to run the generateComponents task.

Set up `generateComponents` task

Next you need to set up the config. You need to define where our Spatial Editor project is and where our custom components are stored.

Here’s an example:

val projectDir = layout.projectDirectory
val sceneDirectory = projectDir.dir("scenes")
spatial {
    allowUsageDataCollection.set(true)
    scenes {
        componentGeneration {
            outputPath.set(sceneDirectory)
            // We attempt to auto-detect where your "custom_components.json" is placed but if this does
            // not work then you can uncomment the following line and force it to a specific location.
            // customComponentsPath.set(projectDir.dir("build/generated/ksp/debug/resources"))
        }
    }
}

Running the `generateComponents` task

Now that you have the generateComponents task set up, you can run it like any Gradle task.

Android Studio Gradle panel with `generateComponents` task highlighted under spatial tasks

You can make the generateComponents task run automatically after your build by adding this code to app/build.gradle.kts.

afterEvaluate {
    tasks.named("assembleDebug") {
        finalizedBy("generateComponents")
    }
}

You can replace assembleDebug with whichever task you’re using to build your app. This will make it so that the generateComponents task runs anytime you build your app.

Did you find this page helpful?