core/com.pico.spatial.core.ecs/Entity/Companion/load

load

@JvmStatic
fun load(uriString: String): Entity

Synchronously loads a 3D model from the specified URI string and returns its root entity.

For complex or high-resolution resources that require significant processing time, it is strongly recommended to leverage coroutines for loading. This approach prevents blocking the main thread, ensuring a responsive and fluid user experience.

Usage

Recommended to call within a coroutine context (preferably not Dispatchers.Main):

val entity = withContext(Dispatchers.IO) {
    Entity.load("asset://models/box.usdz")  // Asset example
    // or
    Entity.load("file:///sdcard/models/box.glb")  // File example
}
Content copied to clipboard

Performance notes

  • This is a blocking I/O operation. Heavy operations block the calling thread.

  • Large models may cause frame drops or even ANR if called on main thread.

  • Textures are recommended to be pre-compressed (ASTC/ETC2).

  • Single texture memory limit: 256MB (includes mipmaps).

  • File access time affects loading duration.

Security considerations

  • Ensure the file is accessible and has the necessary permissions.

  • Avoid loading models from files that may contain sensitive data.

  • Avoid loading models from files that are not intended for public consumption.

Return

The root entity of the loaded scene.

Parameters

uriString

The URI representing the location of the 3D model to load. Supported URI schemes:

  • asset:// - Loads from application assets.

  • file:// - Loads from local storage. For content:// URIs, use load(contentResolver: ContentResolver, uri: Uri) instead.

See also

loadSuspend(String) for non-blocking alternative.

Throws

If loading fails due to invalid URI, missing file, unsupported format, and more.

@JvmStatic
fun load(file: File): Entity

Synchronously loads a 3D model from a file and returns its root entity.

For complex or high-resolution resources that require significant processing time, it is strongly recommended to leverage coroutines for loading. This approach prevents blocking the main thread, ensuring a responsive and fluid user experience.

Usage

Recommended to call within a coroutine context (preferably not Dispatchers.Main):

val entity = withContext(Dispatchers.IO) {
    Entity.load(File("/sdcard/models/box.glb"))
}
Content copied to clipboard

Performance notes

  • This is a blocking I/O operation. Heavy operations block the calling thread.

  • Large models may cause frame drops or even ANR if called on main thread.

  • Textures are recommended to be pre-compressed (ASTC/ETC2).

  • Single texture memory limit: 256MB (includes mipmaps).

  • File access time affects loading duration.

Security considerations

  • Ensure the file is accessible and has the necessary permissions.

  • Avoid loading models from files that may contain sensitive data.

  • Avoid loading models from files that are not intended for public consumption.

Return

The root entity of the loaded scene.

Parameters

file

The file containing the 3D model to load. The path must be accessible. Supported file formats:

  • USD variants: .usdz, .usda, .usdc.

  • GLTF variants: .glb, .gltf.

See also

loadSuspend(File) for non-blocking alternative.

Throws

If loading fails due to invalid format, missing assets, exceeding memory limits, and more.

@JvmStatic
fun load(contentResolver: ContentResolver, uri: Uri): Entity

Synchronously loads a 3D model from a content provider URI and returns its root entity.

For complex or high-resolution resources that require significant processing time, it is strongly recommended to leverage coroutines for loading. This approach prevents blocking the main thread, ensuring a responsive and fluid user experience.

To load a .gltf model, make sure that all data is stored in a single .gltf file. While for Entity.load(uriString: String) and Entity.load(file: File), you can also load a .gltf model stored in a folder (in this case, the actual data is stored in the .bin file, instead of the .gltf file).

Usage

Recommended to call within a coroutine context (preferably not Dispatchers.Main):

val entity = withContext(Dispatchers.IO) {
    Entity.load(
        contentResolver,
        Uri.parse("content://com.example.provider/models/box.glb")
    )
}
Content copied to clipboard

Performance notes

  • This is a blocking I/O operation. Heavy operations block the calling thread.

  • Large models may cause frame drops or even ANR if called on main thread.

  • Textures are recommended to be pre-compressed (ASTC/ETC2).

  • Single texture memory limit: 256MB (includes mipmaps).

  • Content provider response time affects loading duration.

Security considerations

  • Ensure the content provider has the necessary permissions to access the specified URI.

  • Avoid loading models from URIs that may contain sensitive data.

Return

The root entity of the loaded scene.

Parameters

contentResolver

The ContentResolver for accessing the content provider.

uri

The content Uri pointing to the 3D model data. Only supports content:// URIs. For other schemes such as asset:// and file:// URIs, use load(uriString: String) instead.

See also

loadSuspend(ContentResolver, Uri) for non-blocking alternative.

Throws

If loading fails due to invalid data, unsupported format, exceeding memory limits, and more.

SecurityException

If the caller does not have permission to access the content provider.

@JvmStatic
fun load(inputStream: InputStream, format: ModelFormat): Entity

Synchronously loads a 3D model from an InputStream and returns its root entity.

For complex or high-resolution resources that require significant processing time, it is strongly recommended to leverage coroutines for loading. This approach prevents blocking the main thread, ensuring a responsive and fluid user experience.

Supported Formats

  • All ModelFormat variants supported by the engine.

  • Format must match the actual stream content.

  • To load a .gltf model, make sure that all data is stored in a single .gltf file. While for Entity.load(uriString: String) and Entity.load(file: File), you can also load a .gltf model stored in a folder (in this case, the actual data is stored in the .bin file, instead of the .gltf file).

Usage

Recommended to call within a coroutine context (preferably not Dispatchers.Main):

val entity = withContext(Dispatchers.IO) {
    context.assets.open("models/box.usdz").use { inputStream ->
        Entity.load(inputStream, ModelFormat.USD)
    }
}
Content copied to clipboard

Performance Notes

  • This is a blocking I/O operation. Heavy operations block the calling thread.

  • Large models may cause frame drops or even ANR if called on main thread.

  • Textures are recommended to be pre-compressed (ASTC/ETC2).

  • Single texture memory limit: 256MB (includes mipmaps).

Resource Management

  • The caller is responsible for opening/closing the InputStream.

  • For automatic resource cleanup, use .use { } block as shown in example.

Return

The root entity of the loaded scene.

Parameters

inputStream

The InputStream containing the raw model data.

format

The ModelFormat of the provided data (must match actual content).

Throws

If loading fails due to invalid data, unsupported format, exceeding memory limits exceeded, and more.

@JvmStatic
fun load(modelName: String, bundle: AssetBundle): Entity

Synchronously loads a 3D model from the specified AssetBundle and returns its root entity.

For complex or high-resolution resources that require significant processing time, it is strongly recommended to leverage coroutines for loading. This approach prevents blocking the main thread, ensuring a responsive and fluid user experience.

Supported file

  • AssetBundles (.bundle) will be automatically packaged into asset:// when:

    1. Spatial Tools dependency is properly configured;

    2. Spatial Editor project is properly configured;

    3. Both bundle name and model name are exactly matched;

    4. Gradle build pipeline completes successfully.

Usage

Recommended to call within a coroutine context (preferably not Dispatchers.Main):

val entity = withContext(Dispatchers.IO) {
    AssetBundle.load("asset://main.bundle").use { bundle ->
        Entity.load("character_model", bundle)
    }
}
Content copied to clipboard

Performance Notes

  • This is a blocking I/O operation. Heavy operations block the calling thread.

  • Large models may cause frame drops if called on main thread;

  • Textures are recommended to be pre-compressed (ASTC/ETC2);

  • Single texture memory limit: 256MB (includes mipmaps);

  • The AssetBundle should be closed after use (prefer .use {} block);

Error Handling & Requirements

  • Model Name must exactly match USD "Scene" names (case-sensitive) in the corresponding Spatial Editor project.

  • Bundle name must match SpatialPackConfig settings in app's build.gradle.

Return

The root entity of the loaded scene.

Parameters

modelName

The name of the model asset in the bundle (case-sensitive).

bundle

The loaded AssetBundle containing the model resources.

See also

for bundle loading procedure.

Throws

If loading fails due to missing model, invalid format, exceeding memory limits, and more.

⇪
Copyright © 2025-2026 PICO. All rights reserved.
Generated by Dokka