Version:

Icon of a magnifying glass.
  Edit on GitHub

Concepts and Terms

The following terms and concepts relate to the O3DE Asset Bundler:

Asset ID All product assets are assigned an Asset ID. The asset ID consists of the source asset’s UUID plus a sub ID, which uniquely identifies a product. Sub IDs are usually generated by an asset builder. They must be stable for running in a build, and mutually exclusive. Each product should have a unique sub ID that does not change. The Asset ID data structure is defined in dev\Code\Framework\AzCore\AzCore\Asset\AssetCommon.h. See also Source GUID.

Asset Browser The Asset Browser program, which is part of the O3DE Editor, shows the current state of your assets. You can use this program to navigate through a set of assets, such as tracking which assets have been processed and which will be processed.

Asset Bundle An asset bundle consists of product assets grouped together in a single compressed file. The bundle is mounted in a O3DE game so that the assets can be loaded and used during runtime. Asset bundles are .pak files, which use the .zip file format.

Asset List An asset list contains information for product assets. This file is generated using the Asset Bundler. The information includes a fingerprint for each asset in the list. The fingerprint includes a modification time and file hash. An asset list can be generated from seed lists, individual seeds, or by using comparison operations on other asset lists. Asset list files have the file extension .assetlist. See also Seed and Seed List.

Builder An asset builder is a C++ module that is used to transform source assets into product assets. For example, a builder that handles textures might also transform a source asset PNG file to a product asset DDS file. Builders emit metadata about source and product assets, such as dependencies. For more information, see Creating a Custom Asset Builder.

Copy Job A copy job is an asset processing task that copies a source asset to the cache without modifying it. There are two ways that copy jobs occur:

  • When you are authoring a builder. If the builder emits a source asset as a product asset, the Asset Processor copies the source to the cache.
  • When using additional asset processing rules as defined in AssetProcessorPlatformConfig.ini. These additional rules can include copy jobs, and are used to copy many file types to the cache. As a best practice, create an Asset Builder for your assets so you can add product dependencies. While it’s easy to add copy jobs to AssetProcessorPlatformConfig.ini, it can be easy to forget to update files for dependencies later.

Leaf Asset A “leaf” asset is a product asset that has no dependencies on other product assets. See also Product Dependency.

Product Asset A product asset is game content that is loaded and used in the runtime game. A product asset is generated from a source asset during asset processing using a builder. The product asset is often a modified version of the source asset, such as image content that is compressed and otherwise optimized for runtime. Product assets reference their product dependencies. See also Source Asset. When running a game using the O3DE asset system, only product assets are available. The source assets are not available. This includes running the game in the O3DE Editor or in a platform-specific launcher. When packaging a game using the Asset Bundler, only product assets are bundled. Product assets are available only from the asset cache or from asset bundles. When working with slices, keep in mind that only dynamic slices can be used at run-time. Non-dynamic slices, even if they are product assets, should not be included in bundles. For more information about the asset life cycle, see Working with the Asset Pipeline and asset files.

Product Dependency A product dependency occurs when one product asset references another product asset. When bundling assets, both the referencing asset and the referenced asset should be included in the bundle. Dependencies are created by referencing the Asset ID of the product asset. See also Source Dependency. Product dependencies are generally relevant during asset packaging and bundling. With product dependencies established, bundling becomes the task of “shipping game level 1 and everything it references”. For example, you have a character that is spawned through a dynamic slice. This character has a model, and the model has a material, which has a texture. In this scenario, the material needs the texture loaded to work, so the material has a product dependency on the texture. The model needs the material loaded to work, so the model has a product dependency on the material. The character needs the model loaded to work, so the dynamic slice for the character has a product dependency on the model. When bundling, you can include the character and expect that all dependencies are included.

Runtime A standalone game is referred to as the runtime. It can be run through a platform-specific launcher or in the O3DE Editor. A runtime uses the O3DE asset system to access only those product assets that were bundled with the game.

Scan Folder Scan folders are scanned for assets during game runtime. A set of scan folders are designated in the AssetProcessorPlatformConfig.ini file. Scan folders are defined when the Asset Processor starts. They cannot be added, removed, or renamed during runtime.

Seed A seed is a product asset added to a seed list. Defining a product asset as a seed can make bundling assets or mounting into a game runtime more efficient. Seeds can also be useful when validating or debugging an asset bundle, such as using “seed mode” in the Asset Validation Gem to track asset dependencies. See also Seed List.

Seed List A seed list is a .seed file containing a collection of seeds for the bundling system to place into an asset list. Seed lists are also used to build asset dependency charts. See also Asset List File. For simple game packages, seed lists are commonly used with level files. For example, you have a game with three levels. Levels 1 and 2 are production levels, and the other is the development test level. You want to ship your game with the two production levels and all files referenced by them. You can use the Asset Bundler to create a MyGame.seed asset list file, and then add your Level 1 and Level 2 product assets as seeds to this file.

Source Asset A source asset is an instance of an asset that is not associated with a specific product. When working with an asset, you edit the source asset and then use an asset builder to generate a product-specific instance of the asset. When authoring edit-time code, you may need to access editor-only product assets or source assets. If your logic is actually editing a file, use the source asset. If your logic is only reading the file, use the editor-only product asset in the asset cache. Source assets are stored in the source asset folder, usually under dev\ProjectName\.

Source Dependency A source dependency occurs when one source asset references another source asset. Source assets list each dependency by referencing the ID of the source asset. See also Product Dependency. In general, source dependencies are relevant during content creation at edit time and when developing tools pipelines. Source dependencies are used in the following scenarios:

  • When an asset is changed, all assets that depend on the changed asset must be updated.

    An asset won’t process until all of the source assets that it depends on finish processing. For example, you’re working with models and materials. Model source assets depend on material source assets. However, the product asset for the model does not need a corresponding product asset for the material. In this scenario, the relevant material must be generated before processing the model source asset, which is an FBX file, to output the product asset as a CGF file.

Source GUID A source GUID is used to identify assets. It is generated by hashing the path-relative to the scan folder-of the source asset file. It is technically a UUID value, but is commonly referred to as a GUID. See also Asset ID. Source assets are associated with a gem, and source GUIDs are unique within a gem’s set of assets. It is possible for source assets from different gems to have the same GUID, if they have the same relative path, file name, and extension. When referencing a source GUID, the file from the highest priority scan folder is returned for all queries and copied to the cache.

Relative Paths Some of the O3DE tool operations take relative paths as inputs. There are two types of relative paths:

  • Cache-relative paths - Tells various systems where to find pre-processed assets in your asset cache. Each O3DE tool that uses cache-relative paths will be relative to a different subdirectory of the asset cache. For example, a cache-relative path from the absolute path C:\O3DE\dev\Cache\SamplesProject\pc\samplesproject\levels\samples\advanced_rinlocomotion\level.pak that does not include the platform and project would be levels\samples\advanced_rinlocomotion\level.pak.
  • Engine-root-relative paths - Specifies files located in directories under C:\O3DE\dev\. For example, an engine-root-relative path lets you represent the location C:\O3DE\dev\SamplesProject\textures\UIEditor_Sample\ButtonNormal.tif as SamplesProject\textures\UIEditor_Sample\ButtonNormal.tif. For more information, see Asset IDs and File Paths.