Asset Pipeline

How asset files turn into in-game GPU/AL/Jolt resources, where they live on disk, and what happens during a project build.

Recognised file types

ExtensionAssetTypeLoader
.threadSceneYAML scene file — entities, components, skybox.
.png .jpg .jpeg .tga .hdr .bmpTexturestb_image. Decoded into a GPU texture by AssetManager (compressed to .ttex where the project does that).
.obj .fbx .gltf .glbMesh (source)Assimp. Editor-only — runtime prefers .tmesh.
.tmeshMesh (compiled)Binary VBO+IBO+submesh table. memcpy load, no parsing.
.tmaterialMaterialYAML with Albedo / TexturePath / Tiling. Edited in the Material Node Editor.
.wav .ogg .mp3AudioWAV: built-in parser. OGG: stb_vorbis. MP3: minimp3.
.animAnimationBaked YAML keyframes. FBX animations are imported via Assimp.
.hScriptA gameplay script or scene system — one header, class named after the file. Attached via the Native Script component. A generated .cpp beside it is folded out of the browser.
.systemSystemSceneSystem registration descriptor.
.uiUIAssetUI screen layout.

Type detection is by file extension, case-insensitive (so Model.FBX works as well as model.fbx).

VFS — virtual file system

The Engine never opens fopen-style paths directly. Instead it goes through VFS::ReadFile, which:

  • In the editor: reads the path verbatim from disk.
  • In a built game: looks the path up inside the bundled assets.pak archive.

Result: scene YAMLs and component fields store paths like "assets/models/player.fbx" and the same scene works in both modes without rewrites.

Meshes — .tmesh runtime format

Asset files of type Mesh can be source (FBX / OBJ / glTF) or precompiled (.tmesh). The runtime auto-redirects: when asked to load foo.fbx and a foo.tmesh sibling exists, the .tmesh wins.

.tmesh layout (little-endian, header + flat arrays):

struct TMeshHeader {
    uint32 magic = 'PMSH';     // 0x48534D50
    uint32 version = 1;
    uint32 flags;
    uint32 vertexCount;
    uint32 indexCount;
    uint32 subMeshCount;
    uint32 materialSlotCount;
    uint32 vertexStride;       // sizeof(Vertex) — validated at load
};

// Followed by:
//   Vertices  [vertexCount  * vertexStride bytes]
//   Indices   [indexCount   * sizeof(uint32_t)]
//   SubMeshes [subMeshCount * 16 bytes  — offset/count/matIdx/reserved]
//   MaterialSlotNames [for each slot: uint32 length + chars]

During an editor build, BuildSystem walks the staging asset folder, calls MeshIO::LoadFromAssimp + WriteTMesh on each FBX/OBJ/glTF/glb, and drops the original. The shipped assets.pak carries only .tmesh — which is why standalone runtime builds can disable Assimp entirely.

Materials — multi-slot

Multi-material meshes (FBX with several Maya materials) produce one SubMesh per source aiMesh inside the engine's Mesh. MaterialComponent carries a vector of slots indexed by SubMesh::MaterialIndex. The renderer iterates submeshes and issues one draw per slot, binding the matching material instance.

Caching

AssetManager keeps a per-process cache: same path returns the same shared_ptr<Mesh> / Texture2D / AudioBuffer. So 50 trees referencing tree.fbx share one GPU mesh.

The cache is cleared in Application::~Application for textures and meshes; audio buffers are cleared explicitly before the OpenAL context dies (otherwise alDeleteBuffers would run after teardown and abort).

Where assets live

Your game's content lives in your project's assets/ folder. At runtime it mounts above the engine's built-in defaults (shaders, fonts, base textures), so a file you add overrides the built-in of the same name, and anything you don't supply falls back to the default.

The editor's Content Browser shows this merged view. On build, the asset folders are merged, meshes are precompiled to .tmesh, and the result is archived into a single assets.pak shipped beside the game executable.

See also

Project Structure · MeshComponent · MaterialComponent

Potok zasobów

Jak pliki assetów zamieniają się w zasoby GPU/AL/Jolt w grze, gdzie leżą na dysku i co dzieje się podczas budowania projektu.

Rozpoznawane typy plików

RozszerzenieAssetTypeLoader
.threadScenePlik sceny YAML — encje, komponenty, skybox.
.png .jpg .jpeg .tga .hdr .bmpTexturestb_image. AssetManager dekoduje do tekstury GPU (kompresowanej do .ttex tam, gdzie projekt to robi).
.obj .fbx .gltf .glbMesh (źródło)Assimp. Tylko w edytorze — runtime woli .tmesh.
.tmeshMesh (skompilowany)Binarny VBO+IBO+tabela podsiatek. Wczytanie przez memcpy, bez parsowania.
.tmaterialMaterialYAML z Albedo / TexturePath / Tiling. Edytowany w węzłowym edytorze materiałów.
.wav .ogg .mp3AudioWAV: wbudowany parser. OGG: stb_vorbis. MP3: minimp3.
.animAnimationWypieczone klatki kluczowe w YAML. Animacje FBX importuje Assimp.
.hScriptSkrypt gry albo system sceny — jeden nagłówek, klasa nazwana jak plik. Podpinany komponentem Native Script. Wygenerowany obok .cpp jest ukryty w przeglądarce.
.systemSystemDeskryptor rejestracji SceneSystem.
.uiUIAssetUkład ekranu UI.

Typ rozpoznawany jest po rozszerzeniu, bez względu na wielkość liter (więc Model.FBX działa tak samo jak model.fbx).

VFS — wirtualny system plików

Silnik nigdy nie otwiera ścieżek bezpośrednio w stylu fopen. Idzie przez VFS::ReadFile, który:

  • W edytorze: czyta ścieżkę wprost z dysku.
  • W zbudowanej grze: szuka ścieżki w dołączonym archiwum assets.pak.

Efekt: pliki scen i pola komponentów przechowują ścieżki typu "assets/models/player.fbx", a ta sama scena działa w obu trybach bez przepisywania.

Siatki — format runtime .tmesh

Pliki typu Mesh mogą być źródłowe (FBX / OBJ / glTF) albo prekompilowane (.tmesh). Runtime przekierowuje automatycznie: proszony o foo.fbx, gdy obok istnieje foo.tmesh, wybiera .tmesh.

Układ .tmesh (little-endian, nagłówek + płaskie tablice):

struct TMeshHeader {
    uint32 magic = 'PMSH';     // 0x48534D50
    uint32 version = 1;
    uint32 flags;
    uint32 vertexCount;
    uint32 indexCount;
    uint32 subMeshCount;
    uint32 materialSlotCount;
    uint32 vertexStride;       // sizeof(Vertex) — sprawdzane przy wczytaniu
};

// Dalej:
//   Vertices  [vertexCount  * vertexStride bajtów]
//   Indices   [indexCount   * sizeof(uint32_t)]
//   SubMeshes [subMeshCount * 16 bajtów — offset/count/matIdx/reserved]
//   MaterialSlotNames [dla każdego slotu: uint32 długość + znaki]

Podczas builda w edytorze BuildSystem przechodzi po roboczym folderze assetów, wywołuje MeshIO::LoadFromAssimp + WriteTMesh dla każdego FBX/OBJ/glTF/glb i usuwa oryginał. Wydany assets.pak zawiera tylko .tmesh — dlatego samodzielne buildy runtime mogą całkiem wyłączyć Assimpa.

Materiały — wiele slotów

Siatki z wieloma materiałami (FBX z kilkoma materiałami z Mayi) dają jedną SubMesh na źródłowy aiMesh w Mesh silnika. MaterialComponent ma wektor slotów indeksowany przez SubMesh::MaterialIndex. Renderer przechodzi po podsiatkach i wykonuje jedno rysowanie na slot, podpinając pasującą instancję materiału.

Buforowanie

AssetManager trzyma cache na proces: ta sama ścieżka zwraca ten sam shared_ptr<Mesh> / Texture2D / AudioBuffer. Więc 50 drzew wskazujących tree.fbx dzieli jedną siatkę na GPU.

Cache tekstur i siatek jest czyszczony w Application::~Application; bufory audio są czyszczone jawnie, zanim zniknie kontekst OpenAL (inaczej alDeleteBuffers wykonałoby się po zamknięciu i przerwało program).

Gdzie leżą assety

Zawartość gry leży w folderze assets/ projektu. W czasie działania montuje się ponad wbudowanymi domyślnymi zasobami silnika (shadery, czcionki, podstawowe tekstury), więc dodany plik zastępuje wbudowany o tej samej nazwie, a wszystko, czego nie dostarczysz, bierze się z domyślnych.

Content Browser edytora pokazuje ten połączony widok. Przy buildzie foldery assetów są łączone, siatki prekompilowane do .tmesh, a wynik pakowany do jednego assets.pak obok pliku wykonywalnego gry.

Zobacz też

Struktura projektu · MeshComponent · MaterialComponent