Engine API Reference - v2.23.0-beta.17
    Preparing search index...

    Class ResourceHandler

    A ResourceHandler loads and opens resources of one asset type on behalf of the ResourceLoader. The engine ships a handler for every built-in AssetType, and an application registers the ones listed in AppOptions#resourceHandlers, so a hand-configured AppBase may support only some types. Register your own with ResourceLoader#addHandler to add a new type.

    A handler works in two steps. load fetches the raw data for a URL and open turns that data into the resource stored on Asset#resource. A handler may also implement patch to resolve references to other assets once the resource exists. Rather than overriding those methods, a handler can register one ResourceParser per file format with addParser and let the base class pick the parser that claims the file.

    class CsvHandler extends ResourceHandler {
        constructor(app) {
            super(app, 'csv');
        }

        load(url, callback) {
            this.fetch(url, 'text', callback);
        }

        open(url, data) {
            return data.split('\n').map(line => line.split(','));
        }
    }
    app.loader.addHandler('csv', new CsvHandler(app));

    Hierarchy (View Summary)

    Index
    constructor
    _app handlerType
    app maxRetries parsers
    addParser fetch load open patch removeParser

    Protected_app

    _app: AppBase

    The running app instance.

    handlerType: string = ''

    Type of the resource the handler handles.

    • get maxRetries(): number

      Gets the number of times to retry a failed request for the resource.

      Returns number

    • set maxRetries(value: number): void

      Sets the number of times to retry a failed request for the resource.

      Parameters

      • value: number

      Returns void

    • Registers a ResourceParser for this handler. Parsers are consulted newest-first: the most recently added parser whose ResourceParser#canParse returns true is selected. This lets a later registration override a built-in parser for the same format.

      Register parsers before starting loads for this handler's type - selection runs for both the load and open phases, so changing the registry while loads are in flight can route them inconsistently. Note that handlers that implement their own loading without consulting registered parsers (for example cubemap or font) ignore registered parsers.

      Parameters

      • parser: ResourceParser

        The parser to register. Must implement canParse(context).

      • Optionaldecider: any

        Removed. Previously a (url, data) => boolean selector; implement canParse(context) on the parser instead. If passed, it is ignored and logs a warning.

      Returns void

      app.loader.getHandler('model').addParser(new ObjModelParser(app.graphicsDevice));

    • Fetches a resource's raw data using this handler's retry settings, reusing pre-fetched asset.file.contents when available. A convenience for a ResourceParser's load method, so parsers don't reimplement the fetch boilerplate.

      Parameters

      • url: string | { load: string; original: string }

        The resource URL, or a load/original structure.

      • responseType: string

        The Http response type to fetch as (for example Http.ResponseType.ARRAY_BUFFER for a binary format, or Http.ResponseType.TEXT).

      • callback: ResourceHandlerCallback

        Called with (err, data) when the fetch completes.

      • Optionalasset: Asset<string>

        The asset being loaded, used to reuse already-fetched contents.

      Returns void

    • Load a resource from a remote URL. When parsers are registered, the matching parser's load is used; otherwise the base implementation does nothing (subclasses may override).

      Parameters

      • url: string | { load: string; original: string }

        Either the URL of the resource to load or a structure containing the load URL (used for loading the resource) and the original URL (used for identifying the resource format; necessary when loading, for example, from a blob URL).

      • callback: ResourceHandlerCallback

        The callback used when the resource is loaded or an error occurs.

      • Optionalasset: Asset<string>

        Optional asset that is passed by ResourceLoader.

      Returns void

    • The open function is passed the raw resource data. The handler can then process the data into a format that can be used at runtime. When parsers are registered, the matching parser's open is used (if it implements one); otherwise the base implementation simply returns the data.

      Parameters

      • url: string

        The URL of the resource to open.

      • data: any

        The raw resource data passed by callback from load.

      • Optionalasset: Asset<string>

        Optional asset that is passed by ResourceLoader.

      Returns any

      The parsed resource data.

    • The patch function performs any operations on a resource that requires a dependency on its asset data or any other asset data. The base implementation does nothing.

      Parameters

      Returns void

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods