@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/resource/formats/gr2/core/shared.js

@@ -1,18 +1,18 @@
-/**
- * GR2 shared projection.
- * @author cppctamber
- * `projectShared(fileInfo, version)` returns the normalized plain-object graph
- * consumed independently by GR2 JSON and CMF output.
- * Normalized integer values are dequantized with float32 reciprocals, Real16
- * values are already converted by reader.js, and non-finite floats use zero
- * except for typed transform components, which use the corresponding Granny
- * identity value.
+/**
+ * GR2 shared projection.
+ * @author cppctamber
+ * `projectShared(fileInfo, version)` returns the normalized plain-object graph
+ * consumed independently by GR2 JSON and CMF output.
+ * Normalized integer values are dequantized with float32 reciprocals, Real16
+ * values are already converted by reader.js, and non-finite floats use zero
+ * except for typed transform components, which use the corresponding Granny
+ * identity value.
  */
 
 const fr = Math.fround;
 
-/**
- * Member type ids whose numeric values need conversion for the shared output.
+/**
+ * Member type ids whose numeric values need conversion for the shared output.
  */
 const MEMBER_TYPES = Object.freeze({
   Real32: 10,
@@ -46,32 +46,32 @@ const INV255 = INV255_VALUE,
   INV127 = INV127_VALUE,
   INV32767 = INV32767_VALUE;
 
-/**
- * Node keys accepted by {@link projectShared}'s `options.classes` map.
- *
- * Each key names one shared projection node shape; the mapped constructor is
- * instantiated with `new` and populated with that node's usual fields instead
- * of a plain object literal.
+/**
+ * Node keys accepted by {@link projectShared}'s `options.classes` map.
+ *
+ * Each key names one shared projection node shape; the mapped constructor is
+ * instantiated with `new` and populated with that node's usual fields instead
+ * of a plain object literal.
  */
 const CLASS_KEYS = Object.freeze(["Root", "Mesh", "BoneBinding", "IndexGroup", "MorphTarget", "Model", "Skeleton", "Bone", "Animation", "TrackGroup", "TransformTrack", "VectorTrack", "Curve"]);
 
-/**
- * Constructors used to hydrate shared projection nodes as class instances.
- *
- * Every key is optional; node types with no matching constructor keep the
- * default plain-object shape. See {@link CLASS_KEYS} for valid keys.
- *
- * @typedef {{[key: string]: new () => object}} Gr2NodeClasses
+/**
+ * Constructors used to hydrate shared projection nodes as class instances.
+ *
+ * Every key is optional; node types with no matching constructor keep the
+ * default plain-object shape. See {@link CLASS_KEYS} for valid keys.
+ *
+ * @typedef {{[key: string]: new () => object}} Gr2NodeClasses
  */
 
-/**
- * Instantiate and populate a node class, or return the plain props unchanged.
- *
- * @param {Gr2NodeClasses} classes Opt-in node class map.
- * @param {string} key Node key to look up in `classes`.
- * @param {object} props Fields to populate onto the instance.
- * @returns {object} A populated class instance, or `props` when no
- * constructor is registered for `key`.
+/**
+ * Instantiate and populate a node class, or return the plain props unchanged.
+ *
+ * @param {Gr2NodeClasses} classes Opt-in node class map.
+ * @param {string} key Node key to look up in `classes`.
+ * @param {object} props Fields to populate onto the instance.
+ * @returns {object} A populated class instance, or `props` when no
+ * constructor is registered for `key`.
  */
 function build(classes, key, props, hydrationOptions = {}) {
   const Ctor = classes[key];
@@ -89,23 +89,23 @@ function populate(instance, props, hydrationOptions = {}) {
   return instance;
 }
 
-/**
- * Root object emitted in the shared GR2 shape.
- *
- * @typedef {object} Gr2SharedRoot
- * @property {number} grannyFileFormatRevision Granny file format revision.
- * @property {string} grannyFileSource Original source filename, or an empty string.
- * @property {object[]} meshes Mesh records with deinterleaved vertex channels.
- * @property {object[]} models Model records with skeleton and mesh bindings.
- * @property {object[]} animations Animation records and transform tracks.
+/**
+ * Root object emitted in the shared GR2 shape.
+ *
+ * @typedef {object} Gr2SharedRoot
+ * @property {number} grannyFileFormatRevision Granny file format revision.
+ * @property {string} grannyFileSource Original source filename, or an empty string.
+ * @property {object[]} meshes Mesh records with deinterleaved vertex channels.
+ * @property {object[]} models Model records with skeleton and mesh bindings.
+ * @property {object[]} animations Animation records and transform tracks.
  */
 
-/**
- * Convert a reflected numeric value to the shared float convention.
- *
- * @param {number} v Raw reflected numeric value.
- * @param {number} memberType Granny member type id.
- * @returns {number} Converted and float32-rounded value.
+/**
+ * Convert a reflected numeric value to the shared float convention.
+ *
+ * @param {number} v Raw reflected numeric value.
+ * @param {number} memberType Granny member type id.
+ * @returns {number} Converted and float32-rounded value.
  */
 function convert(v, memberType) {
   switch (memberType) {
@@ -122,26 +122,26 @@ function convert(v, memberType) {
   }
 }
 
-/**
- * Replace non-finite untyped numbers with zero.
- *
- * @param {number} v Candidate numeric value.
- * @returns {number} The original finite value, or zero.
+/**
+ * Replace non-finite untyped numbers with zero.
+ *
+ * @param {number} v Candidate numeric value.
+ * @returns {number} The original finite value, or zero.
  */
 function sf(v) {
   return Number.isFinite(v) ? v : 0;
 }
 
-/**
- * Copy and dequantize one vertex channel from reflected vertex objects.
- *
- * Missing Granny members return an empty channel.
- *
- * @param {object[]} vertices Reflected vertex array with non-enumerable type metadata.
- * @param {string} memberName Granny vertex member name to copy.
- * @param {number} destWidth Number of components in the emitted channel.
- * @param {boolean} [preserveWidth] Retain an authored three- or four-component width.
- * @returns {number[]} Flat deinterleaved channel values.
+/**
+ * Copy and dequantize one vertex channel from reflected vertex objects.
+ *
+ * Missing Granny members return an empty channel.
+ *
+ * @param {object[]} vertices Reflected vertex array with non-enumerable type metadata.
+ * @param {string} memberName Granny vertex member name to copy.
+ * @param {number} destWidth Number of components in the emitted channel.
+ * @param {boolean} [preserveWidth] Retain an authored three- or four-component width.
+ * @returns {number[]} Flat deinterleaved channel values.
  */
 function copyChannel(vertices, memberName, destWidth, preserveWidth = false) {
   const type = vertices.__type || [],
@@ -161,7 +161,7 @@ function copyChannel(vertices, memberName, destWidth, preserveWidth = false) {
   }
   return out;
 }
-const VERTEX_CHANNELS = Object.freeze([["position", "Position", 3], ["blendIndice", "BoneIndices", 4], ["tangent", "Tangent", 4, true], ["normal", "Normal", 3], ["texcoord0", "TextureCoordinates0", 2], ["texcoord1", "TextureCoordinates1", 2], ["binormal", "Binormal", 4, true], ["blendWeight", "BoneWeights", 4]]);
+const VERTEX_CHANNELS = Object.freeze([["position", "Position", 3, true], ["blendIndice", "BoneIndices", 4], ["tangent", "Tangent", 4, true], ["normal", "Normal", 3], ["texcoord0", "TextureCoordinates0", 2, true], ["texcoord1", "TextureCoordinates1", 2, true], ["binormal", "Binormal", 4, true], ["blendWeight", "BoneWeights", 4]]);
 function emitVertexChannels(vertices) {
   const channels = {};
   for (const [name, memberName, width, preserveWidth] of VERTEX_CHANNELS) {
@@ -170,11 +170,11 @@ function emitVertexChannels(vertices) {
   return channels;
 }
 
-/**
- * Flatten reflected scalar-array wrappers into plain JavaScript values.
- *
- * @param {ArrayLike<any>} a Reflected scalar array or already-flat array.
- * @returns {any[]} Plain scalar values.
+/**
+ * Flatten reflected scalar-array wrappers into plain JavaScript values.
+ *
+ * @param {ArrayLike<any>} a Reflected scalar array or already-flat array.
+ * @returns {any[]} Plain scalar values.
  */
 function scalarArray(a) {
   if (!a || !a.length) return [];
@@ -185,8 +185,8 @@ function scalarArray(a) {
   return a;
 }
 
-/**
- * Granny curve format ids emitted by the shared curve projector.
+/**
+ * Granny curve format ids emitted by the shared curve projector.
  */
 const CURVE_FORMATS = Object.freeze({
   DaKeyframes32f: 0,
@@ -211,11 +211,11 @@ const CURVE_FORMATS = Object.freeze({
 });
 const F = CURVE_FORMATS;
 
-/**
- * Locate the inline curve-data header inside a reflected curve-data object.
- *
- * @param {object} cd Reflected Granny curve-data object.
- * @returns {{Format: number, Degree: number}|null} Header object when present.
+/**
+ * Locate the inline curve-data header inside a reflected curve-data object.
+ *
+ * @param {object} cd Reflected Granny curve-data object.
+ * @returns {{Format: number, Degree: number}|null} Header object when present.
  */
 function curveHeader(cd) {
   for (const k of Object.keys(cd)) {
@@ -224,13 +224,13 @@ function curveHeader(cd) {
   return null;
 }
 
-/**
- * Convert a reflected scalar array to float32-rounded finite numbers.
- *
- * @param {ArrayLike<any>} a Reflected scalar array.
- * @param {number[]} [fallback] Semantic values used cyclically for non-finite
- *   components; defaults to zero for untyped data.
- * @returns {number[]} Float array.
+/**
+ * Convert a reflected scalar array to float32-rounded finite numbers.
+ *
+ * @param {ArrayLike<any>} a Reflected scalar array.
+ * @param {number[]} [fallback] Semantic values used cyclically for non-finite
+ *   components; defaults to zero for untyped data.
+ * @returns {number[]} Float array.
  */
 function farr(a, fallback = null) {
   return scalarArray(a).map((x, index) => {
@@ -239,22 +239,22 @@ function farr(a, fallback = null) {
   });
 }
 
-/**
- * Convert a reflected scalar array to unsigned 32-bit integer values.
- *
- * @param {ArrayLike<any>} a Reflected scalar array.
- * @returns {number[]} Unsigned integer array.
+/**
+ * Convert a reflected scalar array to unsigned 32-bit integer values.
+ *
+ * @param {ArrayLike<any>} a Reflected scalar array.
+ * @returns {number[]} Unsigned integer array.
  */
 function uarr(a) {
   return scalarArray(a).map(x => x >>> 0);
 }
 
-/**
- * Project one Granny Curve2 object into shared form.
- *
- * @param {object} curve2 Reflected Granny curve object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Compact curve record with format-specific fields.
+/**
+ * Project one Granny Curve2 object into shared form.
+ *
+ * @param {object} curve2 Reflected Granny curve object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Compact curve record with format-specific fields.
  */
 function emitCurve(curve2, classes = {}, controlFallback = [0]) {
   const cd = curve2 && curve2.CurveData;
@@ -334,11 +334,11 @@ function emitCurve(curve2, classes = {}, controlFallback = [0]) {
   return build(classes, "Curve", o);
 }
 
-/**
- * Convert arbitrary reflected variant data to JSON-safe plain values.
- *
- * @param {any} v Reflected variant value.
- * @returns {JsonValue} JSON-compatible value.
+/**
+ * Convert arbitrary reflected variant data to JSON-safe plain values.
+ *
+ * @param {any} v Reflected variant value.
+ * @returns {JsonValue} JSON-compatible value.
  */
 function emitVariant(v) {
   if (v === null || v === undefined) return null;
@@ -354,12 +354,12 @@ function emitVariant(v) {
   return v;
 }
 
-/**
- * Attach converted extended data when the reflected variant is present.
- *
- * @param {object} target Projected GR2 object to mutate.
- * @param {object|null|undefined} ext Reflected extended-data variant.
- * @returns {void}
+/**
+ * Attach converted extended data when the reflected variant is present.
+ *
+ * @param {object} target Projected GR2 object to mutate.
+ * @param {object|null|undefined} ext Reflected extended-data variant.
+ * @returns {void}
  */
 function addExtendedData(target, ext) {
   if (ext !== null && ext !== undefined && typeof ext === "object") {
@@ -367,15 +367,15 @@ function addExtendedData(target, ext) {
   }
 }
 
-/**
- * Project one reflected Granny morph target (blend shape).
- *
- * Morph target vertex data uses the same deinterleaved channel layout as a
- * mesh's primary vertex data.
- *
- * @param {object} mt Reflected Granny `granny_morph_target` object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted morph-target record.
+/**
+ * Project one reflected Granny morph target (blend shape).
+ *
+ * Morph target vertex data uses the same deinterleaved channel layout as a
+ * mesh's primary vertex data.
+ *
+ * @param {object} mt Reflected Granny `granny_morph_target` object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted morph-target record.
  */
 function emitMorphTarget(mt, classes = {}) {
   const vd = mt.VertexData,
@@ -430,12 +430,12 @@ function emitVertexAnnotationTarget(set, vertexCount, classes = {}) {
   return build(classes, "MorphTarget", target);
 }
 
-/**
- * Project a reflected Granny mesh.
- *
- * @param {object} mesh Reflected Granny mesh object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted mesh record.
+/**
+ * Project a reflected Granny mesh.
+ *
+ * @param {object} mesh Reflected Granny mesh object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted mesh record.
  */
 function emitMesh(mesh, classes = {}, rebuildMissingBounds = false) {
   const o = {};
@@ -458,6 +458,10 @@ function emitMesh(mesh, classes = {}, rebuildMissingBounds = false) {
   const vd = mesh.PrimaryVertexData,
     verts = vd && vd.Vertices || [];
   o.vertex = emitVertexChannels(verts);
+  // Traffic instance meshes store path IDs in Position.w and animation
+  // controls in four-wide texture coordinates. Preserve the authored stream
+  // width; its vertex count cannot be inferred by dividing positions by three.
+  if (verts.length && o.vertex.position.length !== verts.length * 3) o.vertexCount = verts.length;
   o.morphTargets = (mesh.MorphTargets || []).map(mt => emitMorphTarget(mt, classes));
   o.morphTargets.push(...(vd?.VertexAnnotationSets || []).map(set => emitVertexAnnotationTarget(set, verts.length, classes)).filter(Boolean));
   const topo = mesh.PrimaryTopology || {},
@@ -488,7 +492,7 @@ function emitMesh(mesh, classes = {}, rebuildMissingBounds = false) {
         faces
       };
       if (rebuildMissingBounds) {
-        const bounds = boundsFromFaces(o.vertex.position, faces);
+        const bounds = boundsFromFaces(o.vertex.position, faces, o.vertex.position.length / verts.length);
         if (bounds) {
           group.minBounds = bounds.min;
           group.maxBounds = bounds.max;
@@ -515,19 +519,19 @@ function emitMesh(mesh, classes = {}, rebuildMissingBounds = false) {
   return build(classes, "Mesh", o);
 }
 
-/**
- * Axis-aligned bounds of the positions a face list references.
- *
- * @param {number[]} positions Flat xyz position channel.
- * @param {number[]} faces Vertex indices.
- * @returns {{min: number[], max: number[]}|null} Bounds, or null without data.
+/**
+ * Axis-aligned bounds of the positions a face list references.
+ *
+ * @param {number[]} positions Flat xyz position channel.
+ * @param {number[]} faces Vertex indices.
+ * @returns {{min: number[], max: number[]}|null} Bounds, or null without data.
  */
-function boundsFromFaces(positions, faces) {
+function boundsFromFaces(positions, faces, width = 3) {
   if (!positions || !positions.length || !faces.length) return null;
   const min = [Infinity, Infinity, Infinity],
     max = [-Infinity, -Infinity, -Infinity];
   for (let i = 0; i < faces.length; i++) {
-    const base = faces[i] * 3;
+    const base = faces[i] * width;
     for (let k = 0; k < 3; k++) {
       const v = positions[base + k];
       if (v < min[k]) min[k] = v;
@@ -540,12 +544,12 @@ function boundsFromFaces(positions, faces) {
   } : null;
 }
 
-/**
- * Project a reflected Granny skeleton bone.
- *
- * @param {object} bone Reflected Granny bone object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted bone record.
+/**
+ * Project a reflected Granny skeleton bone.
+ *
+ * @param {object} bone Reflected Granny bone object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted bone record.
  */
 function emitBone(bone, classes = {}) {
   const t = bone.LocalTransform || bone.Transform || {
@@ -565,12 +569,12 @@ function emitBone(bone, classes = {}) {
   return build(classes, "Bone", o);
 }
 
-/**
- * Project a reflected Granny skeleton.
- *
- * @param {object|null} skel Reflected Granny skeleton object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted skeleton record.
+/**
+ * Project a reflected Granny skeleton.
+ *
+ * @param {object|null} skel Reflected Granny skeleton object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted skeleton record.
  */
 function emitSkeleton(skel, classes = {}) {
   const o = {};
@@ -580,14 +584,14 @@ function emitSkeleton(skel, classes = {}) {
   return build(classes, "Skeleton", o);
 }
 
-/**
- * Project a reflected Granny model.
- *
- * @param {object} model Reflected Granny model object.
- * @param {object} fileInfo Root reflected Granny file-info object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @param {WeakMap<object, object>} [skeletonCache] Emitted skeleton identity cache.
- * @returns {object} Emitted model record.
+/**
+ * Project a reflected Granny model.
+ *
+ * @param {object} model Reflected Granny model object.
+ * @param {object} fileInfo Root reflected Granny file-info object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @param {WeakMap<object, object>} [skeletonCache] Emitted skeleton identity cache.
+ * @returns {object} Emitted model record.
  */
 function emitModel(model, fileInfo, classes = {}, skeletonCache = new WeakMap()) {
   const o = {};
@@ -607,12 +611,12 @@ function emitModel(model, fileInfo, classes = {}, skeletonCache = new WeakMap())
   return build(classes, "Model", o);
 }
 
-/**
- * Project a reflected Granny transform track.
- *
- * @param {object} tt Reflected Granny transform-track object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted transform-track record.
+/**
+ * Project a reflected Granny transform track.
+ *
+ * @param {object} tt Reflected Granny transform-track object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted transform-track record.
  */
 function emitTransformTrack(tt, classes = {}) {
   // Neither runtime transform consumers nor JSON can use Granny's non-finite
@@ -628,12 +632,12 @@ function emitTransformTrack(tt, classes = {}) {
   });
 }
 
-/**
- * Project a reflected Granny vector track.
- *
- * @param {object} vt Reflected Granny vector-track object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted vector-track record.
+/**
+ * Project a reflected Granny vector track.
+ *
+ * @param {object} vt Reflected Granny vector-track object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted vector-track record.
  */
 function emitVectorTrack(vt, classes = {}) {
   return build(classes, "VectorTrack", {
@@ -643,12 +647,12 @@ function emitVectorTrack(vt, classes = {}) {
   });
 }
 
-/**
- * Project a reflected Granny track group.
- *
- * @param {object} tg Reflected Granny track-group object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted track-group record.
+/**
+ * Project a reflected Granny track group.
+ *
+ * @param {object} tg Reflected Granny track-group object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted track-group record.
  */
 function emitTrackGroup(tg, classes = {}) {
   return build(classes, "TrackGroup", {
@@ -658,12 +662,12 @@ function emitTrackGroup(tg, classes = {}) {
   });
 }
 
-/**
- * Project a reflected Granny animation.
- *
- * @param {object} anim Reflected Granny animation object.
- * @param {Gr2NodeClasses} [classes] Opt-in node class map.
- * @returns {object} Emitted animation record.
+/**
+ * Project a reflected Granny animation.
+ *
+ * @param {object} anim Reflected Granny animation object.
+ * @param {Gr2NodeClasses} [classes] Opt-in node class map.
+ * @returns {object} Emitted animation record.
  */
 function emitAnimation(anim, classes = {}) {
   const o = {};
@@ -678,23 +682,23 @@ function emitAnimation(anim, classes = {}) {
   return build(classes, "Animation", o);
 }
 
-/**
- * Convert a reflected `granny_file_info` graph into the shared GR2 projection.
- *
- * The key order and numeric conversion rules are stable so downstream tools can
- * compare emitted data.
- *
- * When `options.classes` is given, matching node types are instantiated and
- * populated as class instances instead of plain object literals; an opt-in
- * alternative to walking the returned projection into application-specific
- * classes by hand. See {@link CLASS_KEYS} for the recognized keys.
- *
- * @param {object} fileInfo Reflected `granny_file_info` object from `reader.js`.
- * @param {number} version Granny file format revision.
- * @param {object} [options] Emission options.
- * @param {Gr2NodeClasses} [options.classes] Opt-in node class map.
- * @returns {Gr2SharedRoot} Plain shared projection, or a
- * populated `classes.Root` instance when provided.
+/**
+ * Convert a reflected `granny_file_info` graph into the shared GR2 projection.
+ *
+ * The key order and numeric conversion rules are stable so downstream tools can
+ * compare emitted data.
+ *
+ * When `options.classes` is given, matching node types are instantiated and
+ * populated as class instances instead of plain object literals; an opt-in
+ * alternative to walking the returned projection into application-specific
+ * classes by hand. See {@link CLASS_KEYS} for the recognized keys.
+ *
+ * @param {object} fileInfo Reflected `granny_file_info` object from `reader.js`.
+ * @param {number} version Granny file format revision.
+ * @param {object} [options] Emission options.
+ * @param {Gr2NodeClasses} [options.classes] Opt-in node class map.
+ * @returns {Gr2SharedRoot} Plain shared projection, or a
+ * populated `classes.Root` instance when provided.
  */
 function projectShared(fileInfo, version, options = {}) {
   const {