Load assets

The AssetLoader service allows you to dynamically load assets such as models, textures, audio, and materials at runtime. You can retrieve assets either by their unique ID, their name (as defined in the editor), or by their file path.

Basic Usage

Inject the AssetLoader into your actor or service to start loading assets.

import { Actor, AssetLoader, BaseActor, inject } from "@hology/core/gameplay";

@Actor()
class TestActor extends BaseActor {
  private assets = inject(AssetLoader)

  async onInit() {    
    // Load a model by name
    const model = await this.assets.getModelByAssetName('MyCharacter')
    this.object.add(model.scene)
    
    // Play a sound
    const audioBuffer = await this.assets.getAudioByAssetName('JumpSound')
    // ... use audioBuffer
  }
}

Loading Methods

Models

Models are returned as a LoadedMesh object, which contains the scene (THREE.Group) and animations (THREE.AnimationClip[]).

• getModelByAssetName(name: string): Promise<LoadedMesh>

  • Finds an asset by its name in the project.

• getModelByAssetId(id: string): Promise<LoadedMesh>

  • Finds an asset by its unique ID.

• getModelAtPath(filePath: string): Promise<THREE.Object3D>

  • Loads a model directly from a file path relative to the project root. Supports .glb, .gltf, .fbx, and .obj.

• getGltfAtPath(filePath: string): Promise<GLTF>

  • Loads a GLTF/GLB file and returns the full GLTF object (including scenes, cameras, animations, etc.).

Textures

Textures are returned as THREE.Texture objects.

• getTextureByAssetName(name: string): Promise<THREE.Texture>

• getTextureByAssetId(id: string): Promise<THREE.Texture>

Audio

Audio is returned as an AudioBuffer, ready to be used with THREE.Audio or THREE.PositionalAudio.

• getAudioByAssetName(name: string): Promise<AudioBuffer>

• getAudioByAssetId(id: string): Promise<AudioBuffer>

• getAudioAtPath(filePath: string): Promise<AudioBuffer>

Materials

Materials are returned as THREE.Material objects.

• getMaterialByAssetId(id: string): Promise<THREE.Material>

Prefabs

Prefabs allow you to spawn pre-configured actors or objects.

• getPrefabByName(name: string): Promise<Prefab>

• getPrefabById(id: string): Promise<Prefab>

Generic Asset Access

If you need access to the raw Asset data structure:

• getAsset(id: string): Promise<Asset>