API reference

A typed, loadable descriptor for one asset of this type. The resource and option types come from the type instance, so a custom type is fully typed at every call site without declaring anything to the module system: ts const world = await loader.load(worldType.asset('level.world'));

Creates the factory for one application, at install time. Called once per Loader, never per request and never at module import, so loader-local state a factory needs - a worker, a compiled module, a lookup shared across every resource of this type - can be built here and torn down with the loader.

The part of a request's identity the source alone does not capture: what makes two requests for one source two DIFFERENT runtime resources. Include every option baked irreversibly into the produced resource - a colour space, a font descriptor, a decoding mode, a runtime interpretation. Exclude load policy (priority, timeout, cancellation) and per-consumer presentation (sampler state, placeholder size): neither changes the resource, and folding them in would build and hold the same resource twice. Never serialize the whole option bag: property order is unstable, control fields would leak in, and the result is unbounded. Select the fields that matter, explicitly. Omit the hook entirely when the source alone identifies the resource.

The part of a request that changes WHICH SOURCE DATA is acquired - a locale, a content variant, an explicit variant token, a known content identity. This is not resourceIdentity. An option that changes only how already-acquired data is interpreted belongs there and must not appear here, or one download would be fetched once per interpretation. The value can outlive the session inside a persistent cache namespace, so it must carry no credentials, no tokens and no request headers. Omit the hook entirely when the locator alone identifies the source.

The source for a request the loader must NOT acquire data for. Returning a source skips acquisition completely: nothing is fetched, decoded or cached for that request, codec is never consulted, and the factory receives what this returns, built from the resolved url alone. Returning undefined acquires normally. Two kinds of asset need this. One transports its own data - a media element streaming from a URL, where downloading the whole file up front is exactly what streaming avoids. The other has no source data of its own at all, because it is derived from assets its factory loads as dependencies. A type that transports its own data over the NETWORK must consult network: declining to acquire also declines the cache, so a type that streamed regardless would keep reaching for the network after the application forbade it. Returning undefined when network.allowsNetwork is false is what puts such a request back on the cache path, where it either hits or misses honestly. A type whose source is derived rather than transported ignores it. This governs an ordinary load only. Loader.cacheSource asks for the acquisition by name and does not consult this hook, so a type that transports its own data is still explicitly cacheable through its codec. The result is wrapped so that a type whose source is legitimately undefined can still say "do not acquire".

How an acquired representation is read back into the source a factory consumes. Required for every type the loader acquires data for, which is nearly all of them. A type whose unacquiredSource always answers has no representation to read and needs none; a type that reaches acquisition without one fails that load with a message saying so.

File suffixes this type claims, without the leading dot. They are app-local: a suffix claimed here is resolved to this type by the applications that installed it and is unknown to every other application in the process. Leave it empty for a type whose assets are always named explicitly.

The type's stable identity - a non-empty string chosen by whoever defines the type, and never changed afterwards. It names the type wherever a name is needed: in resource identities, in diagnostics, and in the storage namespaces a persistent cache derives from it. Because it survives a reload, it must not be derived from anything that does not: a class name a minifier may rewrite, an installation order, or a value generated at runtime. Reverse-DNS ('com.example.world') keeps independently authored types apart. Two types with the same id cannot be installed on one application.

How an acquired representation is laid out when an application caches it. The default keeps the representation in one record, which is what a codec producing a single value needs. Override it to raise the version when the stored representation changes shape - records written under the old version are then no longer found, and the source is acquired again - or to supply a layout that spreads one representation across several records. Whether anything is cached at all, and where, is the application's decision. A type describes only how its representation would be laid out.

What this type hands out for one of its assets in a catalog, before the payload arrives. The default is a deferred AssetRef. A type whose resource can be handed out empty and healed in place supplies a SeamlessAdapter instead; a type with no meaningful placeholder declares 'none', which also takes its suffixes out of bare-path catalog resolution.