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
| Extension | AssetType | Loader |
|---|---|---|
.thread | Scene | YAML scene file — entities, components, skybox. |
.png .jpg .jpeg .tga .hdr .bmp | Texture | stb_image. Decoded into a GPU texture by AssetManager (compressed to .ttex where the project does that). |
.obj .fbx .gltf .glb | Mesh (source) | Assimp. Editor-only — runtime prefers .tmesh. |
.tmesh | Mesh (compiled) | Binary VBO+IBO+submesh table. memcpy load, no parsing. |
.tmaterial | Material | YAML with Albedo / TexturePath / Tiling. Edited in the Material Node Editor. |
.wav .ogg .mp3 | Audio | WAV: built-in parser. OGG: stb_vorbis. MP3: minimp3. |
.anim | Animation | Baked YAML keyframes. FBX animations are imported via Assimp. |
.h | Script | A 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. |
.system | System | SceneSystem registration descriptor. |
.ui | UIAsset | UI 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.pakarchive.
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
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
| Rozszerzenie | AssetType | Loader |
|---|---|---|
.thread | Scene | Plik sceny YAML — encje, komponenty, skybox. |
.png .jpg .jpeg .tga .hdr .bmp | Texture | stb_image. AssetManager dekoduje do tekstury GPU (kompresowanej do .ttex tam, gdzie projekt to robi). |
.obj .fbx .gltf .glb | Mesh (źródło) | Assimp. Tylko w edytorze — runtime woli .tmesh. |
.tmesh | Mesh (skompilowany) | Binarny VBO+IBO+tabela podsiatek. Wczytanie przez memcpy, bez parsowania. |
.tmaterial | Material | YAML z Albedo / TexturePath / Tiling. Edytowany w węzłowym edytorze materiałów. |
.wav .ogg .mp3 | Audio | WAV: wbudowany parser. OGG: stb_vorbis. MP3: minimp3. |
.anim | Animation | Wypieczone klatki kluczowe w YAML. Animacje FBX importuje Assimp. |
.h | Script | Skrypt gry albo system sceny — jeden nagłówek, klasa nazwana jak plik. Podpinany komponentem Native Script. Wygenerowany obok .cpp jest ukryty w przeglądarce. |
.system | System | Deskryptor rejestracji SceneSystem. |
.ui | UIAsset | Ukł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.