emeraldengine 2.2.0 → 3.0.0

package/src/StateMachine.js

@@ -0,0 +1,82 @@
+/**
+ * @class StateMachine
+ * @description A lightweight finite state machine for entity AI, animation
+ * states, game flow, etc. Each state can define `enter`, `update(dt)`, and
+ * `exit` handlers. Drive it from a Behaviour's update().
+ *
+ * @example
+ * const fsm = new StateMachine();
+ * fsm.add("idle", {
+ *   update: (dt, sm) => { if (seesPlayer) sm.set("chase"); },
+ * });
+ * fsm.add("chase", {
+ *   enter: () => playRoarSound(),
+ *   update: (dt, sm) => moveTowardPlayer(dt),
+ * });
+ * fsm.set("idle");
+ * // in update(dt): fsm.update(dt);
+ */
+class StateMachine {
+  constructor() {
+    this.states = new Map();
+    this.current = null;
+    this.currentName = null;
+    this.previousName = null;
+  }
+
+  /**
+   * @method add
+   * @description Registers a state.
+   * @param {string} name - State name
+   * @param {{enter?:Function, update?:Function, exit?:Function}} handlers
+   * @returns {StateMachine} - this
+   */
+  add(name, handlers) {
+    this.states.set(name, handlers || {});
+    return this;
+  }
+
+  /**
+   * @method set
+   * @description Transitions to a state, running exit/enter handlers. Re-entering
+   * the same state is a no-op unless `force` is true.
+   * @param {string} name - Target state name
+   * @param {boolean} [force] - Allow re-entering the current state
+   * @returns {StateMachine} - this
+   */
+  set(name, force = false) {
+    if (this.currentName === name && !force) return this;
+    if (!this.states.has(name)) {
+      console.warn(`[StateMachine] > Unknown state "${name}"`);
+      return this;
+    }
+
+    if (this.current && this.current.exit) this.current.exit(this);
+    this.previousName = this.currentName;
+    this.currentName = name;
+    this.current = this.states.get(name);
+    if (this.current.enter) this.current.enter(this);
+    return this;
+  }
+
+  /**
+   * @method update
+   * @description Runs the current state's update handler.
+   * @param {number} dt - Seconds since the last frame
+   */
+  update(dt) {
+    if (this.current && this.current.update) this.current.update(dt, this);
+  }
+
+  /**
+   * @method is
+   * @description Whether the given state is current.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  is(name) {
+    return this.currentName === name;
+  }
+}
+
+export default StateMachine;

package/src/Storage.js

@@ -3,61 +3,189 @@
  * @description Manages the storage of the game
  */
 class Storage {
-    /**
-     * @method writeToLocalStorage
-     * @description Writes to local storage
-     * @param {string} key - The key to write to
-     * @param {any} value - The value to write to
-     */
-    static writeToLocalStorage(key, value) {
-        localStorage.setItem(key, JSON.stringify(value));
-    }
+  /**
+   * @method writeToLocalStorage
+   * @description Writes to local storage
+   * @param {string} key - The key to write to
+   * @param {any} value - The value to write to
+   */
+  static writeToLocalStorage(key, value) {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
 
-    /**
-     * @method readFromLocalStorage
-     * @description Reads from local storage
-     * @param {string} key - The key to read from
-     * @returns {any} - The value read from local storage
-     */
-    static readFromLocalStorage(key) {
-        return JSON.parse(localStorage.getItem(key));
-    }
+  /**
+   * @method readFromLocalStorage
+   * @description Reads from local storage
+   * @param {string} key - The key to read from
+   * @returns {any} - The value read from local storage
+   */
+  static readFromLocalStorage(key) {
+    return JSON.parse(localStorage.getItem(key));
+  }
+
+  /**
+   * @method clearLocalStorage
+   * @description Clears local storage
+   */
+  static clearLocalStorage() {
+    localStorage.clear();
+  }
+
+  /**
+   * @method writeToSessionStorage
+   * @description Writes to session storage
+   * @param {string} key - The key to write to
+   * @param {any} value - The value to write to
+   */
+  static writeToSessionStorage(key, value) {
+    sessionStorage.setItem(key, JSON.stringify(value));
+  }
+
+  /**
+   * @method readFromSessionStorage
+   * @description Reads from session storage
+   * @param {string} key - The key to read from
+   * @returns {any} - The value read from session storage
+   */
+  static readFromSessionStorage(key) {
+    return JSON.parse(sessionStorage.getItem(key));
+  }
 
-    /**
-     * @method clearLocalStorage
-     * @description Clears local storage
-     */
-    static clearLocalStorage() {
-        localStorage.clear();
+  /**
+   * @method clearSessionStorage
+   * @description Clears session storage
+   */
+  static clearSessionStorage() {
+    sessionStorage.clear();
+  }
+
+  /**
+   * @method save
+   * @description Writes a versioned save under `key`. The payload is wrapped in
+   * an envelope `{ v, t, data }` so it can be migrated later, and the previous
+   * value is mirrored to `key + ".bak"` for corruption recovery. Quota and
+   * serialization errors are caught and reported rather than thrown.
+   * @param {string} key - The storage key
+   * @param {any} data - The data to persist (must be JSON-serializable)
+   * @param {Object} [options] - { version = 1, backup = true }
+   * @returns {boolean} - Whether the write succeeded
+   */
+  static save(key, data, options = {}) {
+    const version = options.version ?? 1;
+    let serialized;
+    try {
+      serialized = JSON.stringify({ v: version, t: Date.now(), data });
+    } catch (e) {
+      console.warn(`[Storage] Could not serialize save "${key}":`, e);
+      return false;
+    }
+    try {
+      if (options.backup !== false) {
+        const prev = localStorage.getItem(key);
+        if (prev != null) {
+          try {
+            localStorage.setItem(key + ".bak", prev);
+          } catch (_) {}
+        }
+      }
+      localStorage.setItem(key, serialized);
+      return true;
+    } catch (e) {
+      console.warn(`[Storage] Failed to save "${key}" (quota exceeded?):`, e);
+      return false;
     }
+  }
 
-    /**
-     * @method writeToSessionStorage
-     * @description Writes to session storage
-     * @param {string} key - The key to write to
-     * @param {any} value - The value to write to
-     */
-    static writeToSessionStorage(key, value) {
-        sessionStorage.setItem(key, JSON.stringify(value));
+  /**
+   * @method _unwrap
+   * @description Parses a stored string into a `{ v, data }` envelope, treating
+   * a plain (pre-versioning) value as version 0. Returns undefined for missing
+   * data and throws for malformed JSON.
+   * @private
+   */
+  static _unwrap(raw) {
+    if (raw == null) return undefined;
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      "v" in parsed &&
+      "data" in parsed
+    ) {
+      return parsed;
     }
+    return { v: 0, data: parsed };
+  }
+
+  /**
+   * @method load
+   * @description Reads a versioned save written by `save`. If the primary value
+   * is corrupt it falls back to the `.bak` copy; if that fails too it returns
+   * `fallback`. When the stored version differs from `version` and a `migrate`
+   * function is given, the data is upgraded (and rewritten unless disabled).
+   * @param {string} key - The storage key
+   * @param {Object} [options] - { version = 1, fallback = null, migrate, rewrite = true }
+   * @returns {any} - The (possibly migrated) saved data, or `fallback`
+   */
+  static load(key, options = {}) {
+    const version = options.version ?? 1;
+    const fallback = options.fallback ?? null;
+    const migrate = options.migrate || null;
 
-    /**
-     * @method readFromSessionStorage
-     * @description Reads from session storage
-     * @param {string} key - The key to read from
-     * @returns {any} - The value read from session storage
-     */
-    static readFromSessionStorage(key) {
-        return JSON.parse(sessionStorage.getItem(key));
+    let env;
+    try {
+      env = Storage._unwrap(localStorage.getItem(key));
+    } catch (e) {
+      try {
+        env = Storage._unwrap(localStorage.getItem(key + ".bak"));
+        if (env !== undefined) {
+          console.warn(
+            `[Storage] "${key}" was corrupt; recovered from backup.`
+          );
+        }
+      } catch (_) {
+        env = undefined;
+      }
     }
+    if (env === undefined) return fallback;
 
-    /**
-     * @method clearSessionStorage
-     * @description Clears session storage
-     */
-    static clearSessionStorage() {
-        sessionStorage.clear();
+    let data = env.data;
+    if (env.v !== version && migrate) {
+      try {
+        data = migrate(data, env.v, version);
+      } catch (e) {
+        console.warn(`[Storage] Migration failed for "${key}":`, e);
+        return fallback;
+      }
+      if (options.rewrite !== false) {
+        Storage.save(key, data, { version, backup: false });
+      }
     }
+    return data;
+  }
+
+  /**
+   * @method hasSave
+   * @description Returns whether a save (or its backup) exists for `key`.
+   * @param {string} key - The storage key
+   * @returns {boolean}
+   */
+  static hasSave(key) {
+    return (
+      localStorage.getItem(key) != null ||
+      localStorage.getItem(key + ".bak") != null
+    );
+  }
+
+  /**
+   * @method removeSave
+   * @description Deletes a save and its backup.
+   * @param {string} key - The storage key
+   */
+  static removeSave(key) {
+    localStorage.removeItem(key);
+    localStorage.removeItem(key + ".bak");
+  }
 }
 
-export default Storage;
+export default Storage;

package/src/Texture.js

@@ -1,67 +1,58 @@
-import { initVertexBuffer } from "./GLUtils.js";
-import Drawable from "./Drawable.js";
-import GLManager from "./managers/GLManager.js";
-
-/**
- * @class Texture
- * @description Represents a texture component
- * @param {string} texturePath - The path to the texture
- * @param {number} frameWidth - The width of the frame
- * @param {number} frameHeight - The height of the frame
- * @param {number} framesPerRow - The number of frames per row
- * @param {number} totalFrames - The total number of frames
- * @param {number} animationSpeed - The speed of the animation
- * @param {boolean} autoPlay - Whether the animation should play automatically
- * @param {boolean} pixelart - Whether the texture is a pixel art texture
- * @param {boolean} useLighting - Whether the texture should react to lighting
- */
-class Texture extends Drawable {
-  constructor(
-    texturePath = {},
-    frameWidth = 0,
-    frameHeight = 0,
-    framesPerRow = 1,
-    totalFrames = 1,
-    animationSpeed = 1000,
-    autoPlay = true,
-    pixelart = true,
-    useLighting = true
-  ) {
-    const vertices = [1.0, 1.0, -1.0, 1.0, 1.0, -1.0, -1.0, -1.0];
-    const verticesBuffer = initVertexBuffer(GLManager.getGL(), vertices);
-    const textureCoordinates = [
-      1.0,
-      1.0, // Top-right
-      0.0,
-      1.0, // Top-left
-      1.0,
-      0.0, // Bottom-right
-      0.0,
-      0.0, // Bottom-left
-    ];
-    const texCoordBuffer = initVertexBuffer(
-      GLManager.getGL(),
-      textureCoordinates
-    );
-
-    super(
-      GLManager.getGL(),
-      GLManager.getProgramInfo(),
-      verticesBuffer,
-      texCoordBuffer,
-      vertices,
-      true,
-      texturePath,
-      frameWidth,
-      frameHeight,
-      framesPerRow,
-      totalFrames,
-      animationSpeed,
-      autoPlay,
-      pixelart,
-      useLighting
-    );
-  }
-}
-
-export default Texture;
+import { initVertexBuffer } from "./GLUtils.js";
+import Drawable from "./Drawable.js";
+import GLManager from "./managers/GLManager.js";
+
+/**
+ * @class Texture
+ * @description Represents a texture component
+ * @param {string} texturePath - The path to the texture
+ * @param {number} frameWidth - The width of the frame
+ * @param {number} frameHeight - The height of the frame
+ * @param {number} framesPerRow - The number of frames per row
+ * @param {number} totalFrames - The total number of frames
+ * @param {number} animationSpeed - The speed of the animation
+ * @param {boolean} autoPlay - Whether the animation should play automatically
+ * @param {boolean} pixelart - Whether the texture is a pixel art texture
+ * @param {boolean} useLighting - Whether the texture should react to lighting
+ */
+class Texture extends Drawable {
+  constructor(
+    texturePath = {},
+    frameWidth = 0,
+    frameHeight = 0,
+    framesPerRow = 1,
+    totalFrames = 1,
+    animationSpeed = 1000,
+    autoPlay = true,
+    pixelart = true,
+    useLighting = true
+  ) {
+    const vertices = [1.0, 1.0, -1.0, 1.0, 1.0, -1.0, -1.0, -1.0];
+    const verticesBuffer = initVertexBuffer(GLManager.getGL(), vertices);
+    const textureCoordinates = [1.0, 1.0, 0.0, 1.0, 1.0, 0.0, 0.0, 0.0];
+    const texCoordBuffer = initVertexBuffer(
+      GLManager.getGL(),
+      textureCoordinates
+    );
+
+    super(
+      GLManager.getGL(),
+      GLManager.getProgramInfo(),
+      verticesBuffer,
+      texCoordBuffer,
+      vertices,
+      true,
+      texturePath,
+      frameWidth,
+      frameHeight,
+      framesPerRow,
+      totalFrames,
+      animationSpeed,
+      autoPlay,
+      pixelart,
+      useLighting
+    );
+  }
+}
+
+export default Texture;

package/src/TextureAtlas.js

@@ -0,0 +1,96 @@
+import TextureManager from "./managers/TextureManager.js";
+
+/**
+ * @class TextureAtlas
+ * @description Loads a packed sprite atlas (image + frame rectangles) and applies
+ * named frames to Drawables as normalized UV regions. Accepts TexturePacker
+ * JSON (hash or array `frames`) or a plain `{ name: {x,y,w,h} }` map.
+ *
+ * @example
+ * const atlas = await TextureAtlas.load("sheet.png", sheetJson, true);
+ * const sprite = new Texture(atlas.texturePath, 0, 0, 1, 1, 0, false, true);
+ * obj.addComponent(sprite);
+ * atlas.applyTo(sprite, "player_idle_0");
+ */
+class TextureAtlas {
+  constructor(texturePath, frames, width, height) {
+    this.texturePath = texturePath;
+    this.frames = frames;
+    this.width = width;
+    this.height = height;
+  }
+
+  /**
+   * @method load
+   * @description Loads the atlas image (caching its GL texture) and parses frames.
+   * @param {string} texturePath
+   * @param {Object} atlasJson - Atlas description
+   * @param {boolean} [pixelart] - Filter mode for the cached texture
+   * @returns {Promise<TextureAtlas>}
+   */
+  static async load(texturePath, atlasJson, pixelart = false) {
+    const image = await TextureManager.loadImage(texturePath);
+    await TextureManager.getTexture(texturePath, pixelart);
+    const w = image.width;
+    const h = image.height;
+    return new TextureAtlas(texturePath, TextureAtlas._parse(atlasJson), w, h);
+  }
+
+  /** @private */
+  static _parse(json) {
+    const out = {};
+    if (json && json.frames) {
+      if (Array.isArray(json.frames)) {
+        for (const f of json.frames) out[f.filename] = f.frame;
+      } else {
+        for (const name in json.frames) out[name] = json.frames[name].frame;
+      }
+    } else if (json) {
+      for (const name in json) out[name] = json[name];
+    }
+    return out;
+  }
+
+  /**
+   * @method getFrame
+   * @description Returns the pixel rect { x, y, w, h } for a frame name.
+   */
+  getFrame(name) {
+    return this.frames[name] || null;
+  }
+
+  /**
+   * @method getRegion
+   * @description Returns the normalized UV region for a frame name.
+   * @returns {{left,top,right,bottom}|null}
+   */
+  getRegion(name) {
+    const f = this.frames[name];
+    if (!f) return null;
+    return {
+      left: f.x / this.width,
+      top: f.y / this.height,
+      right: (f.x + f.w) / this.width,
+      bottom: (f.y + f.h) / this.height,
+    };
+  }
+
+  /**
+   * @method applyTo
+   * @description Applies a frame's UV region to a Drawable.
+   * @param {Drawable} drawable
+   * @param {string} name - Frame name
+   * @returns {TextureAtlas} - this
+   */
+  applyTo(drawable, name) {
+    const r = this.getRegion(name);
+    if (r) {
+      drawable.setRegion(r.left, r.top, r.right, r.bottom);
+    } else {
+      console.warn(`[TextureAtlas] > Unknown frame "${name}"`);
+    }
+    return this;
+  }
+}
+
+export default TextureAtlas;