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 runtime map has no source data of its own: it is built from the tiledSource asset its factory loads. Acquiring the document here as well would download, parse and validate it a second time under a second identity.

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.