2D panels in Spatial SDK

Updated: Sep 30, 2025

Overview

Spatial SDK lets you use any Android UI framework to create 2D UIs, then create a panel for them in your 3D scene. Spatial SDK handles rendering and input handling, allowing you to focus on creating UIs.

Here is an example of panels in the video player sample app:

New developers should explore design guidelines. These guidelines ensure your application is immersive and accessible.

Understanding panels

Think of panels as Android UIs that exist as objects in your scene. A panel displays your Android UI like a physical computer monitor displays your desktop. Instead of sitting on a desk, it can float in mid-air, attach to walls, or move around to follow a user.

Panels solve a fundamental challenge: bringing familiar Android UI development into immersive 3D experiences. Rather than rebuilding everything from scratch in 3D, panels let you:

Leverage existing skills: Use the Android development knowledge you already have

Maintain familiar interactions: Buttons, lists, and forms work as users expect

Present complex information clearly: Text, images, and structured data display better on flat surfaces than in 3D space

Integrate seamlessly: Your 2D interfaces become natural parts of the 3D world

The blueprint and instance model

Panels follow a two-phase lifecycle that separates what they are from where they appear:

Registration creates the blueprint for a panel. It defines what the panel looks like, how it behaves, and what it displays. This is similar to creating a template or class definition. You can register a panel once and use it multiple times.

Spawning creates actual instances of a registered panel in your 3D scene. It positions specific panels at particular locations with individual properties.

This separation means you can have multiple copies of the same panel type, like multiple video players. You can also dynamically create and destroy panels as needed without redefining their core behavior.

Once spawned, panels become objects with spatial properties:

Position: They exist at specific coordinates in your 3D world

Orientation: They can face different directions or be angled for optimal viewing

Scale: They can be resized while maintaining their aspect ratio and functionality

Physics: They can respond to physics interactions, be grabbed, or moved around

Depth: They have proper occlusion with other 3D objects in your scene

The Spatial SDK projects your 2D Android UI onto 3D surfaces while maintaining proper input handling. When users touch or point at your panel, the SDK translates 3D interactions into familiar Android touch events.

Why use 2D panels?

Integrating 2D panels into 3D scenes provides several benefits:

Present information clearly: 2D panels excel at displaying text, images, and UI components with clarity and precision. This can be challenging with purely 3D elements.

Familiar user interface: Panels offer a familiar interface, making navigation and interaction more intuitive in a 3D space.

Performance: 2D elements are generally less resource-intensive than 3D objects. This helps maintain better performance in your applications.

Development mindset

Differences

Traditional Android: “How does this look on different screen sizes?”

Spatial: “How does this look at different distances and viewing angles?”

Your Android skills still apply

// This familiar Android code works the same in panels:
val button = findViewById<Button>(R.id.my_button)
button.setOnClickListener {
    Toast.makeText(this, "Clicked in 3D space!", Toast.LENGTH_SHORT).show()
}

3D placement

// This is the new part - positioning your UI in 3D space:
Entity.createPanelEntity(
    R.id.my_panel,
    Transform(Pose(Vector3(0f, 1.5f, -2f))), // 2m forward, 1.5m up
)

The SDK handles the complex work of making your 2D Android UI appear as a 3D object.

Implementation

Register your panel: Create the blueprint for your panel

Spawn your panel: Add the panel to your 3D scene

Panels in Spatial Editor: Use the Spatial Editor to create and manage panels

Configuration guides

Once you have basic panels working, explore these advanced topics:

Panel Resolution & Config: Performance optimization

Panel Layers: Visual quality improvements

Panel Communication: Inter-panel messaging

DRM Protected Content: Secure content display

Design guidelines

2D UI Key Considerations

Display

2D art assets

Did you find this page helpful?