@carbonenginejs/runtime-resource 0.8.0 → 0.9.0

package/dist/formats/bnk/CjsBnkFormat.js

@@ -1,10 +1,10 @@
-import { wwiseIdFromName, joinSoundbanksInfo, buildSoundbanksCatalog, parseSoundbanksInfo, isSoundbanksInfo } from './core/soundbanksInfo.js';
-import { DEFAULT_VALUES, normalizeValues, readWithValues, inspectWithValues, isSupportedWithValues, toJsonValue, toBytes, extractMedia, isBNK, OUTPUT_MEDIA, OUTPUT_BNK_JSON, OUTPUT_JSON, OUTPUT_RAW, HIRC_TYPE_NAMES } from './core/helpers.js';
-import { eventMediaFromBanks } from './core/graph.js';
-import { parseMusicSwitch, parseMusicPlaylist, parseMusicTrack, parseMusicSegment, musicNodesFromBanks } from './core/musicNodes.js';
-
-const FORMAT_NAME = "CjsBnkFormat";
-
+import { wwiseIdFromName, joinSoundbanksInfo, buildSoundbanksCatalog, parseSoundbanksInfo, isSoundbanksInfo } from './core/soundbanksInfo.js';
+import { DEFAULT_VALUES, normalizeValues, readWithValues, inspectWithValues, isSupportedWithValues, toJsonValue, toBytes, extractMedia, isBNK, OUTPUT_MEDIA, OUTPUT_BNK_JSON, OUTPUT_JSON, OUTPUT_RAW, HIRC_TYPE_NAMES } from './core/helpers.js';
+import { eventMediaFromBanks } from './core/graph.js';
+import { parseMusicSwitch, parseMusicPlaylist, parseMusicTrack, parseMusicSegment, musicNodesFromBanks } from './core/musicNodes.js';
+
+const FORMAT_NAME = "CjsBnkFormat";
+
 /**
  * Reader for Audiokinetic Wwise soundbank (.bnk) containers.
  *
@@ -14,175 +14,175 @@ const FORMAT_NAME = "CjsBnkFormat";
  * embedded media items undecoded. The read path stays a pure container
  * reader; the Wwise-domain toolkit (SoundbanksInfo catalog helpers, id hash,
  * event -> media graph resolution) is grouped under the `wwise` static.
- */
-class CjsBnkFormat {
-  #values = DEFAULT_VALUES;
-
+ */
+class CjsBnkFormat {
+  #values = DEFAULT_VALUES;
+
   /**
    * Create a reusable bnk format profile.
    *
    * @param {object} [options] Default read/inspect options.
-   */
-  constructor(options = {}) {
-    this.SetValues(options);
-  }
-
+   */
+  constructor(options = {}) {
+    this.SetValues(options);
+  }
+
   /**
    * Merge options into this profile.
    *
    * @param {object} [options] Values to merge.
    * @returns {CjsBnkFormat} This format profile.
-   */
-  SetValues(options = {}) {
-    this.#values = normalizeValues(this.#values, options, FORMAT_NAME);
-    return this;
-  }
-
+   */
+  SetValues(options = {}) {
+    this.#values = normalizeValues(this.#values, options, FORMAT_NAME);
+    return this;
+  }
+
   /**
    * Get normalized profile values with optional per-call overrides.
    *
    * @param {object} [options] Per-call values.
    * @returns {object} Normalized read values.
-   */
-  GetValues(options = {}) {
-    return normalizeValues(this.#values, options, FORMAT_NAME);
-  }
-
+   */
+  GetValues(options = {}) {
+    return normalizeValues(this.#values, options, FORMAT_NAME);
+  }
+
   /**
    * Read soundbank bytes with this profile.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Per-call values.
    * @returns {object} GPU-free raw/debug/media payload for the selected emit target.
-   */
-  Read(input, options = {}) {
-    return readWithValues(input, this.GetValues(options));
-  }
-
+   */
+  Read(input, options = {}) {
+    return readWithValues(input, this.GetValues(options));
+  }
+
   /**
    * Read soundbank bytes asynchronously with this profile.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Per-call values.
    * @returns {Promise<object>} GPU-free raw/debug/media payload for the selected emit target.
-   */
-  async ReadAsync(input, options = {}) {
-    return this.Read(input, options);
-  }
-
+   */
+  async ReadAsync(input, options = {}) {
+    return this.Read(input, options);
+  }
+
   /**
    * Inspect soundbank bytes without copying media payloads.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Per-call values.
    * @returns {object} Soundbank metadata.
-   */
-  Inspect(input, options = {}) {
-    return inspectWithValues(input, this.GetValues(options));
-  }
-
+   */
+  Inspect(input, options = {}) {
+    return inspectWithValues(input, this.GetValues(options));
+  }
+
   /**
    * Report whether soundbank input and requested output variants are supported.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Per-call values.
    * @returns {object} Support/probe report.
-   */
-  IsSupported(input, options = {}) {
-    return isSupportedWithValues(input, this.GetValues(options));
-  }
-
+   */
+  IsSupported(input, options = {}) {
+    return isSupportedWithValues(input, this.GetValues(options));
+  }
+
   /**
    * Convert format output into JSON-compatible debug data.
    *
    * @param {any} value Format output.
    * @returns {any} JSON-compatible value.
-   */
-  ToJSON(value) {
-    return toJsonValue(value);
-  }
-
+   */
+  ToJSON(value) {
+    return toJsonValue(value);
+  }
+
   /**
    * One-shot soundbank read.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Read options.
    * @returns {object} GPU-free raw/debug/media payload for the selected emit target.
-   */
-  static read(input, options = {}) {
-    return readWithValues(input, normalizeValues(DEFAULT_VALUES, options, FORMAT_NAME));
-  }
-
+   */
+  static read(input, options = {}) {
+    return readWithValues(input, normalizeValues(DEFAULT_VALUES, options, FORMAT_NAME));
+  }
+
   /**
    * One-shot asynchronous soundbank read.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Read options.
    * @returns {Promise<object>} GPU-free raw/debug/media payload for the selected emit target.
-   */
-  static async readAsync(input, options = {}) {
-    return CjsBnkFormat.read(input, options);
-  }
-
+   */
+  static async readAsync(input, options = {}) {
+    return CjsBnkFormat.read(input, options);
+  }
+
   /**
    * One-shot soundbank inspection.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Inspect options.
    * @returns {object} Soundbank metadata.
-   */
-  static inspect(input, options = {}) {
-    return inspectWithValues(input, normalizeValues(DEFAULT_VALUES, options, FORMAT_NAME));
-  }
-
+   */
+  static inspect(input, options = {}) {
+    return inspectWithValues(input, normalizeValues(DEFAULT_VALUES, options, FORMAT_NAME));
+  }
+
   /**
    * One-shot soundbank support probe.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {object} [options] Probe options.
    * @returns {object} Support/probe report.
-   */
-  static isSupported(input, options = {}) {
-    return isSupportedWithValues(input, normalizeValues(DEFAULT_VALUES, options, FORMAT_NAME));
-  }
-
+   */
+  static isSupported(input, options = {}) {
+    return isSupportedWithValues(input, normalizeValues(DEFAULT_VALUES, options, FORMAT_NAME));
+  }
+
   /**
    * Extract embedded media payloads as views over the soundbank bytes.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Soundbank bytes.
    * @param {number} [mediaId] Optional single media id filter.
    * @returns {Array<object>} Extracted media items with undecoded bytes.
-   */
-  static extractMedia(input, mediaId) {
-    const bytes = toBytes(input);
-    const metadata = inspectWithValues(bytes, DEFAULT_VALUES);
-    return extractMedia(bytes, metadata, mediaId);
-  }
-
+   */
+  static extractMedia(input, mediaId) {
+    const bytes = toBytes(input);
+    const metadata = inspectWithValues(bytes, DEFAULT_VALUES);
+    return extractMedia(bytes, metadata, mediaId);
+  }
+
   /**
    * Convert format output into JSON-compatible debug data.
    *
    * @param {any} value Format output.
    * @returns {any} JSON-compatible value.
-   */
-  static toJSON(value) {
-    return toJsonValue(value);
-  }
-
+   */
+  static toJSON(value) {
+    return toJsonValue(value);
+  }
+
   /**
    * Test whether bytes look like a Wwise soundbank.
    *
    * @param {Uint8Array|ArrayBuffer|DataView} input Candidate soundbank bytes.
    * @returns {boolean} True when the BKHD header chunk is present.
-   */
-  static isBNK(input) {
-    try {
-      return isBNK(toBytes(input));
-    } catch {
-      return false;
-    }
-  }
-
+   */
+  static isBNK(input) {
+    try {
+      return isBNK(toBytes(input));
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Wwise-domain toolkit, grouped apart from the container-reading statics -
    * the single home for the SoundbanksInfo catalog helpers
@@ -202,37 +202,37 @@ class CjsBnkFormat {
    * entries (HIRC 10-13) into typed nodes - children, meter, cue markers,
    * clips, playlist trees, decision trees, and transition rules. See
    * core/musicNodes.js for the anchored, exact-end-validated parse.
-   */
-  static wwise = Object.freeze({
-    isSoundbanksInfo,
-    parseSoundbanksInfo,
-    buildSoundbanksCatalog,
-    joinSoundbanksInfo,
-    wwiseIdFromName,
-    eventMediaFromBanks,
-    musicNodesFromBanks,
-    parseMusicSegment,
-    parseMusicTrack,
-    parseMusicPlaylist,
-    parseMusicSwitch
-  });
-
+   */
+  static wwise = Object.freeze({
+    isSoundbanksInfo,
+    parseSoundbanksInfo,
+    buildSoundbanksCatalog,
+    joinSoundbanksInfo,
+    wwiseIdFromName,
+    eventMediaFromBanks,
+    musicNodesFromBanks,
+    parseMusicSegment,
+    parseMusicTrack,
+    parseMusicPlaylist,
+    parseMusicSwitch
+  });
+
   /**
    * Emit targets for this format (canonical frozen enum).
-   */
-  static Output = Object.freeze({
-    RAW: OUTPUT_RAW,
-    JSON: OUTPUT_JSON,
-    BNK_JSON: OUTPUT_BNK_JSON,
-    MEDIA: OUTPUT_MEDIA
-  });
-  static HIRC_TYPE_NAMES = HIRC_TYPE_NAMES;
-  static type = Object.freeze(["audio"]);
-  static mediaTypes = Object.freeze(["audio"]);
-  static inputTypes = Object.freeze(["bnk"]);
-  static outputTypes = Object.freeze([OUTPUT_RAW, OUTPUT_MEDIA]);
-  static debugOutputTypes = Object.freeze([OUTPUT_BNK_JSON, OUTPUT_RAW]);
-}
-
-export { CjsBnkFormat };
-//# sourceMappingURL=CjsBnkFormat.js.map
+   */
+  static Output = Object.freeze({
+    RAW: OUTPUT_RAW,
+    JSON: OUTPUT_JSON,
+    BNK_JSON: OUTPUT_BNK_JSON,
+    MEDIA: OUTPUT_MEDIA
+  });
+  static HIRC_TYPE_NAMES = HIRC_TYPE_NAMES;
+  static type = Object.freeze(["audio"]);
+  static mediaTypes = Object.freeze(["audio"]);
+  static inputTypes = Object.freeze(["bnk"]);
+  static outputTypes = Object.freeze([OUTPUT_RAW, OUTPUT_MEDIA]);
+  static debugOutputTypes = Object.freeze([OUTPUT_BNK_JSON, OUTPUT_RAW]);
+}
+
+export { CjsBnkFormat };
+//# sourceMappingURL=CjsBnkFormat.js.map

package/dist/formats/bnk/core/graph.js

@@ -1,140 +1,140 @@
-// Wwise soundbank object-graph interpretation: event -> media resolution over
-// one or more inspected banks. Exposed as `CjsBnkFormat.eventMediaFromBanks`.
-// This is NOT part of the format read path and is never used by the resource
-// lifecycle - it exists so consumers can go from `inspect()` output to "what
-// does event X play?" without writing their own graph walk.
-//
-// Inputs are plain inspect() results (formats/bnk): the typed HIRC fields
-// (event actionIds, action actionType/targetId, sound/track sourceIds) plus
-// per-object raw payload views for the structures that stay undecoded
-// (container children, positioning, RTPC data).
-//
-// Verified against EVE soundbanks (bank generator version 150 / Wwise 2022.1):
-// - Banks may split responsibilities: EVE keeps every event/action in one
-//   bank (common.bnk) and the sounds/containers they target in the media
-//   banks, so edges only resolve over the MERGED graph - always pass every
-//   related bank to one call.
-// - Walk policy: only play-family actions (actionType high byte 0x04) are
-//   followed; sounds and music tracks are terminals (their typed sourceIds
-//   are the media); actor-mixers and buses are never entered, because node
-//   payloads carry parent/bus back-pointers that would otherwise drag every
-//   sibling sound into the result.
-// - Container children lists are undecoded, so references are recovered with
-//   a validated id-scan: a u32 at ANY byte offset of a container payload
-//   counts only when it matches a traversable object id or a known wem id.
-//   Wwise ids are 32-bit hashes, making in-bank collisions vanishingly rare.
-
-const HIRC_SOUND = 2;
-const HIRC_ACTION = 3;
-const HIRC_EVENT = 4;
-const HIRC_MUSIC_TRACK = 11;
-
-// Types the walk may traverse INTO from a play action or container:
-// sound (2), random-sequence (5), switch (6), blend/layer (9),
-// music segment/track/switch/playlist (10-13).
-const TRAVERSABLE_TYPES = new Set([2, 5, 6, 9, 10, 11, 12, 13]);
-
-// Media-bearing terminals: typed sourceIds are collected, no traversal out.
-const TERMINAL_TYPES = new Set([HIRC_SOUND, HIRC_MUSIC_TRACK]);
-
-// actionType high byte for the play family (for example 0x0403 = play; the
-// low byte is scope). Stop is 0x01xx, pause 0x02xx, resume 0x03xx.
-const PLAY_ACTION_FAMILY = 0x0400;
-
-/**
- * Resolve event -> wem media edges over one or more inspected soundbanks.
- *
- * @param {Array<object>} inspections `CjsBnkFormat.inspect()` results for every related bank.
- * @param {object} [options] Optional settings.
- * @param {Iterable<number|string>} [options.knownWemIds] Streamed wem ids to validate media references against; every bank's embedded media ids are always included.
- * @returns {{eventMedia: Map<number, Set<number>>, diagnostics: object}} Event object id -> wem id set, plus walk diagnostics.
- */
-function eventMediaFromBanks(inspections, {
-  knownWemIds = []
-} = {}) {
-  const objects = new Map();
-  const diagnostics = {
-    objectCount: 0,
-    eventCount: 0
-  };
-  for (const inspection of inspections) {
-    for (const entry of inspection.hirc || []) {
-      objects.set(entry.id, entry);
-      diagnostics.objectCount++;
-    }
-  }
-  const wemIdSet = new Set();
-  for (const id of knownWemIds) wemIdSet.add(Number(id) >>> 0);
-  for (const inspection of inspections) {
-    for (const record of inspection.media || []) wemIdSet.add(record.id);
-  }
-
-  // Validated id-scan over a container payload, cached per object id -
-  // containers are shared between many events.
-  const scanCache = new Map();
-  const scanObject = entry => {
-    let cached = scanCache.get(entry.id);
-    if (cached) return cached;
-    const nodeRefs = new Set();
-    const mediaRefs = new Set();
-    cached = {
-      nodeRefs,
-      mediaRefs
-    };
-    scanCache.set(entry.id, cached);
-    const body = entry.payload;
-    if (!body) return cached;
-    for (let at = 0; at + 4 <= body.byteLength; at++) {
-      const value = (body[at] | body[at + 1] << 8 | body[at + 2] << 16 | body[at + 3] * 0x1000000) >>> 0;
-      if (value === entry.id) continue;
-      if (wemIdSet.has(value)) mediaRefs.add(value);
-      const target = objects.get(value);
-      if (target && TRAVERSABLE_TYPES.has(target.type)) nodeRefs.add(value);
-    }
-    return cached;
-  };
-  const eventMedia = new Map();
-  for (const entry of objects.values()) {
-    if (entry.type !== HIRC_EVENT) continue;
-    diagnostics.eventCount++;
-    const media = new Set();
-    const visited = new Set();
-    const stack = [];
-    for (const actionId of entry.actionIds || []) {
-      const action = objects.get(actionId);
-      if (!action || action.type !== HIRC_ACTION) continue;
-      if (((action.actionType ?? 0) & 0xff00) !== PLAY_ACTION_FAMILY) continue;
-      const target = objects.get(action.targetId);
-      if (target && TRAVERSABLE_TYPES.has(target.type)) stack.push(target.id);
-    }
-    while (stack.length) {
-      const node = objects.get(stack.pop());
-      if (!node || visited.has(node.id)) continue;
-      visited.add(node.id);
-      const {
-        nodeRefs,
-        mediaRefs
-      } = scanObject(node);
-      for (const wemId of mediaRefs) media.add(wemId);
-      if (node.type === HIRC_SOUND && node.sourceId !== undefined && wemIdSet.has(node.sourceId)) {
-        media.add(node.sourceId);
-      }
-      if (node.type === HIRC_MUSIC_TRACK) {
-        for (const source of node.sources || []) {
-          if (wemIdSet.has(source.sourceId)) media.add(source.sourceId);
-        }
-      }
-      if (!TERMINAL_TYPES.has(node.type)) {
-        for (const next of nodeRefs) stack.push(next);
-      }
-    }
-    if (media.size) eventMedia.set(entry.id, media);
-  }
-  return {
-    eventMedia,
-    diagnostics
-  };
-}
-
-export { eventMediaFromBanks };
-//# sourceMappingURL=graph.js.map
+// Wwise soundbank object-graph interpretation: event -> media resolution over
+// one or more inspected banks. Exposed as `CjsBnkFormat.eventMediaFromBanks`.
+// This is NOT part of the format read path and is never used by the resource
+// lifecycle - it exists so consumers can go from `inspect()` output to "what
+// does event X play?" without writing their own graph walk.
+//
+// Inputs are plain inspect() results (formats/bnk): the typed HIRC fields
+// (event actionIds, action actionType/targetId, sound/track sourceIds) plus
+// per-object raw payload views for the structures that stay undecoded
+// (container children, positioning, RTPC data).
+//
+// Verified against EVE soundbanks (bank generator version 150 / Wwise 2022.1):
+// - Banks may split responsibilities: EVE keeps every event/action in one
+//   bank (common.bnk) and the sounds/containers they target in the media
+//   banks, so edges only resolve over the MERGED graph - always pass every
+//   related bank to one call.
+// - Walk policy: only play-family actions (actionType high byte 0x04) are
+//   followed; sounds and music tracks are terminals (their typed sourceIds
+//   are the media); actor-mixers and buses are never entered, because node
+//   payloads carry parent/bus back-pointers that would otherwise drag every
+//   sibling sound into the result.
+// - Container children lists are undecoded, so references are recovered with
+//   a validated id-scan: a u32 at ANY byte offset of a container payload
+//   counts only when it matches a traversable object id or a known wem id.
+//   Wwise ids are 32-bit hashes, making in-bank collisions vanishingly rare.
+
+const HIRC_SOUND = 2;
+const HIRC_ACTION = 3;
+const HIRC_EVENT = 4;
+const HIRC_MUSIC_TRACK = 11;
+
+// Types the walk may traverse INTO from a play action or container:
+// sound (2), random-sequence (5), switch (6), blend/layer (9),
+// music segment/track/switch/playlist (10-13).
+const TRAVERSABLE_TYPES = new Set([2, 5, 6, 9, 10, 11, 12, 13]);
+
+// Media-bearing terminals: typed sourceIds are collected, no traversal out.
+const TERMINAL_TYPES = new Set([HIRC_SOUND, HIRC_MUSIC_TRACK]);
+
+// actionType high byte for the play family (for example 0x0403 = play; the
+// low byte is scope). Stop is 0x01xx, pause 0x02xx, resume 0x03xx.
+const PLAY_ACTION_FAMILY = 0x0400;
+
+/**
+ * Resolve event -> wem media edges over one or more inspected soundbanks.
+ *
+ * @param {Array<object>} inspections `CjsBnkFormat.inspect()` results for every related bank.
+ * @param {object} [options] Optional settings.
+ * @param {Iterable<number|string>} [options.knownWemIds] Streamed wem ids to validate media references against; every bank's embedded media ids are always included.
+ * @returns {{eventMedia: Map<number, Set<number>>, diagnostics: object}} Event object id -> wem id set, plus walk diagnostics.
+ */
+function eventMediaFromBanks(inspections, {
+  knownWemIds = []
+} = {}) {
+  const objects = new Map();
+  const diagnostics = {
+    objectCount: 0,
+    eventCount: 0
+  };
+  for (const inspection of inspections) {
+    for (const entry of inspection.hirc || []) {
+      objects.set(entry.id, entry);
+      diagnostics.objectCount++;
+    }
+  }
+  const wemIdSet = new Set();
+  for (const id of knownWemIds) wemIdSet.add(Number(id) >>> 0);
+  for (const inspection of inspections) {
+    for (const record of inspection.media || []) wemIdSet.add(record.id);
+  }
+
+  // Validated id-scan over a container payload, cached per object id -
+  // containers are shared between many events.
+  const scanCache = new Map();
+  const scanObject = entry => {
+    let cached = scanCache.get(entry.id);
+    if (cached) return cached;
+    const nodeRefs = new Set();
+    const mediaRefs = new Set();
+    cached = {
+      nodeRefs,
+      mediaRefs
+    };
+    scanCache.set(entry.id, cached);
+    const body = entry.payload;
+    if (!body) return cached;
+    for (let at = 0; at + 4 <= body.byteLength; at++) {
+      const value = (body[at] | body[at + 1] << 8 | body[at + 2] << 16 | body[at + 3] * 0x1000000) >>> 0;
+      if (value === entry.id) continue;
+      if (wemIdSet.has(value)) mediaRefs.add(value);
+      const target = objects.get(value);
+      if (target && TRAVERSABLE_TYPES.has(target.type)) nodeRefs.add(value);
+    }
+    return cached;
+  };
+  const eventMedia = new Map();
+  for (const entry of objects.values()) {
+    if (entry.type !== HIRC_EVENT) continue;
+    diagnostics.eventCount++;
+    const media = new Set();
+    const visited = new Set();
+    const stack = [];
+    for (const actionId of entry.actionIds || []) {
+      const action = objects.get(actionId);
+      if (!action || action.type !== HIRC_ACTION) continue;
+      if (((action.actionType ?? 0) & 0xff00) !== PLAY_ACTION_FAMILY) continue;
+      const target = objects.get(action.targetId);
+      if (target && TRAVERSABLE_TYPES.has(target.type)) stack.push(target.id);
+    }
+    while (stack.length) {
+      const node = objects.get(stack.pop());
+      if (!node || visited.has(node.id)) continue;
+      visited.add(node.id);
+      const {
+        nodeRefs,
+        mediaRefs
+      } = scanObject(node);
+      for (const wemId of mediaRefs) media.add(wemId);
+      if (node.type === HIRC_SOUND && node.sourceId !== undefined && wemIdSet.has(node.sourceId)) {
+        media.add(node.sourceId);
+      }
+      if (node.type === HIRC_MUSIC_TRACK) {
+        for (const source of node.sources || []) {
+          if (wemIdSet.has(source.sourceId)) media.add(source.sourceId);
+        }
+      }
+      if (!TERMINAL_TYPES.has(node.type)) {
+        for (const next of nodeRefs) stack.push(next);
+      }
+    }
+    if (media.size) eventMedia.set(entry.id, media);
+  }
+  return {
+    eventMedia,
+    diagnostics
+  };
+}
+
+export { eventMediaFromBanks };
+//# sourceMappingURL=graph.js.map