Create a new Spatial SDK app

Updated: Feb 18, 2025

By the end of this tutorial, you’ll have created a new Spatial SDK app and previewed it on your headset. Creating a new Spatial SDK app is the quickest way to get started with the SDK. You aren’t constrained by the structure of an existing codebase.

If you’d rather add Spatial SDK to an existing 2D Android app, see Add Spatial SDK to an existing 2D app.

Preview the app on Meta Quest

For brand new projects, project templates are the fastest way to get started, but this tutorial uses the CustomComponentsStarter sample as the foundation of your new app to provide some structure and custom scripts. To download and preview the CustomComponentsStarter sample, follow these steps.

Download the Meta Spatial SDK Samples⁠ zipped folder from GitHub.

Once the folder is downloaded, right-click on the folder and extract all files.

In Android Studio, in the CodelabStarters folder, open the CustomComponentsStarter project.

Gradle will begin building, indicated by the progress bar in the lower-right corner of Android Studio.

If a Trust and Open Project window appears, select Trust Project.

In your headset, ensure you are on your home screen.

Once Gradle has finished building, in the Android Studio toolbar, click the green Run ‘app’ button.

Once the starter app has finished building, it will launch automatically on your headset. It should look like this.

(Optional) Explore the Spatial SDK app directories

In Android Studio, familiarize yourself with the structure of the Spatial SDK app to effectively navigate and utilize its features.

App directory:

app/src/main/java: Contains source files for the Spatial SDK or immersive application.

app/scenes: Contains the Main.metaspatial file, 3D models, and textures.

app/scenes/Composition: Includes the Main.metaspatialcomp file, the main composition file.

Gradle directory: Configuration has been pre-set for you.

Note: If your project directory doesn’t match the file paths listed above, make sure the drop-down at the top of the directory is set to Project.

(Optional) Open the composition in Spatial Editor

Spatial SDK stores information about a scene’s 2D and 3D objects and their associated audio, materials, and components in a composition file. To edit a composition file, you open it in the Meta Spatial Editor.

In the Android Studio file hierarchy, open the Main.metaspatial file.

Right-click the file.

Select either Open In > Finder (for Mac), or Open In > Explorer (for Windows).

Double-click the file to open it in Spatial Editor.