Focus showcase - Immersive environments and design guidelines

Updated: Sep 29, 2025

Create immersive environments

Immersive VR environments transport users to new or distant places. The quality of the environment can make or break the immersion. When done well, they can help a user focus on application content more effectively.

Focus offers three immersive environments for project development, each consisting of a 3D model, a skybox, and scene lighting. These elements function independently, but are combined in Focus to form a cohesive concept.

Load and switch between panoramas (skybox)

To create a panorama or skybox, you can use Spatial SDK’s skybox Mesh primitive, and set a 360 image to the baseTextureAndroidResourceId attribute:

skybox =  Entity.create(
Mesh(Uri.parse("mesh://skybox")),
Material().apply {
baseTextureAndroidResourceId = R.drawable.skybox1
           unlit = true // Prevent scene lighting from affecting the skybox
     },
Transform(Pose(Vector3(0f)))
)

Use a single entity for multiple skyboxes in your scene due to the large size of skybox textures. Change the texture of this entity whenever you need to display a different skybox.

skybox.setComponent(
    Material().apply {
        baseTextureAndroidResourceId = R.drawable.skybox2
        unlit = true
    },
)

To improve performance, create a system that progressively loads skyboxes when you need to display them simultaneously or combine them.

Load and switch between 3D model scenes

You can create 3D environments that resemble any custom 3D object in your scene. You can do this by creating an entity with a mesh component in the scene.xml file or directly from your activity. For Focus, the direct configuration method is used.

environment = Entity.create(
    Mesh(mesh = Uri.parse("environment1.glb")),
    Visible(false),
)

Like any other 3D object, environments, tend to be larger than other models. If you plan to use multiple environments, similar to the skyboxes recommendation, consider changing the mesh model instead of creating a separate entity.

environment.setComponent(Mesh(mesh = Uri.parse("environment2.glb")))

Change the lighting environment

You can set your scene’s lighting in two ways.

The first option is using a .env file. You probably want to use your skybox texture to generate this file. This ensures the lighting will match the colors and properties of your skybox.

scene.updateIBLEnvironment("skybox.env")

Set an ambience and directional light with vectors:

scene.setLightingEnvironment(
    Vector3(2.5f, 2.5f, 2.5f), // ambient light color (none in this case)
    Vector3(1.8f, 1.8f, 1.8f), // directional light color
    -Vector3(1.0f, 3.0f, 2.0f), // directional light direction
)

Focus has three different environments. There are different light configurations for each one, including the introduction lighting:

private fun setLighting(env: Int) {
    when (env) {
        -1 -> {
            scene.setLightingEnvironment(
                Vector3(2.5f, 2.5f, 2.5f), // ambient light color (none in this case)
                Vector3(1.8f, 1.8f, 1.8f), // directional light color
                -Vector3(1.0f, 3.0f, 2.0f), // directional light direction
            )
        }
        0 -> {
            scene.setLightingEnvironment(
                Vector3(1.8f, 1.5f, 1.5f),
                Vector3(1.5f, 1.5f, 1.5f),
                -Vector3(1.0f, 3.0f, 2.0f),
            )
        }
        1 -> {
            scene.setLightingEnvironment(
                Vector3(1.5f, 1.5f, 1.5f),
                Vector3(1.5f, 1.5f, 1.5f),
                -Vector3(1.0f, 3.0f, 2.0f),
            )
        }
        2 -> {
            scene.setLightingEnvironment(
                Vector3(3.5f, 3.5f, 3.5f),
                Vector3(2f, 2f, 2f),
                -Vector3(1.0f, 3.0f, 2.0f),
            )
        }
    }
}