@zylem/game-lib 0.3.16 → 0.3.17

package/dist/lib/game/game-blueprint.d.ts

@@ -0,0 +1,44 @@
+import type { Stage } from '../stage/stage';
+import type { BasicTypes, GlobalVariablesType, ZylemGameConfig } from './game-interfaces';
+import type { GameOptions } from '../core/utility/nodes';
+/**
+ * A lightweight, serializable blueprint representing the initial configuration
+ * of a `Game`. It should not include runtime references. Use blueprints only to
+ * build games.
+ */
+export interface GameBlueprint<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType> {
+    id: string;
+    name?: string;
+    config: Partial<ZylemGameConfig<Stage, any, TGlobals>>;
+}
+export declare const gameBlueprintsState: {
+    byId: Record<string, GameBlueprint>;
+    order: string[];
+    currentId: string | null;
+};
+/** Reset the blueprints store back to its initial empty state. */
+export declare function resetGameBlueprints(): void;
+/** Create and register a new `GameBlueprint`. */
+export declare function createGameBlueprint<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType>(config: Partial<ZylemGameConfig<Stage, any, TGlobals>>, options?: {
+    id?: string;
+    name?: string;
+    setCurrent?: boolean;
+}): GameBlueprint<TGlobals>;
+/** Upsert a blueprint into the store. */
+export declare function upsertGameBlueprint<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType>(blueprint: GameBlueprint<TGlobals>): void;
+/** Remove a blueprint by id. */
+export declare function removeGameBlueprint(id: string): void;
+/** Get a blueprint by id. */
+export declare function getGameBlueprint(id: string): GameBlueprint | undefined;
+/** List all blueprints in insertion order. */
+export declare function listGameBlueprints(): GameBlueprint[];
+/** Set the current blueprint id (or clear by passing null). */
+export declare function setCurrentGameBlueprint(id: string | null): void;
+/** Get the current blueprint object, if any. */
+export declare function getCurrentGameBlueprint(): GameBlueprint | null;
+/**
+ * Build a `Game` instance from a blueprint and optional extra `GameOptions`
+ * (e.g., additional stages or nodes). This returns a `Game` wrapper instance;
+ * call `.start()` to run it.
+ */
+export declare function buildGameFromBlueprint<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType>(input: string | GameBlueprint<TGlobals>, ...extras: GameOptions<TGlobals>): import("./game").Game<TGlobals>;

package/dist/lib/game/game-canvas.d.ts

@@ -0,0 +1,34 @@
+import { AspectRatioValue } from '../device/aspect-ratio';
+export interface GameCanvasOptions {
+    id: string;
+    container?: HTMLElement;
+    containerId?: string;
+    canvas?: HTMLCanvasElement;
+    bodyBackground?: string;
+    fullscreen?: boolean;
+    aspectRatio: AspectRatioValue | number;
+}
+/**
+ * GameCanvas is a DOM delegate that owns:
+ * - container lookup/creation and styling (including fullscreen centering)
+ * - body background application
+ * - canvas mounting into container
+ * - aspect ratio sizing via AspectRatioDelegate
+ */
+export declare class GameCanvas {
+    id: string;
+    container: HTMLElement;
+    canvas: HTMLCanvasElement;
+    bodyBackground?: string;
+    fullscreen: boolean;
+    aspectRatio: number;
+    private ratioDelegate;
+    constructor(options: GameCanvasOptions);
+    applyBodyBackground(): void;
+    mountCanvas(): void;
+    mountRenderer(rendererDom: HTMLCanvasElement, onResize: (width: number, height: number) => void): void;
+    centerIfFullscreen(): void;
+    attachAspectRatio(onResize: (width: number, height: number) => void): void;
+    destroy(): void;
+    private ensureContainer;
+}

package/dist/lib/game/game-canvas.js

@@ -0,0 +1,57 @@
+import { AspectRatioDelegate as s } from "../device/aspect-ratio.js";
+class o {
+  id;
+  container;
+  canvas;
+  bodyBackground;
+  fullscreen;
+  aspectRatio;
+  ratioDelegate = null;
+  constructor(t) {
+    this.id = t.id, this.container = this.ensureContainer(t.containerId ?? t.id, t.container), this.canvas = t.canvas ?? document.createElement("canvas"), this.bodyBackground = t.bodyBackground, this.fullscreen = !!t.fullscreen, this.aspectRatio = (typeof t.aspectRatio == "number", t.aspectRatio);
+  }
+  applyBodyBackground() {
+    this.bodyBackground && (document.body.style.background = this.bodyBackground);
+  }
+  mountCanvas() {
+    for (; this.container.firstChild; )
+      this.container.removeChild(this.container.firstChild);
+    this.container.appendChild(this.canvas);
+  }
+  mountRenderer(t, i) {
+    for (; this.container.firstChild; )
+      this.container.removeChild(this.container.firstChild);
+    this.container.appendChild(t), this.canvas = t, this.attachAspectRatio(i);
+  }
+  centerIfFullscreen() {
+    if (!this.fullscreen)
+      return;
+    const t = this.container.style;
+    t.display = "flex", t.alignItems = "center", t.justifyContent = "center", t.position = "fixed", t.inset = "0";
+  }
+  attachAspectRatio(t) {
+    this.ratioDelegate ? this.ratioDelegate.apply() : (this.ratioDelegate = new s({
+      container: this.container,
+      canvas: this.canvas,
+      aspectRatio: this.aspectRatio,
+      onResize: t
+    }), this.ratioDelegate.attach());
+  }
+  destroy() {
+    this.ratioDelegate?.detach(), this.ratioDelegate = null;
+  }
+  ensureContainer(t, i) {
+    if (i)
+      return i;
+    if (t) {
+      const a = document.getElementById(t);
+      if (a)
+        return a;
+    }
+    const n = t || this.id || "zylem-root", e = document.createElement("main");
+    return e.setAttribute("id", n), e.style.position = "relative", e.style.width = "100%", e.style.height = "100%", document.body.appendChild(e), e;
+  }
+}
+export {
+  o as GameCanvas
+};

package/dist/lib/game/game-config.d.ts

@@ -0,0 +1,47 @@
+import { StageInterface } from "../types";
+import { GameInputConfig } from "./game-interfaces";
+import { AspectRatio, AspectRatioValue } from "../device/aspect-ratio";
+export type GameConfigLike = Partial<{
+    id: string;
+    globals: Record<string, any>;
+    stages: StageInterface[];
+    debug: boolean;
+    time: number;
+    input: GameInputConfig;
+    /** numeric value or key in AspectRatio */
+    aspectRatio: AspectRatioValue | keyof typeof AspectRatio;
+    fullscreen: boolean;
+    /** CSS background value for document body */
+    bodyBackground: string;
+    /** existing container by reference */
+    container: HTMLElement;
+    /** create/find container by id */
+    containerId: string;
+    /** optional canvas if caller wants to manage it */
+    canvas: HTMLCanvasElement;
+}>;
+export declare class GameConfig {
+    id: string;
+    globals: Record<string, any>;
+    stages: StageInterface[];
+    debug: boolean;
+    time: number;
+    input: GameInputConfig | undefined;
+    aspectRatio: number;
+    fullscreen: boolean;
+    bodyBackground: string | undefined;
+    container: HTMLElement;
+    containerId?: string | undefined;
+    canvas?: HTMLCanvasElement | undefined;
+    constructor(id: string, globals: Record<string, any>, stages: StageInterface[], debug: boolean, time: number, input: GameInputConfig | undefined, aspectRatio: number, fullscreen: boolean, bodyBackground: string | undefined, container: HTMLElement, containerId?: string | undefined, canvas?: HTMLCanvasElement | undefined);
+}
+export declare function createDefaultGameConfig(base?: Partial<Pick<GameConfig, 'id' | 'debug' | 'time' | 'input'>> & {
+    stages?: StageInterface[];
+    globals?: Record<string, any>;
+}): GameConfig;
+export declare function resolveGameConfig(user?: GameConfigLike): GameConfig;
+/**
+ * Factory for authoring configuration objects in user code.
+ * Returns a plain object that can be passed to `game(...)`.
+ */
+export declare function gameConfig(config: GameConfigLike): GameConfigLike;

package/dist/lib/game/game-config.js

@@ -0,0 +1,53 @@
+import { AspectRatio as d } from "../device/aspect-ratio.js";
+class g {
+  id;
+  globals;
+  stages;
+  debug;
+  time;
+  input;
+  aspectRatio;
+  fullscreen;
+  bodyBackground;
+  container;
+  containerId;
+  canvas;
+  constructor(n, o, e, i, a, c, s, l, u, m, f, p) {
+    this.id = n, this.globals = o, this.stages = e, this.debug = i, this.time = a, this.input = c, this.aspectRatio = s, this.fullscreen = l, this.bodyBackground = u, this.container = m, this.containerId = f, this.canvas = p;
+  }
+}
+function r(t, n) {
+  if (n)
+    return n;
+  if (t) {
+    const i = document.getElementById(t);
+    if (i)
+      return i;
+  }
+  const o = t || "zylem-root", e = document.createElement("main");
+  return e.setAttribute("id", o), e.style.position = "relative", e.style.width = "100%", e.style.height = "100%", document.body.appendChild(e), e;
+}
+function b(t) {
+  const n = t?.id ?? "zylem", o = r(n);
+  return new g(n, t?.globals ?? {}, t?.stages ?? [], !!t?.debug, t?.time ?? 0, t?.input, d.SixteenByNine, !0, "#000000", o, n, void 0);
+}
+function y(t) {
+  const n = b({
+    id: t?.id ?? "zylem",
+    debug: !!t?.debug,
+    time: t?.time ?? 0,
+    input: t?.input,
+    stages: t?.stages ?? [],
+    globals: t?.globals ?? {}
+  }), o = t?.containerId ?? n.containerId, e = r(o, t?.container ?? null), i = t?.aspectRatio ?? n.aspectRatio, a = typeof i == "number" ? i : d[i] ?? d.SixteenByNine, c = t?.fullscreen ?? n.fullscreen, s = t?.bodyBackground ?? n.bodyBackground, l = t?.canvas ?? void 0;
+  return new g(t?.id ?? n.id, t?.globals ?? n.globals, t?.stages ?? n.stages, !!(t?.debug ?? n.debug), t?.time ?? n.time, t?.input ?? n.input, a, c, s, e, o, l);
+}
+function B(t) {
+  return { ...t };
+}
+export {
+  g as GameConfig,
+  b as createDefaultGameConfig,
+  B as gameConfig,
+  y as resolveGameConfig
+};

package/dist/lib/game/game-default.d.ts

@@ -0,0 +1,18 @@
+import { Stage } from '../stage/stage';
+import type { BasicTypes, GlobalVariablesType, ZylemGameConfig, GameInputConfig } from './game-interfaces';
+export declare const gameDefaultsState: Partial<ZylemGameConfig<Stage, any, GlobalVariablesType>>;
+/** Replace multiple defaults at once (shallow merge). */
+export declare function setGameDefaults(partial: Partial<ZylemGameConfig<Stage, any, GlobalVariablesType>>): void;
+/** Reset defaults back to library defaults. */
+export declare function resetGameDefaults(): void;
+/**
+ * Get a plain object copy of the current defaults.
+ */
+export declare function getGameDefaultConfig<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType>(): {
+    id: string;
+    globals: TGlobals;
+    stages: Stage[];
+    debug?: boolean;
+    time?: number;
+    input?: GameInputConfig;
+};

package/dist/lib/game/game-default.js

@@ -0,0 +1,24 @@
+import { proxy as i } from "valtio/vanilla";
+import { stage as e } from "../stage/stage.js";
+const a = () => ({
+  id: "zylem",
+  globals: {},
+  stages: [e()],
+  debug: !1,
+  time: 0,
+  input: void 0
+}), t = i({ ...a() });
+function g() {
+  return {
+    id: t.id ?? "zylem",
+    globals: t.globals ?? {},
+    stages: t.stages ?? [e()],
+    debug: t.debug,
+    time: t.time,
+    input: t.input
+  };
+}
+export {
+  t as gameDefaultsState,
+  g as getGameDefaultConfig
+};

package/dist/lib/game/game.d.ts

@@ -1,9 +1,8 @@
-import { BaseNode } from '../core/base-node';
 import { ZylemGame } from './zylem-game';
 import { Stage } from '../stage/stage';
 import { DestroyFunction, IGame, SetupFunction, UpdateFunction } from '../core/base-node-life-cycle';
-import { GameEntityLifeCycle } from '../entities/entity';
-import { BasicTypes, GlobalVariablesType, ZylemGameConfig } from './game-interfaces';
+import { BasicTypes, GlobalVariablesType } from './game-interfaces';
+import { GameOptions } from '../core/utility/nodes';
 export declare class Game<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType> implements IGame<TGlobals> {
     gameRef: ZylemGame<TGlobals> | null;
     options: GameOptions<TGlobals>;
@@ -28,7 +27,6 @@ export declare class Game<TGlobals extends Record<string, BasicTypes> = GlobalVa
     setGlobal<K extends keyof TGlobals>(key: K, value: TGlobals[K]): void;
     onGlobalChange<K extends keyof TGlobals>(key: K, callback: (value: TGlobals[K]) => void): void;
 }
-type GameOptions<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType> = Array<ZylemGameConfig<Stage, Game<TGlobals>, TGlobals> | Stage | GameEntityLifeCycle | BaseNode>;
 /**
  * create a new game
  * @param options GameOptions - Array of IGameOptions, Stage, GameEntity, or BaseNode objects
@@ -38,4 +36,3 @@ type GameOptions<TGlobals extends Record<string, BasicTypes> = GlobalVariablesTy
  * @returns Game
  */
 export declare function game<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType>(...options: GameOptions<TGlobals>): Game<TGlobals>;
-export {};

package/dist/lib/game/game.js

@@ -1,37 +1,10 @@
-import { BaseNode as h } from "../core/base-node.js";
-import { ZylemGame as c } from "./zylem-game.js";
-import { Stage as o, stage as l } from "../stage/stage.js";
+import { ZylemGame as n } from "./zylem-game.js";
+import { Stage as o } from "../stage/stage.js";
 import { setPaused as r } from "../debug/debug-state.js";
-import { GameEntity as u } from "../entities/entity.js";
-import { getGlobalState as m, setGlobalState as p } from "./game-state.js";
-const f = {
-  id: "zylem",
-  globals: {},
-  stages: [
-    l()
-  ]
-};
-function d(n) {
-  let e = { ...f };
-  const t = [], s = [], a = [];
-  return Object.values(n).forEach((i) => {
-    if (i instanceof o)
-      s.push(i);
-    else if (i instanceof u)
-      a.push(i);
-    else if (i instanceof h)
-      a.push(i);
-    else if (i.constructor.name === "Object" && typeof i == "object") {
-      const g = Object.assign(f, { ...i });
-      t.push(g);
-    }
-  }), t.forEach((i) => {
-    e = Object.assign(e, { ...i });
-  }), s.forEach((i) => {
-    i.addEntities(a);
-  }), s.length ? e.stages = s : e.stages[0].addEntities(a), e;
-}
-class R {
+import { getGlobalState as g, setGlobalState as f } from "./game-state.js";
+import { convertNodes as h } from "../core/utility/nodes.js";
+import { resolveGameConfig as l } from "./game-config.js";
+class u {
   gameRef = null;
   options;
   pendingGlobalChangeHandlers = [];
@@ -42,17 +15,20 @@ class R {
   destroy = () => {
   };
   refErrorMessage = "lost reference to game";
-  constructor(e) {
-    this.options = e;
+  constructor(t) {
+    this.options = t;
   }
   async start() {
-    const e = await this.load();
-    return this.gameRef = e, this.setOverrides(), e.start(), this;
+    const t = await this.load();
+    return this.gameRef = t, this.setOverrides(), t.start(), this;
   }
   async load() {
     console.log("loading game", this.options);
-    const e = d(this.options), t = new c(e, this);
-    return await t.loadStage(e.stages[0]), t;
+    const t = await h(this.options), s = l(t), e = new n({
+      ...t,
+      ...s
+    }, this);
+    return await e.loadStage(t.stages[0]), e;
   }
   setOverrides() {
     if (!this.gameRef) {
@@ -60,8 +36,8 @@ class R {
       return;
     }
     if (this.gameRef.customSetup = this.setup, this.gameRef.customUpdate = this.update, this.gameRef.customDestroy = this.destroy, this.pendingGlobalChangeHandlers.length) {
-      for (const { key: e, callback: t } of this.pendingGlobalChangeHandlers)
-        this.gameRef.onGlobalChange(e, t);
+      for (const { key: t, callback: s } of this.pendingGlobalChangeHandlers)
+        this.gameRef.onGlobalChange(t, s);
       this.pendingGlobalChangeHandlers = [];
     }
   }
@@ -83,75 +59,75 @@ class R {
       console.error(this.refErrorMessage);
       return;
     }
-    const e = this.gameRef.currentStageId, t = this.gameRef.stages.findIndex((a) => a.stageRef.uuid === e), s = this.gameRef.stages[t + 1];
-    if (!s) {
+    const t = this.gameRef.currentStageId, s = this.gameRef.stages.findIndex((a) => a.stageRef.uuid === t), e = this.gameRef.stages[s + 1];
+    if (!e) {
       console.error("next stage called on last stage");
       return;
     }
-    await this.gameRef.loadStage(s);
+    await this.gameRef.loadStage(e);
   }
   async previousStage() {
     if (!this.gameRef) {
       console.error(this.refErrorMessage);
       return;
     }
-    const e = this.gameRef.currentStageId, t = this.gameRef.stages.findIndex((a) => a.stageRef.uuid === e), s = this.gameRef.stages[t - 1];
-    if (!s) {
+    const t = this.gameRef.currentStageId, s = this.gameRef.stages.findIndex((a) => a.stageRef.uuid === t), e = this.gameRef.stages[s - 1];
+    if (!e) {
       console.error("previous stage called on first stage");
       return;
     }
-    await this.gameRef.loadStage(s);
+    await this.gameRef.loadStage(e);
   }
   async goToStage() {
   }
   async end() {
   }
-  add(...e) {
-    for (const t of e)
-      if (t) {
-        if (t instanceof o) {
-          this.gameRef ? (this.gameRef.stages.push(t), this.gameRef.stageMap.set(t.stageRef.uuid, t)) : this.options.push(t);
+  add(...t) {
+    for (const s of t)
+      if (s) {
+        if (s instanceof o) {
+          this.gameRef ? (this.gameRef.stages.push(s), this.gameRef.stageMap.set(s.stageRef.uuid, s)) : this.options.push(s);
           continue;
         }
-        if (typeof t == "function") {
+        if (typeof s == "function") {
           try {
-            const s = t();
-            s instanceof o ? this.gameRef ? (this.gameRef.stages.push(s), this.gameRef.stageMap.set(s.stageRef.uuid, s)) : this.options.push(s) : s && typeof s.then == "function" && s.then((a) => {
+            const e = s();
+            e instanceof o ? this.gameRef ? (this.gameRef.stages.push(e), this.gameRef.stageMap.set(e.stageRef.uuid, e)) : this.options.push(e) : e && typeof e.then == "function" && e.then((a) => {
               a instanceof o && (this.gameRef ? (this.gameRef.stages.push(a), this.gameRef.stageMap.set(a.stageRef.uuid, a)) : this.options.push(a));
             }).catch((a) => console.error("Failed to add async stage", a));
-          } catch (s) {
-            console.error("Error executing stage factory", s);
+          } catch (e) {
+            console.error("Error executing stage factory", e);
           }
           continue;
         }
-        t && typeof t.then == "function" && t.then((s) => {
-          s instanceof o && (this.gameRef ? (this.gameRef.stages.push(s), this.gameRef.stageMap.set(s.stageRef.uuid, s)) : this.options.push(s));
-        }).catch((s) => console.error("Failed to add async stage", s));
+        s && typeof s.then == "function" && s.then((e) => {
+          e instanceof o && (this.gameRef ? (this.gameRef.stages.push(e), this.gameRef.stageMap.set(e.stageRef.uuid, e)) : this.options.push(e));
+        }).catch((e) => console.error("Failed to add async stage", e));
       }
     return this;
   }
-  getGlobal(e) {
-    return this.gameRef ? this.gameRef.getGlobal(e) : m(e);
+  getGlobal(t) {
+    return this.gameRef ? this.gameRef.getGlobal(t) : g(t);
   }
-  setGlobal(e, t) {
+  setGlobal(t, s) {
     if (this.gameRef) {
-      this.gameRef.setGlobal(e, t);
+      this.gameRef.setGlobal(t, s);
       return;
     }
-    p(e, t);
+    f(t, s);
   }
-  onGlobalChange(e, t) {
+  onGlobalChange(t, s) {
     if (this.gameRef) {
-      this.gameRef.onGlobalChange(e, t);
+      this.gameRef.onGlobalChange(t, s);
       return;
     }
-    this.pendingGlobalChangeHandlers.push({ key: e, callback: t });
+    this.pendingGlobalChangeHandlers.push({ key: t, callback: s });
   }
 }
-function M(...n) {
-  return new R(n);
+function S(...i) {
+  return new u(i);
 }
 export {
-  R as Game,
-  M as game
+  u as Game,
+  S as game
 };

package/dist/lib/game/zylem-game.d.ts

@@ -5,6 +5,10 @@ import { Timer } from '../core/three-addons/Timer';
 import { ZylemCamera } from '~/lib/camera/zylem-camera';
 import { Stage } from '../stage/stage';
 import { BasicTypes, GlobalVariablesType, ZylemGameConfig } from './game-interfaces';
+import { GameConfig } from './game-config';
+import { AspectRatioDelegate } from '../device/aspect-ratio';
+import { GameCanvas } from './game-canvas';
+type ZylemGameOptions<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType> = ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals> & Partial<GameConfig>;
 export declare class ZylemGame<TGlobals extends Record<string, BasicTypes> = GlobalVariablesType> {
     id: string;
     initialGlobals: TGlobals;
@@ -26,10 +30,17 @@ export declare class ZylemGame<TGlobals extends Record<string, BasicTypes> = Glo
         dom: HTMLElement;
     } | null;
     defaultCamera: ZylemCamera | null;
+    container: HTMLElement | null;
+    canvas: HTMLCanvasElement | null;
+    aspectRatioDelegate: AspectRatioDelegate | null;
+    resolvedConfig: GameConfig | null;
+    gameCanvas: GameCanvas | null;
     static FRAME_LIMIT: number;
     static FRAME_DURATION: number;
     static MAX_DELTA_SECONDS: number;
-    constructor(options: ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals>, wrapperRef: Game<TGlobals>);
+    constructor(options: ZylemGameOptions<TGlobals>, wrapperRef: Game<TGlobals>);
+    loadGameCanvas(config: GameConfig): void;
+    loadDebugOptions(options: ZylemGameOptions<TGlobals>): void;
     loadStage(stage: Stage): Promise<void>;
     unloadCurrentStage(): void;
     setGlobals(options: ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals>): void;