melonjs 20.12.0 → 20.14.0

package/build/loader/loader.d.ts

@@ -1,19 +1,28 @@
 
 /**
- * Sets the options for the loader.
- * @param {Object} options - The options to set.
- * @param {string} [options.crossOrigin] - The crossOrigin attribute to configure the CORS requests for Image and Video data element.
- * @param {boolean} [options.nocache] - Enable or disable the nocache mechanism.
- * @param {boolean} [options.withCredentials] - Indicates whether or not cross-site Access-Control requests should be made using credentials.
+ * Set the loader's global options, for every asset loaded from then on.
+ * Each option left out keeps its current value.
+ * @param {Object} options - the options to set
+ * @param {string} [options.crossOrigin] - the `crossOrigin` attribute of the
+ * `<video>` and `<script>` elements and glTF images the loader creates
+ * (`"anonymous"` or `"use-credentials"`). Every other asset is always
+ * requested with CORS. See {@link crossOrigin}.
+ * @param {boolean} [options.nocache] - when true, append a random query
+ * string to every asset URL, so the browser fetches a fresh copy rather than
+ * a cached one (development only: it also defeats the HTTP cache in
+ * production)
+ * @param {boolean} [options.withCredentials] - whether requests to another
+ * origin carry credentials (cookies, HTTP authentication). Requests to the
+ * game's own origin always carry them. See {@link withCredentials}.
  * @example
- * // Set the crossOrigin attribute to "anonymous"
- * me.loader.setOptions({ crossOrigin: "anonymous" });
+ * // play videos from another origin, without credentials
+ * loader.setOptions({ crossOrigin: "anonymous" });
  *
- * // Enable the nocache mechanism
- * me.loader.setOptions({ nocache: true });
+ * // bypass the browser cache while developing
+ * loader.setOptions({ nocache: true });
  *
- * // Enable withCredentials
- * me.loader.setOptions({ withCredentials: true });
+ * // send cookies to a CDN that serves assets behind a login
+ * loader.setOptions({ withCredentials: true });
  * @category Assets
  */
 export function setOptions(options: {
@@ -22,95 +31,103 @@ export function setOptions(options: {
     withCredentials?: boolean | undefined;
 }): void;
 /**
- * change the default baseURL for the given asset type.<br>
- * (this will prepend the asset URL and must finish with a '/')
- * @public
- * @param {string} type  - "*", "audio", "video", "binary", "image", "json", "js", "tmx", "tsx", "fontface", "aseprite", "shader", "obj", "mtl", "gltf", "glb"
- * @param {string} [url="./"] - default base URL
+ * Set the base URL prepended to the `src` of every asset of a type, so the
+ * descriptors need not repeat it. Applies to assets loaded from then on; a
+ * data URI `src` is never prefixed.
+ *
+ * `"*"` sets it for every built-in type except `obj`, `mtl`, `gltf` and
+ * `glb`, which resolve their own references (a `map_Kd` texture, a glTF
+ * buffer) relative to their file and would be prefixed twice: set those one
+ * by one. Custom types registered with {@link setParser} are not covered by
+ * `"*"` either.
+ * @param {string} type - the asset type ("audio", "video", "binary", "image",
+ * "json", "js", "tmx", "tsx", "fontface", "aseprite", "shader", "obj", "mtl",
+ * "gltf", "glb", or a custom type), or `"*"`
+ * @param {string} [url="./"] - the base URL, ending with a `/`
  * @example
- * // change the base URL relative address for audio assets
- * me.loader.setBaseURL("audio", "data/audio/");
- * // change the base URL absolute address for all object types
- * me.loader.setBaseURL("*", "http://myurl.com/")
+ * // a relative path for the images
+ * loader.setBaseURL("image", "data/img/");
+ * // so that a descriptor names the file alone: loads data/img/player.png
+ * await loader.preload([{ name: "player", type: "image", src: "player.png" }]);
+ *
+ * // or an absolute URL for every 2D asset type at once
+ * loader.setBaseURL("*", "https://cdn.example.com/");
  * @category Assets
  */
 export function setBaseURL(type: string, url?: string): void;
 /**
- * A registered parser, normalized by {@link loader.setParser}.
- *
- * Every type gets the same shape whether or not it needs the src hooks, so
- * `load()` can treat all of them alike. The alternative — a bare function that
- * some types decorate with extra properties — puts the knowledge of which
- * types are special back into the caller, which is what moving it out was for.
- * @typedef {object} AssetParser
- * @property {Function} parse - preloads the asset and returns how many
- * resources it will load (0 when already cached)
- * @property {function(string): string} normalizeSrc - turns a type-specific
- * descriptor into a bare path, before any base URL is applied. Identity unless
- * the type overrides it
- * @property {function(string): boolean} needsBaseURL - whether the normalized
- * src is relative to this type's base URL. Declares only this type's own
- * exceptions, such as a `local()` font naming an installed family — data URIs
- * are excluded for every type before this is consulted
- * @ignore
- * @internal
- */
-/**
- * an asset definition to be used with the loader
+ * An asset descriptor: what to load, and the name to keep it under. The same
+ * descriptors go in a {@link preload} list, in a bundle ({@link setBundle}),
+ * or to {@link load} on their own.
+ *
+ * The type and the name together identify an asset, so two assets of
+ * different types may share a name: a texture atlas is usually an `"image"`
+ * and a `"json"` both called `"texture"`.
  * @typedef {object} Asset
- * @property {string} name - name of the asset
- * @property {string} type  - the type of the asset ("audio"|"binary"|"image"|"json"|"js"|"tmx"|"tsx"|"fontface"|"video"|"aseprite"|"shader"|"obj"|"mtl"|"gltf"|"glb"). JSON-serialised Tiled maps and tilesets (`.tmj` / `.tsj`) load under `"tmx"` / `"tsx"` — those are file extensions, not asset types. Any other type is one registered with {@link loader.setParser}.
- * @property {string|string[]} [src]  - path and/or file name of the resource (for audio assets only the path is required).
- * For image assets, an array of sources can be provided as a fallback chain (e.g. compressed texture formats by priority, with a PNG fallback).
- * The loader will try each source in order and use the first one that loads successfully.
- * @property {string|{glsl?: string, wgsl?: string}} [data]  - inline content if not provided through a src url: TMX data for "tmx" assets, GLSL source (the ShaderEffect fragment-body convention) for "shader" assets. A shader may instead carry a `{glsl, wgsl}` pair, so one asset serves both backends; either half may be omitted
- * @property {boolean} [stream=false] - Set to true to not to wait for large audio or video file to be downloaded before playing.
- * @property {boolean} [autoplay=false] - Set to true to automatically start playing audio or video when loaded or added to a scene (using autoplay might require user iteraction to enable it)
- * @property {boolean} [loop=false] - Set to true to automatically loop the audio or video when playing
+ * @property {string} name - the name the asset is kept and read back under
+ * (`loader.getImage(name)`, `new Sprite(x, y, { image: name })`,
+ * `level.load(name)`, `audio.play(name)`)
+ * @property {string} type - the type of the asset, which picks its parser:
+ * "audio", "binary", "image", "json", "js", "tmx", "tsx", "fontface", "video",
+ * "aseprite", "shader", "obj", "mtl", "gltf" or "glb". JSON-serialised Tiled
+ * maps and tilesets (`.tmj` / `.tsj`) load under `"tmx"` / `"tsx"`: those are
+ * file extensions, not asset types. Any other type is one registered with
+ * {@link loader.setParser}.
+ * @property {string|string[]} [src] - the URL of the file, relative to the
+ * page or to the type's base URL ({@link setBaseURL}), or a data URI.
+ * For `"audio"` it is the **directory** holding the clip: the loader appends
+ * the asset name and each extension given to `audio.init()`, and keeps the
+ * first that decodes.
+ * For `"image"` it may be an array of sources, tried in order until one loads:
+ * a fallback chain, such as compressed texture formats by priority with a PNG
+ * last.
+ * For `"shader"` it may be an object of URLs instead (see the example).
+ * @property {string|{glsl?: string, wgsl?: string}} [data] - inline content
+ * in place of a `src`: the parsed Tiled JSON map or tileset (an object) for
+ * `"tmx"` / `"tsx"`, the GLSL source of an effect body for `"shader"`, or a
+ * `{glsl, wgsl}` pair of them so that one asset serves both backends (either
+ * half may be omitted)
+ * @property {boolean} [stream=false] - audio and video: start playing before
+ * the whole file is downloaded, rather than waiting for it
+ * @property {boolean} [autoplay=false] - audio and video: start playing once
+ * loaded, or once added to a scene (a browser may require a user interaction
+ * first)
+ * @property {boolean} [loop=false] - audio and video: loop when playing
  * @see {@link preload}
  * @see {@link load}
+ * @see {@link setBundle}
  * @example
- *   // PNG tileset
- *   {name: "tileset-platformer", type: "image",  src: "data/map/tileset.png"}
- *   // PNG packed texture
- *   {name: "texture", type:"image", src: "data/gfx/texture.png"}
- *   // PNG base64 encoded image
- *   {name: "texture", type:"image", src: "data:image/png;base64,iVBORw0KAAAQAAAAEACA..."}
- *   // compressed texture with fallback chain (tries each source in order until one succeeds)
- *   {name: "terrain", type:"image", src: ["data/gfx/terrain.astc.ktx", "data/gfx/terrain.dds", "data/gfx/terrain.png"]}
- *   // TSX file
- *   {name: "meta_tiles", type: "tsx", src: "data/map/meta_tiles.tsx"}
- *   // TMX level (XML & JSON)
- *   {name: "map1", type: "tmx", src: "data/map/map1.json"}
- *   {name: "map2", type: "tmx", src: "data/map/map2.tmx"}
- *   {name: "map3", type: "tmx", format: "json", data: {"height":15,"layers":[...],"tilewidth":32,"version":1,"width":20}}
- *   {name: "map4", type: "tmx", format: "xml", data: {xml representation of tmx}}
- *   // audio resources
- *   {name: "bgmusic", type: "audio",  src: "data/audio/"}
- *   {name: "cling",   type: "audio",  src: "data/audio/"}
- *   // base64 encoded audio resources
- *   {name: "band",   type: "audio",  src: "data:audio/wav;base64,..."}
- *   // binary file
- *   {name: "ymTrack", type: "binary", src: "data/audio/main.ym"}
- *   // JSON file (used for texturePacker)
- *   {name: "texture", type: "json", src: "data/gfx/texture.json"}
- *   // JSON file holding collision shapes drawn in a physics-shape editor,
- *   // named by a body definition as `{ shapes: "shapes", id: <body name> }`
- *   {name: "shapes", type: "json", src: "data/physics/shapes.json"}
- *   // JavaScript file
- *   {name: "plugin", type: "js", src: "data/js/plugin.js"}
- *   // Font Face
- *   { name: "'kenpixel'", type: "fontface",  src: "data/font/kenvector_future.woff2" }
- *   // video resources
- *   {name: "intro", type: "video",  src: "data/video/"}
- *   // 3D assets: Wavefront OBJ model + MTL material library
- *   {name: "ship",  type: "obj", src: "data/models/ship.obj"}
- *   {name: "ship",  type: "mtl", src: "data/models/ship.mtl"}
- *   // glTF / GLB scene (auto-registers with the level director)
- *   {name: "diorama", type: "glb", src: "data/scenes/diorama.glb"}
- *   // shader assets: an effect body, or a complete dual-backend program
- *   {name: "flash", type: "shader", src: "shaders/flash.frag"}
- *   {name: "toon",  type: "shader", src: {vertex: "shaders/toon.vert", fragment: "shaders/toon.frag", wgsl: "shaders/toon.wgsl"}}
+ * // images: a file, a data URI, or a fallback chain (first that loads wins)
+ * { name: "tileset", type: "image", src: "data/img/tileset.png" }
+ * { name: "logo",    type: "image", src: "data:image/png;base64,iVBORw0KGgo..." }
+ * { name: "terrain", type: "image", src: ["data/gfx/terrain.astc.ktx", "data/gfx/terrain.dds", "data/gfx/terrain.png"] }
+ * // a texture atlas: its image and its JSON descriptor, under the same name
+ * { name: "texture", type: "image", src: "data/gfx/texture.png" }
+ * { name: "texture", type: "json",  src: "data/gfx/texture.json" }
+ * // Tiled: a map (XML or JSON), an external tileset, or a map given inline
+ * { name: "map1",    type: "tmx", src: "data/map/map1.tmx" }
+ * { name: "map2",    type: "tmx", src: "data/map/map2.tmj" }
+ * { name: "tileset", type: "tsx", src: "data/map/tileset.tsx" }
+ * { name: "map3",    type: "tmx", data: { width: 20, height: 15, tilewidth: 32, tileheight: 32, layers: [], tilesets: [] } }
+ * // audio: src is the directory, the extension comes from audio.init()
+ * { name: "cling",   type: "audio", src: "data/sfx/" }
+ * { name: "bgmusic", type: "audio", src: "data/bgm/", stream: true }
+ * // video: src is the file
+ * { name: "intro", type: "video", src: "data/video/intro.mp4" }
+ * // other data: raw bytes, JSON (collision shapes from a shape editor), a script
+ * { name: "ymTrack", type: "binary", src: "data/audio/main.ym" }
+ * { name: "shapes",  type: "json",   src: "data/physics/shapes.json" }
+ * { name: "plugin",  type: "js",     src: "data/js/plugin.js" }
+ * // a web font, used by its name as a CSS font family
+ * { name: "kenpixel", type: "fontface", src: "data/font/kenvector_future.woff2" }
+ * // 3D: a Wavefront OBJ model and its MTL materials, or a glTF/GLB scene
+ * // (which registers with the level director, like a Tiled map)
+ * { name: "ship",    type: "obj", src: "data/models/ship.obj" }
+ * { name: "ship",    type: "mtl", src: "data/models/ship.mtl" }
+ * { name: "diorama", type: "glb", src: "data/scenes/diorama.glb" }
+ * // shaders: an effect body, or a complete program for both backends
+ * { name: "flash", type: "shader", src: "shaders/flash.frag" }
+ * { name: "toon",  type: "shader", src: { vertex: "shaders/toon.vert", fragment: "shaders/toon.frag", wgsl: "shaders/toon.wgsl" } }
  */
 /**
  * Teach the loader an asset type of your own, or replace the parser of an
@@ -140,6 +157,7 @@ export function setBaseURL(type: string, url?: string): void;
  * this type by name: the `"*"` wildcard does not cover custom types.
  * @param {string} type - asset type
  * @param {Function} parserFn - parser function, as described above
+ * @throws {Error} when `parserFn` is not a function
  * @see {@link Asset.type}
  * @example
  * // a texture generated in code rather than loaded, baked behind the
@@ -180,129 +198,438 @@ export function setBaseURL(type: string, url?: string): void;
  */
 export function setParser(type: string, parserFn: Function): void;
 /**
- * set all the specified game assets to be preloaded.
- * @param {Asset[]} assets - list of assets to load
- * @param {Function} [onloadcb=loader.onload] - function to be called when all resources are loaded
- * @param {boolean} [switchToLoadState=true] - automatically switch to the loading screen
- * @returns {Promise<void>} resolves once every asset has loaded (rejects on a
- * load failure). The `onloadcb` callback is still invoked on success, so both
- * the callback and `await` forms work — use whichever you prefer.
+ * Declare every bundle of a record and load them all, behind the loading
+ * screen: the boot call of a game with several levels, given the record its
+ * assets file exports (`{ common: [...], level1: [...], ... }`).
+ *
+ * Each key becomes a bundle, exactly as {@link loader.setBundle} would make
+ * it, with the same checks. A bundle already declared with the same assets
+ * is left as it is; one declared with other assets is redefined, which throws
+ * while it is loaded or loading. Every key is checked before any is declared,
+ * so a bad one throws with nothing changed.
+ *
+ * Every bundle is then loaded as one preload, as with a flat list: one
+ * progress bar over all their assets (an asset several bundles list is loaded
+ * once, and counted once), the shader warm-up, then the callback,
+ * `LOADER_COMPLETE`, and the promise resolves. From there each bundle is
+ * loaded as if by `load(id)`: `loader.unload(id)` frees the assets only that
+ * bundle holds, and `loader.load(id)` brings them back. Calling it again
+ * fetches nothing already in memory.
+ * @overload
+ * @param {Object<string, Asset[]>} bundles - bundle id → its asset descriptors
+ * @param {Function} [onloadcb] - called once every asset has loaded, before
+ * `LOADER_COMPLETE`
+ * @param {boolean} [switchToLoadState=true] - switch to the loading screen
+ * (`state.LOADING`) while loading
+ * @returns {Promise<void>} resolves once every asset has loaded; rejects if
+ * one fails to load
+ * @throws {TypeError} synchronously, when `bundles` is not a record of asset
+ * arrays — a single asset descriptor passed by mistake included (wrap it in
+ * an array)
+ * @throws {Error} synchronously, when a key names a bundle that is loaded or
+ * loading with other assets, or an asset has an unknown type
  * @example
- * game.assets = [
- *   // PNG tileset
- *   {name: "tileset-platformer", type: "image",  src: "data/map/tileset.png"},
- *   // PNG packed texture
- *   {name: "texture", type:"image", src: "data/gfx/texture.png"}
- *   // PNG base64 encoded image
- *   {name: "texture", type:"image", src: "data:image/png;base64,iVBORw0KAAAQAAAAEACA..."},
- *   // compressed texture with fallback chain (tries each source in order until one succeeds)
- *   {name: "terrain", type:"image", src: ["data/gfx/terrain.astc.ktx", "data/gfx/terrain.dds", "data/gfx/terrain.png"]},
- *   // TSX file
- *   {name: "meta_tiles", type: "tsx", src: "data/map/meta_tiles.tsx"},
- *   // TMX level (XML & JSON)
- *   {name: "map1", type: "tmx", src: "data/map/map1.json"},
- *   {name: "map2", type: "tmx", src: "data/map/map2.tmx"},
- *   {name: "map3", type: "tmx", format: "json", data: {"height":15,"layers":[...],"tilewidth":32,"version":1,"width":20}},
- *   {name: "map4", type: "tmx", format: "xml", data: {xml representation of tmx}},
- *   // audio resources
- *   {name: "bgmusic", type: "audio",  src: "data/audio/"},
- *   {name: "cling",   type: "audio",  src: "data/audio/"},
- *   // base64 encoded audio resources
- *   {name: "band",   type: "audio",  src: "data:audio/wav;base64,..."},
- *   // binary file
- *   {name: "ymTrack", type: "binary", src: "data/audio/main.ym"},
- *   // JSON file (used for texturePacker)
- *   {name: "texture", type: "json", src: "data/gfx/texture.json"},
- *   // JSON file holding collision shapes drawn in a physics-shape editor,
- *   // named by a body definition as `{ shapes: "shapes", id: <body name> }`
- *   {name: "shapes", type: "json", src: "data/physics/shapes.json"},
- *   // JavaScript file
- *   {name: "plugin", type: "js", src: "data/js/plugin.js"},
- *   // Font Face
- *   {name: "'kenpixel'", type: "fontface",  src: "data/font/kenvector_future.woff2"},
- *   // video resources
- *   {name: "intro", type: "video",  src: "data/video/"},
- *   // base64 encoded video asset
- *   me.loader.load({name: "avatar", type:"video", src: "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZ..."};
+ * // resources.js: what every level uses, then each level's own assets
+ * export default {
+ *     common: [
+ *         { name: "player", type: "image", src: "img/player.png" },
+ *         { name: "jump",   type: "audio", src: "sfx/" },
+ *     ],
+ *     map1: [
+ *         { name: "map1",  type: "tmx",   src: "map/map1.tmx" },
+ *         { name: "hills", type: "image", src: "img/hills.png" },
+ *     ],
+ *     map2: [
+ *         { name: "map2",  type: "tmx",   src: "map/map2.tmx" },
+ *         { name: "hills", type: "image", src: "img/hills.png" }, // shared
+ *     ],
+ * };
+ *
+ * // game.js: the same call as with a flat list
+ * import resources from "./resources.js";
+ * await loader.preload(resources);
+ * state.change(state.PLAY);
+ * @category Assets
+ */
+export function preload(bundles: {
+    [x: string]: Asset[];
+}, onloadcb?: Function | undefined, switchToLoadState?: boolean | undefined): Promise<void>;
+/**
+ * Load a list of assets behind the loading screen: the boot call.
+ *
+ * It switches to the loading screen (`state.LOADING`, unless told not to),
+ * loads every asset of the list, warms the shaders (see the `prewarm`
+ * application setting), then calls `onloadcb`, emits `LOADER_COMPLETE`, and
+ * resolves. Each call has
+ * only its own callback: a preload given none calls nothing on completion,
+ * whatever an earlier preload was given.
+ *
+ * Progress is reported through {@link event.LOADER_PROGRESS} as the share of
+ * this call's assets loaded so far, reaching 1 with the last of them. A
+ * preload started while another is still loading joins it, and the progress
+ * then covers the assets of both; once they have all settled, the next
+ * preload counts from zero again.
+ *
+ * If an asset fails to load, {@link event.LOADER_ERROR} is emitted with it,
+ * the promise rejects, and neither the callback nor `LOADER_COMPLETE` comes;
+ * {@link loader.reload} retries the asset and then completes this preload.
+ *
+ * The list may also name bundles declared with {@link loader.setBundle},
+ * mixed freely with asset descriptors: each id stands for the assets of that
+ * bundle, and those bundles are loaded by this call exactly as `load(id)`
+ * would load them. An asset that appears more than once (in two bundles, or
+ * in a bundle and directly) is loaded once. An asset listed directly is
+ * pinned: no bundle unload frees it, only {@link loader.unload} with the
+ * descriptor, or {@link loader.unloadAll}.
+ * @overload
+ * @param {Array<Asset|string>} assets - the asset descriptors to load,
+ * and/or ids of bundles declared with {@link loader.setBundle}
+ * @param {Function} [onloadcb] - called once every asset has loaded, before
+ * `LOADER_COMPLETE`
+ * @param {boolean} [switchToLoadState=true] - switch to the loading screen
+ * (`state.LOADING`) while loading
+ * @returns {Promise<void>} resolves once every asset has loaded (after the
+ * callback, which is still called: use either form); rejects if one fails to
+ * load
+ * @throws {Error} synchronously, on an unknown bundle id (before anything is
+ * loaded) or an unknown asset type
+ * @example
+ * import { loader, state } from "melonjs";
+ *
+ * const resources = [
+ *     // an image, and a texture atlas (its image and JSON descriptor)
+ *     { name: "background", type: "image", src: "data/img/background.png" },
+ *     { name: "texture",    type: "image", src: "data/img/texture.png" },
+ *     { name: "texture",    type: "json",  src: "data/img/texture.json" },
+ *     // a Tiled map, its external tileset and the tileset's image
+ *     { name: "map1",    type: "tmx",   src: "data/map/map1.tmx" },
+ *     { name: "tileset", type: "tsx",   src: "data/map/tileset.tsx" },
+ *     { name: "tileset", type: "image", src: "data/map/tileset.png" },
+ *     // sounds: src is the directory (see audio.init)
+ *     { name: "jump", type: "audio", src: "data/sfx/" },
+ *     // a web font
+ *     { name: "PressStart2P", type: "fontface", src: "data/fnt/PressStart2P.ttf" },
  * ];
- * ...
- * // set all resources to be loaded (callback form)
- * me.loader.preload(game.assets, () => this.loaded());
- * // ...or await it (the callback still fires too)
- * await me.loader.preload(game.assets);
+ *
+ * // await it...
+ * await loader.preload(resources);
+ * state.change(state.PLAY);
+ *
+ * // ...or pass a callback
+ * loader.preload(resources, () => {
+ *     state.change(state.PLAY);
+ * });
+ * @example
+ * // bundles and descriptors in one list
+ * loader.setBundle("common", commonAssets);
+ * loader.setBundle("level1", level1Assets);
+ * await loader.preload([
+ *     "common",
+ *     "level1",
+ *     { name: "logo", type: "image", src: "img/logo.png" },
+ * ]);
  * @category Assets
  */
-export function preload(assets: Asset[], onloadcb?: Function, switchToLoadState?: boolean): Promise<void>;
+export function preload(assets: Array<Asset | string>, onloadcb?: Function | undefined, switchToLoadState?: boolean | undefined): Promise<void>;
 /**
- * retry loading assets after a loading failure
- * @param {string} src - src of asset to reload
+ * Retry an asset that failed to load in a {@link loader.preload} (or a
+ * `load(id)`), given its `src` as reported by {@link event.LOADER_ERROR}.
+ *
+ * The retried asset counts towards the progress of the call it failed in,
+ * and once every asset of that call has loaded, that call completes: its own
+ * callback is called, if it was given one, and `LOADER_COMPLETE` is emitted.
+ * The promise that call returned has already rejected, and stays rejected.
+ * The asset then belongs to whoever asked for it: pinned if it was listed
+ * directly, held by its bundles if a bundle asked for it. Should it fail
+ * again, `LOADER_ERROR` is emitted again.
+ * @param {string} src - the `src` of the asset to retry, exactly as in its
+ * descriptor (`asset.src` of the asset `LOADER_ERROR` passed)
+ * @throws {TypeError} when no failed asset has that `src`
  * @example
- *  event.on(
- *      event.LOADER_ERROR,
- *      (res) => {
- *          // custom function
- *          showErrorNotification({
- *              text: `Error during loading content: ${res.name}`,
- *              done: loader.reload(res.src);
- *          })
- *      }
- *  );
- **/
+ * import { event, loader } from "melonjs";
+ *
+ * event.on(event.LOADER_ERROR, (asset) => {
+ *     // the game's own dialog, with a "retry" button
+ *     showErrorDialog(`Could not load ${asset.name}`, () => {
+ *         loader.reload(asset.src);
+ *     });
+ * });
+ * @category Assets
+ */
 export function reload(src: string): void;
 /**
- * Load a single asset (to be used if you need to load additional asset(s) during the game)
- * @param {Asset} asset
- * @param {Function} [onload] - function to be called when the asset is loaded
- * @param {Function} [onerror] - function to be called in case of error
- * @returns {number|Promise<void>} with `onload`/`onerror` provided, the amount
- * of corresponding resource to be preloaded (the legacy callback form). With
- * **both omitted**, a Promise that resolves once the asset has loaded, so you
- * can `await loader.load(asset)` for a one-off dynamic load.
+ * Declare a bundle and load it, in one call: exactly
+ * {@link loader.setBundle} with these assets followed by `load(id)`, so the
+ * same checks, the same progress and shader warm-up, `LOADER_COMPLETE`, and
+ * the same promise. Handy where a level's assets are declared next to the
+ * code that enters it.
+ *
+ * Called again with the same assets (same type, name and src, in any order),
+ * it simply loads the bundle, fetching nothing already in memory. With
+ * different assets it redefines the bundle, which is allowed only while that
+ * bundle is not loaded or loading, and throws synchronously otherwise, as
+ * `setBundle` does. Release it with {@link loader.unload} and its id.
+ * @overload
+ * @param {string} id - the bundle id
+ * @param {Asset[]|Asset} assets - the bundle's asset descriptors (one
+ * descriptor on its own is accepted too)
+ * @returns {Promise<void>} resolves once every asset of the bundle has
+ * loaded; rejects if one fails to load
+ * @throws {TypeError} synchronously, on an invalid id or asset list
+ * @throws {Error} synchronously, when the bundle is loaded or loading with
+ * other assets, or an asset has an unknown type
  * @example
- * // load an image asset (callback form)
- * me.loader.load({name: "avatar",  type:"image",  src: "data/avatar.png"}, () => this.onload(), () => this.onerror());
- * // ...or await a single dynamic asset (no callbacks)
- * await me.loader.load({name: "avatar", type: "image", src: "data/avatar.png"});
- * // load a compressed texture with fallback chain
- * me.loader.load({name: "terrain", type:"image", src: ["data/gfx/terrain.astc.ktx", "data/gfx/terrain.dds", "data/gfx/terrain.png"]}, () => this.onload());
- * // load a base64 image asset
- *  me.loader.load({name: "avatar", type:"image", src: "data:image/png;base64,iVBORw0KAAAQAAAAEACA..."};
- *  // load a base64 video asset
- *  me.loader.load({
- *     name: "avatar",
- *     type:"video",
- *     src: "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZ.."
- *  };
- * // start loading music
- * me.loader.load({
- *     name   : "bgmusic",
- *     type   : "audio",
- *     src    : "data/audio/"
- * }, function () {
- *     me.audio.play("bgmusic");
+ * // a level's assets, declared where they are loaded
+ * await loader.load("level2", [
+ *     { name: "level2", type: "tmx",   src: "data/map/level2.tmx" },
+ *     { name: "tiles",  type: "image", src: "data/img/tiles.png" },
+ * ]);
+ * await level.load("level2", { async: true });
+ * // ...and later, by id as usual
+ * loader.unload("level2");
+ * @category Assets
+ */
+export function load(id: string, assets: Asset[] | Asset): Promise<void>;
+/**
+ * Load a bundle declared with {@link loader.setBundle} (or by a record
+ * passed to {@link loader.preload}), while the game keeps running.
+ *
+ * Every asset of the bundle that is not already in memory is loaded, then the
+ * shaders are warmed, as {@link loader.preload} does: `LOADER_PROGRESS`
+ * reports this call's assets (each asset is one step, and one already in
+ * memory counts as a step done at once), then `onload` is called,
+ * `LOADER_COMPLETE` is emitted and the promise resolves. Unlike `preload` it
+ * does NOT switch to the loading screen; to show it for a level, use
+ * `loader.preload([id])`.
+ *
+ * The bundle then holds its assets: they stay in memory until
+ * {@link loader.unload} with the same id releases them, and are freed then
+ * unless another loaded bundle lists them too, or they were loaded the old
+ * way (by `preload` / `load` with a descriptor), which pins them. Assets keep
+ * their own names: `getImage("tiles")` reads a bundle's image as any other.
+ *
+ * If an asset fails to load, `LOADER_ERROR` is emitted with it, `onerror` is
+ * called and the promise rejects; the assets that did load stay, held by the
+ * bundle, and {@link loader.reload} retries the one that failed.
+ * @overload
+ * @param {string} id - the id of a declared bundle
+ * @param {Function} [onload] - called once every asset of the bundle has
+ * loaded, before `LOADER_COMPLETE`
+ * @param {Function} [onerror] - called with the error if an asset fails to
+ * load (the returned promise then needs no `catch` of its own)
+ * @returns {Promise<void>} resolves once the bundle is loaded, with or
+ * without the callbacks; rejects if an asset fails to load
+ * @throws {Error} synchronously, when no bundle is declared under that id
+ * @example
+ * // before entering a level that may have been unloaded: fetches only what
+ * // is missing, and nothing at all when the bundle is still in memory
+ * await loader.load("level1");
+ * await level.load("level1", { async: true });
+ * @example
+ * // the next level's assets, loaded while the current one keeps playing
+ * loader.load("level3", () => {
+ *     nextLevelReady = true;
  * });
  * @category Assets
  */
-export function load(asset: Asset, onload?: Function, onerror?: Function): number | Promise<void>;
+export function load(id: string, onload?: Function | undefined, onerror?: Function | undefined): Promise<void>;
+/**
+ * Load a single asset, and wait for it: for an asset needed during the game
+ * that was not preloaded.
+ *
+ * No loading screen, progress or loader event: the promise is the only
+ * signal. An asset already in memory resolves at once, without a request
+ * (for every type but `"binary"`, `"fontface"`, `"aseprite"` and `"js"`,
+ * which are fetched again). The asset is pinned: unloading a bundle that also lists it does not free it,
+ * {@link loader.unload} with the descriptor does.
+ * @overload
+ * @param {Asset} asset - the asset to load
+ * @returns {Promise<void>} resolves once the asset has loaded; rejects with
+ * the error if it fails to load
+ * @throws {Error} synchronously, when the asset type is unknown
+ * @example
+ * await loader.load({ name: "avatar", type: "image", src: "data/img/avatar.png" });
+ * const avatar = new Sprite(0, 0, { image: "avatar" });
+ * @category Assets
+ */
+export function load(asset: Asset): Promise<void>;
+/**
+ * Load a single asset, with callbacks: the original form of
+ * `load(asset)`, for an asset needed during the game that was not preloaded.
+ *
+ * No loading screen, progress or loader event: the callbacks are the only
+ * signal. The asset is pinned: unloading a bundle that also lists it does not
+ * free it, {@link loader.unload} with the descriptor does.
+ * @overload
+ * @param {Asset} asset - the asset to load
+ * @param {Function} [onload] - called once the asset has loaded. Not called
+ * for an asset already in memory: the function then returns `0` (for every
+ * type but `"binary"`, `"fontface"`, `"aseprite"` and `"js"`, which are
+ * fetched again)
+ * @param {Function} [onerror] - called with the error if it fails to load
+ * @returns {number|Promise<void>} the number of resources it started loading
+ * (usually `1`), or `0` when the asset was already in memory. With `onload`
+ * and `onerror` both undefined it is the promise form above, and returns a
+ * promise
+ * @throws {Error} synchronously, when the asset type is unknown
+ * @example
+ * loader.load(
+ *     { name: "bgmusic", type: "audio", src: "data/bgm/" },
+ *     () => audio.play("bgmusic"),
+ *     (error) => console.warn("no music", error),
+ * );
+ * @category Assets
+ */
+export function load(asset: Asset, onload?: Function | undefined, onerror?: Function | undefined): number | Promise<void>;
 /**
- * unload the specified asset to free memory
- * @param {Asset} asset
- * @returns {boolean} true if unloaded
- * @example me.loader.unload({name: "avatar",  type:"image"});
+ * Release a bundle, or free a single asset: a string is a bundle id, an
+ * object is an asset descriptor. So `loader.unload("map1")` releases the
+ * bundle `"map1"`, and `loader.unload({ name: "map1", type: "tmx" })` frees
+ * that one map, whichever bundles list it.
+ *
+ * **With a bundle id** (see {@link loader.setBundle}), the bundle lets go of
+ * each of its assets, and every one that nothing else still holds is freed:
+ * an asset another loaded bundle lists stays, and so does one loaded the old
+ * way (by `preload` / `load` with a descriptor), which pins it. Freeing a map
+ * or a glTF scene this way also unregisters its level, so `level.load` of it
+ * throws "not found" until the bundle is loaded again. Unload the bundle of
+ * the level being left once the next level is in: unloading the bundle of the
+ * level being played leaves the world as it is, but with no current level,
+ * so `level.reload()` has nothing to reload. Allowed while the bundle is
+ * still loading: its assets are then freed as they arrive.
+ *
+ * **With an asset descriptor** (only `name` and `type` are read), the asset is
+ * freed at once, whoever holds it: a bundle listing it reports
+ * {@link loader.isLoaded} `false` afterwards, and loading that bundle again
+ * fetches it again.
+ *
+ * Either way, freeing an image also frees the texture the renderer uploaded
+ * from it, a shader its GPU program, a font its place in `document.fonts`.
+ * A shader handed out by {@link loader.getShader} is not tracked once handed
+ * out, so an effect that outlives a level (a HUD's, a camera's) belongs in a
+ * bundle that outlives it too, or it is freed under whatever still uses it.
+ * @param {string|Asset} asset - a bundle id, or the descriptor of the asset
+ * to free
+ * @returns {boolean} with a bundle id, `false` when the bundle was not
+ * loaded; with a descriptor, `false` when the asset was not in memory
+ * @throws {Error} synchronously, on an unknown bundle id, or a descriptor
+ * whose type the loader keeps nothing for (a type registered with
+ * {@link loader.setParser}: the game keeps those assets itself)
+ * @example
+ * // level 1 is behind the player for good: free what only it uses
+ * await level.load("level2", { async: true });
+ * loader.unload("level1");
+ * @example
+ * // free one asset, whatever loaded it
+ * loader.unload({ name: "avatar", type: "image" });
  * @category Assets
  */
-export function unload(asset: Asset): boolean;
+export function unload(asset: string | Asset): boolean;
 /**
- * unload all resources to free memory
- * @example me.loader.unloadAll();
+ * Free every asset the loader holds, whoever holds it: the caches, the audio
+ * clips, and what the engine made from them (GPU textures, shader programs,
+ * fonts in `document.fonts`).
+ *
+ * Bundles declared with {@link loader.setBundle} stay declared, all of them
+ * back to not loaded, so they can be loaded again by id. Base URLs, options
+ * and parsers are kept too. Levels stay registered with the level director:
+ * load the bundles (or preload the assets) again before loading one.
+ * @example
+ * // back to the title screen: drop everything, then load what it needs
+ * loader.unloadAll();
+ * await loader.load("common");
  * @category Assets
  */
 export function unloadAll(): void;
+/**
+ * Declare a bundle: a named list of the asset descriptors you would otherwise
+ * pass to {@link loader.preload}, to load and free together — typically the
+ * assets of one level, plus a `"common"` bundle for what every level uses.
+ * Passing a record of bundles to `preload` (`{ common: [...], level1: [...] }`,
+ * as an assets file exports it) declares each of its keys this way.
+ *
+ * A bundle is a lifetime, not a namespace: its assets keep their own names
+ * and live in the same caches as every other asset, so `getImage("tiles")`
+ * and `level.load("map1")` read them as before. Bundle ids and asset names
+ * are separate, so a level's bundle may share its map's name. Load it with
+ * {@link loader.load} (or name it in a {@link loader.preload} list), check it
+ * with {@link loader.isLoaded}, and release it with {@link loader.unload}. An
+ * asset listed in several bundles is loaded once and freed with the last
+ * loaded bundle that lists it, so list a shared asset in every bundle that
+ * uses it.
+ *
+ * Declaring does not load anything, and a bundle can be declared before the
+ * parsers of custom types it uses are registered. Redefining an id replaces
+ * its list, but only while that bundle is not loaded or loading: unload it
+ * first. The list is copied, so changing the array afterwards changes nothing.
+ * An asset listed twice is one asset (type and name identify it), and an
+ * empty list is allowed: such a bundle loads at once and is always loaded.
+ * @param {string} id - the bundle id
+ * @param {Asset[]} assets - its asset descriptors (bundle ids cannot be nested)
+ * @throws {TypeError} on an empty or non-string id, or a list that is not an
+ * array of asset descriptors
+ * @throws {Error} when that bundle is loaded or loading
+ * @example
+ * loader.setBundle("common", [
+ *     { name: "player", type: "image", src: "img/player.png" },
+ *     { name: "font",   type: "fontface", src: "font/PressStart2P.ttf" },
+ * ]);
+ * loader.setBundle("level1", [
+ *     { name: "level1", type: "tmx",   src: "map/level1.tmx" },
+ *     { name: "hills",  type: "image", src: "img/hills.png" },
+ * ]);
+ * loader.setBundle("level2", [
+ *     { name: "level2", type: "tmx",   src: "map/level2.tmx" },
+ *     { name: "hills",  type: "image", src: "img/hills.png" }, // shared
+ * ]);
+ *
+ * // boot: behind the loading screen
+ * await loader.preload(["common", "level1"]);
+ *
+ * // moving on: load the next level, switch, then free the previous one
+ * // ("hills" stays in memory: level2 lists it too)
+ * await loader.load("level2");
+ * await level.load("level2", { async: true });
+ * loader.unload("level1");
+ * @category Assets
+ */
+export function setBundle(id: string, assets: Asset[]): void;
+/**
+ * The asset list of a declared bundle, or `undefined` when there is none:
+ * the way to test whether an id is declared, since the other bundle calls
+ * throw on an unknown one.
+ * @param {string} id - the bundle id
+ * @returns {Asset[]|undefined} a copy of its asset descriptors, or
+ * `undefined` when no bundle is declared under that id
+ * @example
+ * if (loader.getBundle("level3") === undefined) {
+ *     loader.setBundle("level3", level3Assets);
+ * }
+ * @category Assets
+ */
+export function getBundle(id: string): Asset[] | undefined;
+/**
+ * Whether every asset of a bundle is in memory, however it got there (by
+ * this bundle, another one, or the old way) — so a game can skip a loading
+ * screen it does not need. `false` again as soon as one of them is unloaded,
+ * by a bundle or on its own. An empty bundle is always loaded.
+ * @param {string} id - the bundle id
+ * @returns {boolean} true if every asset of the bundle is loaded
+ * @throws {Error} when no bundle is declared under that id
+ * @example
+ * if (!loader.isLoaded("level2")) {
+ *     await loader.preload(["level2"]); // with the loading screen
+ * }
+ * level.load("level2");
+ * @category Assets
+ */
+export function isLoaded(id: string): boolean;
 /**
  * additional import for TypeScript
  * @import {CompressedImage} from "./parsers/compressed_textures/compressed_image.js";
  * @import GLShader from "../video/webgl/glshader.js";
  * @import ShaderEffect from "../video/effects/shadereffect.js";
+ * @import {AssetParser, Bundle, PreloadTally} from "./internal-types.ts";
  */
 /**
  * The parsed glTF/GLB scene descriptors, re-exported from the parser that
@@ -318,118 +645,127 @@ export function unloadAll(): void;
  * @typedef {import("./parsers/gltf.js").GLTFNode} GLTFNode
  */
 /**
- * a small class to manage loading of stuff and manage resources
- * @namespace loader
+ * the cache-busting query string appended to asset URLs, set through
+ * {@link setOptions} (`nocache: true`)
+ * @ignore
  */
 export let nocache: string;
 /**
+ * The base URL of each asset type, as set by {@link setBaseURL}: prepended to
+ * the `src` of every asset of that type, unless the `src` is a data URI. A
+ * type with no entry here is loaded from its `src` as written.
+ * Read it here, change it through `setBaseURL`.
  * @type {Object.<string, string>}
+ * @example
+ * loader.setBaseURL("image", "data/img/");
+ * loader.baseURL.image; // "data/img/"
  */
 export const baseURL: {
     [x: string]: string;
 };
 /**
- * crossOrigin attribute to configure the CORS requests for Image and Video data element.
- * By default (that is, when the attribute is not specified), CORS is not used at all.
- * The "anonymous" keyword means that there will be no exchange of user credentials via cookies,
- * client-side SSL certificates or HTTP authentication as described in the Terminology section of the CORS specification.<br>
+ * The `crossOrigin` attribute the loader gives the `<video>` and `<script>`
+ * elements it creates, and the images of a glTF model: `"anonymous"` sends no
+ * user credentials (cookies, client-side TLS certificates or HTTP
+ * authentication) to another origin, `"use-credentials"` sends them, as
+ * `withCredentials` does.<br>
+ * Every other asset (images, JSON, maps, binary files, buffered audio...) is
+ * always requested with CORS, whatever this says: an asset on another origin
+ * loads when its server allows it (an `Access-Control-Allow-Origin` header),
+ * and fails to load, with an error naming the asset, when it does not.
  * @type {string}
  * @default undefined
  * @see {@link setOptions}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes}
- * @deprecated since 20.4.0, read-only — set it with
- * {@link setOptions}. This is a module binding, so assigning to it throws a
- * `TypeError`; the example below never worked.
+ * @deprecated since 20.4.0 as a setting: it is read-only, set it with
+ * {@link setOptions}. It is a module binding, so assigning to it
+ * (`loader.crossOrigin = "anonymous"`) throws a `TypeError`, and always did.
  * @example
- *  // allow for cross-origin texture loading
- * me.loader.setOptions({ crossOrigin: "anonymous" });
- *
- * // set all resources to be loaded
- * me.loader.preload(game.resources, () => this.loaded());
+ * // play videos from another origin, without credentials
+ * loader.setOptions({ crossOrigin: "anonymous" });
+ * await loader.preload(resources);
  */
 export let crossOrigin: string;
 /**
- * indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies,
- * authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests.
- * @public
+ * Whether requests to another origin carry credentials: cookies,
+ * authorization headers or TLS client certificates. It has no effect on
+ * requests to the game's own origin, which always carry the browser's
+ * credentials, as the page and its scripts do, so a game behind a login or a
+ * session cookie loads its own assets without it.
  * @type {boolean}
- * @see {@link setOptions}
  * @default false
+ * @see {@link setOptions}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials}
- * @deprecated since 20.4.0, read-only — set it with
- * {@link setOptions}. This is a module binding, so assigning to it throws a
- * `TypeError`; the example below never worked.
+ * @deprecated since 20.4.0 as a setting: it is read-only, set it with
+ * {@link setOptions}. It is a module binding, so assigning to it
+ * (`loader.withCredentials = true`) throws a `TypeError`, and always did.
  * @example
- *  // enable withCredentials, for assets behind a session cookie or login
- * me.loader.setOptions({ withCredentials: true });
- *
- * // set all resources to be loaded
- * me.loader.preload(game.resources, () => this.loaded());
+ * // assets on a CDN behind a session cookie or a login
+ * loader.setOptions({ withCredentials: true });
+ * await loader.preload(resources);
  */
 export let withCredentials: boolean;
 /**
- * A registered parser, normalized by {@link loader.setParser}.
+ * An asset descriptor: what to load, and the name to keep it under. The same
+ * descriptors go in a {@link preload} list, in a bundle ({@link setBundle}),
+ * or to {@link load} on their own.
  *
- * Every type gets the same shape whether or not it needs the src hooks, so
- * `load()` can treat all of them alike. The alternative — a bare function that
- * some types decorate with extra properties — puts the knowledge of which
- * types are special back into the caller, which is what moving it out was for.
- */
-export type AssetParser = {
-    /**
-     * - preloads the asset and returns how many
-     * resources it will load (0 when already cached)
-     */
-    parse: Function;
-    /**
-     * - turns a type-specific
-     * descriptor into a bare path, before any base URL is applied. Identity unless
-     * the type overrides it
-     */
-    normalizeSrc: (arg0: string) => string;
-    /**
-     * - whether the normalized
-     * src is relative to this type's base URL. Declares only this type's own
-     * exceptions, such as a `local()` font naming an installed family — data URIs
-     * are excluded for every type before this is consulted
-     */
-    needsBaseURL: (arg0: string) => boolean;
-};
-/**
- * an asset definition to be used with the loader
+ * The type and the name together identify an asset, so two assets of
+ * different types may share a name: a texture atlas is usually an `"image"`
+ * and a `"json"` both called `"texture"`.
  */
 export type Asset = {
     /**
-     * - name of the asset
+     * - the name the asset is kept and read back under
+     * (`loader.getImage(name)`, `new Sprite(x, y, { image: name })`,
+     * `level.load(name)`, `audio.play(name)`)
      */
     name: string;
     /**
-     * - the type of the asset ("audio"|"binary"|"image"|"json"|"js"|"tmx"|"tsx"|"fontface"|"video"|"aseprite"|"shader"|"obj"|"mtl"|"gltf"|"glb"). JSON-serialised Tiled maps and tilesets (`.tmj` / `.tsj`) load under `"tmx"` / `"tsx"` — those are file extensions, not asset types. Any other type is one registered with {@link loader.setParser}.
+     * - the type of the asset, which picks its parser:
+     * "audio", "binary", "image", "json", "js", "tmx", "tsx", "fontface", "video",
+     * "aseprite", "shader", "obj", "mtl", "gltf" or "glb". JSON-serialised Tiled
+     * maps and tilesets (`.tmj` / `.tsj`) load under `"tmx"` / `"tsx"`: those are
+     * file extensions, not asset types. Any other type is one registered with
+     * {@link loader.setParser}.
      */
     type: string;
     /**
-     * - path and/or file name of the resource (for audio assets only the path is required).
-     * For image assets, an array of sources can be provided as a fallback chain (e.g. compressed texture formats by priority, with a PNG fallback).
-     * The loader will try each source in order and use the first one that loads successfully.
+     * - the URL of the file, relative to the
+     * page or to the type's base URL ({@link setBaseURL}), or a data URI.
+     * For `"audio"` it is the **directory** holding the clip: the loader appends
+     * the asset name and each extension given to `audio.init()`, and keeps the
+     * first that decodes.
+     * For `"image"` it may be an array of sources, tried in order until one loads:
+     * a fallback chain, such as compressed texture formats by priority with a PNG
+     * last.
+     * For `"shader"` it may be an object of URLs instead (see the example).
      */
     src?: string | string[];
     /**
-     * - inline content if not provided through a src url: TMX data for "tmx" assets, GLSL source (the ShaderEffect fragment-body convention) for "shader" assets. A shader may instead carry a `{glsl, wgsl}` pair, so one asset serves both backends; either half may be omitted
+     * - inline content
+     * in place of a `src`: the parsed Tiled JSON map or tileset (an object) for
+     * `"tmx"` / `"tsx"`, the GLSL source of an effect body for `"shader"`, or a
+     * `{glsl, wgsl}` pair of them so that one asset serves both backends (either
+     * half may be omitted)
      */
     data?: string | {
         glsl?: string;
         wgsl?: string;
     };
     /**
-     * - Set to true to not to wait for large audio or video file to be downloaded before playing.
+     * - audio and video: start playing before
+     * the whole file is downloaded, rather than waiting for it
      */
     stream?: boolean;
     /**
-     * - Set to true to automatically start playing audio or video when loaded or added to a scene (using autoplay might require user iteraction to enable it)
+     * - audio and video: start playing once
+     * loaded, or once added to a scene (a browser may require a user interaction
+     * first)
      */
     autoplay?: boolean;
     /**
-     * - Set to true to automatically loop the audio or video when playing
+     * - audio and video: loop when playing
      */
     loop?: boolean;
 };