Asset import¶
Source assets (glTF models, PNG and JPEG images, Slang shaders) are made for artists; a game wants its own formats, ready to load. Importing turns one into the other and keeps the result, so that it is done once, not at every start.
Apogee.Runtime --import Samples/Mods/res # import what changed (in the folder's imported/)
Apogee.Runtime --import Samples/Mods/res --force # import everything again
./build.sh pack Samples/Mods/res Bin/data/game.pack --cooked # pack the artifacts instead of the sources they replace
What it makes¶
| Source | Artifact | |
|---|---|---|
.glb, .gltf |
imported/<path>.amodel |
the model as the engine uses it (ModelFile): vertex and index buffers compressed with meshoptimizer's lossless codecs (the geometry comes back bit for bit), the textures embedded as GPU-compressed KTX 2 files (below), the rest plain fields. Loads without a glTF parser or any image decoding |
.slang |
imported/<path>.ashader |
a shader module compiled ahead of time (ShaderBundle, Graphics): SPIR-V (Vulkan) and Metal shading language for each entry point, and the reflection, for the module without defines and for each <Variant> of its settings. A module with no [shader(…)] entry point (a library such as common.slang) is not an asset; it is a dependency of every shader that imports it, so editing it imports those shaders again |
.png, .jpg, .jpeg |
imported/<path>.ktx2 |
a KTX 2 file with its whole mip chain: Basis Universal UASTC blocks (below), or with compression="none" 8-bit RGBA (Ktx2Writer). Either way the levels are supercompressed with zstd, which libktx inflates when it loads |
imported/index.xml says which source each artifact came from and which other files it was made from (a glTF's .bin and its textures):
<Imports version="1">
<Import source="models/car.gltf" artifact="imported/models/car.gltf.amodel" key="9c1e…">
<Dependency path="models/car.bin"/>
<Dependency path="models/wood.png"/>
</Import>
</Imports>
An image that a model reads is part of that model and is not imported on its own. Files and folders whose name starts with a dot, and the imported folder itself, are never imported.
GPU texture compression¶
Textures are cooked to Basis Universal UASTC inside KTX 2: one file for every platform, which Ktx2Loader transcodes when it loads to what the GPU samples (BC7 on desktop, ASTC 4x4 on mobile and Apple, RGBA8 where
neither exists; TextureCaps says which). The encoder is the one in libktx (KTX-Software 4.4.2, Native libraries); BasisEncoder drives it:
- Colour and data maps: UASTC level 2 (the default speed/quality trade-off) with RDO at quality 1.0, which shapes the blocks so that zstd squeezes them further, then zstd level 18 over the levels.
- Normal maps (a material's normal texture inside a model, or an image whose settings say
normalMap="true"): UASTC level 3, no RDO, and linear whateversrgbsays: errors in a normal show as lighting noise, so these take the slower and more accurate settings. They stay RGB, so shaders read them as they always did. (libktx has a "normal map" mode that keeps two channels as RRRG, which would need the shaders and a BC5 target to go with it; it is not used.) - sRGB or linear is written in the file (the data format descriptor's transfer function);
ContentLoaderreads it from there, so a caller cannot get it wrong. The mip chain is the one the importer built (sRGB averaged in linear light). - A texture with a side under 4 pixels stays RGBA8 (a block would be bigger than the texture).
compression="none"in the settings keeps RGBA8 for anything, such as a UI image that must not show block artifacts. - The encoder is deterministic (the same bytes on any number of cores) and slow, which is what the import cache is for: nothing is encoded again until the image, its settings or the encoder settings (part of the importer's fingerprint) change.
Measured on the 11 MB BoomBox.glb sample (four 2048 x 2048 PNGs; Linux, 28 threads, Release):
RGBA8 + zstd (compression="none") |
UASTC (the default) | |
|---|---|---|
.amodel artifact |
11.7 MB | 5.5 MB (5.2 MiB) |
in a --cooked pack |
11.7 MB | 5.5 MB |
| textures on the GPU (all levels) | 85.3 MiB | 21.3 MiB (BC7: 4x less) |
| first import | 1.0 s | 18.7 s (139 s of CPU) |
| import with nothing changed | 0.07 s | 0.07 s |
The artifact used to be about the size of its source; now it is half, and a GPU holds a quarter of the memory.
When something is imported again¶
Each artifact has a key: the SHA-256 of the importer's version, the asset's .import.xml settings, the asset itself, and every file the import read for it. --import makes an artifact
again only when its key is different, so changing a texture of a model, or a model's buffer, re-imports the model, and touching nothing re-imports nothing. An artifact whose source is
gone is deleted. A failed import (a file that is not a PNG, a settings file that is wrong) is reported with its file, does not stop the others, exits with code 2, and leaves the artifact the
game had (and its index entry) until the source is fixed.
UIDs and the key¶
Importing also gives each asset a UID in its .import.xml (<Import uid="uid://…"/>, made if there is no sidecar) and lists them in imported/assets.xml. The uid attribute is not part of the key
(ImportSettings.KeyText leaves it out), so a UID that is added, or that changes, imports nothing again.
Settings¶
An <asset>.import.xml next to an asset (checked against the engine's schema) changes how it is imported; every attribute is optional:
<Import srgb="false" mips="false" optimize="false"/>
srgb (default true) is for images: colour maps are sRGB, normal maps, roughness and masks are linear. mips (default true) builds the mip chain. compression is uastc (the default) or none, for images
and for the textures of a model; normalMap (default false) says that an image is a normal map (linear, encoded for accuracy). optimize (default true) is for models: merge duplicate vertices and reorder for the GPU's
vertex cache. A model's textures take their sRGB or linear setting, and whether they are normal maps, from how its materials use them.
For a shader, <Variant> children each list the preprocessor defines of one more version to compile (the version with no defines is always compiled); the shader is loaded in a variant by passing the same defines to ShaderLibrary.Load:
<Import>
<Variant><Define name="SHADOWS"/><Define name="QUALITY" value="3"/></Variant>
</Import>
Loading¶
ContentLoader is what a game calls: it takes the artifact when there is one and the source otherwise, so the same call works in the editor (sources), in a development run that has imported
(artifacts) and in a shipped game (artifacts in a pack). A mod's files are not imported by the game, but a mod may be imported as a folder of its own and ship its imported/ (a mod that brings compiled
shaders does); the loader finds it at mod://id/imported:
var content = new ContentLoader(files);
ModelData car = content.LoadModel("res://models/car.gltf");
TextureData ground = content.LoadTexture("res://textures/ground.png", srgb: true, caps);
It does not check that an artifact is current: importing is the step that does (and hot reload, in the editor, runs it when a file changes). The textures of an imported model or image are transcoded for the GPU in ContentOptions.TextureCaps / the caps argument, as those of a source model are.
Packing¶
--pack … --cooked leaves out every source that has an artifact, the files it was made from and its .import.xml, and packs the rest with imported/. It needs an import first. A shipped game
therefore holds models/car.gltf.amodel and textures/ground.png.ktx2, not the glTF, the .bin and the PNGs, and ContentLoader.LoadModel("res://models/car.gltf") finds the artifact by the
path of the source it replaced.
A cooked pack also holds the authored documents (.ascene, see AuthoredAssets.Extensions) and the UID list imported/assets.xml as cooked XML, each at the path of its source, so a
shipped game parses no text for them and a UID still names its asset after the sidecar has been left out. So are the definitions of the base packages: the .xml files in the content folders
(<Content path="data"/>) of each packages/<id>/mod.xml that reads. Everything else stays as it is: other .xml files, the manifests mod.xml, schemas (.xsd), RmlUi documents, the scripts, and
everything under dev_mods/. The packing is GamePacker (Packs); --pack is a thin command on top of it. A scene or a definition file that is not well-formed XML
stops the pack, with its path and line.
Shaders¶
Shipped games never load the Slang compiler. ./build.sh aot publishes the runtime and then runs Apogee.Runtime --import on its Shaders folder, which writes Shaders/imported/*.ashader; the
renderers load those (ShaderLibrary, Rendering). In development nothing needs importing: a shader without an artifact is compiled and cached, as before. The bundle records the
engine's shader ABI, so a mod's old compiled shader is refused with "import it again" rather than crashing the driver; to make a mod's shaders, import the mod's folder with the engine's dev runtime. CI runs the published runtime
with the compiler libraries and every .slang source deleted, running the fixture game, to prove it.
Cooked XML¶
Authored XML (scenes, and later prefabs and materials) and definitions are small, but a shipped game still gains from not parsing text: a cooked file is the same document in a binary encoding, APXB, in
Apogee.Content.Xml.XmlBinary. It is not typed by the reflection registry: it holds the XmlNode tree (names, attributes in their order, text, the line each element started on, children) with every
distinct name and value stored once, so it works for any XML file, does not depend on which components the engine had when the file was cooked, and gives back exactly the tree that was written. A scene with
a thousand entities is less than half the size of its text.
| Part | What it is |
|---|---|
| Header, 16 bytes | the magic APXB, a format version (1), flags (none are defined), the number of strings and the number of elements; little-endian |
| Strings | each one a length and its UTF-8 bytes, in the order the writer first used them, so the same tree always gives the same file |
| Elements | in document order, root first: name, line, attributes (name and value), text, number of children; every number is a varint (7 bits per byte) |
byte[] cooked = XmlBinary.Write(XmlNode.Parse(text));
XmlNode again = XmlBinary.Read(cooked, "res://scenes/start.ascene"); // a ContentException if it is damaged
XmlNode either = XmlFile.Read(files, "res://scenes/start.ascene"); // text or cooked, whichever the file is
XmlFile.Read(files, path) is the one way to read an authored or definition file: it takes a file that starts with the magic as cooked (no text XML file can: those begin with <, a byte order mark or white
space) and anything else as UTF-8 text, so the same code runs on the sources in development and on the cooked files of a shipped pack. A cooked file keeps the path of its source, which is why a script that
reads it as text (fs.read_text) gets bytes, and reading it with XmlFile is the way that works for both. --pack --cooked writes it for authored documents, the definitions of the base packages and the UID list
(see Packing).
Everything in the engine that reads such a file goes through XmlFile.Read: DefDatabase (the definitions, so defs in scripts), World.LoadSceneFile (and world:load_scene_file), the asset database's UID list, and the Luau
xml.load(path), which gives scripts the table xml.decode gives for a text or a cooked file (Definitions). What is not read that way is never cooked: the package manifests mod.xml, schemas
(.xsd), .rml documents, the import index and the sidecars, game.xml, and the files of mods, which stay text because players and tools open them.
The origin of an element is not stored: the reader gives every element the path it was asked to read, so an error in a cooked file still names the file and the source line. The reader accepts the versions up to the
one it knows; a file from a newer engine, or with a flag it does not know, is refused with "cook again". A file cut short or damaged is a ContentException, never anything else, and a count in it (strings,
elements, attributes, children) is checked against the bytes that are left before the reader makes room for it, so a hostile file cannot make it allocate more than a small multiple of its own size. Nesting is
limited as in the text parser (XmlNode.MaxDepth).
AuthoredAssets.ReadUid also reads the uid of a cooked document, from its root only.
What gets cooked, and what does not (the plan)¶
A rule first: source formats always load. Mods are Luau and data, are never imported, and ship as folders or zips; the editor works on sources. So every loader keeps a source path
(as ContentLoader does), and cooking is only an optimization for the base game: a faster, sometimes smaller artifact that is a cache of the source. No format exists only cooked.
Use a standard container where there is one, and an engine format only where there is none. So no .atex: textures stay KTX 2, which the engine already reads (including GPU-compressed
data that is transcoded at load). That leaves .amodel as the one engine-specific binary so far, because glTF is an interchange format and there is no standard runtime one.
| Kind | Authored as | Cooked? | Artifact |
|---|---|---|---|
| Models | glTF | yes, done | .amodel (meshoptimizer) |
| Textures | PNG, JPEG | yes, done: Basis UASTC in KTX 2, transcoded to BC7/ASTC/RGBA8 at load | .ktx2 |
| Shaders | Slang | yes, done: SPIR-V and Metal shading language and reflection ahead of time, in one bundle (DXIL has a slot), so a shipped game does not carry the compiler | .ashader |
| Materials | XML definition (a Material type with a schema: textures by path, factors, alpha mode) |
not for now. They are small data, which mods must be able to author and patch like any definition; a model's built-in materials are already in .amodel |
none (an .amat only if profiling asks) |
| Scenes, prefabs | XML: entities and their components, written and read through the reflection registry | yes, done: APXB in place (Cooked XML): --pack --cooked writes the tree of the document as a binary file in place of the source, under the same path, so that scenes, prefabs and definitions share one format and one reader; the definitions of the base packages are cooked the same way (a mod's are not: mods are never cooked) |
binary XML (APXB), same path |
| Audio | WAV, FLAC, MP3 and Ogg Vorbis, decoded when loaded (streamed if asked) | already compressed by the formats; a cook would only trade load time for size | none |
| Scripts | Luau | no (a bytecode cache could come later; it is not needed to ship) | none |
How it grows. AssetImporter is a small registry. An importer (IAssetImporter) is a name, the extensions it takes, a fingerprint (part of the key: its version, and the versions and options of the tools it calls, such as Slang's, so
changing what it writes imports again), and a function from the source and its settings to an artifact, or to nothing for a file that is not an asset on its own. It reads files through the ImportContext, which records them as the
artifact's dependencies. new AssetImporter(files, importers) runs them in the order of the list (a file an earlier importer read is not imported by a later one); AssetImporter.Defaults is models and images and the runtime adds
ShaderImporter, which lives in Apogee.Rendering because Content does not reference Graphics. A new kind of asset is a new importer and a Load… that takes its artifact; the index, the keys, the sidecar settings, --import
and --pack --cooked stay as they are.
What is open for you to decide: whether a .amat is ever worth having. It blocks nothing.
Tests¶
Tests/Apogee.Content.Tests: GPU compression (transcoding to BC7, ASTC and RGBA8 and how close it stays, the colour space read from the file, normal maps, determinism, the sidecar, a model's textures and the caps of the loader), the registry (order, an asset that is not one, what an earlier importer read, the fingerprint, a package's own artifacts, shader variants in the settings), the KTX 2 writer read back by libktx's reader (sRGB and linear, odd sizes, one level or a chain, the data format descriptor), the model file (every field bit for
bit, deterministic, a mesh that is not a triangle list, damaged and foreign files), and the importer (artifacts and the index, nothing imported twice, a change to the source, a dependency or
the settings, deleted sources, failures that keep the old artifact, hidden folders, a damaged index, settings checked against their schema) and ContentLoader (the artifact is the one
used, a source otherwise, a mod's files). cooked XML (XmlBinaryTests: every field of a tree back, escapes and non-ASCII text, the same bytes every time, size against the text, text and cooked read alike, a newer version or a flag refused, every truncation and a thousand flipped bytes, counts that do not fit the file, nesting). Tests/Apogee.Graphics.Tests: the shader bundle (variants, damaged files, another ABI, backends that are not written yet). Tests/Apogee.Rendering.Tests: the shader importer and ShaderLibrary (dependencies, variants, the compiler never started when an artifact exists, no compiler no artifact, a mod's artifacts). Tests/Apogee.Runtime.Tests runs --import and --pack --cooked end to end, for shaders too.
Status and re-importing one asset¶
AssetImporter.StatusOf("models/car.glb") says where one asset stands (AssetStatus: NotImportable, NotImported, UpToDate, or Stale when the file, its .import.xml or what the import read changed) and Reimport(source)
imports just that asset again, leaving the rest of the index as it is. The editor's asset browser uses them.