This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

Python Asset Builder Descriptor

The Descriptor provides Asset Processor the information required to identify the Python Asset Builder so that it can invoke callbacks for the Create Jobs and Process Job events. It also registers the file patterns for the source file types the Python Asset Builder can process. To register a Python Asset Builder, define a function to create an Asset Builder Descriptor (azlmbr.asset.builder.AssetBuilderDesc) and register the Python Asset Builder (azlmbr.asset.builder.PythonAssetBuilderRequestBus).

Asset Builder Descriptor

azlmbr.asset.builder.AssetBuilderDesc is a class that provides four fields that describe the Python Asset Builder to Asset Processor.

FieldTypeDescription
busIdazlmbr.math.UuidThe universal unique ID (UUID) for the Asset Builder.
nameStringThe name of the Asset Builder.
patternsList[azlmbr.asset.builder.AssetBuilderPattern]The collection of file patterns that the Asset Builder can process.
versionNumberThe version number of the Asset Builder.
Note:
Asset Processor uses the UUID and version of the Asset Builder to track product assets and jobs produced by the Asset Builder. If the UUID or version number are modified, all jobs that were previously processed by the Asset Builder are reprocessed. Increment the version value when the Asset Builder is modified to ensure all assets are reprocessed with the latest Asset Builder.

Create a UUID

The busId field is a UUID used by Asset Processor to identify and track process jobs from the Asset Builder. It’s also used to generate the sub ID for product assets generated by the Asset Builder. Changing the UUID triggers all source assets that have been previously processed by the Asset Builder to be reprocessed. You can use the uuid Python module to generate a UUID for the busId field.

> python
>>> import uuid
>>> uuid.uuid4()
UUID('639f403e-1b7e-4cfe-a250-90e6767247cb')

Register file patterns

The patterns field is an AssetBuilderPattern list that specifies what asset types the Asset Builder can process. Patterns can be wildcards with file extensions such as *.myasset, or file and folder regular expressions such as ^[a-zA-Z]:\\MyAssets[\\\S|*\S]?.*$).

azlmbr.asset.builder.AssetBuilderPattern is a structure that defines which type of pattern to use for source assets.

FieldTypeDescription
typeazlmbr.asset.builder.AssetBuilderPattern TypeThe type of the asset pattern: azlmbr.asset.builder.AssetBuilderPattern_Wildcard or azlmbr.asset.builder.AssetBuilderPattern_Regex.
patternStringThe file path pattern to use.

Register the Python Asset Builder

The Python Asset Builder has to be registered so that Asset Processor is aware of it, and so that it can respond to Create Jobs and Process Job events for supported asset types.

To register the Asset Builder, bind the script to the asset building process with azlmbr.asset.builder.PythonAssetBuilderRequestBus. When the Python Asset Builder is successfully registered, create an azlmbr.asset.builder.PythonBuilderNotificationBusHandler.

azlmbr.asset.builder.PythonAssetBuilderRequestBus is a singleton EBus that serves methods to enable Python Asset Builders.

TypeDescriptionInputOutput
RegisterAssetBuilderRegisters an Asset Builder using a builder Descriptor.azlmbr.asset.builder.AssetBuilderDescOutcome_bool
GetExecutableFolderReturns the current executable folder.Outcome_string

Add notification bus handlers

The notification bus handler is used by the Asset Builder to handle Create Jobs and Process Job events. The handler must be created in the global module scope so that the callbacks can stay active.

Create an azlmbr.asset.builder.PythonBuilderNotificationBusHandler. Connect the Asset Builder’s busId to the notification bus handler, and provide the callback handlers for Create Jobs and Process Job.

HandlerDescriptionInputOutput
OnCreateJobsRequestCallback function type for creating jobs from job requests.Tuple(azlmbr.asset.builder.CreateJobsRequest)azlmbr.asset.builder.CreateJobsResponse
OnProcessJobRequestCallback function type for processing jobs from process job requests.azlmbr.asset.builder.ProcessJobRequestazlmbr.asset.builder.ProcessJobResponse

Example: Registering the Python Asset Builder

This example below defines a complete Descriptor and registers a Python Asset Builder.

import azlmbr.asset
import azlmbr.asset.builder
import azlmbr.bus
import azlmbr.math

busId = azlmbr.math.Uuid_CreateString('{CF5C74D1-9ED4-4851-85B1-9B15090DBEC7}', 0)

def on_create_jobs(args):
    # TODO: create jobs logic.
    return azlmbr.asset.builder.CreateJobsResponse()

def on_process_job(args):
    # TODO: process job logic.
    return azlmbr.asset.builder.ProcessJobResponse()

# register asset builder
def register_asset_builder():
    assetPattern = azlmbr.asset.builder.AssetBuilderPattern()
    assetPattern.pattern = '*.newasset'
    assetPattern.type = azlmbr.asset.builder.AssetBuilderPattern_Wildcard

    builderDescriptor = azlmbr.asset.builder.AssetBuilderDesc()
    builderDescriptor.name = "New Asset"
    builderDescriptor.patterns = [assetPattern]
    builderDescriptor.busId = busId
    builderDescriptor.version = 1

    outcome = azlmbr.asset.builder.PythonAssetBuilderRequestBus(azlmbr.bus.Broadcast, 'RegisterAssetBuilder', builderDescriptor)
    if outcome.IsSuccess():
        # created the asset builder to hook into the notification bus
        h = azlmbr.asset.builder.PythonBuilderNotificationBusHandler()
        h.connect(busId)
        h.add_callback('OnCreateJobsRequest', on_create_jobs)
        h.add_callback('OnProcessJobRequest', on_process_job)
        return h

# the module global asset builder handler
handler = register_asset_builder()