Buildify – Creating Custom Sellable Assets

Salepage : Buildify – Creating Custom Sellable Assets
Archive : Buildify – Creating Custom Sellable Assets Digital Download
Delivery : Digital Download Immediately

Creating a PDF using a Custom Asset Builder

You may use the Asset Builder SDK to create an asset builder that converts your custom asset type source files into game-ready files. This subject demonstrates how to design your own asset builder using the Lumberyard example asset builder.

To make a builder for a custom asset type, follow these steps:

1. Create Builder Classes – Create one or more builder classes that will be used to construct the object. The classes must implement the necessary callbacks and handle Asset Processor shutdown notifications.

2. Build a Lifecycle Component – Build a lifecycle AZ::Component that registers all of your builder classes. The lifecycle component offers information to Asset Processor to ensure that the relevant asset builder is run for a file.

3. Tag Components for Builder Mode – Use the AssetBuilder tag to guarantee that your lifecycle component and any accompanying AZ::Component instances are engaged in builder mode.

4. (Optional) Enable Message Logging – To log builder-related messages or errors, use the BuilderLog() method and standard AZ Trace macros.

This item explains how to construct builder classes, register your builder, tag your components, and add message logging to your builder.

Resources for Builders

This subject is based on the following materials, all of which are provided with Lumberyard:

Lumberyard Asset Builder SDK – With the Asset Builder SDK, you can create bespoke asset processing tools. The source code may be found in the directory: lumberyard versiondevCodeToolsAssetProcessorAssetBuilderSDKAssetBuilderSDK
CustomAssetExample gem – This gem contains example custom asset builder code. The gem’s builder-related source files may be found in the following directory: lumberyard versiondevGemsCustomAssetExampleCodeSourceCustomAssetExampleBuilder\sPrerequisites

This article assumes you are familiar with Lumberyard Gems, AZ::Modules, and AZ::Components. The following section provides a basic summary of asset builders found within gems.

Inside Gems Asset Builders

Modules are divided into two types in gems:

gem name.dll is a runtime module.
A utilities module: gem name.Editor.dll

These modules include both system and tool components. When Lumberyard starts, an AZ::ComponentApplication activates all essential system components for the project’s gems.

1. Develop Builder Classes

You must implement one or more builder classes in order to establish an asset builder. You may make a builder class by following these steps:

A. Include the CreateJobsFunction Callback Function in your code.

B. Declare Source File Dependencies (Optional)

C. Declare Job Dependencies (Optional)

D. Handle Platform-Specific Cases (Optional)

E. Use the ProcessJobFunction Callback.

F. Declare Product Dependencies (Optional)

G. Declare Product Path Dependencies (Optional)

Create a JobCancelListener if desired.

I. Completely shut down

Each builder class necessitates the use of two callback functions: one for CreateJobFunction and one for ProcessJobFunction. These callbacks are used by Asset Processor to connect with your builder class.

The lumberyard versiondevGemsCustomAssetExampleCodeSourceBuilderCustomAssetExampleBuilderWorker.cpp file contains an example builder class code.

A. Include the CreateJobsFunction Callback Function in your code.

In most circumstances, you should create a JobDescriptor for each supported platform’s processing task. Then, in the CreateJobsFunction callback, add the JobDescriptor to the CreateJobsResponse list.

Remember the following:

Lumberyard Editor blocks on startup until all callbacks for CreateJobFunction have completed to guarantee that necessary files are included. Because of this starting limitation, we recommend that your code execute as little work as possible during the CreateJobsFunction callback. Use the ProcessJobFunction callback for heavy processing work.
You can add arbitrary key-value pairs to the JobDescriptor.m jobParameters field for further flexibility. The key-value pairs are saved and passed to the ProcessJobsFunction callback. You may save information acquired during the CreateJobsFunction callback in these key-value pairs and then give it as parameters to the ProcessJobsFunction callback.
Asset Processor checks the JobDescriptor that you generate with the JobDescriptors that were created in the previous iteration to eliminate stale products. JobDescriptors with the same input source files, PlatformInfo value, and job key are compared by Asset Processor.
You don’t have to worry about whether a JobDescriptor you build has to be handled later. Instead, for each enabled platform, generate all potential tasks for a certain input asset at each iteration.

See the CustomAssetExample::ExampleBuilderWorker::CreateJobs() function in the CustomAssetExample gem for an example of a CreateJobsFunction callback.

B. Declare Source File Dependencies (Optional)

You can use the Asset Builder SDK to declare dependencies between source files. Any file in the project directory or directories can be used as a source file. They do not have to be source files that a builder consumes.

Declaring Dependencies on Assets

Declare dependencies by adding them to m sourceFileDependencyList in the CreateJobsResponse structure in the CreateJobsFunction callback in your builder class.

Remember the following:

Declaring dependencies on a source file implies that the data in its output will change if the files on which the source file is dependent change. If any of the source dependency files are modified, Asset Processor reprocesses the dependent files by calling the CreateJobsFunction and ProcessJobsFunction callbacks.
Asset Processor recursively handles source file dependencies. You do not need to recursively traverse the full tree of dependencies if the source files downstream emit their own dependencies when queried. Asset Processor handles the rest by emitting your local dependencies for each node in the tree.
You do not need to add metafiles such as *.assetinfo files as dependencies because they are special case files that cause your asset to rebuild automatically.
Paths vs. UUIDs for Source Files

m sourceFileDependencyPath and m sourceFileDependencyUUID are properties of the SourceFileDependency structure. Only one of these fields must have a value in your builder class.

Remember the following:

If the builder knows the UUID of the file to add as a dependency inside the CreateJobs method, he or she can simply fill in the m sourceFileDependencyUUID field. Otherwise, the builder must provide the m sourceFileDependencyPathfield with the appropriate source dependency file path.
Path dependencies are classified into two types, as indicated by m sourceDependencyType. These are Absolute and Wildcard. Absolute dependencies only process files that exactly match the provided path. Wildcard dependencies allow the use of * and % characters in asset paths to match any number of characters. The use of Wildcard can lengthen asset build times, so use it sparingly.
The m sourceFileDependencyPath field accepts both absolute and relative file paths. If a relative path is specified, the appropriate overriding asset, if it exists, is used.
The specified path must be relative to one of the watched directories if the builder uses a relative file path for the m sourceFileDependencyPath field. If the source and the source dependency file are both in the same directory, you can provide the file name without specifying a path.

See the CustomAssetExampleBuilderWorker::CreateJobs() function in the CustomAssetExample gem for an example of adding dependencies inside a CreateJobsFunction callback.

C. Declare Job Dependencies (Optional)

You can declare that your custom asset build is dependent on another job registered with the Asset Processor using the Asset Builder SDK. Job dependencies are determined by either the fingerprint of changes in another job or the successful completion of a job.

Job Dependencies Types

The AssetBuilderSDK distinguishes two types of job dependencies:

JobDependencyType value passed to AssetBuilderSDK constructor:

JobDependency objects. The dependency type is saved in the created object’s m type member. These are the two kinds:

When the job on which it is dependent is reprocessed, the fingerprint dependency causes the job to re-run, and the artifacts generated by the dependent job change according to its fingerprint definition. Fingerprint definitions can include any information, but the state of the source file is always included. As a result, fingerprint dependencies are a subset of source file dependencies.
Order: The Order dependency causes a job to be processed whenever the job on which it is dependent finishes, regardless of whether any artifacts or fingerprints have changed. Using order dependencies reduces the ability to parallelize asset build tasks, so use them sparingly.
Declare Employment Dependencies

Adding job dependencies is accomplished by attaching JobDependency objects to an existing JobDescriptor via the m jobDependencyList member. For instance, to include a Fingerprint dependency on the test. For the job key, an example source file for the ExamplePlatform platform Job as an example:

Descriptor for AssetBuilderSDK::JobDescriptor; descriptor.m jobKey = “Example Job”; / Key for matching dependent jobs descriptor.

SetPlatformIdentifier(“ExamplePlatform”)); / Identifier of the platform for matching dependent jobs.

sourceFile.m sourceFileDependencyPath = “test.example”; / Source file processed by dependent jobs AssetBuilderSDK::SourceFileDependency sourceFile; sourceFile.m sourceFileDependencyPath = “test.example”;

jobDependency(descriptor.m jobKey, “ExamplePlatform”, AssetBuilderSDK::JobDependencyType::Fingerprint, sourceFile ); descriptor.m jobDependencyList.push back(jobDependency);

response.m createJobOutputs.push back(descriptor);

D. Handle Platform-Specific Cases (Optional)

CreateJobsRequest provides helper functions for platform-related operations. These helper functions can be used to construct the output JobDescriptor for a specific enabled platform.

See Configuring the Asset Pipeline for more information on declaring, enabling, and disabling platforms.

The Asset Builder SDK includes the following functions. See lumberyard versiondevCodeToolsAssetProcessorAssetBuilderSDKAssetBuilderSDKAssetBuilderSDKAssetBuilderSDKAssetBuilderSDKAssetBuilderSDKAssetBuilderSDKAssetBuilderSDKAssetBuild

HasPlatform(const char* platformIdentifier) – Returns whether the specified platform is enabled for this CreateJobsRequest for the specified platform identifier. The platform identifier is data-driven and user-configurable. Typically, it is a string representation of the platform name (for example, “pc” or “osx”).
HasPlatformWithTag(const char* platformTag) – Returns whether Lumberyard has any enabled platforms in the CreateJobRequest that contain the specified platform tag. Data-driven tags are user-specified. They typically identify features that are not platform-specific (for example, “mobile” or “console”).
E. Use the ProcessJobFunction Callback.

When the Asset Processor receives a job for the builder class to process, it calls the ProcessJobFunction callback. The following tasks should be performed by the callback for your ProcessJobFunction:

Process the source file and complete all tasks within the temporary directory.
In the temporary directory, create at least one product file.
ProcessJobResponse should be used to register the product files.
In ProcessJobResponse, return a success value.

Remember the following:

Because the callback occurs on a worker thread, do not spawn threads in your builder class to do the work.
During the callback, avoid interacting with other threads. The JobDescriptor received by the callback is the JobDescriptor created by your builder class in the CreateJobsFunction callback.
Only create, modify, or write files in the temporary directory during the callback. You are free to use this temporary directory however you see fit. For example, you can use this directory to create intermediate files as well as final products.
When your job is completed successfully, Asset Processor copies your registered products to the asset cache. Do not directly write to the cache.

See CustomAssetExample:: for an example of a ProcessJobFunction callback.

The CustomAssetExample gem in the lumberyard versiondevGemsCustomAssetExampleCodeSourceCustomAssetExampleBuilderCustomAssetExampleBuilderWorker.cpp file contains the ExampleBuilderWorker::ProcessJob() function.

F. (Optional) Declare Product Dependencies

Product dependencies are used to indicate product files needed at runtime. An example of this kind of dependency is a mesh file that depends on a material. Product dependencies can be referred to by AssetId, path to the source file, or the path to the product. This section describes adding product dependencies based on AssetId references. For information about path dependencies, see the next step, declare product path dependencies.

Product dependencies based on AssetId are represented by ProductDependency objects, and may also have an associated 64-bit field flag for metadata. JobProduct objects are assigned dependencies by adding them to the JobProduct.m_dependencies member. If a job’s dependencies have their own dependencies, they’re correctly handled by the Asset Bundler.

G. (Optional) Declare Product Path Dependencies

For situations where you can’t use an AssetId to define a product dependency, use either the source or product path to define a product dependency.Where possible, use the AssetId reference system. Product dependencies defined by paths are intended for use with legacy systems and third party tools that don’t integrate properly with the AssetId system.

Path dependencies are created as ProductPathDependency objects. These objects are constructed with the ProductPathDependencyType and the string representing the file’s path. Path dependencies can be absolute or relative. They are identified either as ProductPathDependencyType::SourceFile for files located in the source folder, or ProductPathDependencyType::ProductFile for product files stored in the cache.

Paths can include the * wildcard character, which matches any number of characters. Wildcards can introduce performance penalties as the Asset Processor evaluates all files of the given ProductPathDependencyType to see if they match the pattern. Additionally, wildcard dependencies are never considered to be resolved and are re-evaluated on each run of the Asset Processor.

JobProduct objects are assigned path dependencies by adding them to the JobDescriptor.m_pathDependencies member.

You can check to see if path dependencies have been resolved by opening the sqlite database in the cache and examining the ProductDependencies table. Unresolved dependencies will have their path in the UnresolvedPath field.

More from Categories : Ecommerce & Selling on Amazon, Funnel Marketing