Asset Loading System

The asset loading system owns asset records, submits asynchronous loading work, and hands renderer-ready data to RenderingDataManager.

Use AssetRegistry handles for stable authored references. Use Asset::Ref when code needs the loaded payload.

Key Types

Type	Meaning	Used For
Asset::Path	Wrapper around std::filesystem::path	Single-file assets: audio clips and direct texture requests
Asset::MeshPath	Source file path plus named object	glTF sub-assets: meshes, materials, skins, animations
Engine::Assets::AssetHandle<Tag>	Index plus generation handle	AssetRegistry stores for scene and component references
Engine::Assets::TextureHandle	Texture registry id plus semantic type	Descriptor lookup for material textures

Use Asset::MeshPath when the asset is a named object inside a container file.

constexpr auto modelPath = CREATE_ASSET_PATH(
    Engine::Core::Path::engineGeometry() / "Defaults/cube_no_texture/cube_no_texture.gltf"
);
 
Asset::MeshPath cubeMesh(modelPath.fsPath(), "Cube");

Use Asset::Path when the asset is the file itself.

Asset::Path soundPath(Engine::Core::Path::engineSounds() / "Eat.wav");

Asset Types

Type	Payload Access	Stable Handle	Owner	Primary Storage
glTF file	Engine::Assets::Model by std::filesystem::path	GltfHandle	ModelAssetManager, GltfStore	Tracks sub-assets created from one source file
glTF renderable	GltfRenderableRecord	GltfRenderableHandle	GltfStore	Node index, mesh index, transform, geometry handle, material handles
Mesh	MeshAssetRef by Asset::MeshPath	GeometryMeshHandle	MeshAssetManager, GeometryMeshStore	Hidden ECS entity with MeshPrimitiveData
Material	MaterialAssetRef by Asset::MeshPath	MaterialHandle	MaterialAssetManager, MaterialStore	Hidden ECS entity with MaterialData and typed texture handles
Texture	TextureAssetRef by Asset::Path	Texture2DHandle, TextureHandle	TextureAssetManager, Texture2DStore, TextureHandleRegistry	Hidden ECS entity with ImageData, then renderer-owned RuntimeTexture
Audio	AudioAssetRef by Asset::Path	AudioClipHandle	AudioAssetManager, AudioClipStore	Decoded PCM fields on Engine::Assets::Audio
Skin	SkinAssetRef by Asset::MeshPath	None in AssetRegistry	SkinAssetManager	Joint hierarchy on Engine::Assets::Skin
Animation	AnimationAssetRef by Asset::MeshPath	None in AssetRegistry	AnimationAssetManager	Animation channels on Engine::Assets::Animation

Asset::Ref::isLoaded() returns true when the current record generation has a loaded payload. AssetHandle<Tag> values are stable references into registry stores, not loaded payload pointers.

Asset Registry

Engine::Core::AssetRegistry stores stable handles for scene and component data. The engine creates it with the central AssetManager, and each Scene exposes it through Scene::getAssetRegistry().

Engine::Core::AssetRegistry* registry = scene->getAssetRegistry();
 
Engine::Assets::GltfHandle gltf = registry->gltfs().load(modelPath.fsPath());
Engine::Assets::GltfRenderableHandle renderable =
    registry->gltfs().renderable(gltf, "Cube");
Engine::Assets::GeometryMeshHandle mesh =
    registry->gltfs().geometryMesh(renderable);

GltfStore::load() reads glTF metadata and creates renderable, geometry mesh, and material handles. Geometry handle creation requests the backing mesh through AssetManager::getAsset<Engine::Assets::Mesh>().

Registry stores reject absolute paths for geometry meshes, materials, glTF files, textures, and audio clips. Use engine-relative authored paths for those handles.

Payload Access

Use Engine::Core::AssetManager::getAsset<T>() when code needs the loaded asset payload.

Engine::Assets::MeshAssetRef meshRef =
    assetManager->getAsset<Engine::Assets::Mesh>(cubeMesh);
 
if (!meshRef.isLoaded()) {
    return;
}
 
Engine::Assets::Mesh* mesh = meshRef.get();

getAsset<Engine::Assets::Mesh>() returns a ref immediately and requests the backing glTF model when the mesh payload is absent.

getAsset<Engine::Assets::Skin>() and getAsset<Engine::Assets::Animation>() request the backing glTF model when the target record is UNLOADED.

getAsset<Engine::Assets::Material>() creates or returns the material ref. Material payloads are resolved when the model pipeline processes the source glTF.

getAsset<Engine::Assets::Texture>() and getAsset<Engine::Assets::Audio>() accept Asset::Path or std::filesystem::path. The facade converts the key to Asset::Path.

Frame Processing

EngineKern::processResourceLoadingPipelines() advances asset work once per frame.

assetManager->getTextureAssetPipeline().tick(true);
assetManager->getMeshAssetPipeline().tick(true);
assetManager->getAudioAssetPipeline().tick(true);
 
renderer->getRenderingDataManager()->processCompletedTextures();

Texture preparation finishes on worker threads. RenderingDataManager::processCompletedTextures() registers finished RuntimeTexture objects and updates TextureHandleRegistry.

Meshlet generation also finishes asynchronously. ModelAssetPipeline::takePendingMeshletCompletions() returns completed meshlet data at render-safe points.

Model Pipeline

ModelAssetPipeline loads glTF files and resolves sub-assets from them.

Stage	Work
submitLoadModel()	Submit tinygltf parse work to the asset loader pool
processModel()	Parse scene extensions, pre-register texture handles, register textures, resolve skins and animations, create material records, and submit primitive loading
processSkinData()	Reserved stage; skin loading currently runs inside processModel()
processMaterial()	Write MaterialData to material asset entities and notify the renderer
processMeshData()	Write mesh primitive metadata, optimize geometry, and schedule meshlet generation
processKtx2Textures()	Poll KTX/KTX2 texture load futures and notify the renderer

Model keeps non-owning pointers to sub-assets created from one source file. The owning managers are MeshAssetManager, MaterialAssetManager, TextureAssetManager, SkinAssetManager, and AnimationAssetManager.

Lightmapped glTF nodes receive material keys named <material>__lightmap__<node>. The metadata import path and the runtime model pipeline use the same naming rule.

Texture Loading

Textures have a CPU asset record and a renderer-owned runtime texture.

Source	Flow
glTF PNG/JPG	tinygltf loads image bytes during model load; processTextures() creates GltfTextureAsset records
glTF KTX/KTX2	Ktx2Loader runs on the asset loader pool; RenderingDataManager::onKtx2TextureLoaded() prepares the runtime texture
EXR lightmaps	TextureAssetPipeline loads headers, then image data, then calls RenderingDataManager::onTextureLoaded()
Direct KTX/KTX2 requests	TextureAssetPipeline runs Ktx2Loader and reports to RenderingDataManager

RenderingDataManager::onTextureLoaded() moves Ecs::ImageData out of the asset entity and creates a RuntimeTexture on a worker thread. RenderingDataManager::processCompletedTextures() registers the texture in AssetManager and writes its descriptor index to TextureHandleRegistry.

Materials store typed texture handles for descriptor lookup.

uint32_t descriptorIndex = textureRegistry->resolveDescriptorIndex(
    material->getBaseColorTextureHandle()
);

TextureHandleRegistry::resolveDescriptorIndex() returns 0xFFFFFFFF until the runtime texture is registered.

Mesh And Material Assets

Meshes and materials are glTF sub-assets keyed by Asset::MeshPath.

Asset::MeshPath materialPath(modelPath.fsPath(), "DefaultMaterial");
Engine::Assets::MaterialAssetRef materialRef =
    assetManager->getAsset<Engine::Assets::Material>(materialPath);

A mesh is loaded when its hidden asset entity has Engine::Ecs::MeshPrimitiveData.

A material is loaded when its hidden asset entity has Engine::Core::MaterialData.

Skin And Animation Assets

Skins and animations are loaded from glTF by the model pipeline and owned by their managers.

Asset::MeshPath skinPath(modelPath.fsPath(), "Armature");
Engine::Assets::SkinAssetRef skinRef =
    assetManager->getAsset<Engine::Assets::Skin>(skinPath);
 
Asset::MeshPath animationPath(modelPath.fsPath(), "Walk");
Engine::Assets::AnimationAssetRef animationRef =
    assetManager->getAsset<Engine::Assets::Animation>(animationPath);

Current skeletal runtime data stores raw pointers to manager-owned payloads.

ECS Component	Pointer
Engine::Ecs::SkeletalMeshData	Engine::Assets::Skin*
Engine::Ecs::AnimationState	Engine::Assets::Animation*

Audio Assets

Audio uses generic asset records and refs. Playback remains path-based.

Asset::Path clipPath(Engine::Core::Path::engineSounds() / "Eat.wav");
Engine::Assets::AudioAssetRef clipRef =
    assetManager->getAsset<Engine::Assets::Audio>(clipPath);

AudioAssetPipeline decodes files on the asset loader pool and resolves Engine::Assets::Audio records. AudioEngine::onAudioLoaded() registers loaded clips by filesystem path, and playback uses AudioEngine::play(path).

AudioClipStore::load() creates an AudioClipHandle and submits the decode request through AssetManager::loadAudioAsset().

Loading State

Asset::Record owns the current payload, load state, generation, error string, and ready future. Asset::Ref is a non-owning handle to that record.

State	Meaning
UNLOADED	No payload is available
REQUESTED_LOAD	A load was requested but no worker owns it yet
LOADING	A pipeline is processing the asset
LOADED	The payload is ready
FAILED	Loading reached a terminal failure

Asset::Ref::readyFuture() resolves with Asset::LoadResult<Key, AssetClass> when the current generation succeeds or fails. A new generation starts when loading restarts, a payload is replaced, or a payload is unloaded.

Unloading And Cancellation

AssetManager::discardSceneLoadingData() clears queued and in-flight scene loading work from texture, model, and audio pipelines. It also asks RenderingDataManager to discard pending texture preparations.

AssetManager::unloadAllData() discards pending work, clears renderer scene resource caches, unloads runtime textures, clears texture handles, and clears all asset managers.

API Reference

API	Purpose
Asset::Path, Asset::MeshPath	Asset keys
Asset::Record, Asset::Ref, Asset::AssetManager, Asset::LoadResult	Generic asset record and payload access API
Engine::Core::AssetManager	Central asset manager facade
Engine::Core::AssetRegistry	Stable handle stores and authored reference resolution
GltfStore, GeometryMeshStore, MaterialStore, Texture2DStore, AudioClipStore	Registry stores
Engine::Assets::AssetHandle	Stable index/generation handle template
TextureAssetPipeline, ModelAssetPipeline, AudioAssetPipeline	Async loading pipelines
Model, Mesh, Material, Texture, Audio, Skin, Animation	Asset payload classes
TextureHandleRegistry, TextureHandle	Runtime texture handle and descriptor lookup API
RenderingDataManager	Runtime texture preparation, GPU upload, and renderer cache invalidation