roavatar-renderer 1.4.0 → 1.4.2

package/dist/index.js

@@ -29514,6 +29514,7 @@ const FLAGS = {
   ROAVATAR_TRYON_PLACE: 135979364355750,
   ASSETDELIVERY_V2: true,
   ASSET_REQUEST_PRIORITY: "high",
+  API_DOMAIN: "roblox.com",
   //assets
   ONLINE_ASSETS: false,
   ASSETS_PATH: "../assets/rbxasset/",
@@ -29630,10 +29631,19 @@ class InstanceWrapper {
     log(false, "Registered InstanceWrapper:", ClassNameToWrapper);
   }
   //virtual functions
+  /**
+   * @virtual
+   */
   created() {
   }
+  /**
+   * @virtual
+   */
   destroy() {
   }
+  /**
+   * @virtual
+   */
   preRender() {
   }
 }
@@ -29764,6 +29774,9 @@ class Color3 {
   clone() {
     return new Color3(this.R, this.G, this.B);
   }
+  isSame(other) {
+    return this.R === other.R && this.G === other.G && this.B === other.B;
+  }
   toColor3uint8() {
     return new Color3uint8(Math.round(this.R * 255), Math.round(this.G * 255), Math.round(this.B * 255));
   }
@@ -29808,6 +29821,9 @@ class NumberSequenceKeypoint {
   clone() {
     return new NumberSequenceKeypoint(this.time, this.value, this.envelope);
   }
+  isSame(other) {
+    return this.time === other.time && this.value === other.value && this.envelope === other.envelope;
+  }
 }
 class NumberSequence {
   keypoints = [];
@@ -29821,6 +29837,13 @@ class NumberSequence {
     }
     return copy;
   }
+  isSame(other) {
+    if (this.keypoints.length !== other.keypoints.length) return false;
+    for (let i = 0; i < this.keypoints.length; i++) {
+      if (!this.keypoints[i].isSame(other.keypoints[i])) return false;
+    }
+    return true;
+  }
   getLowerKey(time2) {
     let resultKey = null;
     for (const key of this.keypoints) {
@@ -29876,6 +29899,9 @@ class ColorSequenceKeypoint {
   clone() {
     return new ColorSequenceKeypoint(this.time, this.value.R, this.value.G, this.value.B);
   }
+  isSame(other) {
+    return this.time === other.time && this.value.isSame(other.value);
+  }
 }
 class ColorSequence {
   keypoints = [];
@@ -29891,6 +29917,13 @@ class ColorSequence {
     }
     return copy;
   }
+  isSame(other) {
+    if (this.keypoints.length !== other.keypoints.length) return false;
+    for (let i = 0; i < this.keypoints.length; i++) {
+      if (!this.keypoints[i].isSame(other.keypoints[i])) return false;
+    }
+    return true;
+  }
   getLowerKey(time2) {
     let resultKey = null;
     for (const key of this.keypoints) {
@@ -30078,17 +30111,23 @@ let lastInstanceId = 0;
 const AllInstances = [];
 class Instance {
   _id;
+  /**
+   * @deprecated Use .Prop("Name") instead
+   */
   _name;
   //USED TO MAKE VIEWING EASIER
   className;
+  /**
+   * @deprecated Do not use this directly
+   */
   _properties = /* @__PURE__ */ new Map();
   _referencedBy = [];
   _connectionReferences = [];
-  children = [];
+  _children = [];
   parent = void 0;
   destroyed = false;
-  hasWrappered = false;
-  canGC = true;
+  _hasWrappered = false;
+  //private _canGC: boolean = true
   classID;
   //dont use this to identify instance class, it is only used during file loading
   objectFormat;
@@ -30123,8 +30162,8 @@ class Instance {
   }
   createWrapper() {
     const wrapper = GetWrapperForInstance(this);
-    if (wrapper && !this.hasWrappered) {
-      this.hasWrappered = true;
+    if (wrapper && !this._hasWrappered) {
+      this._hasWrappered = true;
       wrapper.created();
     }
   }
@@ -30242,6 +30281,13 @@ class Instance {
     name = this.fixPropertyName(name);
     return !!this._properties.get(name);
   }
+  /**
+   * Returns the value of a property
+   * @param name Name of property
+   * @returns Property's value
+   * 
+   * @throws When property doesn't exist, PropOrDefault is a safer alternative
+   */
   Property(name) {
     let property = this._properties.get(name);
     if (property) return property.value;
@@ -30285,6 +30331,13 @@ class Instance {
       throw new Error(`Property: ${name} does not exist`);
     }
   }
+  /**
+   * Returns the value of a property
+   * @param name Name of property
+   * @returns Property's value
+   * 
+   * @throws When property doesn't exist, PropOrDefault is a safer alternative
+   */
   Prop(name) {
     return this.Property(name);
   }
@@ -30305,9 +30358,9 @@ class Instance {
       throw new Error("Cannot set parent of instance to a destroyed instance");
     }
     if (this.parent) {
-      const index = this.parent.children.indexOf(this);
+      const index = this.parent._children.indexOf(this);
       if (index !== -1) {
-        this.parent.children.splice(index, 1);
+        this.parent._children.splice(index, 1);
       }
     }
     const originalParent = this.parent;
@@ -30316,7 +30369,7 @@ class Instance {
       originalParent.ChildRemoved.Fire(this);
     }
     if (instance) {
-      instance.children.push(this);
+      instance._children.push(this);
     }
     if (fireEvents) {
       if (instance) {
@@ -30373,7 +30426,7 @@ class Instance {
   }
   GetChildren() {
     const childrenList = [];
-    for (const child of this.children) {
+    for (const child of this._children) {
       childrenList.push(child);
     }
     return childrenList;
@@ -30403,7 +30456,7 @@ class Instance {
     return this.FindFirstChild(name);
   }
   FindFirstChildOfClass(className) {
-    for (const child of this.children) {
+    for (const child of this._children) {
       if (child.className === className) {
         return child;
       }
@@ -30411,7 +30464,7 @@ class Instance {
   }
   FindLastChildOfClass(className) {
     let lastChild = void 0;
-    for (const child of this.children) {
+    for (const child of this._children) {
       if (child.className === className) {
         lastChild = child;
       }
@@ -30527,7 +30580,7 @@ class RBX {
   treeGenerated = false;
   xmlString;
   get instances() {
-    return this.dataModel.children;
+    return this.dataModel.GetChildren();
   }
   constructor() {
     this.reset();
@@ -31421,6 +31474,10 @@ class RBX {
     }
     return buffer2;
   }
+  /**
+   * Generates if needed hierarchy and returns root instance
+   * @returns Root instance
+   */
   generateTree() {
     if (this.treeGenerated) {
       warn(false, "Tree already generated");
@@ -32722,6 +32779,10 @@ class Outfit {
     }
     return issues;
   }
+  /**
+   * @deprecated Outdated
+   * @returns 
+   */
   async toHumanoidDescription() {
     const response = await fetch("/assets/HumanoidDescriptionTemplate.xml");
     if (response.status !== 200)
@@ -32876,10 +32937,12 @@ class Outfit {
     return HumanoidDescription;
   }
   //TODO: Implement
+  /** @deprecated */
   async fromHumanoidDescription(rootDocument) {
     const humanoidDescription = rootDocument.querySelector(".HumanoidDescription");
     log(false, humanoidDescription);
   }
+  /** @deprecated */
   async downloadHumanoidDescription() {
     const humanoidDescription = await this.toHumanoidDescription();
     if (humanoidDescription) {
@@ -33022,6 +33085,9 @@ class Outfit {
     asset.assetType.name = typeName;
     this.assets.push(asset);
   }
+  /**
+   * Fixes multiple layered assets having the same order value
+   */
   fixOrders() {
     for (const asset of this.assets.slice().reverse()) {
       if (!AccessoryAssetTypes.includes(asset.assetType.name) && LayeredAssetTypes.includes(asset.assetType.name)) {
@@ -35133,6 +35199,9 @@ class Authentication {
   }
 }
 async function RBLXPost(url, auth, body, attempt = 0, method = "POST") {
+  if (url.match(/https?:\/\/[a-z]+.roblox.com/)) {
+    url = url.replace("roblox.com", FLAGS.API_DOMAIN);
+  }
   if (typeof body !== "string") {
     body = JSON.stringify(body);
   }
@@ -35179,6 +35248,9 @@ async function RBLXPost(url, auth, body, attempt = 0, method = "POST") {
   });
 }
 async function RBLXGet(url, headers, includeCredentials = true) {
+  if (url.match(/https?:\/\/[a-z]+.roblox.com/)) {
+    url = url.replace("roblox.com", FLAGS.API_DOMAIN);
+  }
   return new Promise((resolve) => {
     let newHeaders = {
       "Content-Type": "application/json"
@@ -36374,6 +36446,16 @@ class RBFDeformerPatch {
   // avoid matrix from being singular
   affectBones = true;
   id = rbfDeformerIdCount++;
+  /**
+   * Creates the deformer and prepares for deformation
+   * @param refMesh The reference cage
+   * @param distMesh The destination cage
+   * @param mesh The mesh to deform
+   * @param ignoredIndices Indices in the reference cage to ignore
+   * @param patchCount Amount of patches spread around the mesh, each one solves a linear equation
+   * @param detailsCount Amount of close vertices in each patch
+   * @param importantsCount Amount of far away vertices in each patch
+   */
   constructor(refMesh, distMesh, mesh, ignoredIndices = [], patchCount = FLAGS.RBF_PATCH_COUNT, detailsCount = FLAGS.RBF_PATCH_DETAIL_SAMPLES, importantsCount = FLAGS.RBF_PATCH_SHAPE_SAMPLES) {
     time(`RBFDeformerPatch.constructor.${this.id}`);
     this.mesh = mesh;
@@ -36423,6 +36505,10 @@ class RBFDeformerPatch {
     this.patchCount = patchCount;
     timeEnd(`RBFDeformerPatch.constructor.${this.id}`);
   }
+  /**
+   * Solves the linear equations asynchronously, required before deformation
+   * @returns void
+   */
   async solveAsync() {
     if (this.refVerts.length === 0) {
       return;
@@ -36448,6 +36534,12 @@ class RBFDeformerPatch {
     this.nearestPatch = new Uint16Array(nearestPatchBuf);
     timeEnd(`RBFDeformerPatch.solveAsync.unpack.${this.id}`);
   }
+  /**
+   * solveAsync() needs to be called before this
+   * Deforms the position of something inside the mesh
+   * @param i The index of the vert to deform, if it is outside the range of vertices it will be a bone instead. For example vertices range from 1 - 100, and bones range from 101 - 110. Then index 101 will represent the first bone
+   * @returns New position after deformation
+   */
   deform(i) {
     if (!this.nearestPatch || !this.neighborIndices || !this.weights) {
       throw new Error("RBF has not been solved");
@@ -36471,6 +36563,10 @@ class RBFDeformerPatch {
     }
     return add(vec, [dx, dy, dz]);
   }
+  /**
+   * solveAsync() needs to be called before this
+   * Deforms vertices and bones in mesh (if this.affectBones = true)
+   */
   deformMesh() {
     if (this.refVerts.length === 0) {
       return;
@@ -44926,6 +45022,12 @@ class RenderDesc extends DisposableDesc {
     }
     this.virtualFromRenderDesc(other);
   }
+  transferFrom(other) {
+    this.virtualTransferFrom(other);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  virtualTransferFrom(_other) {
+  }
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   virtualFromRenderDesc(_other) {
     throw new Error("Virtual method virtualFromRenderDesc called");
@@ -45331,7 +45433,6 @@ class EmitterDesc extends DisposableDesc {
   passedTime = 0;
   lockedToPart = false;
   lifetime = new NumberRange(1, 1);
-  rate = 10;
   spreadAngle = new Vector22(0, 0);
   speed = new NumberRange(1, 1);
   rotation = new NumberRange(0, 0);
@@ -45344,9 +45445,6 @@ class EmitterDesc extends DisposableDesc {
   zOffset = 0;
   offset = new Vector32();
   shapeInOut = 0;
-  colorTexture;
-  alphaTexture;
-  texture;
   opacity = 1;
   lightEmission = 1;
   blending = AdditiveBlending;
@@ -45354,16 +45452,52 @@ class EmitterDesc extends DisposableDesc {
   size = new NumberSequence();
   transparency = new NumberSequence([new NumberSequenceKeypoint(0, 0, 0)]);
   normalizeSizeKeypointTime = true;
+  //requires recompilation
+  rate = 10;
+  colorTexture;
+  alphaTexture;
+  texture;
+  //results
   instanceOpacityBuffer;
   instanceColorBuffer;
   instanceSeedTimeBuffer;
   result;
   particles = [];
+  initialParticleCount = 0;
   get maxCount() {
-    return Math.max(Math.ceil(this.lifetime.Max * this.rate) * 2, 1);
+    const calculatedMax = Math.max(Math.ceil(this.lifetime.Max * this.rate) * 2, 1);
+    const particleMax = this.initialParticleCount + calculatedMax;
+    return particleMax;
+  }
+  needsRegeneration(other) {
+    return this.texture === other.texture && this.alphaTexture === other.alphaTexture && this.colorTexture === other.colorTexture && this.rate === other.rate;
   }
   isSame(other) {
-    return this.lifetime.isSame(other.lifetime) && this.rate === other.rate && this.texture === other.texture;
+    return !this.needsRegeneration(other) && this.lockedToPart === other.lockedToPart && this.lifetime.isSame(other.lifetime) && this.spreadAngle.isSame(other.spreadAngle) && this.speed.isSame(other.speed) && this.rotation.isSame(other.rotation) && this.rotationSpeed.isSame(other.rotationSpeed) && this.localAcceleration.isSame(other.localAcceleration) && this.acceleration.isSame(other.acceleration) && this.drag === other.drag && this.timeScale === other.timeScale && this.orientation === other.orientation && this.zOffset === other.zOffset && this.offset.isSame(other.offset) && this.shapeInOut === other.shapeInOut && this.opacity === other.opacity && this.lightEmission === other.lightEmission && this.blending === other.blending && this.color.isSame(other.color) && this.size.isSame(other.size) && this.transparency.isSame(other.transparency) && this.normalizeSizeKeypointTime === other.normalizeSizeKeypointTime;
+  }
+  fromEmitterDesc(other) {
+    this.lockedToPart = other.lockedToPart;
+    this.lifetime = other.lifetime.clone();
+    this.rate = other.rate;
+    this.spreadAngle = other.spreadAngle.clone();
+    this.speed = other.speed.clone();
+    this.rotation = other.rotation.clone();
+    this.rotationSpeed = other.rotationSpeed.clone();
+    this.localAcceleration = other.localAcceleration.clone();
+    this.acceleration = other.acceleration.clone();
+    this.drag = other.drag;
+    this.timeScale = other.timeScale;
+    this.orientation = other.orientation;
+    this.zOffset = other.zOffset;
+    this.offset = other.offset.clone();
+    this.shapeInOut = other.shapeInOut;
+    this.opacity = other.opacity;
+    this.lightEmission = other.lightEmission;
+    this.blending = other.blending;
+    this.color = other.color.clone();
+    this.size = other.size.clone();
+    this.transparency = other.transparency.clone();
+    this.normalizeSizeKeypointTime = other.normalizeSizeKeypointTime;
   }
   dispose(renderer, scene) {
     const mesh = this.result;
@@ -45589,17 +45723,14 @@ class EmitterGroupDesc extends RenderDesc {
     if (this.needsRegeneration(other)) {
       return false;
     }
-    if (this.time !== other.time) {
-      return false;
-    }
-    return true;
+    return this.time === other.time;
   }
   needsRegeneration(other) {
     if (this.emitterDescs.length !== other.emitterDescs.length) {
       return true;
     }
     for (let i = 0; i < this.emitterDescs.length; i++) {
-      if (!this.emitterDescs[i].isSame(other.emitterDescs[i])) {
+      if (!this.emitterDescs[i].needsRegeneration(other.emitterDescs[i])) {
         return true;
       }
     }
@@ -45611,6 +45742,17 @@ class EmitterGroupDesc extends RenderDesc {
     this.lowerBound = other.lowerBound;
     this.higherBound = other.higherBound;
     this.emitterDir = other.emitterDir;
+    for (let i = 0; i < this.emitterDescs.length; i++) {
+      this.emitterDescs[i].fromEmitterDesc(other.emitterDescs[i]);
+    }
+  }
+  virtualTransferFrom(other) {
+    if (this.emitterDescs.length === other.emitterDescs.length) {
+      for (let i = 0; i < this.emitterDescs.length; i++) {
+        this.emitterDescs[i].particles = other.emitterDescs[i].particles;
+        this.emitterDescs[i].initialParticleCount = this.emitterDescs[i].particles.length;
+      }
+    }
   }
   fromInstance(child) {
     this.instance = child;
@@ -46897,6 +47039,11 @@ class AnimatorWrapper extends InstanceWrapper {
       this._switchToolAnimation(this.data.currentToolAnimation);
     }
   }
+  /**
+   * Resets all joints in the rig to be in their rest pose
+   * @param includeMotors If motors (body movement joints) should be set to rest pose
+   * @param includeFACS If FACS (face movement bones) should be set to rest pose
+   */
   restPose(includeMotors = true, includeFACS = true) {
     const rig = this.instance.parent?.parent;
     if (!rig) {
@@ -46916,6 +47063,12 @@ class AnimatorWrapper extends InstanceWrapper {
       }
     }
   }
+  /**
+   * Renders animation pose
+   * @param addTime Time to add to the current time
+   * @param forceTime Time to force animation to be at, -1 is in the middle of the animation
+   * @param forceKeyframe Keyframe to force animation to be at
+   */
   renderAnimation(addTime = 1 / 60, forceTime, forceKeyframe) {
     const humanoid = this.instance.parent;
     if (!humanoid) {
@@ -46988,11 +47141,22 @@ class AnimatorWrapper extends InstanceWrapper {
       }
     }
   }
+  /**
+   * 
+   * @returns Currently playing animation track
+   */
   getCurrentAnimationTrack() {
     if (this.data.currentAnimationTrack) {
       return this.data.currentAnimationTrack;
     }
   }
+  /**
+   * Loads a new animation
+   * @param id 
+   * @param isEmote 
+   * @param forceLoop Forces animation track to loop
+   * @returns undefined on success
+   */
   async loadAvatarAnimation(id, isEmote = false, forceLoop = false) {
     const humanoid = this.instance.parent;
     if (!humanoid) {
@@ -47103,6 +47267,12 @@ class AnimatorWrapper extends InstanceWrapper {
       }
     }
   }
+  /**
+   * Switches to new animation
+   * @param name Animation name, such as "idle", "walk" or "emote.1234"
+   * @param type 
+   * @returns If animation sucessfully played
+   */
   playAnimation(name, type = "main") {
     const humanoid = this.instance.parent;
     if (!humanoid) {
@@ -47753,6 +47923,11 @@ class HumanoidDescriptionWrapper extends InstanceWrapper {
       return void 0;
     }
   }
+  /**
+   * Update the data of the HumanoidDescription to match that inside an Outfit
+   * @param outfit 
+   * @returns HumanoidDescription or Response if it fails
+   */
   async fromOutfit(outfit) {
     this.instance.setProperty("BodyTypeScale", outfit.scale.bodyType);
     this.instance.setProperty("ProportionScale", outfit.scale.proportion);
@@ -49161,14 +49336,17 @@ class RBXRendererScene {
   ambientLight;
   directionalLight;
   directionalLight2;
+  /** Forces viewport to be within bounds */
   setRect(bounds) {
     this.viewport = [bounds.left, window.innerHeight - bounds.bottom, bounds.width, bounds.height];
     this.scissor = [...this.viewport];
   }
+  /** Makes viewport size 0x0, invisible */
   noRect() {
     this.viewport = [0, 0, 0, 0];
     this.scissor = [0, 0, 0, 0];
   }
+  /** Destroys all renderDescs but does not call Destroy on instances */
   destroy() {
     if (this.destroyed) return;
     this.destroyed = true;
@@ -49185,6 +49363,12 @@ class RBXRendererScene {
       this.shadowPlane = void 0;
     }
   }
+  /**
+   * Exports scene as a GLTF or GLB
+   * @param name Name of the resulting file if autoDownload is true
+   * @param autoDownload If resulting file should be auto downloaded
+   * @returns The GLB (buffer) or GLTF (object)
+   */
   async exportGLTF(name = "scene", autoDownload = true) {
     return new Promise((resolve, reject) => {
       const exporter = new GLTFExporter();
@@ -49667,6 +49851,7 @@ class RBXRenderer {
       }
     } else {
       if (!renderScene.isRenderingMesh.get(instance)) {
+        if (oldDesc) newDesc.transferFrom(oldDesc);
         newDesc.results = oldDesc?.results;
         renderScene.renderDescs.set(instance, newDesc);
         renderScene.isRenderingMesh.set(instance, true);
@@ -49793,6 +49978,9 @@ class RBXRenderer {
   static getRendererControls() {
     return RBXRenderer.controls;
   }
+  /**
+   * @returns ThreeJS renderer
+   */
   static getRenderer() {
     return RBXRenderer.renderer;
   }
@@ -49800,7 +49988,8 @@ class RBXRenderer {
   static getScene() {
     return RBXRenderer.scene;
   }
-  /**@deprecated
+  /**
+   * @deprecated Superseded by RBXRendererScene.exportGLTF()
    * This function is unstable and can throw errors, but might work
    */
   static exportScene(renderScene = RBXRenderer.firstScene) {
@@ -50096,6 +50285,7 @@ class OutfitRenderer {
   currentlyChangingRig = false;
   currentlyUpdating = false;
   hasNewUpdate = false;
+  _queuedMainAnimation;
   lastFrameTime = Date.now() / 100;
   animationInterval;
   animationFPS = 60;
@@ -50162,6 +50352,10 @@ class OutfitRenderer {
         const humanoid = this.currentRig.FindFirstChildOfClass("Humanoid");
         if (humanoid) {
           hrpWrapper.applyDescription(humanoid).then((result) => {
+            if (this._queuedMainAnimation) {
+              this.setMainAnimation(this._queuedMainAnimation);
+              this._queuedMainAnimation = void 0;
+            }
             this.currentlyUpdating = false;
             if (this.currentRig) {
               RBXRenderer.addInstance(this.currentRig, this.auth, this.renderScene);
@@ -50268,6 +50462,8 @@ class OutfitRenderer {
           }
         }
       }
+    } else {
+      this._queuedMainAnimation = name;
     }
   }
 }
@@ -50463,10 +50659,12 @@ export {
   FindFirstMatchingAttachment,
   FullBodyColors,
   GetAttachedPart,
+  GetWrapperForInstance,
   HSR,
   HumanoidDescriptionWrapper,
   HumanoidRigType,
   Instance,
+  InstanceWrapper,
   ItemInfo,
   ItemSort,
   LayeredAssetTypes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roavatar-renderer",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "A renderer for Roblox avatars, used by the RoAvatar extension.",
   "author": "steinan",
   "type": "module",
@@ -46,6 +46,7 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
+    "typedoc": "^0.28.19",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.45.0",
     "vite": "^7.1.7",