@moku-labs/game 0.9.0 → 0.11.0

package/dist/app.mjs

@@ -0,0 +1,235 @@
+import { H as platformPlugin, i as screen, jt as audioPlugin, t as createApp, xt as effectsPlugin } from "./src-BSbtHZWk.mjs";
+import { t as memory } from "./memory-CWlqhS7l.mjs";
+import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
+//#region src/app/define.ts
+/**
+* The moment the default fake clock starts at, in epoch milliseconds. A test stamps times from it.
+*
+* @example
+* ```ts
+* game.headless().clock.now() === startMoment; // true
+* ```
+*/
+const startMoment = 1e6;
+/** The rng seed of a new save when neither the definition nor the seam names one. */
+const defaultSeed = 42;
+/** The plugins every app has: the engine's core five and the core plugins `log` and `env`. */
+const corePluginNames = [
+	"time",
+	"lifecycle",
+	"model",
+	"clock",
+	"flow",
+	"log",
+	"env"
+];
+/**
+* Builds the error of a list entry that is not a feature.
+*
+* @param path - The list and index, `features[2]`, or `shared`.
+* @returns The error.
+* @example
+* ```ts
+* notAFeature("features[2]").message; // "[game] defineGameApp: features[2] is not a feature.\n  Make it with defineFeature(name, description)."
+* ```
+*/
+function notAFeature(path) {
+	return /* @__PURE__ */ new Error(`[game] defineGameApp: ${path} is not a feature.\n  Make it with defineFeature(name, description).`);
+}
+/**
+* Throws for the first entry of a feature list that `defineFeature` did not make. The type already
+* says so; a game in JavaScript, or one that casts, is caught here, at the definition.
+*
+* @param list - `features`, `headless.features`, or `[shared]`.
+* @param pathOf - Names an entry by its index.
+* @throws {Error} When an entry has no `logicOnly`.
+*/
+function checkFeatures(list, pathOf) {
+	for (const [index, entry] of list.entries()) if (entry?.logicOnly === void 0) throw notAFeature(pathOf(index));
+}
+/**
+* Checks what TypeScript cannot stop: a definition from JavaScript, or one that casts.
+*
+* @param definition - The game's definition.
+* @throws {Error} When `flow` is missing, or a feature entry is not a feature.
+*/
+function checkDefinition(definition) {
+	if (definition.flow === void 0) throw new Error("[game] defineGameApp needs flow.\n  Pass the main flow: defineGameApp({ flow: mainFlow, ... }).");
+	if (definition.shared !== void 0) checkFeatures([definition.shared], () => "shared");
+	checkFeatures(definition.features ?? [], (index) => `features[${index}]`);
+	checkFeatures(definition.headless?.features ?? [], (index) => `headless.features[${index}]`);
+}
+/**
+* Copies the keys of a seam whose value is set, so a seam left out never erases a game value.
+*
+* @param seam - One seam object, or `undefined`.
+* @returns The set keys only.
+* @example
+* ```ts
+* definedKeys({ journal: 200, context: undefined }); // { journal: 200 }
+* ```
+*/
+function definedKeys(seam) {
+	if (seam === void 0) return {};
+	return Object.fromEntries(Object.entries(seam).filter(([, value]) => value !== void 0));
+}
+/**
+* Merges the seam-owned keys over the game's plugin configs, one plugin at a time: a key the game
+* owns stays, a key the shell owns is written. With `screen` the screen keys are written too.
+*
+* @param definition - The game's definition.
+* @param seams - The seams of this call.
+* @param runtime - The clock and the save provider of this call.
+* @param withScreen - Whether the app is the screen app.
+* @returns The plugin configs of the app.
+*/
+function mergeConfigs(definition, seams, runtime, withScreen) {
+	const game = definition.pluginConfigs ?? {};
+	const logic = {
+		...game,
+		model: {
+			...game.model,
+			playerProvider: runtime.provider,
+			initialPlayer: seams.player ?? definition.player,
+			initialSession: seams.session ?? definition.session,
+			seed: seams.seed ?? definition.seed ?? defaultSeed
+		},
+		clock: { source: runtime.clock },
+		flow: {
+			...game.flow,
+			mainFlow: definition.flow,
+			safeNode: definition.safeNode
+		}
+	};
+	if (!withScreen) return logic;
+	return {
+		...logic,
+		platform: {
+			provider: seams.platform,
+			keepAwake: seams.keepAwake ?? false
+		},
+		renderer: {
+			...game.renderer,
+			...definedKeys(seams.renderer)
+		},
+		assets: {
+			...game.assets,
+			manifest: seams.manifest,
+			io: seams.io
+		},
+		audio: {
+			...game.audio,
+			...definedKeys(seams.audio)
+		}
+	};
+}
+/**
+* Keeps the configs of the plugins an app composes. Core takes unknown keys at run time, but the
+* headless app's type would not: a headless app gets no screen or unlisted game plugin config.
+*
+* @param configs - The merged configs.
+* @param plugins - The plugins the app composes beyond the core.
+* @returns The configs of the composed plugins only.
+*/
+function composedOnly(configs, plugins) {
+	const names = /* @__PURE__ */ new Set([...corePluginNames, ...plugins.map((plugin) => plugin.name)]);
+	return Object.fromEntries(Object.entries(configs).filter(([name]) => names.has(name)));
+}
+/**
+* Picks the clock and the save provider of one call: the seams', or a fresh fake clock at
+* `startMoment` and a fresh memory provider.
+*
+* @param seams - The seams of this call.
+* @returns The clock and the provider.
+*/
+function runtimeOf(seams) {
+	return {
+		clock: seams.clock ?? fakeClock(1e6),
+		provider: seams.provider ?? memory()
+	};
+}
+/**
+* Creates one app over the engine: the plugins in order, the merged configs, and `referenceLong`
+* only when the definition sets it.
+*
+* @param definition - The game's definition.
+* @param plugins - The plugins beyond the core, in order.
+* @param pluginConfigs - The merged configs.
+* @returns The app, not started.
+*/
+function appOf(definition, plugins, pluginConfigs) {
+	return createApp({
+		plugins: [...plugins],
+		pluginConfigs,
+		...definition.referenceLong === void 0 ? {} : { config: { referenceLong: definition.referenceLong } }
+	});
+}
+/**
+* Makes the headless app of a definition: the logic of `headless.features`, then
+* `headless.plugins`.
+*
+* @param definition - The game's definition.
+* @param seams - The seams of this call.
+* @returns The app, not started, and its clock and provider.
+*/
+function headlessOf(definition, seams) {
+	const runtime = runtimeOf(seams);
+	const plugins = [...(definition.headless?.features ?? []).map((feature) => feature.logicOnly), ...definition.headless?.plugins ?? []];
+	return {
+		app: appOf(definition, plugins, composedOnly(mergeConfigs(definition, seams, runtime, false), plugins)),
+		...runtime
+	};
+}
+/**
+* Makes the screen app of a definition: the screen set, `audio`, `effects`, `platform`, then
+* `shared`, the features and the game's plugins.
+*
+* @param definition - The game's definition.
+* @param seams - The seams of this call.
+* @returns The app, not started, and its clock and provider.
+*/
+function screenOf(definition, seams) {
+	const runtime = runtimeOf(seams);
+	return {
+		app: appOf(definition, [
+			...screen,
+			audioPlugin,
+			effectsPlugin,
+			platformPlugin,
+			...definition.shared === void 0 ? [] : [definition.shared],
+			...definition.features ?? [],
+			...definition.plugins ?? []
+		], mergeConfigs(definition, seams, runtime, true)),
+		...runtime
+	};
+}
+/**
+* Turns a game's one data object into the game: `game.headless()` for logic tests and
+* `game.screen()` for the page and the screen tests. Every type comes from the object: the plugin
+* tuples, the player and the session. Checks the definition at once, so an error points at
+* `index.ts`.
+*
+* @param definition - The game: its flow, starting state, features, plugins and plugin configs.
+* @returns The game, with `headless()` and `screen()`; no app is created yet.
+* @throws {Error} When `flow` is missing, or an entry of `shared`, `features` or `headless.features` is not a feature.
+* @example
+* ```ts
+* // index.ts of a game: the whole game, no createApp call. Its tests import it as `game`.
+* export default defineGameApp({
+*   flow: mainFlow, safeNode: "home", player: startingPlayer, session: startingSession,
+*   shared: sharedFeature, features: [homeFeature, boardFeature, rewardFeature], plugins: [loadingPlugin],
+*   headless: { features: [rewardFeature] }, pluginConfigs: { ui: { tapTargetPt: 48 } }
+* });
+* game.headless({ seed: 7 }).app.flow.state().running; // false: the test starts it
+* ```
+*/
+function defineGameApp(definition) {
+	const wide = definition;
+	checkDefinition(wide);
+	return {
+		headless: (seams = {}) => headlessOf(wide, seams),
+		screen: (seams = {}) => screenOf(wide, seams)
+	};
+}
+//#endregion
+export { defineGameApp, startMoment };