Resources & Assets

By convention, production files are called resources (eg. the project resources).

Files issued from the compilation of production files for a specific target are called assets (eg. the project assets for Windows PC).

Resource Formats

During development resources are stored in production formats, these formats are meant for editing. Before they can be loaded at runtime, resources must be compiled into their runtime formats as assets specific to the target platform.

To compile a project resources use:

assetc <project_resources_folder> [<optional_project_assets_folder>]

If no output folder is specified the input folder suffixed with _compiled is implied.

Upon execution the assets compiler will scan the input folder and compile all supported resource types to assets. Unsupported resources are copied untransformed to the output folder.

The following table lists all supported resource types, their production and runtime formats.

Resource TypeProduction FormatRuntime Format
Texturejpg, png, tga, gif, bmp, psd, hdr, pic, pnmPlatform-specific (eg. RAW, ETC1, ETC2, BCx as DDS, PVR or TEX)
ShaderGLSL-like meta languagePlatform-specific (eg. HLSL, GLSL)
Pipeline ShaderGLSL-like meta languageSet of platform-specific shaders (eg. HLSL, GLSL)
GeometryIntermediate binary formatPacked index/vertex buffers
LuaLua scriptLua bytecode as generated by luac
PhysicsJSON descriptor (see Physics)Backend specific binary
PathfindingJSON descriptor (see Navigation)Backend specific binary

One resource file may compile to multiple asset files.

For more information, see Compiling to Assets.

Fine-tuning Resource Compilation

Most production formats need to be extended with additional information to control the compilation process. The asset compiler will look for an optional parameter file associated with each resource it compiles.

These parameter files are JSON dictionaries of key-value named as the resource file they extend suffixed with the .meta extension. The following table lists supported keys per resource type.

Texture

KeyDescriptionPossible ValuesDefault Value
typeHint in case a specific compression is not specified.Standard, NormalMapStandard
max-sizeResize input if any axis exceeds the specified limit.-16384
compressionExplicit compression format.RAW, BC1, BC2, BC3, BC4, BC5, BC6H, BC7RAW
generate-mipsGenerate mip levels.true/falsetrue
generate-probeFor HDR latlong envmap, generate radiance/irradiance probes.true/falsefalse

Geometry

KeyDescriptionPossible ValuesDefault Value
cook-modelGenerate a model from this geometry.true/falsetrue

Loading Assets at Runtime

All functions to load an asset type exist in at least two versions: one to load from the host filesystem and one to load from the assets packaging system. Here is a table listing both load functions for each asset type.

Asset TypeHost FilesystemAssets Packaging System
TextureLoadTextureFromFileLoadTextureFromAssets
ShaderLoadProgramFromFileLoadProgramFromAssets
Pipeline ShaderLoadPipelineProgramFromFileLoadPipelineProgramFromAssets
ModelLoadModelFromFileLoadModelFromAssets
Pathfinding[LoadNavMeshFromFile][LoadNavMeshFromAssets]

Notice the change from the Geometry resource type to the Model asset type. A geometry holds much more information than its model counterpart which is optimized to only carry essential informations for displaying the input geometry accurately at runtime.

When loading an asset from the host filesystem, you can use its absolute or relative path. When using relative path the host filesystem lookup rules apply.

It is recommend to not load assets from the host filesystem as it might make it harder to properly locate assets on disk.

A better option is to use the assets packaging system, a virtual filesystem to which you can connect multiple data sources:

  • A folder from the host filesystem, sandboxed with only its content and the content of its subfolders accessible.
  • A zip archive to store assets as a single file on disk.

See AddAssetsFolder/RemoveAssetsFolder and AddAssetsPackage/RemoveAssetsPackage.

Refer to Compiling to Assets for how to compile resources to assets.