emeraldengine 2.2.1 → 3.0.0

package/src/importers/Aseprite.js

@@ -0,0 +1,142 @@
+/**
+ * @class Aseprite
+ * @description Imports sprite-sheet metadata exported from Aseprite
+ * (File ▸ Export Sprite Sheet, with "JSON Data" on) and turns its frame tags
+ * into engine animation clips. Works with both the Hash and Array JSON layouts.
+ * Pure parsing — pass it the already-parsed JSON object.
+ *
+ * Assumes the sheet is a uniform grid in frame order (the common case), so the
+ * frame indices line up with the engine's Texture/Animator frame numbering.
+ *
+ * @example
+ * const cfg = Aseprite.spriteConfig(sheetJson); // {frameWidth, framesPerRow, ...}
+ * const tex = new Texture("hero.png", cfg.frameWidth, cfg.frameHeight,
+ *   cfg.framesPerRow, cfg.totalFrames, 0, false);
+ * obj.addComponent(tex);
+ * const anim = new Animator();
+ * obj.addComponent(anim);
+ * Aseprite.applyTo(anim, sheetJson);   // registers "idle", "run", ... clips
+ * anim.play("run");
+ */
+class Aseprite {
+  /**
+   * @method frames
+   * @description Returns the frames as an ordered array regardless of whether
+   * the export used the Hash (object) or Array layout.
+   * @param {Object} sheet - Parsed Aseprite JSON
+   * @returns {Array<Object>}
+   */
+  static frames(sheet) {
+    const f = sheet.frames;
+    if (Array.isArray(f)) return f;
+    return f ? Object.values(f) : [];
+  }
+
+  /**
+   * @method spriteConfig
+   * @description Derives the uniform-grid sprite config (for Texture) from the
+   * first frame and the sheet size.
+   * @param {Object} sheet - Parsed Aseprite JSON
+   * @returns {{frameWidth:number, frameHeight:number, framesPerRow:number, totalFrames:number}}
+   */
+  static spriteConfig(sheet) {
+    const frames = Aseprite.frames(sheet);
+    const first =
+      frames[0] && frames[0].frame ? frames[0].frame : { w: 0, h: 0 };
+    const frameWidth = first.w || 0;
+    const frameHeight = first.h || 0;
+    const sheetW =
+      (sheet.meta && sheet.meta.size && sheet.meta.size.w) || frameWidth;
+    return {
+      frameWidth,
+      frameHeight,
+      framesPerRow: frameWidth
+        ? Math.max(1, Math.round(sheetW / frameWidth))
+        : 1,
+      totalFrames: frames.length,
+    };
+  }
+
+  /**
+   * @method durations
+   * @description Per-frame durations in milliseconds, in frame order.
+   * @param {Object} sheet - Parsed Aseprite JSON
+   * @returns {number[]}
+   */
+  static durations(sheet) {
+    return Aseprite.frames(sheet).map((f) => f.duration || 100);
+  }
+
+  /** @private */
+  static _expandTag(tag) {
+    const from = tag.from;
+    const to = tag.to;
+    const forward = [];
+    for (let i = from; i <= to; i++) forward.push(i);
+    const dir = (tag.direction || "forward").toLowerCase();
+    if (dir === "reverse") return forward.slice().reverse();
+    if (dir === "pingpong" || dir === "ping-pong") {
+      const back = forward.slice(1, -1).reverse();
+      return forward.concat(back);
+    }
+    return forward;
+  }
+
+  /**
+   * @method toClips
+   * @description Builds clip descriptors from the sheet's frame tags. Each clip
+   * is `{ name, frames, speed }` where `frames` are frame indices and `speed`
+   * is the average frame duration (ms) — the per-clip speed the Animator uses.
+   * If the sheet has no tags, a single "default" clip spanning all frames is
+   * returned.
+   * @param {Object} sheet - Parsed Aseprite JSON
+   * @returns {Array<{name:string, frames:number[], speed:number}>}
+   */
+  static toClips(sheet) {
+    const durations = Aseprite.durations(sheet);
+    const avg = (indices) => {
+      if (!indices.length) return 100;
+      let sum = 0;
+      let n = 0;
+      for (const i of indices) {
+        sum += durations[i] != null ? durations[i] : 100;
+        n++;
+      }
+      return Math.round(sum / n);
+    };
+
+    const tags = (sheet.meta && sheet.meta.frameTags) || [];
+    if (!tags.length) {
+      const all = durations.map((_, i) => i);
+      return [{ name: "default", frames: all, speed: avg(all) }];
+    }
+    return tags.map((tag) => {
+      const frames = Aseprite._expandTag(tag);
+      return { name: tag.name, frames, speed: avg(frames) };
+    });
+  }
+
+  /**
+   * @method applyTo
+   * @description Registers every clip from the sheet on an Animator. Clips loop
+   * by default; pass `loop` as a boolean (applies to all) or an object mapping
+   * clip name -> boolean to override individual clips.
+   * @param {Animator} animator - Target animator
+   * @param {Object} sheet - Parsed Aseprite JSON
+   * @param {Object} [options] - { loop = true }
+   * @returns {Animator} - The animator (for chaining)
+   */
+  static applyTo(animator, sheet, options = {}) {
+    const loopOpt = options.loop ?? true;
+    for (const clip of Aseprite.toClips(sheet)) {
+      const loop =
+        typeof loopOpt === "object" && loopOpt !== null
+          ? (loopOpt[clip.name] ?? true)
+          : !!loopOpt;
+      animator.addClip(clip.name, clip.frames, { speed: clip.speed, loop });
+    }
+    return animator;
+  }
+}
+
+export default Aseprite;

package/src/importers/TiledMap.js

@@ -0,0 +1,158 @@
+import Tilemap from "../Tilemap.js";
+
+const FLIP_FLAGS = 0xe0000000;
+const GID_MASK = 0x1fffffff;
+
+/**
+ * @class TiledMap
+ * @description Imports orthogonal maps exported from the Tiled editor
+ * (https://www.mapeditor.org) in JSON format into the engine's Tilemap, plus
+ * helpers to pull object layers (spawn points, triggers, etc.) out as plain
+ * data. Pure parsing — pass it the already-parsed JSON object (load it with
+ * AssetManager.json or fetch).
+ *
+ * @example
+ * const map = TiledMap.toTilemap(mapJson, "tiles.png");
+ * scene.add(map.gameObject);
+ * map.buildColliders(physics);
+ * const spawns = TiledMap.objects(mapJson, { layer: "spawns", flipY: true });
+ */
+class TiledMap {
+  /**
+   * @method tilesetFor
+   * @description Finds the tileset a (masked) global id belongs to.
+   * @param {Object} map - Parsed Tiled map JSON
+   * @param {number} gid - Masked global tile id (flip flags removed)
+   * @returns {Object|null}
+   */
+  static tilesetFor(map, gid) {
+    const sets = map.tilesets || [];
+    let best = null;
+    for (const ts of sets) {
+      if (ts.firstgid <= gid && (!best || ts.firstgid > best.firstgid)) {
+        best = ts;
+      }
+    }
+    return best;
+  }
+
+  /** @private */
+  static _tileLayer(map, layer) {
+    const layers = (map.layers || []).filter((l) => l.type === "tilelayer");
+    if (layer == null) return layers[0] || null;
+    if (typeof layer === "number") return layers[layer] || null;
+    return layers.find((l) => l.name === layer) || null;
+  }
+
+  /**
+   * @method toFrameGrid
+   * @description Converts a tile layer into a 2D array of local frame indices
+   * (-1 for empty), ready for Tilemap.setMap. Global ids are converted to
+   * tileset-local indices and flip flags are stripped.
+   * @param {Object} map - Parsed Tiled map JSON
+   * @param {Object} [options] - { layer } (name, index, or first tile layer)
+   * @returns {number[][]}
+   */
+  static toFrameGrid(map, options = {}) {
+    const layer = TiledMap._tileLayer(map, options.layer);
+    if (!layer) return [];
+    const cols = layer.width;
+    const rows = layer.height;
+    const data = layer.data || [];
+    const grid = [];
+    for (let r = 0; r < rows; r++) {
+      const row = [];
+      for (let c = 0; c < cols; c++) {
+        const raw = data[r * cols + c] || 0;
+        if (raw === 0) {
+          row.push(-1);
+          continue;
+        }
+        const gid = (raw & GID_MASK) >>> 0;
+        const ts = TiledMap.tilesetFor(map, gid);
+        row.push(ts ? gid - ts.firstgid : gid - 1);
+      }
+      grid.push(row);
+    }
+    return grid;
+  }
+
+  /**
+   * @method toTilemap
+   * @description Builds a ready-to-render Tilemap from a Tiled map. The tile
+   * sheet config (frame size, columns, count) is read from the map's first
+   * tileset; the render tile size comes from the map's tilewidth.
+   * @param {Object} map - Parsed Tiled map JSON
+   * @param {string} texturePath - Path to the tile sheet image
+   * @param {Object} [options] - { layer, pixelart = true, name, originX, originY }
+   * @returns {Tilemap}
+   */
+  static toTilemap(map, texturePath, options = {}) {
+    const ts = (map.tilesets || [])[0] || {};
+    const tilemap = new Tilemap(options.name || "tiledmap", texturePath, {
+      tileSize: options.tileSize ?? map.tilewidth ?? ts.tilewidth ?? 16,
+      frameWidth: ts.tilewidth ?? map.tilewidth ?? 16,
+      frameHeight: ts.tileheight ?? map.tileheight ?? 16,
+      framesPerRow: ts.columns ?? 1,
+      totalFrames: ts.tilecount ?? 1,
+      pixelart: options.pixelart ?? true,
+    });
+    const grid = TiledMap.toFrameGrid(map, options);
+    tilemap.setMap(grid, {
+      originX: options.originX ?? 0,
+      originY: options.originY ?? 0,
+      flipY: options.flipY ?? true,
+    });
+    return tilemap;
+  }
+
+  /**
+   * @method objects
+   * @description Extracts the objects from an object layer as plain data
+   * (spawn points, triggers, regions). Tiled `properties` arrays are flattened
+   * into a `props` object. With `flipY` set, y is converted from Tiled's
+   * top-left pixel origin to a y-up world using the map's pixel height.
+   * @param {Object} map - Parsed Tiled map JSON
+   * @param {Object} [options] - { layer, flipY = false, originX = 0, originY = 0 }
+   * @returns {Array<Object>}
+   */
+  static objects(map, options = {}) {
+    const groups = (map.layers || []).filter((l) => l.type === "objectgroup");
+    let group;
+    if (options.layer == null) group = groups[0];
+    else if (typeof options.layer === "number") group = groups[options.layer];
+    else group = groups.find((l) => l.name === options.layer);
+    if (!group) return [];
+
+    const flipY = options.flipY ?? false;
+    const originX = options.originX ?? 0;
+    const originY = options.originY ?? 0;
+    const mapPixelH = (map.height || 0) * (map.tileheight || 0);
+
+    return (group.objects || []).map((o) => {
+      const props = {};
+      if (Array.isArray(o.properties)) {
+        for (const p of o.properties) props[p.name] = p.value;
+      }
+      const worldY = flipY ? mapPixelH - o.y : o.y;
+      return {
+        id: o.id,
+        name: o.name || "",
+        type: o.type || o.class || "",
+        x: originX + o.x,
+        y: originY + worldY,
+        width: o.width || 0,
+        height: o.height || 0,
+        rotation: o.rotation || 0,
+        gid: o.gid != null ? (o.gid & GID_MASK) >>> 0 : null,
+        point: !!o.point,
+        ellipse: !!o.ellipse,
+        polygon: o.polygon || null,
+        props,
+      };
+    });
+  }
+}
+
+export { FLIP_FLAGS, GID_MASK };
+export default TiledMap;

package/src/lights/DirectionalLight.js

@@ -10,15 +10,14 @@ import { Vector2 } from "../Physics.js";
  */
 class DirectionalLight {
   constructor(position, direction, color, intensity, width) {
-    this.position = position; // Vector2 - origin point of the light
-    // Normalize the direction vector
+    this.position = position;
     const length = Math.sqrt(
       direction.x * direction.x + direction.y * direction.y
     );
-    this.direction = new Vector2(direction.x / length, direction.y / length); // Vector2 - normalized direction vector
-    this.color = color; // Color
-    this.intensity = intensity; // Number
-    this.width = width; // Number - width of the light beam
+    this.direction = new Vector2(direction.x / length, direction.y / length);
+    this.color = color;
+    this.intensity = intensity;
+    this.width = width;
   }
 
   /**
@@ -27,38 +26,30 @@ class DirectionalLight {
    * @returns {number} - Light intensity (0-1)
    */
   getIntensityAtPoint(point) {
-
-    // Calculate distance from light position to point
     const dx = point.x - this.position.x;
     const dy = point.y - this.position.y;
     const distance = Math.sqrt(dx * dx + dy * dy);
 
-    // Calculate the projection of the point onto the light direction
     const lightDirNormalized = new Vector2(this.direction.x, this.direction.y);
     const toPoint = new Vector2(dx, dy);
     const projection =
       toPoint.x * lightDirNormalized.x + toPoint.y * lightDirNormalized.y;
 
-    // If point is behind the light, no illumination
     if (projection < 0) {
       return 0;
     }
 
-    // Calculate perpendicular distance from the light beam center
     const perpDistance = Math.abs(
       toPoint.x * lightDirNormalized.y - toPoint.y * lightDirNormalized.x
     );
 
-    // If point is outside the light beam width, no illumination
     if (perpDistance > this.width / 2) {
       return 0;
     }
 
-    // Calculate intensity based on distance within the beam
     const widthFactor = 1 - perpDistance / (this.width / 2);
 
-    // Optional: Add distance attenuation
-    const maxDistance = 1000; // Maximum effective distance
+    const maxDistance = 1000;
     const distanceFactor = Math.max(0, 1 - distance / maxDistance);
 
     return this.intensity * widthFactor * distanceFactor;

package/src/lights/PointLight.js

@@ -7,10 +7,10 @@
  */
 class PointLight {
   constructor(position, color, intensity, radius) {
-    this.position = position; // Vector2
-    this.color = color; // Color
-    this.intensity = intensity; // Number
-    this.radius = radius; // Number
+    this.position = position;
+    this.color = color;
+    this.intensity = intensity;
+    this.radius = radius;
   }
 }
 

package/src/managers/AssetManager.js

@@ -0,0 +1,239 @@
+import TextureManager from "./TextureManager.js";
+
+/**
+ * @class AssetManager
+ * @description A general async loader for everything a game needs at startup:
+ * images/textures, audio, JSON, text, and web fonts. It deduplicates by key,
+ * reports aggregate progress (so you can drive a loading bar), and stores the
+ * resolved assets for synchronous lookup afterwards via `get(key)`.
+ *
+ * Textures are routed through TextureManager so the GL upload cache is shared
+ * with the rest of the engine.
+ *
+ * @example
+ * const assets = new AssetManager();
+ * assets.image("player", "player.png", { pixelart: true });
+ * assets.audio("jump", "jump.wav");
+ * assets.json("level1", "levels/1.json");
+ * assets.font("Press Start 2P", "fonts/press-start.woff2");
+ * assets.onProgress((loaded, total) => bar.set(loaded / total));
+ * await assets.load();
+ * const img = assets.get("player");      // HTMLImageElement
+ * const data = assets.get("level1");     // parsed JSON
+ */
+class AssetManager {
+  constructor() {
+    /** @private */
+    this._queue = new Map();
+    this.assets = new Map();
+    /** @private */
+    this._paths = new Map();
+    /** @private */
+    this._progressHandlers = [];
+    /** @private */
+    this._loaded = 0;
+    /** @private */
+    this._total = 0;
+  }
+
+  /**
+   * @method image
+   * @description Queues an image/texture. The GL texture is created lazily by
+   * the renderer; `get(key)` returns the HTMLImageElement.
+   */
+  image(key, path, options = {}) {
+    this._queue.set(key, { type: "image", path, pixelart: !!options.pixelart });
+    return this;
+  }
+
+  /**
+   * @method audio
+   * @description Queues an audio file (returns an HTMLAudioElement on get()).
+   */
+  audio(key, path) {
+    this._queue.set(key, { type: "audio", path });
+    return this;
+  }
+
+  /**
+   * @method json
+   * @description Queues a JSON file (parsed on get()).
+   */
+  json(key, path) {
+    this._queue.set(key, { type: "json", path });
+    return this;
+  }
+
+  /**
+   * @method text
+   * @description Queues a plain-text file.
+   */
+  text(key, path) {
+    this._queue.set(key, { type: "text", path });
+    return this;
+  }
+
+  /**
+   * @method font
+   * @description Queues a web font. `key` is the font-family name you will use
+   * in CSS/canvas; `path` is the font file URL.
+   */
+  font(key, path, descriptors = {}) {
+    this._queue.set(key, { type: "font", family: key, path, descriptors });
+    return this;
+  }
+
+  /**
+   * @method onProgress
+   * @description Registers a callback invoked as (loaded, total) after each
+   * asset resolves.
+   */
+  onProgress(handler) {
+    if (typeof handler === "function") this._progressHandlers.push(handler);
+    return this;
+  }
+
+  /**
+   * @method progress
+   * @returns {number} - Fraction loaded in [0, 1] (1 when nothing is queued).
+   */
+  progress() {
+    return this._total === 0 ? 1 : this._loaded / this._total;
+  }
+
+  /**
+   * @method load
+   * @description Loads every queued asset, resolving when all are done. Failed
+   * assets reject the returned promise unless `continueOnError` is true, in
+   * which case they resolve to null and loading continues.
+   * @param {Object} [options] - { continueOnError = false }
+   * @returns {Promise<Map>} - The resolved assets map
+   */
+  async load(options = {}) {
+    const { continueOnError = false } = options;
+    const entries = Array.from(this._queue.entries());
+    this._total = entries.length;
+    this._loaded = 0;
+
+    await Promise.all(
+      entries.map(async ([key, spec]) => {
+        try {
+          const asset = await this._loadOne(spec);
+          this.assets.set(key, asset);
+          if (spec.type === "image") {
+            this._paths.set(key, { path: spec.path, pixelart: spec.pixelart });
+          }
+        } catch (err) {
+          if (!continueOnError) throw err;
+          console.warn(`[AssetManager] Failed to load "${key}":`, err);
+          this.assets.set(key, null);
+        } finally {
+          this._loaded++;
+          for (const handler of this._progressHandlers) {
+            handler(this._loaded, this._total);
+          }
+        }
+      })
+    );
+
+    this._queue.clear();
+    return this.assets;
+  }
+
+  /** @private */
+  _loadOne(spec) {
+    switch (spec.type) {
+      case "image":
+        return TextureManager.loadImage(spec.path);
+      case "audio":
+        return AssetManager._loadAudio(spec.path);
+      case "json":
+        return fetch(spec.path).then((r) => {
+          if (!r.ok) throw new Error(`HTTP ${r.status} for ${spec.path}`);
+          return r.json();
+        });
+      case "text":
+        return fetch(spec.path).then((r) => {
+          if (!r.ok) throw new Error(`HTTP ${r.status} for ${spec.path}`);
+          return r.text();
+        });
+      case "font":
+        return AssetManager._loadFont(spec);
+      default:
+        return Promise.reject(new Error(`Unknown asset type: ${spec.type}`));
+    }
+  }
+
+  /** @private */
+  static _loadAudio(path) {
+    return new Promise((resolve, reject) => {
+      const audio = new Audio();
+      audio.addEventListener("canplaythrough", () => resolve(audio), {
+        once: true,
+      });
+      audio.addEventListener("error", () =>
+        reject(new Error(`Failed to load audio: ${path}`))
+      );
+      audio.src = path;
+      audio.load();
+    });
+  }
+
+  /** @private */
+  static async _loadFont(spec) {
+    if (typeof FontFace === "undefined" || !document.fonts) {
+      return null;
+    }
+    const face = new FontFace(
+      spec.family,
+      `url(${spec.path})`,
+      spec.descriptors
+    );
+    const loaded = await face.load();
+    document.fonts.add(loaded);
+    return loaded;
+  }
+
+  /**
+   * @method get
+   * @description Returns a previously loaded asset by key.
+   */
+  get(key) {
+    return this.assets.get(key);
+  }
+
+  /**
+   * @method has
+   * @returns {boolean} - Whether an asset has been loaded for the key.
+   */
+  has(key) {
+    return this.assets.has(key);
+  }
+
+  /**
+   * @method getTexture
+   * @description Convenience: returns the cached GL texture for an image asset
+   * that was queued with `image()`. Resolves once the upload completes.
+   * @param {string} key - The image asset key
+   * @returns {Promise<{texture: WebGLTexture, width: number, height: number}>}
+   */
+  getTexture(key) {
+    const info = this._paths.get(key);
+    if (!info) return Promise.reject(new Error(`No image asset "${key}"`));
+    return TextureManager.getTexture(info.path, info.pixelart);
+  }
+
+  /**
+   * @method clear
+   * @description Forgets all loaded assets (does not free GL textures; use
+   * TextureManager.clear for that).
+   */
+  clear() {
+    this.assets.clear();
+    this._queue.clear();
+    this._loaded = 0;
+    this._total = 0;
+  }
+}
+
+export default AssetManager;