Manage asset sources and apply assets to scenes.
Asset sources provide assets like images, videos, fonts, and other media that can be applied to design blocks. This API allows registering custom asset sources, querying available assets, and applying them to scenes or specific blocks. It supports both local and remote asset sources, with extensible middleware for custom asset handling.
Event Subscriptions#
Subscribe to asset source changes and lifecycle events.
onAssetSourceAdded()#
Subscribe to asset source addition events.
engine.asset.onAssetSourceAdded((sourceID) => { console.log(`Added source: ${sourceID}`);});
Parameters#
Parameter | Type | Description |
---|---|---|
callback | (sourceID ) => void | The function called whenever an asset source is added. |
Returns#
A method to unsubscribe from the event.
(): void;
Returns#
void
Signature#
onAssetSourceAdded(callback: (sourceID: string) => void): () => void
onAssetSourceRemoved()#
Subscribe to asset source removal events.
engine.asset.onAssetSourceRemoved((sourceID) => { console.log(`Removed source: ${sourceID}`);});
Parameters#
Parameter | Type | Description |
---|---|---|
callback | (sourceID ) => void | The function called whenever an asset source is removed. |
Returns#
A method to unsubscribe from the event.
(): void;
Returns#
void
Signature#
onAssetSourceRemoved(callback: (sourceID: string) => void): () => void
onAssetSourceUpdated()#
Subscribe to asset source content change events.
engine.asset.onAssetSourceUpdated((sourceID) => { console.log(`Updated source: ${sourceID}`);});
Parameters#
Parameter | Type | Description |
---|---|---|
callback | (sourceID ) => void | The function called whenever an asset source’s contents are updated. |
Returns#
A method to unsubscribe from the event.
(): void;
Returns#
void
Signature#
onAssetSourceUpdated(callback: (sourceID: string) => void): () => void
Asset Source Management#
Register, remove, and query asset sources for different types of media.
addSource()#
Add a custom asset source with unique ID.
The asset source provides methods for finding assets, applying them to scenes or blocks, and managing asset lifecycle. All source operations are handled asynchronously.
engine.asset.addSource({ id: 'foobar', async findAssets(queryData) { return Promise.resolve({ assets: [ { id: 'logo', meta: { uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg', } } ], total: 1, currentPage: queryData.page, nextPage: undefined }); },});
Parameters#
Parameter | Type | Description |
---|---|---|
source | AssetSource | The asset source configuration. |
Returns#
void
Signature#
addSource(source: AssetSource): void
addLocalSource()#
Add a local asset source.
Local asset sources allow dynamic asset management through the add/remove methods. You can specify supported MIME types to restrict what assets can be added.
engine.asset.addLocalSource('local-source');
Parameters#
Parameter | Type | Description |
---|---|---|
id | string | Unique identifier for the asset source. |
supportedMimeTypes? | string [] | The mime types of assets that are allowed to be added to this local source. |
applyAsset? | (asset ) => Promise <undefined | number > |
applyAssetToBlock? | (asset , block ) => Promise <void > | An optional callback that can be used to override the default behavior of applying an asset result to a given block. |
Returns#
void
Signature#
addLocalSource(id: string, supportedMimeTypes?: string[], applyAsset?: (asset: CompleteAssetResult) => Promise<undefined | number>, applyAssetToBlock?: (asset: CompleteAssetResult, block: number) => Promise<void>): void
removeSource()#
Remove a registered asset source.
This permanently removes the asset source and all its associated assets. Any ongoing operations with this source will be cancelled.
engine.asset.removeSource('asset-source-id');
Parameters#
Parameter | Type | Description |
---|---|---|
id | string | The ID of the asset source to remove. |
Returns#
void
Signature#
removeSource(id: string): void
findAllSources()#
Get all registered asset source IDs.
engine.asset.findAllSources();
Returns#
string
[]
A list with the IDs of all registered asset sources.
Signature#
findAllSources(): string[]
Asset Discovery#
Search and filter assets from registered sources with advanced query options.
findAssets()#
Search for assets in a specific source with advanced filtering.
Supports pagination, text search, tag filtering, grouping, and sorting options. Results include asset metadata, thumbnails, and application context.
const result = await engine.asset.findAssets('asset-source-id', { page: 0, perPage: 100});const asset = result.assets[0];
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
query | AssetQueryData | Query options to filter and sort the search results. |
Returns#
Promise
<AssetsQueryResult
<CompleteAssetResult
>>
Promise resolving to paginated search results.
Signature#
findAssets(sourceId: string, query: AssetQueryData): Promise<AssetsQueryResult<CompleteAssetResult>>
Asset Information#
Retrieve metadata, credits, licenses, and supported formats from asset sources.
getGroups()#
Get available asset groups from a source.
Groups provide categorization for assets within a source, enabling filtered discovery.
const groups = engine.asset.getGroups(customSource.id);
Parameters#
Parameter | Type | Description |
---|---|---|
id | string | The ID of the asset source. |
Returns#
Promise
<string
[]>
Promise resolving to list of available group names.
Signature#
getGroups(id: string): Promise<string[]>
getSupportedMimeTypes()#
Get supported MIME types for an asset source.
Returns the file types that can be added to this source. An empty result means all MIME types are supported.
const mimeTypes = engine.asset.getSupportedMimeTypes('asset-source-id');
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
Returns#
string
[]
Array of supported MIME type strings.
Signature#
getSupportedMimeTypes(sourceId: string): string[]
getCredits()#
Get attribution credits for an asset source.
const credits = engine.asset.getCredits('asset-source-id');
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
Returns#
| undefined
| {
name
: string
;
url
: undefined
| string
;
}
The asset source’s credits info consisting of a name and an optional URL.
Signature#
getCredits(sourceId: string): undefined | object
getLicense()#
Get license information for an asset source.
const license = engine.asset.getLicense('asset-source-id');
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
Returns#
| undefined
| {
name
: string
;
url
: undefined
| string
;
}
The asset source’s license info consisting of a name and an optional URL.
Signature#
getLicense(sourceId: string): undefined | object
canManageAssets()#
Check if an asset source supports asset management.
Returns true if the source allows adding and removing assets dynamically, via ‘Add File’ and ‘Delete’ button on the UI. This is typically true for local asset sources and false for remote sources.
engine.asset.canManageAssets('asset-source-id');
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source to check. |
Returns#
boolean
True if the source supports asset management operations.
Signature#
canManageAssets(sourceId: string): boolean
Asset Application#
Apply assets to scenes, blocks, or specific properties with customizable behavior.
apply()#
Apply an asset to the active scene.
Creates a new block configured according to the asset’s properties and adds it to the scene.
The behavior can be customized by providing an applyAsset
function when registering the asset source.
await engine.asset.apply('asset-source-id', assetResult.assets[0]);
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
assetResult | AssetResult | A single asset result from a findAssets query. |
Returns#
Promise
<undefined
| number
>
Promise resolving to the created block ID, or undefined if no block was created.
Signature#
apply(sourceId: string, assetResult: AssetResult): Promise<undefined | number>
applyToBlock()#
Apply an asset to a specific block.
Modifies the target block’s properties according to the asset’s configuration.
The behavior can be customized by providing an applyAssetToBlock
function when registering the asset source.
await engine.asset.applyToBlock('asset-source-id', assetResult.assets[0]);
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
assetResult | AssetResult | A single asset result from a findAssets query. |
block | number | The block to apply the asset to. |
Returns#
Promise
<void
>
Signature#
applyToBlock(sourceId: string, assetResult: AssetResult, block: number): Promise<void>
applyProperty()#
Apply a specific asset property to the currently selected element.
Allows applying individual properties (like colors, fonts, or effects) from an asset
without creating a new block. The behavior can be customized by providing an applyAssetProperty
function.
const asset = assetResult.assets[0];if (asset.payload && asset.payload.properties) { for (const property of asset.payload.properties) { await engine.asset.applyProperty('asset-source-id', asset, property); }}
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The ID of the asset source. |
assetResult | AssetResult | A single asset result from a findAssets query. |
property | AssetProperty | The specific asset property to apply. |
Returns#
Promise
<void
>
Signature#
applyProperty(sourceId: string, assetResult: AssetResult, property: AssetProperty): Promise<void>
defaultApplyAsset()#
Apply an asset using the engine’s default implementation.
The default implementation already handles various different kinds of assets and acts as a good starting point.
engine.asset.addSource({ id: 'foobar', async findAssets(queryData) { return Promise.resolve({ assets: [ { id: 'logo', meta: { uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg', } } ], total: 1, currentPage: queryData.page, nextPage: undefined }); }, async applyAsset(assetResult) { return engine.asset.defaultApplyAsset(assetResult); },});
Parameters#
Parameter | Type | Description |
---|---|---|
assetResult | AssetResult | A single asset result from a findAssets query. |
Returns#
Promise
<undefined
| number
>
Promise resolving to the created block ID, or undefined if no block was created.
Signature#
defaultApplyAsset(assetResult: AssetResult): Promise<undefined | number>
defaultApplyAssetToBlock()#
Apply an asset to a block using the engine’s default implementation.
The default implementation already handles various different kinds of assets and acts as a good starting point.
engine.asset.addSource({ id: 'foobar', async findAssets(queryData) { return Promise.resolve({ assets: [ { id: 'logo', meta: { uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg', } } ], total: 1, currentPage: queryData.page, nextPage: undefined }); }, async applyAssetToBlock(assetResult, block) { engine.asset.defaultApplyAssetToBlock(assetResult, block); },});
Parameters#
Parameter | Type | Description |
---|---|---|
assetResult | AssetResult | A single asset result from a findAssets query. |
block | number | The block to apply the asset to. |
Returns#
Promise
<void
>
Signature#
defaultApplyAssetToBlock(assetResult: AssetResult, block: number): Promise<void>
Asset Lifecycle#
Add, remove, and manage assets within local asset sources.
addAssetToSource()#
Add an asset to a local asset source.
Only works with local asset sources that support asset management. The asset will be validated against the source’s supported MIME types.
engine.asset.addAssetToSource('local-source', { id: 'asset-id', label: { en: 'My Asset' }, meta: { uri: 'https://example.com/asset.jpg', mimeType: 'image/jpeg' }});
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The local asset source ID that the asset should be added to. |
asset | AssetDefinition | The asset definition to add to the source. |
Returns#
void
Signature#
addAssetToSource(sourceId: string, asset: AssetDefinition): void
removeAssetFromSource()#
Remove an asset from a local asset source.
Only works with local asset sources that support asset management. The asset will be permanently deleted from the source.
engine.asset.removeAssetFromSource('local-source', 'asset-id');
Parameters#
Parameter | Type | Description |
---|---|---|
sourceId | string | The id of the local asset source that currently contains the asset. |
assetId | string | The id of the asset to be removed. |
Returns#
void
Signature#
removeAssetFromSource(sourceId: string, assetId: string): void
assetSourceContentsChanged()#
Notify the engine that an asset source’s contents have changed.
This triggers refresh of any UI components that display assets from this source and notifies subscribers to the asset source update events.
engine.asset.assetSourceContentsChanged('asset-source-id');
Parameters#
Parameter | Type | Description |
---|---|---|
sourceID | string | The asset source whose contents changed. |
Returns#
void
Signature#
assetSourceContentsChanged(sourceID: string): void
Experimental Features#
Experimental middleware system for custom asset processing workflows.
unstable_registerApplyAssetMiddleware()#
Register middleware that intercepts asset application to scenes.
The middleware function receives the source ID, asset result, and the original apply function. It can perform custom logic before, after, or instead of the default asset application.
Parameters#
Parameter | Type | Description |
---|---|---|
middleware | (sourceId , assetResult , apply ) => Promise <undefined | number > |
Returns#
VoidFunction
A function that can be used to remove the middleware. This API is experimental and may change or be removed in future versions.
Example#
engine.asset.unstable_registerApplyAssetMiddleware(async (sourceId, assetResult, apply) => { // do something before applying the asset // You still have the choice to call apply or skip it const blockId = await apply(sourceId, assetResult); // do something after applying the asset return blockId;})
unstable_registerApplyAssetToBlockMiddleware()#
Register middleware that intercepts asset application to specific blocks.
The middleware function receives the source ID, asset result, target block, and the original apply function. It can perform custom logic before, after, or instead of the default block asset application.
Parameters#
Parameter | Type | Description |
---|---|---|
middleware | (sourceId , assetResult , block , applyToBlock ) => Promise <void > | The middleware function that is called before applying the asset. |
Returns#
VoidFunction
A function that can be used to remove the middleware. This API is experimental and may change or be removed in future versions.
Example#
engine.asset.unstable_registerApplyAssetToBlockMiddleware(async (sourceId, assetResult, block, applyToBlock) => { // do something before applying the asset // You still have the choice to call applyToBlock or skip it await applyToBlock(sourceId, assetResult, block); // do something after applying the asset})