@moku-labs/game 0.0.1 → 0.0.3

package/dist/assets.d.mts

@@ -0,0 +1,213 @@
+import { l as Manifest } from "./types-DgwbzDLP.mjs";
+
+//#region src/plugins/assets/scan/cli.d.ts
+/**
+ * The part of the branded console the scanner writes through. A `BrandConsole` fits it, and a
+ * test passes a recorder instead.
+ */
+type ScanUi = {
+  /** Writes one neutral line. */info(message: string): void; /** Writes one warning line. */
+  warn(message: string): void; /** Writes one error line. */
+  error(message: string, cause?: unknown): void;
+};
+/** What one strings compile reports back. `CompileReport` of i18n has this shape. */
+type StringsReport = {
+  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, sorted. */
+  locales: readonly string[]; /** Every message key, sorted. */
+  keys: readonly string[]; /** One line per key a locale lacks. Nothing here stops a build. */
+  notes: readonly string[];
+};
+/**
+ * Compiles the feature strings of a root into a folder, or checks them in a check run.
+ * `compileStrings` of i18n fits it, and a test passes a stub instead.
+ */
+type StringsCompiler = (root: string, out: string, options: {
+  check: boolean;
+}) => Promise<StringsReport>;
+/**
+ * Runs the asset key scanner: walk the features, write the manifest and the key module, then
+ * compile the feature strings next to the key module, or check that all of it is current. With
+ * `--pack <dir>` it packs the art for production on the same scan (`--no-cache` for a cold run).
+ * Nothing here calls `process.exit`; the caller does.
+ *
+ * @param argv - The arguments after the script name.
+ * @param compile - The strings compiler, `compileStrings` of i18n.
+ * @param ui - Where the lines go. The branded console by default.
+ * @returns The exit code: `1` when the scan, the compile or the pack failed or `--check` found a
+ *   difference, else `0`.
+ * @example
+ * ```ts
+ * await runCli(["--root", "src", "--manifest", "public/assets/manifest.json", "--check"], compileStrings);
+ * // 1 when public/assets/manifest.json is older than the files in src/features
+ *
+ * await runCli(["--root", "src", "--keys", "src/generated/assets.ts", "--pack", "dist/assets"], compileStrings);
+ * // 0, and dist/assets holds the pages, the loose files and the packed manifest.json
+ * ```
+ */
+declare function runCli(argv: string[], compile: StringsCompiler, ui?: ScanUi): Promise<number>;
+//#endregion
+//#region src/plugins/i18n/compile/compile.d.ts
+/**
+ * What one compile produced.
+ */
+type CompileReport = {
+  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, sorted. */
+  locales: readonly string[]; /** Every message key, sorted. */
+  keys: readonly string[]; /** One line per key a locale lacks. Nothing here stops a build. */
+  notes: readonly string[];
+};
+/**
+ * What one compile is told beyond its two paths.
+ */
+type CompileOptions = {
+  /** True for a check run: nothing is written. */check?: boolean; /** Name of the folder that holds the features. Default `"features"`. */
+  features?: string;
+};
+/**
+ * Walks `features/*​/strings/<locale>.json` of a game, compiles every message and writes the
+ * generated modules: the types module `strings.ts` and one `strings.<locale>.ts` per locale. A
+ * check run writes nothing and only reports whether something would change.
+ *
+ * @param root - Game source root, the folder that holds the features.
+ * @param out - The generated directory the modules are written into.
+ * @param options - Whether this is a check run, and what the features folder is called.
+ * @returns Whether an output differed, the locales, the keys and the notes.
+ * @throws {Error} One error that lists every problem the compile found.
+ * @example
+ * ```ts
+ * const report = await compileStrings("src", "src/generated");
+ * // report.locales: ["en", "ru"], report.changed: true on the first run
+ * ```
+ */
+declare function compileStrings(root: string, out: string, options?: CompileOptions): Promise<CompileReport>;
+/**
+ * Tells whether the generated modules of a game are current, without writing anything. The
+ * `--check` run of `bun run assets:keys` covers the strings with it.
+ *
+ * @param root - Game source root, the folder that holds the features.
+ * @param out - The generated directory the modules live in.
+ * @returns True when nothing would change.
+ * @throws {Error} One error that lists every problem the compile found.
+ * @example
+ * ```ts
+ * await checkStrings("src", "src/generated"); // false when a message changed since the last run
+ * ```
+ */
+declare function checkStrings(root: string, out: string): Promise<boolean>;
+//#endregion
+//#region src/plugins/assets/scan/emit.d.ts
+/**
+ * Writes `manifest.json`: two-space JSON with a trailing newline, bundles sorted by name, pages
+ * by id and files by key. The version is written as given: `1` from the scanner, `2` from the
+ * packer.
+ *
+ * @param manifest - What the scan produced.
+ * @returns The text of the file.
+ * @example
+ * ```ts
+ * emitManifest({ version: 1, bundles: {} }); // '{\n  "version": 1,\n  "bundles": {}\n}\n'
+ * ```
+ */
+declare function emitManifest(manifest: Manifest): string;
+/**
+ * Writes `generated/assets.ts`: `AssetKey` over every kind, the narrower `FontKey` and `AudioKey`
+ * next to it, `BundleKey`, and the nine-slice table. A game commits this file, so `defineGame` can
+ * type `Sprite`, a text style, a sound, `defineBundles` and the `load` effect from it.
+ *
+ * @param manifest - What the scan produced.
+ * @returns The text of the module.
+ * @example
+ * ```ts
+ * emitKeys({ version: 1, bundles: {} });
+ * // the header, four unions that are all "never" and an empty nine-slice table
+ * ```
+ */
+declare function emitKeys(manifest: Manifest): string;
+//#endregion
+//#region src/plugins/assets/scan/pack/pack.d.ts
+/**
+ * What one pack is told: where the sources are, what the scan found and where everything goes.
+ */
+type PackOptions = {
+  /** Path of the game source root: the `path` of every file of `manifest` is relative to it. */root: string; /** The manifest the scan produced (version 1, loose files). */
+  manifest: Manifest; /** The pack folder. It belongs to the command: created, written and pruned. */
+  out: string; /** Where the packed manifest (version 2) goes. */
+  manifestFile: string; /** The cache folder, or `false` for a run that neither reads nor writes the cache. */
+  cache: string | false;
+};
+/**
+ * What a pack wrote.
+ */
+type PackResult = {
+  /** The packed manifest, version 2, as written. */manifest: Manifest; /** How many atlas pages the pack folder holds. */
+  pages: number; /** How many textures stayed files of their own. */
+  loose: number; /** The bytes of every file the manifest references. */
+  bytes: number; /** How many of the pages were replayed from the cache. */
+  cacheHits: number;
+};
+/**
+ * Packs the art of a game for production: per bundle, the textures of the `fx` group and of the
+ * `main` group go onto WebP atlas pages (2048 px at most, 2 px padding and border, never trimmed
+ * or rotated), a texture with a side above 512 px and a group of one stay loose files, fonts and
+ * sounds are copied, every file name carries the hash of its bytes, and the packed manifest
+ * (version 2) names it all. Nothing is written while a problem is open; afterwards the pack folder
+ * holds exactly what the manifest references, plus `manifest.json`. Two runs on the same tree and
+ * the same `sharp` write the same bytes.
+ *
+ * @param options - The sources, the scanned manifest, the pack folder, the manifest file, the cache.
+ * @returns The packed manifest and what was written.
+ * @throws {Error} One error that lists every problem, when `sharp` is missing, or when the pack
+ *   folder holds the sources.
+ * @example
+ * ```ts
+ * // After `scanAssets` read the features of the game. `cache: false` skips the cache.
+ * const { manifest, pages, cacheHits } = await packAssets({
+ *   root: "src", manifest: scanned, cache: "node_modules/.cache/moku-game-pack",
+ *   out: "dist/assets", manifestFile: "dist/assets/manifest.json"
+ * });
+ * // manifest.version: 2; on a second run with the same art, cacheHits equals pages
+ * ```
+ */
+declare function packAssets(options: PackOptions): Promise<PackResult>;
+//#endregion
+//#region src/plugins/assets/scan/scan.d.ts
+/**
+ * What one scan is told: where the features are and where the two generated files go.
+ */
+type ScanOptions = {
+  /** Path of the game source root, the folder that holds the features. */root: string; /** Name of the folder that holds the features. Default `"features"`. */
+  features?: string; /** Path of the `manifest.json` to write. */
+  manifest: string; /** Path of the generated key module to write. */
+  keys: string; /** False for a check run: nothing is written. Default true. */
+  write?: boolean;
+};
+/**
+ * What a scan produced.
+ */
+type ScanResult = {
+  /** The manifest, with bundles sorted by name and files sorted by key. */manifest: Manifest; /** The text of the generated key module. */
+  keysSource: string; /** True when an output on disk differs from what the scan produced. */
+  changed: boolean; /** One line per file the scan left out. Nothing here stops a build. */
+  notes: readonly string[];
+};
+/**
+ * Walks the features of a game and writes its two generated files: one bundle per feature, split
+ * by the optional `assets.ts` of that feature, every file keyed by the key rule. A check run
+ * (`write: false`) writes nothing and only reports whether something would change.
+ *
+ * @param options - The game source root, the two output paths and whether to write.
+ * @returns The manifest, the text of the key module and whether an output differed.
+ * @throws {Error} One error that lists every problem the scan found.
+ * @example
+ * ```ts
+ * const { manifest, changed } = await scanAssets({
+ *   root: "src",
+ *   manifest: "public/assets/manifest.json",
+ *   keys: "src/generated/assets.ts"
+ * });
+ * // manifest.bundles.ui.files[0].key: "ui.button.primary", changed: true on the first run
+ * ```
+ */
+declare function scanAssets(options: ScanOptions): Promise<ScanResult>;
+//#endregion
+export { type CompileOptions, type CompileReport, type PackOptions, type PackResult, type ScanOptions, type ScanResult, type ScanUi, type StringsCompiler, type StringsReport, checkStrings, compileStrings, emitKeys, emitManifest, packAssets, runCli, scanAssets };