roavatar-renderer 1.4.1 → 1.4.2

package/dist/index.d.ts

@@ -213,10 +213,38 @@ export declare class AnimatorWrapper extends InstanceWrapper {
     private _switchToolAnimation;
     isValidTrackForSet(track: AnimationTrack, name: string): boolean;
     private _fixUnloaded;
+    /**
+     * 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?: boolean, includeFACS?: boolean): void;
+    /**
+     * 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?: number, forceTime?: number, forceKeyframe?: number): void;
+    /**
+     *
+     * @returns Currently playing animation track
+     */
     getCurrentAnimationTrack(): AnimationTrack | undefined;
+    /**
+     * Loads a new animation
+     * @param id
+     * @param isEmote
+     * @param forceLoop Forces animation track to loop
+     * @returns undefined on success
+     */
     loadAvatarAnimation(id: bigint, isEmote?: boolean, forceLoop?: boolean): Promise<Response | undefined>;
+    /**
+     * Switches to new animation
+     * @param name Animation name, such as "idle", "walk" or "emote.1234"
+     * @param type
+     * @returns If animation sucessfully played
+     */
     playAnimation(name: string, type?: "main" | "mood" | "tool"): boolean;
 }
 
@@ -590,7 +618,7 @@ export declare class BodyColor3s {
     fromJson(bodyColorsJson: BodyColor3sJson): void;
 }
 
-declare type BodyColor3sJson = {
+export declare type BodyColor3sJson = {
     headColor3?: string;
     torsoColor3?: string;
     rightArmColor3?: string;
@@ -626,7 +654,7 @@ export declare class BodyColors {
     toColor3(): BodyColor3s;
 }
 
-declare type BodyColorsJson = {
+export declare type BodyColorsJson = {
     headColorId?: number;
     torsoColorId?: number;
     rightArmColorId?: number;
@@ -1187,7 +1215,9 @@ export declare class FileMeshSubset {
     clone(): FileMeshSubset;
 }
 
-/** @category Mesh */
+/**
+ * Converts a FileMesh to geometry that can be used by ThreeJS
+ * @category Mesh */
 export declare function fileMeshToTHREEGeometry(mesh: FileMesh, canIncludeSkinning?: boolean, forceVertexColor?: Vector3): THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>;
 
 export declare function FindFirstMatchingAttachment(attachmentName: string, rig: Instance): Instance | null;
@@ -1196,53 +1226,103 @@ export declare function FindFirstMatchingAttachment(attachmentName: string, rig:
  * @category FLAGS
  */
 export declare const FLAGS: {
+    /** Only used by RoAvatar UI */
     HAIR_IS_BODYPART: boolean;
+    /**wip, do not enable */
     AVATAR_JOINT_UPGRADE: boolean;
+    /**wip, only for memory leak debugging */
     INSTANCE_GARBAGE_COLLECT: boolean;
+    /**outfits returned by api use Color3 instead of BrickColor */
     BODYCOLOR3: boolean;
+    /**allows API to cache data */
     ENABLE_API_CACHE: boolean;
+    /**allows API to cache mesh data */
     ENABLE_API_MESH_CACHE: boolean;
+    /**allows API to cache RBX data */
     ENABLE_API_RBX_CACHE: boolean;
+    /**url of model to load that lists issues with specific versions (only used by RoAvatar) */
     ROAVATAR_DATA_URL: string;
+    /**the place try-on button sends you to (only used by RoAvatar) */
     ROAVATAR_TRYON_PLACE: number;
-    ASSETS_PATH: string;
+    /**API uses assetdelivery v2 instead of v1 */
     ASSETDELIVERY_V2: boolean;
+    /**request priority given to fetch for assetdelivery */
     ASSET_REQUEST_PRIORITY: RequestPriority | undefined;
+    /**the domain all api requests go through */
+    API_DOMAIN: string;
+    /**loads assets from assetdelivery instead of local files */
     ONLINE_ASSETS: boolean;
+    /**path to rbxasset:// local files*/
+    ASSETS_PATH: string;
+    /**path to RigR6.rbxm and RigR15.rbxm*/
     RIG_PATH: string;
+    /**if WebWorkers (multithreading) can be used */
     USE_WORKERS: boolean;
+    /**makes linear algorithms cache weights */
     ENABLE_LC_WEIGHT_CACHE: boolean;
+    /**only used by linear algorithms */
     INFLATE_LAYERED_CLOTHING: number;
+    /**algorithm, rbf (default) is fastest, others are deprecated */
     LAYERED_CLOTHING_ALGORITHM: "linear" | "linearnormal" | "linearnormal2" | "rbf";
+    /**renders cage mesh instead of actual mesh */
     SHOW_CAGE: boolean;
+    /**cooldown between mesh recompile */
     LAYERED_CLOTHING_COOLDOWN: number;
+    /**function WorkerPool uses to create workers, replace with your own if workers cant be created using the default method */
     GET_WORKER_FUNC: () => Worker;
+    /**amount of "patches" that are used for layered clothing, multiple verts share the same patch */
     RBF_PATCH_COUNT: number;
+    /**amount of nearby vertices each patch samples from */
     RBF_PATCH_DETAIL_SAMPLES: number;
+    /**amount of far-away vertices (importants) each patch samples from, this is done so that the overall mesh shape is preserved */
     RBF_PATCH_SHAPE_SAMPLES: number;
+    /**forces vertex color to be white when false */
     USE_VERTEX_COLOR: boolean;
+    /**this is needed to enable bloom, but ugly since it disables anti aliasing... */
     USE_POST_PROCESSING: boolean;
+    /**doubles render resolution when using post processing */
     POST_PROCESSING_IS_DOUBLE_SIZE: boolean;
+    /**makes HumanoidDescription load gears */
     GEAR_ENABLED: boolean;
+    /**makes Audio instances play sound when played */
     AUDIO_ENABLED: boolean;
+    /**makes welds immediately update (bad for performance) */
     LEGACY_WELD_BEHAVIOR: boolean;
+    /**enables full texture compilation using ThreeJS RenderTarget */
     USE_RENDERTARGET: boolean;
+    /**the renderer will attempt to restore the webgl context when it is lost */
     AUTO_RESTORE_CONTEXT: boolean;
+    /**RenderTarget textures are converted to CanvasTextures which can be exported */
     RENDERTARGET_TO_CANVASTEXTURE: boolean;
+    /**Amount of time thumbnail generator will wait after no assets are being loaded to resolve */
     THUMBNAIL_TIMEOUT: number;
+    /**shows ThreeJS SkeletonHelper */
     SHOW_SKELETON_HELPER: boolean;
+    /**skeleton is updated every frame */
     UPDATE_SKELETON: boolean;
+    /**skeleton is animated every frame */
     ANIMATE_SKELETON: boolean;
+    /**autoskin is applied even when its disabled */
     AUTO_SKIN_EVERYTHING: boolean;
+    /**skeleton is local instead of global (broken) */
     USE_LOCAL_SKELETONDESC: boolean;
+    /**enables HSR (hidden surface removal) */
     ENABLE_HSR: boolean;
+    /**shows rays created by HSR */
     HSR_SHOW_RAY: boolean;
+    /**hides layered clothing */
     HIDE_LAYERED_CLOTHING: boolean;
+    /**rays per triangle */
     HSR_RAY_COUNT: number;
+    /**length of each ray */
     HSR_RAY_LENGTH: number;
+    /**caches amount of hits for each triangle */
     CACHE_HSR_HITS: boolean;
+    /**enables logging for non-critical information */
     VERBOSE_LOGGING: boolean;
+    /**makes renderer print out strings in RBX that contain SEARCH_FOR_STRING */
     SEARCH_FOR_STRING: string | undefined;
+    /**only used by RoAvatar, set this to a string to load a place file, for example "../assets/UniversalApp.rbxm" */
     LOAD_TEST_PLACE: string | undefined;
 };
 
@@ -2098,6 +2178,14 @@ export declare function mount(container: HTMLDivElement): void;
  * Mounting function for use with React
  * @param container Container to mount inside
  * @category Renderer
+ * @example
+ * ```ts
+ * export default function Component(): React.JSX.Element {
+ *     const containerRef = useCallback(mountElement, [])
+ *
+ *     return <div ref={containerRef}></div>
+ * }
+ * ```
  */
 export declare function mountElement(container: HTMLDivElement): void;
 
@@ -2312,6 +2400,10 @@ export declare class Outfit {
      */
     isValid(): boolean;
     getValidationIssues(): ValidationIssue[];
+    /**
+     * @deprecated Outdated
+     * @returns
+     */
     toHumanoidDescription(): Promise<Document | null>;
     /** @deprecated */
     fromHumanoidDescription(rootDocument: Document): Promise<void>;
@@ -2324,6 +2416,9 @@ export declare class Outfit {
     removeAsset(assetId: number): void;
     removeAssetType(type: string | number): void;
     addAsset(id: number, type: string | number, name: string, supportsHeadShapes?: boolean): void;
+    /**
+     * Fixes multiple layered assets having the same order value
+     */
     fixOrders(): void;
     getAssetsAtOrder(order: number): Asset[];
     isOrderUsed(order: number, self?: Asset): boolean;
@@ -2337,7 +2432,7 @@ export declare class Outfit {
     toBuffer(): ArrayBuffer;
 }
 
-declare type OutfitJson = {
+export declare type OutfitJson = {
     scale?: ScaleJson;
     playerAvatarType?: AvatarType;
     assets?: AssetJson[];
@@ -2374,6 +2469,7 @@ export declare class OutfitRenderer {
     currentlyChangingRig: boolean;
     currentlyUpdating: boolean;
     hasNewUpdate: boolean;
+    private _queuedMainAnimation;
     lastFrameTime: number;
     animationInterval?: NodeJS.Timeout;
     animationFPS: number;
@@ -2538,6 +2634,7 @@ declare class Ray_2 {
 }
 
 /**
+ * The deformer used for layered clothing
  * @category Mesh
  */
 export declare class RBFDeformerPatch {
@@ -2557,9 +2654,33 @@ export declare class RBFDeformerPatch {
     epsilon: number;
     affectBones: boolean;
     id: number;
+    /**
+     * 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: FileMesh, distMesh: FileMesh, mesh: FileMesh, ignoredIndices?: number[], patchCount?: number, detailsCount?: number, importantsCount?: number);
+    /**
+     * Solves the linear equations asynchronously, required before deformation
+     * @returns void
+     */
     solveAsync(): Promise<void>;
+    /**
+     * 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: number): Vec3;
+    /**
+     * solveAsync() needs to be called before this
+     * Deforms vertices and bones in mesh (if this.affectBones = true)
+     */
     deformMesh(): void;
 }
 
@@ -2684,7 +2805,7 @@ export declare class RBXRenderer {
     static _createEffectComposer(renderScene?: RBXRendererScene): void;
     /**Removes an instance from the renderer */
     static removeInstance(instance: Instance, renderScene?: RBXRendererScene): void;
-    static _addRenderDesc(instance: Instance, auth: Authentication, DescClass: typeof RenderDesc, renderScene: RBXRendererScene): void;
+    private static _addRenderDesc;
     /**Adds an instance to the renderer or updates it */
     static addInstance(instance: Instance, auth: Authentication, renderScene?: RBXRendererScene): void;
     static setRendererSize(width: number, height: number): void;
@@ -2704,10 +2825,14 @@ export declare class RBXRenderer {
     static setCameraFov(fov: number, renderScene?: RBXRendererScene): void;
     /**@deprecated This can only get the first renderScene's controls */
     static getRendererControls(): OrbitControls | undefined;
+    /**
+     * @returns ThreeJS renderer
+     */
     static getRenderer(): THREE.WebGLRenderer | undefined;
     /**@deprecated This can only get the first renderScene's scene */
     static getScene(): THREE.Scene;
-    /**@deprecated
+    /**
+     * @deprecated Superseded by RBXRendererScene.exportGLTF()
      * This function is unstable and can throw errors, but might work
      */
     static exportScene(renderScene?: RBXRendererScene): void;
@@ -2745,7 +2870,14 @@ export declare class RBXRendererScene {
     setRect(bounds: DOMRect): void;
     /** Makes viewport size 0x0, invisible */
     noRect(): void;
+    /** Destroys all renderDescs but does not call Destroy on instances */
     destroy(): void;
+    /**
+     * 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)
+     */
     exportGLTF(name?: string, autoDownload?: boolean): Promise<ArrayBuffer | {
         [key: string]: unknown;
     }>;
@@ -2905,7 +3037,7 @@ export declare function ScaleAccessoryForRig(accessory: Instance, rig: Instance,
 
 export declare function ScaleCharacter(rig: Instance, outfit: Outfit, humanoidDescription: Instance): RigData | undefined;
 
-declare type ScaleJson = {
+export declare type ScaleJson = {
     height?: number;
     width?: number;
     head?: number;
@@ -3229,13 +3361,13 @@ export declare interface UserOmniSearch_Result {
     "nextPageToken": string;
 }
 
-declare type ValidationIssue = {
+export declare type ValidationIssue = {
     type: ValidationIssueType;
     text: string;
     assetIndex?: number;
 };
 
-declare type ValidationIssueType = "AccessoryLimit" | "LayeredLimit" | "OneOfTypeLimit" | "DuplicateId" | "NotWearable" | "MissingLayeredMeta" | "InvalidAsset" | "MakeupLimit";
+export declare type ValidationIssueType = "AccessoryLimit" | "LayeredLimit" | "OneOfTypeLimit" | "DuplicateId" | "NotWearable" | "MissingLayeredMeta" | "InvalidAsset" | "MakeupLimit";
 
 /** @category Mesh */
 export declare type Vec2 = [number, number];

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/",
@@ -32778,6 +32779,10 @@ class Outfit {
     }
     return issues;
   }
+  /**
+   * @deprecated Outdated
+   * @returns 
+   */
   async toHumanoidDescription() {
     const response = await fetch("/assets/HumanoidDescriptionTemplate.xml");
     if (response.status !== 200)
@@ -33080,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)) {
@@ -35191,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);
   }
@@ -35237,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"
@@ -36432,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;
@@ -36481,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;
@@ -36506,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");
@@ -36529,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;
@@ -47001,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) {
@@ -47020,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) {
@@ -47092,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) {
@@ -47207,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) {
@@ -49280,6 +49346,7 @@ class RBXRendererScene {
     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;
@@ -49296,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();
@@ -49905,6 +49978,9 @@ class RBXRenderer {
   static getRendererControls() {
     return RBXRenderer.controls;
   }
+  /**
+   * @returns ThreeJS renderer
+   */
   static getRenderer() {
     return RBXRenderer.renderer;
   }
@@ -49912,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) {
@@ -50208,6 +50285,7 @@ class OutfitRenderer {
   currentlyChangingRig = false;
   currentlyUpdating = false;
   hasNewUpdate = false;
+  _queuedMainAnimation;
   lastFrameTime = Date.now() / 100;
   animationInterval;
   animationFPS = 60;
@@ -50274,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);
@@ -50380,6 +50462,8 @@ class OutfitRenderer {
           }
         }
       }
+    } else {
+      this._queuedMainAnimation = name;
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roavatar-renderer",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "A renderer for Roblox avatars, used by the RoAvatar extension.",
   "author": "steinan",
   "type": "module",