@carbonenginejs/runtime-resource 0.1.0 → 0.8.0

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

@@ -0,0 +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

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

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