Class AssetReference

AssetReferences can be used to load glTF or GLB assets

Use AssetReference.getOrCreateFromUrl to get an AssetReference for a URL to be easily loaded. When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.

Important methods:

  • preload to load the asset binary without creating an instance yet.
  • loadAssetAsync to load the asset and create an instance.
  • instantiate to load the asset and create another instance.
  • unload to dispose allocated memory and destroy the asset instance.

Example: Loading an asset from a URL

import { AssetReference } from '@needle-tools/engine';
const assetRef = AssetReference.getOrCreateFromUrl("https://example.com/myModel.glb");
const instance = await assetRef.loadAssetAsync();
scene.add(instance);

Example: Referencing an asset in a component and loading it on start

import { Behaviour, serializable, AssetReference } from '@needle-tools/engine';

export class MyComponent extends Behaviour {

  @serializable(AssetReference)
  myModel?: AssetReference;
  
  // Load the model on start. Start is called after awake and onEnable
  start() { 
    if (this.myModel) {
      this.myModel.loadAssetAsync().then(instance => {
        if (instance) {
          // add the loaded model to this component's game object
          this.gameObject.add(instance); 
        }
      });
    }
  }
}

Related:

Constructors

constructor

Accessors

asset hasUrl rawAsset uri url urlName

Methods

beginListenDownload endListenDownload instantiate instantiateSynced isLoaded loadAssetAsync preload unload getOrCreate getOrCreateFromUrl

Constructors

constructor

  • new AssetReference(uri: string, _hash?: string, asset?: any): AssetReference

    Parameters

    • uri: string
    • Optional_hash: string
    • Optionalasset: any

    Returns AssetReference

Accessors

asset

  • get asset(): null | Object3D<Object3DEventMap>

    The loaded asset root

    Returns null | Object3D<Object3DEventMap>

  • set asset(val: null | Object3D<Object3DEventMap>): void

    Parameters

    Returns void

hasUrl

  • get hasUrl(): boolean

    Returns boolean

    true if the uri is a valid URL (http, https, blob)

rawAsset

  • get rawAsset(): any

    This is the loaded asset root object. If the asset is a glb/gltf file this will be the three#Scene object.

    Returns any

uri

  • get uri(): string

    The url of the loaded asset (or the asset to be loaded)

    Returns string

    Deprecated

    use url

url

  • get url(): string

    The url of the loaded asset (or the asset to be loaded)

    Returns string

urlName

  • get urlName(): string

    The name of the assigned url. This name is deduced from the url and might not reflect the actual name of the asset

    Returns string

Methods

beginListenDownload

  • beginListenDownload(evt: ProgressCallback): void

    Parameters

    • evt: ProgressCallback

    Returns void

endListenDownload

  • endListenDownload(evt: ProgressCallback): void

    Parameters

    • evt: ProgressCallback

    Returns void

instantiate

  • instantiate(
        parent?: null | Object3D<Object3DEventMap> | IInstantiateOptions,
    ): Promise<null | Object3D<Object3DEventMap>>

    loads and returns a new instance of asset

    Parameters

    • Optionalparent: null | Object3D<Object3DEventMap> | IInstantiateOptions

    Returns Promise<null | Object3D<Object3DEventMap>>

instantiateSynced

isLoaded

  • isLoaded(): boolean | ArrayBufferLike

    Returns boolean | ArrayBufferLike

    true if the asset has been loaded (via preload) or if it exists already (assigned to asset)

loadAssetAsync

  • loadAssetAsync(
        prog?: null | ProgressCallback,
    ): Promise<null | Object3D<Object3DEventMap>>

    Loads the asset and creates one instance (assigned to asset)

    Parameters

    • Optionalprog: null | ProgressCallback

    Returns Promise<null | Object3D<Object3DEventMap>>

    the loaded asset

preload

  • preload(): Promise<null | ArrayBufferLike>

    loads the asset binary without creating an instance

    Returns Promise<null | ArrayBufferLike>

unload

  • unload(): void

    frees previously allocated memory and destroys the current asset instance (if any)

    Returns void

StaticgetOrCreate

  • getOrCreate(
        sourceId: string | IComponent,
        url: string,
        context?: Context,
    ): AssetReference

    Get an AssetReference for a URL to be easily loaded.
    AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.

    Parameters

    Returns AssetReference

StaticgetOrCreateFromUrl

  • getOrCreateFromUrl(url: string, context?: Context): AssetReference

    Get an AssetReference for a URL to be easily loaded.
    AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.

    Parameters

    • url: string

      The URL of the asset to load. The url can be relative or absolute.

    • Optionalcontext: Context

      The context to use for loading the asset

    Returns AssetReference

    the AssetReference for the URL

Settings

Member Visibility

On This Page

AssetReferences can be used to load glTF or GLB assetsRelated:
Constructors
Accessors
Methods