descriptor.md

linkTitle	title	description	weight	toc
Descriptor	Python Asset Builder Descriptor	The Python Asset Builder registers the builder with Asset Processor in Open 3D Engine (O3DE).	200	true

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.

Field	Type	Description
busId	azlmbr.math.Uuid	The universal unique ID (UUID) for the Asset Builder.
name	String	The name of the Asset Builder.
patterns	List[azlmbr.asset.builder.AssetBuilderPattern]	The collection of file patterns that the Asset Builder can process.
version	Number	The 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. {{< /note >}}

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.

Field	Type	Description
type	azlmbr.asset.builder.AssetBuilderPattern Type	The type of the asset pattern: azlmbr.asset.builder.AssetBuilderPattern_Wildcard or azlmbr.asset.builder.AssetBuilderPattern_Regex.
pattern	String	The 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.

Type	Description	Input	Output
RegisterAssetBuilder	Registers an Asset Builder using a builder Descriptor.	azlmbr.asset.builder.AssetBuilderDesc	Outcome_bool
GetExecutableFolder	Returns 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.

Handler	Description	Input	Output
OnCreateJobsRequest	Callback function type for creating jobs from job requests.	Tuple(azlmbr.asset.builder.CreateJobsRequest)	azlmbr.asset.builder.CreateJobsResponse
OnProcessJobRequest	Callback function type for processing jobs from process job requests.	azlmbr.asset.builder.ProcessJobRequest	azlmbr.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()