@moku-labs/game 0.0.1 → 0.0.2

package/dist/types-DWILGrPn.d.mts

@@ -0,0 +1,622 @@
+import { T as Descriptor, k as Api$2, lt as Require, t as Api$1, x as NodeInfo } from "./types-JNc_UQBo.mjs";
+import { r as PixiTexture, t as Api$3 } from "./types-BxkNNYul.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/plugins/assets/types.d.ts
+declare namespace types_d_exports {
+  export { Api, AssetKind, AssetsCtx, AssetsIo, AtlasFrame, BundleMap, BundleRecord, BundleSpec, BundleUsage, Config, CreateTextureOptions, DecodedImage, DefineBundles, Deps, Events, FetchResponse, FlowRest, FontAsset, FontPage, Inflight, KernelSlice, LoadBundles, LoadReason, LoadResult, LoadedAssets, LoadedFont, Manifest, ManifestBundle, ManifestFile, NineBorders, NineSlice, PreloadQueue, State, Texture, Tier, Usage };
+}
+/**
+ * When a bundle is loaded. `boot` and `core` stay for the whole session, `scene` and `feature`
+ * come and go with the graph, `lazy` is never preloaded.
+ *
+ * @example
+ * ```ts
+ * const tier: Tier = "scene";
+ * ```
+ */
+type Tier = "boot" | "core" | "scene" | "feature" | "lazy";
+/**
+ * What one file of a bundle is. A `.fnt` with its `.png` pages is one `font`, an `.mp3` is
+ * `audio`, everything else is a `texture`. A file of an older manifest that names no kind is a
+ * texture.
+ *
+ * @example
+ * ```ts
+ * const kind: AssetKind = "font";
+ * ```
+ */
+type AssetKind = "texture" | "font" | "audio";
+/**
+ * A GPU texture. `assets` owns its lifetime and never imports Pixi: `renderer` makes and destroys
+ * it, this plugin only says when.
+ */
+type Texture = PixiTexture;
+/**
+ * A decoded image, ready for the upload. `createImageBitmap` produces the first shape.
+ */
+type DecodedImage = ImageBitmap | HTMLImageElement;
+/**
+ * Nine-slice borders in pixels, in the order left, top, right, bottom.
+ *
+ * @example
+ * ```ts
+ * const borders: NineBorders = [48, 48, 48, 48];
+ * ```
+ */
+type NineBorders = readonly [number, number, number, number];
+/**
+ * Options of `io.createTexture`. Same shape as `renderer.sync.textures.create`.
+ *
+ * @example
+ * ```ts
+ * const options: CreateTextureOptions = { nine: [48, 48, 48, 48] };
+ * ```
+ */
+type CreateTextureOptions = {
+  nine?: NineBorders;
+};
+/**
+ * The part of a fetch response the plugin reads: the manifest is `json`, a texture is a `blob`,
+ * a font file is `text` and an audio file stays the raw `arrayBuffer`. The global `Response`
+ * fits it.
+ */
+type FetchResponse = {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+  blob(): Promise<Blob>;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+};
+/**
+ * The I/O seam: everything that leaves the plugin. `undefined` in the config means the browser
+ * pair plus `renderer.sync.textures`; a test passes a fake and nothing touches the network or a GPU.
+ *
+ * @example
+ * ```ts
+ * // A unit test serves two files from memory and counts the textures it handed out.
+ * const io: AssetsIo = {
+ *   fetch: async () => ({
+ *     ok: true,
+ *     status: 200,
+ *     json: async () => ({}),
+ *     blob: async () => blob,
+ *     text: async () => 'info face="body"',
+ *     arrayBuffer: async () => new ArrayBuffer(8)
+ *   }),
+ *   decode: async () => bitmap,
+ *   createTexture: () => ({ id: "t1" }) as unknown as Texture,
+ *   destroyTexture: texture => destroyed.push(texture)
+ * };
+ *
+ * createApp({ plugins: [...screen], pluginConfigs: { assets: { io, manifest } } });
+ * ```
+ */
+type AssetsIo = {
+  /**
+   * Fetches one URL: the manifest, or a file of a bundle.
+   *
+   * @param url - Absolute or root-relative URL.
+   * @param init - Carries the abort signal of the running load.
+   * @param init.signal - Aborts the request when the load is cancelled.
+   * @returns The response.
+   */
+  fetch(url: string, init: {
+    signal: AbortSignal;
+  }): Promise<FetchResponse>;
+  /**
+   * Decodes one image file.
+   *
+   * @param blob - The bytes of the file.
+   * @returns The decoded image.
+   */
+  decode(blob: Blob): Promise<DecodedImage>;
+  /**
+   * Uploads one decoded image to the GPU.
+   *
+   * @param image - The decoded image.
+   * @param options - `nine` becomes the default nine-slice borders of the texture.
+   * @returns The new texture.
+   */
+  createTexture(image: DecodedImage, options?: CreateTextureOptions): Texture;
+  /**
+   * Frees one texture and its source.
+   *
+   * @param texture - The texture to free.
+   */
+  destroyTexture(texture: Texture): void;
+};
+/**
+ * Nine-slice metadata of one file, as the scanner writes it. Always four numbers: the tags
+ * `{nine=N}`, `{nine=H,V}` and `{nine=L,T,R,B}` all land here.
+ *
+ * @example
+ * ```ts
+ * const nine: NineSlice = { left: 48, top: 48, right: 48, bottom: 48 };
+ * ```
+ */
+type NineSlice = {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+};
+/**
+ * Reserved atlas placement. V2 never writes it and refuses to load a file that carries it.
+ *
+ * @example
+ * ```ts
+ * const frame: AtlasFrame = { page: "ui-0.png", x: 0, y: 0, width: 128, height: 128 };
+ * ```
+ */
+type AtlasFrame = {
+  page: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+/**
+ * One page image of a font. A page has no key of its own: it belongs to the `.fnt` file that
+ * names it, and is loaded and freed with it.
+ *
+ * @example
+ * ```ts
+ * const page: FontPage = {
+ *   path: "features/ui/assets/body_0.png",
+ *   width: 256,
+ *   height: 128,
+ *   mb: 0.125
+ * };
+ * ```
+ */
+type FontPage = {
+  path: string;
+  width: number;
+  height: number;
+  mb: number;
+};
+/**
+ * One file of a bundle. `mb` is what it costs: `width × height × 4` bytes for a texture, the sum
+ * of the pages for a font, the size of the file for audio. `kind` is absent for a texture, which
+ * is what every manifest written before fonts and audio carries.
+ *
+ * @example
+ * ```ts
+ * const file: ManifestFile = {
+ *   key: "ui.panel",
+ *   path: "features/ui/assets/panel{nine=48}.png",
+ *   width: 256,
+ *   height: 128,
+ *   mb: 0.125,
+ *   nine: { left: 48, top: 48, right: 48, bottom: 48 }
+ * };
+ * ```
+ */
+type ManifestFile = {
+  key: string;
+  path: string;
+  kind?: AssetKind;
+  width: number;
+  height: number;
+  mb: number;
+  pages?: readonly FontPage[];
+  nine?: NineSlice;
+  atlas?: AtlasFrame;
+};
+/**
+ * One bundle of the manifest: which feature owns it, when it loads and what it costs.
+ *
+ * @example
+ * ```ts
+ * const bundle: ManifestBundle = { feature: "ui", tier: "core", mb: 0.125, files: [] };
+ * ```
+ */
+type ManifestBundle = {
+  feature: string;
+  tier: Tier;
+  mb: number;
+  files: readonly ManifestFile[];
+};
+/**
+ * The manifest: the contract between the scanner, this plugin and the editor later. Bundles are
+ * sorted by name and files by key, so two scans of the same tree give the same bytes.
+ *
+ * @example
+ * ```ts
+ * const manifest: Manifest = {
+ *   version: 1,
+ *   bundles: { ui: { feature: "ui", tier: "core", mb: 0, files: [] } }
+ * };
+ *
+ * createApp({ plugins: [...screen], pluginConfigs: { assets: { manifest } } });
+ * ```
+ */
+type Manifest = {
+  version: 1;
+  bundles: Readonly<Record<string, ManifestBundle>>;
+};
+/**
+ * What a feature declares about one of its bundles. `files` are globs relative to the feature's
+ * `assets/`; a bundle with `files` takes those files out of the feature's default bundle.
+ *
+ * @example
+ * ```ts
+ * const spec: BundleSpec = { tier: "lazy", files: ["chains/*.png"] };
+ * ```
+ */
+type BundleSpec = {
+  tier: Tier;
+  files?: readonly string[];
+};
+/**
+ * What `defineBundles` returns: plain data the scanner and the plugin both read.
+ *
+ * @example
+ * ```ts
+ * const bundles: BundleMap = {
+ *   kind: "bundles",
+ *   map: { board: { tier: "scene" }, "board.chains": { tier: "lazy", files: ["chains/*.png"] } }
+ * };
+ * ```
+ */
+type BundleMap<Key extends string = string> = {
+  kind: "bundles";
+  map: Partial<Record<Key, BundleSpec>>;
+};
+/**
+ * `defineBundles` bound to the bundle keys of one game. `defineGame` returns it, so a key that is
+ * not in `BundleKey` does not compile.
+ *
+ * @example
+ * ```ts
+ * const defineGameBundles: DefineBundles<"board" | "board.chains"> = defineBundles;
+ * ```
+ */
+type DefineBundles<Key extends string> = (map: Partial<Record<Key, BundleSpec>>) => BundleMap<Key>;
+/**
+ * The `load` descriptor helper bound to the bundle keys of one game.
+ *
+ * @example
+ * ```ts
+ * const loadGameBundle: LoadBundles<"board" | "board.chains"> = load;
+ * ```
+ */
+type LoadBundles<Key extends string> = (bundle: Key | readonly Key[]) => Descriptor;
+/**
+ * What the `load` effect resolves with, so a loading node can write its own progress.
+ *
+ * @example
+ * ```ts
+ * const result: LoadResult = { loaded: ["board.chains"], mb: 1.25 };
+ * ```
+ */
+type LoadResult = {
+  loaded: string[];
+  mb: number;
+};
+/**
+ * Why a bundle was loaded. It is the reason of the caller that started the load; a later waiter
+ * changes nothing.
+ *
+ * @example
+ * ```ts
+ * const reason: LoadReason = "enter";
+ * ```
+ */
+type LoadReason = "boot" | "enter" | "request" | "preload";
+/**
+ * The running load of one bundle. Every caller is a waiter; the last one to leave aborts it.
+ * `promise` never rejects: what broke waits in `error`, so a load nobody joined any more cannot
+ * become an unhandled rejection.
+ */
+type Inflight = {
+  promise: Promise<void>;
+  controller: AbortController;
+  waiters: number;
+  error: unknown;
+};
+/**
+ * A loaded font: the `.fnt` file as text and the page textures it names. `text` installs the
+ * first page in the renderer; every page is destroyed with the bundle.
+ *
+ * @example
+ * ```ts
+ * const font: FontAsset = { fnt: 'info face="body" size=32', texture };
+ * ```
+ */
+type FontAsset = {
+  fnt: string;
+  texture: Texture;
+};
+/**
+ * What the plugin keeps for a loaded font: the public pair plus every page, because a font of
+ * two pages owns two textures.
+ */
+type LoadedFont = FontAsset & {
+  pages: readonly Texture[];
+};
+/**
+ * What one bundle brought, by asset key: textures, fonts with their pages, and the undecoded
+ * bytes of the audio files. A running load fills the same three maps before they are published.
+ */
+type LoadedAssets = {
+  textures: Map<string, Texture>;
+  fonts: Map<string, LoadedFont>;
+  audio: Map<string, ArrayBuffer>;
+};
+/**
+ * What the plugin knows about one bundle. `lastUsed` is the value of `useCounter` at the last
+ * touch: a counter, never a clock.
+ */
+type BundleRecord = LoadedAssets & {
+  status: "idle" | "loading" | "loaded";
+  inflight: Inflight | undefined;
+  lastUsed: number;
+};
+/**
+ * The background preload. A new rest node replaces it and aborts the old controller.
+ */
+type PreloadQueue = {
+  bundles: string[];
+  controller: AbortController;
+};
+/**
+ * assets plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [...screen, boardFeature],
+ *   pluginConfigs: { assets: { manifest: "/assets/manifest.json", textureBudgetMb: 192 } }
+ * });
+ * ```
+ */
+type Config = {
+  /** URL of `manifest.json`, or the parsed manifest itself (tests, headless). `undefined`: an empty manifest. */manifest: string | Manifest | undefined; /** Texture memory budget in MB. */
+  textureBudgetMb: number; /** How many edges from a rest node the background preload looks ahead. `0` turns preload off. */
+  preloadDepth: number; /** Prefix of every file URL. The CDN seam. `undefined`: the folder of the manifest URL, or `"/"`. */
+  baseUrl: string | undefined; /** I/O seam. `undefined`: the browser pair plus `renderer.sync.textures`, or headless. */
+  io: AssetsIo | undefined;
+};
+/**
+ * assets plugin state.
+ */
+type State = {
+  /** `undefined` means headless: manifest only, no fetches, no textures. */io: AssetsIo | undefined; /** Empty until `onStart` read it. */
+  manifest: Manifest; /** Asset key to the bundle that carries it. */
+  bundleOfKey: Map<string, string>; /** Scene id to its bundle, read from the `scenes` key of `flow.features`. */
+  bundleOfScene: Map<string, string>; /** Flow id to the feature that owns it, read from the `flows` key of `flow.features`. */
+  featureOfFlow: Map<string, string>;
+  records: Map<string, BundleRecord>; /** Bundles of the node entered last. They are never unloaded. */
+  pinned: Set<string>; /** The bundle of the scene entered last. A node without `scene` keeps it. */
+  sceneBundle: string | undefined;
+  queue: PreloadQueue | undefined;
+  current: NodeInfo | undefined;
+  useCounter: number; /** Keys already reported missing, so one key warns and starts its background load once. */
+  warned: Set<string>; /** `onEnter`, the `load` handler and the texture provider. */
+  removers: Array<() => void>;
+};
+/**
+ * What `usage()` reports about one loaded bundle.
+ *
+ * @example
+ * ```ts
+ * const entry: BundleUsage = { name: "board", tier: "scene", mb: 3.5, lastUsed: 12 };
+ * ```
+ */
+type BundleUsage = {
+  name: string;
+  tier: Tier;
+  mb: number;
+  lastUsed: number;
+};
+/**
+ * What `usage()` reports: the numbers a dev overlay and the tests read.
+ *
+ * @example
+ * ```ts
+ * const report: Usage = { textureMb: 3.5, budgetMb: 192, bundles: [] };
+ * ```
+ */
+type Usage = {
+  textureMb: number;
+  budgetMb: number;
+  bundles: readonly BundleUsage[];
+};
+/**
+ * assets plugin events.
+ *
+ * @example
+ * ```ts
+ * // A game reports every loaded bundle to its analytics.
+ * createPlugin("loadReport", {
+ *   depends: [assetsPlugin],
+ *   hooks: ctx => ({ "assets:bundle-loaded": ({ bundle, mb }) => ctx.log.info("loaded", { bundle, mb }) })
+ * }); // the board bundle logs { bundle: "board", mb: 3.5 }
+ *
+ * // A splash screen fills its loading bar file by file.
+ * createPlugin("loadingBar", {
+ *   depends: [assetsPlugin],
+ *   createState: () => ({ share: 0 }),
+ *   hooks: ctx => ({
+ *     "assets:bundle-progress": ({ loaded, total }) => {
+ *       ctx.state.share = loaded / total;
+ *     }
+ *   })
+ * }); // a board bundle of four files sets share to 0.25, 0.5, 0.75 and 1; bundle-loaded follows
+ * ```
+ */
+type Events = {
+  /** Every file of a bundle is a texture now. */"assets:bundle-loaded": {
+    bundle: string;
+    tier: Tier;
+    mb: number;
+    reason: LoadReason;
+  };
+  /**
+   * One more file of a running load settled. `loaded` counts the settled files (a font once, with
+   * its pages), `total` is the file count of the bundle; the last one of a load has
+   * `loaded === total` and comes before `assets:bundle-loaded`. An aborted load sends none.
+   */
+  "assets:bundle-progress": {
+    bundle: string;
+    loaded: number;
+    total: number;
+  }; /** The textures of a bundle were destroyed. `keys` names every asset that went with it. */
+  "assets:bundle-unloaded": {
+    bundle: string;
+    tier: Tier;
+    mb: number;
+    reason: "budget" | "request";
+    keys: readonly string[];
+  };
+};
+/**
+ * assets plugin API, `app.assets`. Bundles of textures by key: the graph decides when they arrive,
+ * the budget decides when they leave.
+ *
+ * @example
+ * ```ts
+ * // A loading node asks for a bundle and a game system asks for one texture of it.
+ * await app.assets.load("board");
+ * app.assets.texture("board.cell"); // the Pixi texture, once the bundle is there
+ * ```
+ */
+type Api = {
+  /**
+   * Loads every file of a bundle. An already loaded bundle resolves at once, a loading one joins
+   * the running load. Headless it resolves at once and touches nothing.
+   *
+   * @param bundle - Name of a bundle of the manifest.
+   * @returns A promise that resolves when every texture of the bundle exists.
+   * @throws {Error} When the manifest has no such bundle, and when a file fails to load.
+   * @example
+   * ```ts
+   * // A game plugin warms the bundle of a timed event before its popup can open.
+   * await app.assets.load("event.halloween");
+   * app.assets.isLoaded("event.halloween"); // true
+   * ```
+   */
+  load(bundle: string): Promise<void>;
+  /**
+   * Destroys the textures of a bundle and tells `renderer` that its keys are gone. A pinned
+   * bundle and the tiers `boot` and `core` are refused with a warning. A running load is aborted.
+   *
+   * @param bundle - Name of a loaded bundle.
+   * @example
+   * ```ts
+   * // The timed event ended: its textures go back to the GPU.
+   * app.assets.unload("event.halloween");
+   * app.assets.isLoaded("event.halloween"); // false
+   * ```
+   */
+  unload(bundle: string): void;
+  /**
+   * Tells whether every texture of a bundle exists. Headless every bundle of the manifest counts
+   * as loaded, so a headless game never waits for a loading screen.
+   *
+   * @param bundle - Name of a bundle of the manifest.
+   * @returns True when the bundle is loaded.
+   * @example
+   * ```ts
+   * // `scenes` skips its loading path when the bundle of the next scene is already there.
+   * if (!app.assets.isLoaded("board")) await app.assets.load("board");
+   * ```
+   */
+  isLoaded(bundle: string): boolean;
+  /**
+   * The texture of a loaded asset key. It touches the use counter of the bundle, which is what
+   * the LRU reads. A key of a bundle that is not loaded warns once, starts a background load and
+   * answers `undefined`; the sprites waiting for it are textured when that load lands.
+   *
+   * @param key - Asset key, as `generated/assets.ts` types it.
+   * @returns The texture, or `undefined` while the bundle is not loaded.
+   * @example
+   * ```ts
+   * // A game system builds one Pixi object by hand instead of using the Sprite component.
+   * const texture = app.assets.texture("board.cell"); // undefined until the board bundle lands
+   * ```
+   */
+  texture(key: string): Texture | undefined;
+  /**
+   * The font of a loaded asset key: the `.fnt` file as text and the texture of its first page.
+   * It touches the use counter of the bundle. A font of a bundle that is not loaded, a key of
+   * another kind and every headless run answer `undefined`.
+   *
+   * @param key - Asset key of a `.fnt` file, as `generated/assets.ts` types it in `FontKey`.
+   * @returns The font, or `undefined` while its bundle is not loaded.
+   * @example
+   * ```ts
+   * // `text` installs the font in the renderer when the bundle that carries it arrived.
+   * const font = app.assets.font("ui.body"); // { fnt: 'info face="body" size=32', texture }
+   *
+   * if (font !== undefined) app.renderer.sync.fonts.install("ui.body", font.fnt, font.texture);
+   * ```
+   */
+  font(key: string): FontAsset | undefined;
+  /**
+   * The bytes of a loaded audio file, exactly as they were fetched: this plugin never decodes
+   * them. It touches the use counter of the bundle. A bundle that is not loaded, a key of
+   * another kind and every headless run answer `undefined`.
+   *
+   * @param key - Asset key of an `.mp3` file, as `generated/assets.ts` types it in `AudioKey`.
+   * @returns The undecoded bytes, or `undefined` while its bundle is not loaded.
+   * @example
+   * ```ts
+   * // `audio` decodes a sound once and keeps it until the bundle is unloaded.
+   * const bytes = app.assets.audio("ui.click"); // the ArrayBuffer of click.mp3
+   * const buffer = bytes === undefined ? undefined : await context.decodeAudioData(bytes);
+   * ```
+   */
+  audio(key: string): ArrayBuffer | undefined;
+  /**
+   * What the loaded bundles cost, sorted by name. `lastUsed` is the use counter, not a clock.
+   *
+   * @returns The used and allowed megabytes and one entry per loaded bundle.
+   * @example
+   * ```ts
+   * // A dev overlay draws the memory bar of the game.
+   * const { textureMb, budgetMb, bundles } = app.assets.usage();
+   * // textureMb: 3.5, budgetMb: 192, bundles: [{ name: "board", tier: "scene", mb: 3.5, lastUsed: 12 }]
+   * ```
+   */
+  usage(): Usage;
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps = {
+  flow: Api$1;
+  renderer: Api$3;
+  time: Api$2;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `index.ts` writes `events` with an annotated `register` (core spec `14-EVENT-REGISTRATION.md`
+ * row 8), so the two own events reach the context the kernel hands the factories and `emit` is the
+ * kernel's own, assets-typed one. No member of the context is cast.
+ */
+type KernelSlice = PluginCtx<Config, State, Events> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the files of the plugin.
+ */
+type AssetsCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * Payload of the one event assets listens to.
+ */
+type FlowRest = {
+  path: string;
+  checkpoint: boolean;
+};
+//#endregion
+export { DefineBundles as a, LoadReason as c, Tier as d, Usage as f, Config as i, Manifest as l, BundleMap as n, Events as o, types_d_exports as p, BundleSpec as r, LoadBundles as s, Api as t, State as u };