Scan Directories

The entry point into the Asset Pipeline is to place a source asset into a scan directory. Scan directories are monitored by Asset Processor for new and updated source assets and asset dependencies.

The system paths to the scan directories are dependent on your project and O3DE configuration and installation. The list of directories below is in descending order of precedence. Source assets in your project directory override source assets in the Gems and Engine directories with the same relative path.

By default, the Asset Processor monitors the following scan directories:

1. Project - The project root directory and subdirectories contain source assets specific to the project.

2. Gems - The directories of Gems that have been added to your project might contain source assets including example assets and critical assets.

3. Engine & Editor - The root directory and subdirectories of the engine and editor contain assets that are generally labeled critical and are required to run O3DE Editor and Launcher.

4. Intermediate Assets - The root directory for intermediate assets which are output by other sources. These files should be treated like the Asset Cache, they are generated files which should not be modified, and do not need to be tracked by source control.

Additional scan directories can be added with registry keys. In most cases it’s better to use Gems as a way to store source assets in additional locations instead of adding scan folders by registry key.

Scan directory locations

The engine, the project, and individual Gems can be installed in any location accessible on a user’s machine. These may not even be the same locations for multiple contributors to the same project. For example, one user may choose to install the project, engine, and all Gems on the same drive, the C drive. Another contributor may choose to mix these across several drives, putting the project on the C drive, the engine on the D drive, some Gems on the E drive, and more Gems on the F drive.

Files in scan directories

Scan directories provide the entry point for asset builders to read files as source assets, for generating product assets into the asset cache.

A file being in a scan directory does not automatically become a source asset. Source assets are files in scan directories that have had jobs created for them. Otherwise, these files are called non-asset source files. A non-asset source file will not have a UUID to identify it, and can only be referenced by path.

Referencing files in scan directories

There are three core points during development where it may be necessary to reference and potentially load a file that is in a scan directory.

In all cases, it’s important to make sure dependencies are accurate for all assets.

From asset builders

When authoring asset builders, loading the primary source asset used by the builder is straightforward. The create jobs and process job functions each have a parameter with the path to the relevant source asset.

Sometimes it may be necessary to load additional files besides the primary source asset within these builders. See this documentation on loading other files for details on handling these situations.

From external tools

In many cases, the files intended to be source assets that will be placed into scan folders, are authored by tools external to O3DE. In some cases, these may be standard, portable file formats generated by many different external tools, such as FBX files. In other cases, these may be files generated only by a specific tool. In either case, the asset builder authors may not have the ability to modify the source file format.

When building out the pipeline, ideally the source asset file format can be designed to avoid relative paths or absolute paths to other files.

When this can’t be done, such as with an existing file format like FBX files referencing textures in materials, then these paths will need to be resolved in some fashion during the asset builder process. Sometimes these paths will be absolute paths from the machine that generated the source asset. Sometimes they will be relative paths that only resolve correctly on the machine that generated the source asset. How to handle this will often come down to specifics about the asset builder being authored, however the most common solution is to ignore all of the path information to the referenced asset except the filename and extension, and then search for a file matching that in the same directory as the asset being processed, dropping the reference entirely if the referenced file isn’t found there.

From in-editor tools

In most cases, when authoring an in-editor tool that reads and writes source assets, the file format can be fully controlled by the author. In this case, when referencing another asset, the author should keep in mind potential pathing issues when one asset references another. In other cases, if the in-editor tool is loading an pre-existing file format that can’t be modified, see the previous section on handling file references from external tools.