Develop

Select your platform

Understand scenes in Spatial SDK

Updated: Sep 17, 2025

Overview

In Spatial SDK, “scene” refers to both a concept and a code implementation.

A spatial scene: A scene is the complete composition that defines a 3D space and contains all the objects within it. It includes both the viewable content and the navigable space that users move through. In spatial scenes, users are positioned within the 3D coordinate system rather than viewing content from a fixed external perspective.

Scene class: The Scene class provides programmatic control over this composed space through methods for environmental lighting, Passthrough (real-world integration), and spatial positioning.

Scene composition

Spatial SDK builds scenes using an Entity-Component-System (ECS) architecture. For a complete understanding of how entities, components, and systems work together in Spatial SDK, see Entity-Component-System (ECS).

Types of scenes

Spatial SDK supports different types of immersive experiences. Understanding these types helps you choose the right approach for your project.

Immersive scenes

Fully immersive scenes create complete virtual environments that replace your physical surroundings. The StarterSample shows this type of scene. Your app controls everything: lighting, environment, skyboxes, and all objects. Users can’t see their physical surroundings. The user’s visual field is entirely occupied by the virtual environment.

Passthrough scenes (mixed reality)

Passthrough scenes blend virtual objects with your physical room. The MixedRealitySample shows this type of scene. The app uses Passthrough to show your real environment, then scans your room with Mixed Reality Utility Kit to understand where walls, floors, and furniture are located. Then it places virtual objects that interact with your real space. For example, virtual basketballs can bounce off your real floor and walls.

Your app needs to handle both designed virtual content and unpredictable real-world spaces. When the app detects your real floor, it removes the virtual floor it initially created.

Hybrid scenes

These scenes combine traditional flat panels in the home space and a fully immersive scene. The HybridSample shows how to switch between 2D panels and a fully immersive scene. The same app can present content as traditional flat panels (like phone screens) or as fully immersive scenes.

Scene creation

Spatial SDK offers two main approaches for creating scenes. Understanding both helps you choose the right method for your project.

Visual design with Spatial Editor

Spatial Editor lets you design scenes visually and export them as GLXF files. This approach works well when:

Visual feedback: You can see how your scene looks while designing it, enabling object arrangement, lighting adjustment, and environment creation.

Team collaboration: Designers can work on environments while developers focus on behavior and logic. This separates visual design tasks from programming tasks.

3D assets: Spatial Editor handles positioning 3D models, managing materials and textures, and creating environmental layouts.

Limitations: Visual tools work for content you can design ahead of time. They are not suitable for scenes that need to change based on data, user behavior, or complex logic.

A basic scene composition taken from the StarterSample

Code-first

Creating scenes programmatically means writing code to build your scene. This approach works well when:

Dynamic content: Your scene changes based on user data, network information, or real-time calculations that can’t be predicted at design time.

Precise control: Code provides exact control over when objects appear, how they behave, and how they respond to different conditions.

Data integration: If your scene needs to display information from databases, APIs, or user input, code-based creation handles this integration.

Limitations: It’s harder to visualize spatial relationships in code. You need to run your app to see how things actually look, which can slow down the design process.

Controlling a scene directly with Kotlin code in Android Studio

Combining both approaches

Apps commonly use both methods together. For example:

Design your main environment in Spatial Editor for visual appeal

Create interactive objects in code for dynamic behavior

Configure lighting and effects in code for precise control

Load 3D models through GLXF but position them with code based on user preferences

This combination provides access to different tools for different parts of your scene.

How scene features work together

Spatial SDK provides different capabilities you can add to your scenes:

PhysicsFeature: Makes objects behave like real-world objects with gravity, collisions, and realistic movement.

MRUKFeature: Helps your app understand and interact with real rooms and furniture.

Spatial audio: Makes sounds appear to come from specific locations in 3D space.

You can use these features independently or combine them. When combining features, ensure they work together logically. If an object has physics, it should move when pushed. If a sound source has a visual component, they should be in the same location.

Scene lifecycle

Understanding when and how to set up your scenes is crucial for creating smooth spatial experiences. Spatial SDK provides specific activity lifecycle callbacks that guide scene creation.

Hot reload support: During development, scenes can be reloaded while your app runs, allowing rapid iteration on visual design.

User comfort

Spatial experiences place users inside your app rather than just viewing it on a screen. This requires understanding how to make experiences comfortable and intuitive.

Comfort considerations

Scale and grounding: Objects should feel appropriately sized. A virtual table that’s too tall or too small can feel unsettling. When users can see both virtual objects and their real environment (in Passthrough), maintaining consistent scale helps users feel grounded.

Movement and transitions: Abrupt changes can cause disorientation. When transitioning between different environments or immersion levels, gradual visual cues and animations help users maintain their sense of place.

Visual stability: Ensure UI elements and important objects remain stable relative to the user’s head or the world. Objects that drift unexpectedly can cause discomfort.

Spatial interaction patterns

Depth awareness: Unlike flat screens, spatial scenes have depth. Place important UI elements within comfortable reach and viewing distances. Objects too close or too far become difficult to interact with.

Natural positioning: Users expect objects to behave like real-world objects. A floating panel should feel deliberately placed, not accidentally hovering.

Context preservation: In Passthrough experiences, avoid obscuring too much of the user’s real environment. This helps maintain their sense of grounding and safety in their physical space.

For comprehensive guidance, see Designing for user comfort and Health and Safety guidelines.

From concepts to implementation

Now that you understand the key concepts of spatial scenes, here’s how these concepts connect to practical implementation:

Scene composition through ECS: The Entity-Component-System architecture you learned about creates SceneObject, SceneMesh, and SceneMaterial objects that you can interact with directly. Systems like MeshCreationSystem continuously transform your component data into the visual scene representation.

Scene types and API methods: The scene types covered here (immersive, Passthrough, hybrid) each use specific Scene class methods. Immersive scenes primarily use lighting and positioning methods, while Passthrough scenes enable real-world integration through enablePassthrough().

User comfort in practice: The comfort principles discussed translate to implementation choices like using setViewOrigin() for smooth positioning transitions and setReferenceSpace(ReferenceSpace.LOCAL_FLOOR) to ensure proper recentering behavior.