Assets - Vircadia API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

The Assets API provides facilities for interacting with the domain's asset server and the client cache.

Assets are stored in the asset server in files with SHA256 names. These files are mapped to user-friendly URLs of the format: atp:/path/filename. The assets may optionally be baked, in which case a request for the original unbaked version of the asset is automatically redirected to the baked version. The asset data may optionally be stored as compressed.

The client cache can be accessed directly, using "atp:" or "cache:" URLs. Interface, avatar, and assignment client scripts can write to the cache. All script types can read from the cache.

Methods

Name	Return Value	Summary
`canWriteCacheValue`	boolean	Checks whether the script can write to the cache.
`compressData`	None	Compresses data in memory using gzip.
`decompressData`	None	Decompresses data in memory using gunzip.
`deleteAsset`	None	Deletes content from the asset server. Not implemented: This method is not implemented yet.
`downloadData`	None	Downloads content from the asset server, from a SHA256-named file.
`extractAssetHash`	string	Gets the SHA256 hexadecimal hash portion of an asset server URL.
`getAsset`	None	Downloads content from the asset server.
`getATPUrl`	string	Gets the normalized ATP URL for a path or hash: ensures that it has `"atp:"` at the start.
`getCacheStatus`	None	Gets the current cache status.
`getMapping`	None	Gets the hash for a path within the asset server. The hash is for the unbaked or baked version of the asset, according to the asset server setting for the particular path.
`hashData`	ArrayBuffer	Calculates the SHA256 hash of given data.
`hashDataHex`	string	Calculates the SHA256 hash of given data, in hexadecimal format.
`initializeCache`	boolean	Initializes the cache if it isn't already initialized.
`isValidFilePath`	boolean	Checks whether a string is a valid path and filename. Note: A valid path and filename must start with a `"/"` but must not end with a `"/"`.
`isValidHash`	boolean	Checks whether a string is a valid SHA256 hexadecimal hash, i.e., 64 hexadecimal characters.
`isValidPath`	boolean	Checks whether a string is a valid path. Note: A valid path must start with a `"/"`.
`loadFromCache`	None	Retrieves data from the cache directly, without downloading it.
`putAsset`	None	Uploads content to the asset server and sets a path-to-hash mapping.
`queryCacheMeta`	None	Gets information about the status of an asset in the cache.
`resolveAsset`	None	Resolves and returns information on a hash or a path in the asset server.
`saveToCache`	None	Saves asset data to the cache directly, without downloading it from a URL. Note: Can only be used in Interface, avatar, and assignment client scripts.
`saveToCache`	None	Saves asset data to the cache directly, without downloading it from a URL. Note: Can only be used in Interface, avatar, and assignment client scripts.
`setBakingEnabled`	None	Sets whether or not to bake an asset in the asset server.
`setMapping`	None	Sets a path-to-hash mapping within the asset server.
`uploadData`	None	Uploads content to the asset server, storing it in a SHA256-named file. Note: The asset server destroys any unmapped SHA256-named file at server restart. Use Assets.setMapping to set a path-to-hash mapping for the new file.

Type Definitions

CacheItemMetaData
Type: object

Information on an asset in the cache. Value returned by Assets.queryCacheMeta and included in the data returned by Assets.loadFromCache.

Properties

Name	Type	Attributes	Summary
attributes	object	<optional>	The attributes that are stored with this cache item. Not used.
expirationDate	Date	<optional>	The date and time when the meta data expires. An invalid date means "never expires".
isValid	boolean		`true` if the item specified in the URL is in the cache, `false` if it isn't.
lastModified	Date	<optional>	The date and time when the meta data was last modified.
rawHeaders	object	<optional>	The raw headers that are set in the meta data. Not used.
saveToDisk	boolean	<optional>	`true` if the cache item is allowed to be store on disk, `false` if it isn't.
url\|metaDataURL	string	<optional>	The ATP URL of the cached item.

CallbackDetails
Type: object

Details of a callback function.

Properties

Name	Type	Summary
scope	object	The scope that the `callback` function is defined in. This object is bound to `this` when the function is called.
callback	Assets~compressDataCallback \| Assets~decompressDataCallback \| Assets~getAssetCallback \| Assets~getCacheStatusCallback \| Assets~loadFromCacheCallback \| Assets~putAssetCallback \| Assets~queryCacheMetaCallback \| Assets~resolveAssetCallback \| Assets~saveToCacheCallback	The function to call upon completion. May be an inline function or a function identifier. If a function identifier, it must be a member of `scope`.

CompressOptions
Type: object

Content and compression options for Assets.compressData.

Properties

Name	Type	Summary
data	string \| ArrayBuffer	The data to compress.
level	number	The compression level, range `-1` – `9`. `-1` means use the default gzip compression level, `0` means no compression, and `9` means maximum compression.

CompressResult
Type: object

Result value returned by Assets.compressData.

Properties

Name	Type	Attributes	Summary
byteLength	number	<optional>	The number of bytes in the compressed data.
compressed	boolean	<optional>	`true` if the data is compressed.
contentType	string	<optional>	The MIME type of the compressed data, i.e., `"application/gzip"`.
data	ArrayBuffer	<optional>	The compressed data.

DecompressOptions
Type: object

Content and decompression options for Assets.decompressData.

Properties

Name

Type

Attributes

Summary

data

ArrayBuffer

The data to decompress.

responseType

Assets.ResponseType

The type of decompressed data to return.

Default Value: text

DecompressResult
Type: object

Result value returned by Assets.decompressData.

Properties

Name	Type	Attributes	Summary
byteLength	number	<optional>	The number of bytes in the decompressed data.
contentType	string	<optional>	The MIME type of the decompressed data.
decompressed	boolean	<optional>	`true` if the data is decompressed.
response	string \| object \| ArrayBuffer	<optional>	The decompressed data.
responseType	Assets.ResponseType	<optional>	The type of the decompressed data in `response`.

DownloadDataError
Type: object

The success or failure of an Assets.downloadData call.

Properties

Name	Type	Summary
errorMessage	string	`""` if the download was successful, otherwise a description of the error.

GetCacheStatusResult
Type: object

Cache status value returned by Assets.getCacheStatus.

Properties

Name	Type	Summary
cacheDirectory	string	The path of the cache directory.
cacheSize	number	The current cache size, in bytes.
maximumCacheSize	number	The maximum cache size, in bytes.

GetOptions
Type: object

Source and download options for Assets.getAsset.

Properties

Name Type Attributes Summary

decompress

boolean

true to gunzip decompress the downloaded data. Synonym: compressed.

Default Value: false

responseType

Assets.ResponseType

The desired result type.

Default Value: "text"

url

string

The mapped path or hash to download. May have a leading "atp:".

GetResult
Type: object

Result value returned by Assets.getAsset.

Properties

Name	Type	Attributes	Summary
byteLength	number	<optional>	The number of bytes in the downloaded content in `response`.
cached	boolean		`true` if the item was retrieved from the cache, `false` if it was downloaded.
contentType	string	<optional>	The automatically detected MIME type of the content.
decompressed	boolean	<optional>	`true` if the content was decompressed, `false` if it wasn't.
hash	string	<optional>	The hash for the downloaded asset.
hashURL	string	<optional>	The ATP URL of the hash file.
path	string	<optional>	The path for the asset, if a path was requested. Otherwise, `undefined`.
response	string \| object \| ArrayBuffer	<optional>	The downloaded content.
responseType	Assets.ResponseType	<optional>	The type of the downloaded content in `response`.
url	string	<optional>	The URL of the asset requested: the path with leading `"atp:"` if a path was requested, otherwise the requested URL.
wasRedirected	boolean	<optional>	`true` if the downloaded data is the baked version of the asset, `false` if it isn't baked.

LoadFromCacheOptions
Type: object

Source and retrieval options for Assets.loadFromCache.

Properties

Name Type Attributes Summary

decompress

boolean

true to gunzip decompress the cached data. Synonym: compressed.

Default Value: false

responseType

Assets.ResponseType

The desired result type.

Default Value: text

url

string

The URL of the asset to load from cache. Must start with "atp:" or "cache:".

LoadFromCacheResult
Type: object

Data and information returned by Assets.loadFromCache.

Properties

Name	Type	Attributes	Summary
byteLength	number	<optional>	The number of bytes in the retrieved data.
contentType	string	<optional>	The automatically detected MIME type of the content.
data	ArrayBuffer		The data bytes.
metadata	Assets.CacheItemMetaData		Information on the cache item.
response	string \| object \| ArrayBuffer	<optional>	The content of the response.
responseType	Assets.ResponseType		The type of the content in `response`.
url	string		The URL of the cache item.

PutOptions
Type: object

Content and upload options for Assets.putAsset.

Properties

Name Type Attributes Summary

compress

boolean

true to gzip compress the content for upload and storage, false to upload and store the data without gzip compression. Synonym: compressed.

Default Value: false

data

string | ArrayBuffer

The content to upload.

path

string

A user-friendly path for the file in the asset server. May have a leading "atp:". If not specified, no path-to-hash mapping is set.

Note: The asset server destroys any unmapped SHA256-named file at server restart. Either set the mapping path with this property or use Assets.setMapping to set a path-to-hash mapping for the uploaded file.

PutResult
Type: object

Result value returned by Assets.putAsset.

Properties

Name	Type	Attributes	Summary
byteLength	number	<optional>	The number of bytes in the hash file stored on the asset server.
compressed	boolean	<optional>	`true` if the content stored is gzip compressed.
contentType	string	<optional>	`"application/gzip"` if the content stored is gzip compressed.
hash	string	<optional>	The SHA256 hash of the content.
url	string	<optional>	The `atp:` URL of the content: using the path if specified, otherwise the hash.
path	string	<optional>	The uploaded content's mapped path, if specified.

QueryCacheMetaOptions
Type: object

Source for Assets.queryCacheMeta.

Properties

Name	Type	Summary
url	string	The URL of the cached asset to get information on. Must start with `"atp:"` or `"cache:"`.

ResolveOptions
Type: object

Source options for Assets.resolveAsset.

Properties

Name	Type	Summary
url	string	The hash or path to resolve. May have a leading `"atp:"`.

ResolveResult
Type: object

Result value returned by Assets.resolveAsset.

Note: If resolving a hash, a file of that hash need not be present on the asset server for the hash to resolve.

Properties

Name	Type	Attributes	Summary
hash	string	<optional>	The hash of the asset.
hashURL	string	<optional>	The url of the asset's hash file, with leading `atp:`.
path	string	<optional>	The path to the asset.
url	string	<optional>	The URL of the asset.
wasRedirected	boolean	<optional>	`true` if the resolved data is for the baked version of the asset, `false` if it isn't.

ResponseType
Type: string

Types of response that Assets.decompressData, Assets.getAsset, or Assets.loadFromCache may provide.

Value	Description
`"arraybuffer"`	A binary `ArrayBuffer` object.
`"json"`	A parsed `JSON` object.
`"text"`	UTF-8 decoded `string` value.

SaveToCacheHeaders
Type: object

Last-modified and expiry times for a cache item.

Properties

Name	Type	Attributes	Summary
expires	string	<optional>	The date and time the cache value expires, in the format: `"ddd, dd MMM yyyy HH:mm:ss"`. The default value is an invalid date, representing "never expires".
last-modified	string	<optional>	The date and time the cache value was last modified, in the format: `"ddd, dd MMM yyyy HH:mm:ss"`. The default value is the current date and time.

SaveToCacheOptions
Type: object

The data to save to the cache and cache options for Assets.saveToCache.

Properties

Name	Type	Attributes	Summary
data	string \| ArrayBuffer		The data to save to the cache.
headers	Assets.SaveToCacheHeaders	<optional>	The last-modified and expiry times for the cache item.
url	string	<optional>	The URL to associate with the cache item. Must start with `"atp:"` or `"cache:"`. If not specified, the URL is `"atp:"` followed by the SHA256 hash of the content.

SaveToCacheResult
Type: object

Information on saving asset data to the cache with Assets.saveToCache.

Properties

Name	Type	Attributes	Summary
byteLength	number	<optional>	The size of the cached data, in bytes.
expirationDate	Date	<optional>	The date and time that the cache item expires. An invalid date means "never expires".
lastModified	Date	<optional>	The date and time that the cache item was last modified.
metaDataURL	string	<optional>	The URL associated with the cache item.
success	boolean	<optional>	`true` if the save to cache request was successful.
url	string	<optional>	The URL associated with the cache item.

compressDataCallback( error, result )
Type: function

Called when an Assets.compressData call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the data was successfully compressed, otherwise a description of the error.
`result`	Assets.CompressResult	Information on and the compressed data.

decompressDataCallback( error, result )
Type: function

Called when an Assets.decompressData call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the data was successfully compressed, otherwise a description of the error.
`result`	Assets.DecompressResult	Information on and the decompressed data.

deleteAssetCallback( error, result )
Type: function

Called when an Assets.deleteAsset call is complete.

Not implemented: This type is not implemented yet.

Parameters

Name	Type	Description
`error`	string	`null` if the content was deleted, otherwise a description of the error.
`result`	Assets.DeleteResult	Information on the content deleted.

downloadDataCallback( data, error )
Type: function

Called when an Assets.downloadData call is complete.

Parameters

Name	Type	Description
`data`	string	The content that was downloaded.
`error`	Assets.DownloadDataError	The success or failure of the download.

getAssetCallback( error, result )
Type: function

Called when an Assets.getAsset call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the content was downloaded, otherwise a description of the error.
`result`	Assets.GetResult	Information on and the content downloaded.

getCacheStatusCallback( error, result )
Type: function

Called when a Assets.getCacheStatus call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the cache status was retrieved without error, otherwise a description of the error.
`result`	Assets.GetCacheStatusResult	Details of the current cache status.

getMappingCallback( error, hash )
Type: function

Called when an Assets.getMapping call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the path was found, otherwise a description of the error.
`hash`	string	The hash value if the path was found, `""` if it wasn't.

loadFromCacheCallback( error, result )
Type: function

Called when an Assets.loadFromCache call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the cache item was successfully retrieved, otherwise a description of the error.
`result`	Assets.LoadFromCacheResult	Information on and the retrieved data.

putAssetCallback( error, result )
Type: function

Called when an Assets.putAsset call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the content was uploaded and any path-to-hash mapping set, otherwise a description of the error.
`result`	Assets.PutResult	Information on the content uploaded.

queryCacheMetaCallback( error, result )
Type: function

Called when Assets.queryCacheMeta is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the URL has a valid cache entry, otherwise a description of the error.
`result`	Assets.CacheItemMetaData	Information on an asset in the cache.

resolveAssetCallback( error, result )
Type: function

Called when an Assets.resolveAsset call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the asset hash or path was resolved, otherwise a description of the error.
`result`	Assets.ResolveResult	Information on the hash or path resolved.

saveToCacheCallback( error, result )
Type: function

Called when an Assets.saveToCache call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the asset data was successfully saved to the cache, otherwise a description of the error.
`result`	Assets.SaveToCacheResult	Information on the cached data.

setBakingEnabledCallback( error )
Type: function

Called when an Assets.setBakingEnabled call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if baking was successfully enabled or disabled, otherwise a description of the error.

setMappingCallback( error )
Type: function

Called when an Assets.setMapping call is complete.

Parameters

Name	Type	Description
`error`	string	`null` if the path-to-hash mapping was set, otherwise a description of the error.

uploadDataCallback( url, hash )
Type: function

Called when an Assets.uploadData call is complete.

Parameters

Name	Type	Description
`url`	string	The raw URL of the file that the content is stored in, with `atp:` as the scheme and the SHA256 hash as the filename (with no extension).
`hash`	string	The SHA256 hash of the content.

Method Details

(static) canWriteCacheValue( url ) → {boolean}
Returns: true if the script is an Interface, avatar, or assignment client script, false if the script is a client entity or server entity script.

Checks whether the script can write to the cache.

Parameters

Name	Type	Description
`url`	string	Not used.

Example

Report whether the script can write to the cache.

print("Can write to cache: " + Assets.canWriteCacheValue(null));

(static) compressData( source, scopeOrCallback, callbackopt )

Compresses data in memory using gzip.

Parameters

Name Type Attributes Description

source

string | ArrayBuffer | Assets.CompressOptions

What to compress and compression options. If a string or ArrayBuffer, the data to compress.

scopeOrCallback

object | Assets.CallbackDetails | Assets~compressDataCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~compressDataCallback

Used if scopeOrCallback specifies the scope.

The function to call upon completion. May be an inline function, a function identifier, or the name of a function in a string. If the name of a function or a function identifier, it must be a member of the scope specified by scopeOrCallback.

(static) decompressData( source, scopeOrCallback, callbackopt )

Decompresses data in memory using gunzip.

Parameters

Name Type Attributes Description

source

Assets.DecompressOptions

What to decompress and decompression options.

scopeOrCallback

object | Assets.CallbackDetails | Assets~decompressDataCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~decompressDataCallback

Used if scopeOrCallback specifies the scope.

(static) deleteAsset( options, scope, callback )

Deletes content from the asset server.

Not implemented: This method is not implemented yet.

Parameters

Name	Type	Description
`options`	Assets.DeleteOptions	The content to delete and delete options.
`scope`	object	The scope that the `callback` function is defined in.
`callback`	Assets~deleteAssetCallback	The function to call upon completion.

(static) downloadData( url, callback )

Downloads content from the asset server, from a SHA256-named file.

Parameters

Name	Type	Description
`url`	string	The raw URL of asset to download: `atp:` followed by the assets's SHA256 hash.
`callback`	Assets~downloadDataCallback	The function to call upon completion.

Example

Store and retrieve a string from the asset server.

var assetURL;

// Store the string.
Assets.uploadData("Hello world!", function (url, hash) {
    assetURL = url;
    print("url: " + assetURL);  // atp:a0g89...
    Assets.setMapping("/assetsExamples/helloWorld.txt", hash, function (error) {
        if (error) {
            print("ERROR: Could not set mapping!");
            return;
        }
    });
});

// Retrieve the string.
Script.setTimeout(function () {
    Assets.downloadData(assetURL, function (data, error) {
        print("Downloaded data: " + data);
        print("Error: " + JSON.stringify(error));
    });
}, 1000);

(static) extractAssetHash( url ) → {string}
Returns: The SHA256 hexadecimal hash portion of the URL if present and valid, "" otherwise.

Gets the SHA256 hexadecimal hash portion of an asset server URL.

Parameters

Name	Type	Description
`url`	string	The URL to get the SHA256 hexadecimal hash from.

(static) getAsset( source, scopeOrCallback, callbackopt )

Downloads content from the asset server.

Parameters

Name Type Attributes Description

source

string | Assets.GetOptions

What to download and download options. If a string, the mapped path or hash to download, optionally including a leading "atp:".

scopeOrCallback

object | Assets.CallbackDetails | Assets~getAssetCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~getAssetCallback

Used if scopeOrCallback specifies the scope.

Example

Retrieve a string from the asset server.

Assets.getAsset(
    {
        url: "/assetsExamples/helloWorld.txt",
        responseType: "text"
    },
    function (error, result) {
        if (error) {
            print("ERROR: Data not downloaded");
        } else {
            print("Data: " + result.response);
        }
    }
);

(static) getATPUrl( url ) → {string}
Returns: The normalized ATP URL.

Gets the normalized ATP URL for a path or hash: ensures that it has "atp:" at the start.

Parameters

Name	Type	Description
`url`	string	The URL to normalize.

(static) getCacheStatus( scopeOrCallback, callbackopt )

Gets the current cache status.

Parameters

Name Type Attributes Description

scopeOrCallback

object | Assets.CallbackDetails | Assets~getCacheStatusCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~getCacheStatusCallback

Used if scopeOrCallback specifies the scope.

Example

Report the cache status.

Assets.getCacheStatus(function (error, status) {
    print("Cache status");
    print("- Error: " + error);
    print("- Status: " + JSON.stringify(status));
});

(static) getMapping( path, callback )

Gets the hash for a path within the asset server. The hash is for the unbaked or baked version of the asset, according to the asset server setting for the particular path.

Parameters

Name	Type	Description
`path`	string	The path to a file in the asset server to get the hash of.
`callback`	Assets~getMappingCallback	The function to call upon completion.

Example

Report the hash of an asset server item.

var assetPath = Window.browseAssets();
if (assetPath) {
    var mapping = Assets.getMapping(assetPath, function (error, hash) {
        print("Asset: " + assetPath);
        print("- hash:  " + hash);
        print("- error: " + error);
    });
}

(static) hashData( data ) → {ArrayBuffer}
Returns: The SHA256 hash of the data.

Calculates the SHA256 hash of given data.

Parameters

Name	Type	Description
`data`	string \| ArrayBuffer	The data to calculate the hash of.

(static) hashDataHex( data ) → {string}
Returns: The SHA256 hash of the data, in hexadecimal format.

Calculates the SHA256 hash of given data, in hexadecimal format.

Parameters

Name	Type	Description
`data`	string \| ArrayBuffer	The data to calculate the hash of.

Example

Calculate the hash of some text.

var text = "Hello world!";
print("Hash: " + Assets.hashDataHex(text));

(static) initializeCache( ) → {boolean} Returns: `true` if the cache is initialized, `false` if it isn't.
Initializes the cache if it isn't already initialized.

(static) isValidFilePath( path ) → {boolean}
Returns: true if the path is a valid file path, false if it isn't.

Checks whether a string is a valid path and filename. Note: A valid path and filename must start with a "/" but must not end with a "/".

Parameters

Name	Type	Description
`path`	string	The path to check.

(static) isValidHash( hash ) → {boolean}
Returns: true if the hash is a valid SHA256 hexadecimal string, false if it isn't.

Checks whether a string is a valid SHA256 hexadecimal hash, i.e., 64 hexadecimal characters.

Parameters

Name	Type	Description
`hash`	string	The hash to check.

(static) isValidPath( path ) → {boolean}
Returns: true if the path is a valid path, false if it isn't.

Checks whether a string is a valid path. Note: A valid path must start with a "/".

Parameters

Name	Type	Description
`path`	string	The path to check.

(static) loadFromCache( options, scopeOrCallback, callbackopt )

Retrieves data from the cache directly, without downloading it.

Parameters

Name Type Attributes Description

options

string | Assets.LoadFromCacheOptions

The URL of the asset to load from the cache if a string, otherwise an object specifying the asset to load from the cache and load options. The URL must start with "atp:" or "cache:".

scopeOrCallback

object | Assets.CallbackDetails | Assets~loadFromCacheCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~loadFromCacheCallback

Used if scopeOrCallback specifies the scope.

Example

Retrieve a string from the cache.

Assets.loadFromCache(
    "cache:/cacheExample/helloCache.txt",
    function (error, result) {
        if (error) {
            print("Error: " + error);
        } else {
            print("Success:");
            print("- Response: " + result.response);
            print("- Content type: " + result.contentType);
            print("- Number of bytes: " + result.byteLength);
            print("- Bytes: " + [].slice.call(new Uint8Array(result.data), 0, result.byteLength));
            print("- URL: " + result.url);
        }
    }
);

(static) putAsset( options, scopeOrCallback, callbackopt )

Uploads content to the asset server and sets a path-to-hash mapping.

Parameters

Name Type Attributes Description

options

string | Assets.PutOptions

The content to upload and upload options. If a string, the value of the string is uploaded but a path-to-hash mapping is not set.

scopeOrCallback

object | Assets.CallbackDetails | Assets~putAssetCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~putAssetCallback

Used if scopeOrCallback specifies the scope.

Example

Store a string in the asset server.

Assets.putAsset(
    {
        data: "Hello world!",
        path: "/assetsExamples/helloWorld.txt"
    },
    function (error, result) {
        if (error) {
            print("ERROR: Data not uploaded or mapping not set");
        } else {
            print("URL: " + result.url);  // atp:/assetsExamples/helloWorld.txt
        }
    }
);

(static) queryCacheMeta( path, scopeOrCallback, callbackopt )

Gets information about the status of an asset in the cache.

Parameters

Name Type Attributes Description

path

string | Assets.QueryCacheMetaOptions

The URL of the cached asset to get information on if a string, otherwise an object specifying the cached asset to get information on. The URL must start with "atp:" or "cache:".

scopeOrCallback

object | Assets.CallbackDetails | Assets~queryCacheMetaCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~queryCacheMetaCallback

Used if scopeOrCallback specifies the scope.

Example

Report details of a string store in the cache.

Assets.queryCacheMeta(
    "cache:/cacheExample/helloCache.txt",
    function (error, result) {
        if (error) {
            print("Error: " + error);
        } else {
            print("Success:");
            print("- URL: " + result.url);
            print("- isValid: " + result.isValid);
            print("- saveToDisk: " + result.saveToDisk);
            print("- expirationDate: " + result.expirationDate);
        }
    }
);

(static) resolveAsset( source, scopeOrCallback, callbackopt )

Resolves and returns information on a hash or a path in the asset server.

Parameters

Name Type Attributes Description

source

string | Assets.ResolveOptions

The hash or path to resolve if a string, otherwise an object specifying what to resolve. If a string, it may have a leading "atp:".

scopeOrCallback

object | Assets.CallbackDetails | Assets~resolveAssetCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~resolveAssetCallback

Used if scopeOrCallback specifies the scope.

Example

Get the hash and URL for a path.

Assets.resolveAsset(
    "/assetsExamples/helloWorld.txt",
    function (error, result) {
        if (error) {
            print("ERROR: " + error);
        } else {
            print("Hash: " + result.hash);
            print("URL: " + result.url);
        }
    }
);

(static) saveToCache( options, scopeOrCallback, callbackopt )

Saves asset data to the cache directly, without downloading it from a URL.

Note: Can only be used in Interface, avatar, and assignment client scripts.

Parameters

Name Type Attributes Description

options

Assets.SaveToCacheOptions

The data to save to the cache and cache options.

scopeOrCallback

object | Assets.CallbackDetails | Assets~saveToCacheCallback

If an object, then the scope that the callback function is defined in. This object is bound to this when the function is called.

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

callback

Assets~saveToCacheCallback

Used if scopeOrCallback specifies the scope.

Example

Save a string in the cache.

Assets.saveToCache(
    {
        url: "cache:/cacheExample/helloCache.txt",
        data: "Hello cache"
    },
    function (error, result) {
        if (error) {
            print("Error: " + error);
        } else {
            print("Success:");
            print("- Bytes: " + result.byteLength);
            print("- URL: " + result.url);
        }
    }
);

(static) saveToCache( url, data, headers, scopeOrCallback, callbackopt )

Saves asset data to the cache directly, without downloading it from a URL.

Note: Can only be used in Interface, avatar, and assignment client scripts.

Parameters

Name	Type	Attributes	Description
`url`	string		The URL to associate with the cache item. Must start with `"atp:"` or `"cache:"`.
`data`	string \| ArrayBuffer		The data to save to the cache.
`headers`	Assets.SaveToCacheHeaders		The last-modified and expiry times for the cache item.
`scopeOrCallback`	object \| Assets.CallbackDetails \| Assets~saveToCacheCallback		If an object, then the scope that the `callback` function is defined in. This object is bound to `this` when the function is called. Otherwise, the function to call upon completion. This may be an inline function or a function identifier.
`callback`	Assets~saveToCacheCallback	<optional>	Used if `scopeOrCallback` specifies the scope. The function to call upon completion. May be an inline function, a function identifier, or the name of a function in a string. If the name of a function or a function identifier, it must be a member of the scope specified by `scopeOrCallback`.

(static) setBakingEnabled( path, enabled, callback )

Sets whether or not to bake an asset in the asset server.

Parameters

Name	Type	Description
`path`	string	The path to a file in the asset server.
`enabled`	boolean	`true` to enable baking of the asset, `false` to disable.
`callback`	Assets~setBakingEnabledCallback	The function to call upon completion.

(static) setMapping( path, hash, callback )

Sets a path-to-hash mapping within the asset server.

Parameters

Name	Type	Description
`path`	string	A user-friendly path for the file in the asset server, without leading `"atp:"`.
`hash`	string	The hash in the asset server.
`callback`	Assets~setMappingCallback	The function to call upon completion.

(static) uploadData( data, callback )

Uploads content to the asset server, storing it in a SHA256-named file.

Note: The asset server destroys any unmapped SHA256-named file at server restart. Use Assets.setMapping to set a path-to-hash mapping for the new file.

Parameters

Name	Type	Description
`data`	string	The content to upload.
`callback`	Assets~uploadDataCallback	The function to call upon completion.

Example

Store a string in the asset server.

Assets.uploadData("Hello world!", function (url, hash) {
    print("URL: " + url);  // atp:0a1b...9g
    Assets.setMapping("/assetsExamples/helloWorld.txt", hash, function (error) {
        if (error) {
            print("ERROR: Could not set mapping!");
            return;
        }
    });
});