roavatar-renderer 1.5.18 → 1.6.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EffectComposer } from 'three/examples/jsm/Addons.js';
+import { EffectComposer } from 'postprocessing';
 import { OrbitControls } from 'three/examples/jsm/Addons.js';
 import * as THREE from 'three';
 
@@ -653,7 +653,7 @@ export declare interface AvatarModel_Result {
     avatarConfigurations: AvatarConfigurations | null;
 }
 
-export declare type AvatarModelUpdateType = "UpdateName" | "UpdateBodyColors" | "UpdateAssets" | "UpdateScales" | "UpdateBackground";
+export declare type AvatarModelUpdateType = "UpdateName" | "UpdateBodyColors" | "UpdateAssets" | "UpdateScales" | "UpdateBackground" | "UpdateAvatarType";
 
 /** @category Outfit */
 export declare type AvatarType = "R6" | "R15";
@@ -683,6 +683,71 @@ export declare function awaitTimeout<T>(promise: Promise<T>, time?: number): Pro
  */
 export declare function awaitTimeoutThrows<T>(promise: Promise<T>, time?: number): Promise<T>;
 
+declare class BackgroundRenderer {
+    auth: Authentication;
+    avatarCyclorama?: Instance;
+    backgroundData?: Instance;
+    backgroundId?: number;
+    lastLoadedBackgroundId?: number;
+    currentlyUpdating: boolean;
+    hasNewUpdate: boolean;
+    affectSceneAppearance: boolean;
+    cameraAffectsTransparency: boolean;
+    lastFrameTime: number;
+    animationInterval?: NodeJS.Timeout;
+    animationFPS: number;
+    renderScene: RBXRendererScene;
+    private _renderSceneCompiledConnection?;
+    private _renderSceneFailedConnection?;
+    hasFiredFullyRendered: boolean;
+    /**Event is fired if a new outfit failed to load (specifically the Instance tree, not the rendering part)
+     *
+     * Simple: Fired when, Instance tree = fail
+     * @returns BackgroundRendererErrorType
+     */
+    onError: Event_2;
+    /**Event is fired if a new outfit successfully loaded (specifically the Instance tree, not the rendering part)
+     *
+     * Simple: Fired when, Instance tree = done
+     * @returns void
+     */
+    onSuccess: Event_2;
+    /**Event is fired when all the renderDescs have been compiled, if any renderDescs fail to render this wil never be fired (can only be fired after Instance tree is done)
+     *
+     * Simple: Fired when, Instance tree = done & Rendering = done (AKA everything)
+     * @returns void
+     */
+    onRenderSuccess: Event_2;
+    /**Event is fired if a renderDesc fails to compile, it can be fired multiple times
+     *
+     * Simple: Fired when, Rendering = fail
+     * @returns void
+     */
+    onRenderError: Event_2;
+    constructor(auth: Authentication, backgroundId?: number, renderScene?: RBXRendererScene);
+    /**Updates background to match the set id */
+    setBackground(id?: number): void;
+    _updateBackground(): Promise<void>;
+    _loadBackgroundData(): Promise<void>;
+    _loadAvatarCyclorama(): Promise<void>;
+    _applyBackgroundData(): void;
+    /**
+     * Starts updating the animation of the background per frame
+     */
+    startAnimating(): void;
+    /**
+     * Updates the animation once
+     */
+    animateOnce(): void;
+    /**
+     * Stops updating the animation of the background per frame
+     */
+    stopAnimating(): void;
+    fireFullyRenderedIfNeeded(): void;
+    /**Calls destroy on the background, stops animating and disconnects connections. The OutfitRenderer should not be interacted with after this */
+    destroy(): void;
+}
+
 /**
  * @category Mesh
  */
@@ -1010,6 +1075,7 @@ export declare class Color3 {
     clone(): Color3;
     isSame(other: Color3): boolean;
     toColor3uint8(): Color3uint8;
+    toArray(): Vec3;
     multiply(vec3: Color3): Color3;
     divide(vec3: Color3): Color3;
     add(vec3: Color3): Color3;
@@ -1026,6 +1092,7 @@ export declare class Color3uint8 {
     constructor(R?: number, G?: number, B?: number);
     clone(): Color3uint8;
     toColor3(): Color3;
+    toArray(): Vec3;
 }
 
 /**
@@ -1493,9 +1560,15 @@ export declare const FLAGS: {
     ALWAYS_SHOW_ATTACHMENTS: boolean;
     /**Multiplier for delta time used by renderer things (does not affect datamodel side of things but particles and such instead) */
     RENDERER_DELTA_TIME_MULTIPLIER: number;
-    /**How many seconds particles will presimulate (mainly so they arent incomplete in thumbnail generations) */
+    /**
+     * How many seconds particles will presimulate (mainly so they arent incomplete in thumbnail generations)
+     * @deprecated This can now be set per-scene
+     * */
     PARTICLES_START_FULL: number;
-    /**Framerate of presimulation particles */
+    /**
+     * Framerate of presimulation particles
+     * @deprecated This can now be set per-scene
+     * */
     PARTICLES_START_FULL_FRAMERATE: number;
     /**shows ThreeJS SkeletonHelper */
     SHOW_SKELETON_HELPER: boolean;
@@ -1621,12 +1694,9 @@ export declare function generateOutfitModelThumbnail(auth: Authentication, outfi
  * **Example on generating 1000x1000 webp thumbnail for blank outfit**
  * ```ts
  * const outfit = new Outfit()
- * FLAGS.THUMBNAIL_TIMEOUT = 1 //makes thumbnail generation faster
- * FLAGS.PARTICLES_START_FULL = 10 //makes emitters appear as if theyve been there for some time (10 seconds)
  * FLAGS.RENDERTARGET_TO_CANVASTEXTURE = true //required for gltf export
  * const result = await generateOutfitThumbnail(new Authentication(), outfit, [1000,1000], "webp", 0.99)
  * FLAGS.RENDERTARGET_TO_CANVASTEXTURE = false
- * FLAGS.PARTICLES_START_FULL = 0
  * console.log(result)
  * ```
  */
@@ -1661,21 +1731,20 @@ export declare function getCameraCFrameForHeadshotCustomized(rig: Instance, fov:
 export declare function getDistIndexArray(ref: FileMesh, dist: FileMesh): (number | undefined)[];
 
 /**
- * @deprecated Use new Thumbnails category instead
  * @category ThumbnailGenerator */
 export declare function getExtents(cframe: CFrame, parts: Instance[]): [Vector3, Vector3];
 
 /**
- * @deprecated Use new Thumbnails category instead
  * @category ThumbnailGenerator */
 export declare function getExtentsCenter(extents: [Vector3, Vector3]): Vector3;
 
 /**
- * @deprecated Use new Thumbnails category instead
  * @category ThumbnailGenerator
  * */
 export declare function getExtentsForParts(parts: Instance[], includeTransform?: boolean): [Vector3, Vector3];
 
+export declare function getExtentsWorld(rig: Instance): [Vector3, Vector3];
+
 export declare function getHeadExtents(rig: Instance): [Vector3, Vector3] | undefined;
 
 /**@category API */
@@ -1707,8 +1776,6 @@ export declare function getPartsInAssembly_Generate(part: Instance): Instance[];
 
 export declare function getRandomBetweenInclusive(min: number, max: number, randomVal?: number): number;
 
-export declare function getRigExtentsWorld(rig: Instance): [Vector3, Vector3];
-
 export declare function getRootAssemblyPart_Generate(part: Instance): Instance;
 
 /**@category API */
@@ -1731,7 +1798,6 @@ export declare interface GetSubscription_Result {
  * Calculates the CFrame the camera should be at when generating a thumbnail
  * @param model The model-like instance to get thumbnail camera for
  * @returns Thumbnail camera cframe
- * @deprecated Use new Thumbnails category instead
  * @category ThumbnailGenerator
  */
 export declare function getThumbnailCameraCFrame(model: Instance, fov: number, forceAngle?: Vec3): CFrame | undefined;
@@ -1921,6 +1987,31 @@ export declare const HumanoidRigType: {
     R15: number;
 };
 
+/**
+ * Renders a scene to an image and returns a data url
+ * @param renderScene Scene that will be rendered
+ * @param width Width in pixels
+ * @param height Height in pixels
+ * @param format Type of image
+ * @param options
+ * @returns data url
+ *
+ * @category ThumbnailGenerator
+ */
+export declare function imageThumbnailClick(renderScene: RBXRendererScene, width: number, height: number, format: ImageThumbnailFormat, options?: Partial<ImageThumbnailOptions>): Promise<string | undefined>;
+
+/**
+ * @category ThumbnailGenerator
+ */
+export declare type ImageThumbnailFormat = "png" | "webp" | "jpeg";
+
+/**
+ * @category ThumbnailGenerator
+ */
+export declare interface ImageThumbnailOptions {
+    quality: number;
+}
+
 export declare function imageUrlToDataUrl(imageUrl: string): Promise<string>;
 
 /**
@@ -2017,6 +2108,7 @@ export declare class Instance {
     FindFirstChildOfClass(className: string): Instance | undefined;
     FindLastChildOfClass(className: string): Instance | undefined;
     IsA(className: string): boolean;
+    IsDescendantOf(instance: Instance): boolean;
     preRender(): void;
 }
 
@@ -2476,6 +2568,31 @@ export declare const minimumDeltaEBodyColorDifference = 11.4;
  */
 export declare function minus(v0: Vec3, v1: Vec3): Vec3;
 
+/**
+ * Generates a 3D model from the scene
+ * @param renderScene Scene that will be rendered
+ * @param format Format of resulting model
+ * @param options
+ * @returns ArrayBuffer for glb or Object for gltf
+ *
+ * @category ThumbnailGenerator
+ */
+export declare function modelThumbnailClick(renderScene: RBXRendererScene, format: ModelThumbnailFormat, options?: Partial<ModelThumbnailOptions>): Promise<ArrayBuffer | {
+    [key: string]: unknown;
+}>;
+
+/**
+ * @category ThumbnailGenerator
+ */
+export declare type ModelThumbnailFormat = "gltf" | "glb";
+
+/**
+ * @category ThumbnailGenerator
+ */
+export declare interface ModelThumbnailOptions {
+    includeAnimations: boolean;
+}
+
 /**
  * @category InstanceWrapper
  */
@@ -2811,15 +2928,49 @@ export declare const OutfitOrigin: {
 
 /**
  * @category Renderer
+ * @example
+ * **Example on usage**
+ * ```ts
+ * const auth = new Authentication()
+ * const outfit = new Outfit()
+ * const renderScene = RBXRenderer.addScene()
+ *
+ * const outfitRenderer = new OutfitRenderer(auth, outfit, renderScene)
+ * outfitRenderer.startAnimating()
+ * outfitRenderer.setMainAnimation("anim.1234") //animation with id 1234, check documentation for other possible values
+ *
+ * outfitRenderer.onRenderSuccess.Connect(() => {
+ *     //handle Instance tree + renderDesc being successfuly
+ * })
+ * outfitRenderer.onError.Connect(() => {
+ *     //handle Instance tree error
+ * })
+ * outfitRenderer.onRenderError.Connect(() => {
+ *     //handle renderDesc error
+ * })
+ *
+ * //onRenderSuccess is fired once after some time
+ *
+ * outfitRenderer.setOutfit(new Outfit())
+ *
+ * //onRenderSuccess is fired again once after some time
+ *
+ * //when we're done rendering
+ * outfitRenderer.destroy()
+ * renderScene.destroy()
+ * ```
  */
 export declare class OutfitRenderer {
     auth: Authentication;
+    outfitModel?: OutfitModel;
     outfit: Outfit;
     currentRig?: Instance; /**Instance for the Model of the current outfit */
     currentRigType: AvatarType;
     doCameraUpdateOnLoad: boolean; /**Makes camera update when new avatar has loaded */
     doCameraUpdate: boolean; /**Does camera update every frame */
     doAddInstance: boolean; /**If outfitRenderer should call RBXRenderer.addInstance() */
+    forceAnimationLoop: boolean; /**If future loaded animations should be set to loop */
+    backgroundRenderer: BackgroundRenderer;
     currentlyChangingRig: boolean;
     currentlyUpdating: boolean;
     hasNewUpdate: boolean;
@@ -2829,21 +2980,42 @@ export declare class OutfitRenderer {
     animationFPS: number;
     deltaTimeMultiplier: number;
     renderScene: RBXRendererScene;
-    /**Event is fired if a new outfit failed to load
+    private _renderSceneCompiledConnection?;
+    private _renderSceneFailedConnection?;
+    hasFiredFullyRendered: boolean;
+    /**Event is fired if a new outfit failed to load (specifically the Instance tree, not the rendering part)
+     *
+     * Simple: Fired when, Instance tree = fail
      * @returns OutfitRendererErrorType
      */
     onError: Event_2;
-    /**Event is fired if a new outfit successfully loaded
+    /**Event is fired if a new outfit successfully loaded (specifically the Instance tree, not the rendering part)
+     *
+     * Simple: Fired when, Instance tree = done
      * @returns void
      */
     onSuccess: Event_2;
+    /**Event is fired when all the renderDescs have been compiled, if any renderDescs fail to render this wil never be fired (can only be fired after Instance tree is done)
+     *
+     * Simple: Fired when, Instance tree = done & Rendering = done (AKA everything)
+     *
+     * NOTE: If FLAGS.LAYERED_CLOTHING_COOLDOWN > 0 (non-default), this may be fired too early and later fire again
+     * @returns void
+     */
+    onRenderSuccess: Event_2;
+    /**Event is fired if a renderDesc fails to compile, it can be fired multiple times
+     *
+     * Simple: Fired when, Rendering = fail
+     * @returns void
+     */
+    onRenderError: Event_2;
     /**
      * Creates a new OutfitRenderer which makes it easy to render outfits
      * @param auth The authentication object, you should have one you use for everything
      * @param outfit The outfit you want to render, it can be updated later by calling setOutfit()
      * @param renderScene The scene the outfit should be rendered in
      */
-    constructor(auth: Authentication, outfit: Outfit, renderScene?: RBXRendererScene);
+    constructor(auth: Authentication, outfit: Outfit | OutfitModel, renderScene?: RBXRendererScene);
     /**
      * Updates the current rig, called internally by _updateOutfit()
      */
@@ -2856,6 +3028,10 @@ export declare class OutfitRenderer {
      * Updates the current outfit being rendered
      */
     setOutfit(outfit: Outfit): void;
+    /**
+     * Updates the current outfitModel being rendered
+     */
+    setOutfitModel(outfitModel: OutfitModel): void;
     /**
      * Centers camera on avatar
      */
@@ -2874,11 +3050,22 @@ export declare class OutfitRenderer {
     stopAnimating(): void;
     /**
      * Sets the current animation being played
-     * @param name The name of the animation, for example "idle", "run" or "emote.1234"
+     * @param name The name of the animation, for example "idle", "run", "emote.1234" or "anim.1234"
      * @returns If the animation started playing, it may start playing later if it has been queued despite returning false
      */
     setMainAnimation(name: string): Promise<boolean>;
-    /**Calls destroy on the rig and stops animating, the OutfitRenderer should not be interacted with after this */
+    fireFullyRenderedIfNeeded(): void;
+    /**
+     * Prepares the OutfitRenderer to be used for a thumbnail, call IMMEDIATELY after creating the OutfitRenderer
+     * @returns true on success
+     */
+    prepareForThumbnail(): Promise<boolean>;
+    private _prepareForThumbnail;
+    /**
+     * Updates rendered particles so they face the camera without simulating them (usually used when generating thumbnails)
+     */
+    updateParticleMatrix(): void;
+    /**Calls destroy on the rig, stops animating and disconnects connections. The OutfitRenderer should not be interacted with after this */
     destroy(): void;
 }
 
@@ -3149,23 +3336,27 @@ export declare class RBXRenderer {
     static scenes: RBXRendererScene[];
     static get firstScene(): RBXRendererScene;
     /**@deprecated This can only get the first renderScene's scene */
-    static get scene(): THREE.Scene;
+    static get scene(): THREE.Scene<THREE.Object3DEventMap>;
     /**@deprecated This can only get the first renderScene's camera */
     static get camera(): THREE.PerspectiveCamera;
     /**@deprecated This can only get the first renderScene's controls */
-    static get controls(): OrbitControls | undefined;
+    static get controls(): OrbitControls<THREE.Camera> | undefined;
     static renderer?: THREE.WebGLRenderer;
     static resolution: [number, number];
-    static backgroundColorHex: number;
+    static backgroundColor: THREE.ColorRepresentation;
+    /**@deprecated Use backgroundColor instead */
+    static get backgroundColorHex(): number;
+    /**@deprecated Use backgroundColor instead */
+    static set backgroundColorHex(val: number);
     static backgroundTransparent: boolean;
     static createLoadingIcon: boolean;
     static canvasContainer: HTMLDivElement;
     static loadingIcon?: HTMLSpanElement;
     static loadingIconStyle?: HTMLStyleElement;
     /**@deprecated This can only get the first renderScene's plane */
-    static get plane(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap> | undefined;
+    static get plane(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap> | undefined;
     /**@deprecated This can only get the first renderScene's shadowPlane */
-    static get shadowPlane(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap> | undefined;
+    static get shadowPlane(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap> | undefined;
     /**@deprecated This can only get the first renderScene's ambientLight */
     static get ambientLight(): THREE.AmbientLight | undefined;
     /**@deprecated This can only get the first renderScene's directionalLight */
@@ -3193,15 +3384,15 @@ export declare class RBXRenderer {
     static setupLostContextHandler(): void;
     /**Sets up a basic scene with lighting
      * @param lightingType "WellLit" is the default lighting for RoAvatar, "Thumbnail" tries to match the Roblox thumbnail lighting
-     * @param backgroundColorHex is the hex code for the background color, for example 0x2b2d33
+     * @param backgroundColor is the color code for the background color, for example 0x2b2d33
      */
-    static setupScene(lightingType?: "WellLit" | "Thumbnail", backgroundColorHex?: number, renderScene?: RBXRendererScene): void;
+    static setupScene(lightingType?: "WellLit" | "Thumbnail", backgroundColorVal?: THREE.ColorRepresentation, renderScene?: RBXRendererScene): void;
     /**Sets up orbit controls */
     static setupControls(renderScene?: RBXRendererScene): void;
     /**
-     * @param colorHex example: 0x2b2d33 which is the default
+     * @param color example: 0x2b2d33 which is the default
      */
-    static setBackgroundColor(colorHex: number): void;
+    static setBackgroundColor(color: THREE.ColorRepresentation): void;
     /**
      * Sets the background and ground's visibility, but not the shadowPlane
      * @param transparent If the background and ground should be transparent
@@ -3240,7 +3431,7 @@ export declare class RBXRenderer {
      */
     static getRenderer(): THREE.WebGLRenderer | undefined;
     /**@deprecated This can only get the first renderScene's scene */
-    static getScene(): THREE.Scene;
+    static getScene(): THREE.Scene<THREE.Object3DEventMap>;
     /**
      * @deprecated Superseded by RBXRendererScene.exportGLTF()
      * This function is unstable and can throw errors, but might work
@@ -3261,9 +3452,15 @@ export declare class RBXRendererScene {
     effectComposer: EffectComposer | undefined;
     scissor?: [number, number, number, number];
     viewport?: [number, number, number, number];
+    addedInstances: Instance[];
     isRenderingMesh: Map<Instance, boolean>;
     renderDescs: Map<Instance, RenderDesc>;
     destroyConnections: Map<Instance, Connection>;
+    compiledRenderDesc: Event_2;
+    failedRenderDesc: Event_2;
+    forceAccurateNeedsRegeneration: boolean;
+    particlesStartFull?: number;
+    particlesStartFullFramerate: number;
     lookAwayVector: Vec3;
     lookAwayDistance: number;
     shadowEnabled: boolean;
@@ -3282,6 +3479,16 @@ export declare class RBXRendererScene {
     noRect(): void;
     /** Destroys all renderDescs but does not call Destroy on instances */
     destroy(): void;
+    /**
+     * Checks that renderDescs for provided instances are compiled, ignores instances that shouldn't be compiled or haven't been added
+     * @returns true if all provided instances's renderDescs have been compiled
+     */
+    areInstancesCompiled(instances: Instance[]): boolean;
+    /**
+     * Checks that all renderDescs are compiled
+     * @return true if all have been compiled
+     */
+    isFullyCompiled(): boolean;
     /**
      * Exports scene as a GLTF or GLB
      * @param name Name of the resulting file if autoDownload is true
@@ -3341,6 +3548,8 @@ declare class RenderDesc extends DisposableDesc {
     renderScene: RBXRendererScene;
     results?: THREE.Object3D[];
     instance?: Instance;
+    compiled: boolean;
+    failed: boolean;
     constructor(renderScene: RBXRendererScene);
     isSame(_other: RenderDesc): boolean;
     needsRegeneration(_other: RenderDesc): boolean;
@@ -3544,7 +3753,6 @@ export declare interface Search_Result {
  * Gives a scene the default appearance for thumbnails
  * @param renderScene RBXRenderScene to setup
  *
- * @deprecated Use new Thumbnails category instead
  * @category ThumbnailGenerator
  */
 export declare function setupThumbnailScene(renderScene: RBXRendererScene): void;
@@ -3925,8 +4133,6 @@ export declare const WrapLayerAutoSkin: {
 
 export declare const xmlMagic = "<roblox ";
 
-export declare function zoomExtents(cameraCFrame: CFrame, modelCFrame: CFrame, modelSize: Vector3, targetFOV: number, distanceScale: number, sizeType?: ZoomExtentsSizeType): void;
-
 /**
  * Makes model fit inside camera
  * @param cameraCFrame Original camera cframe
@@ -3936,6 +4142,8 @@ export declare function zoomExtents(cameraCFrame: CFrame, modelCFrame: CFrame, m
  * @param distanceScale Distance is multiplied by this
  * @category ThumbnailGenerator
  */
+export declare function zoomExtents(cameraCFrame: CFrame, modelCFrame: CFrame, modelSize: Vector3, targetFOV: number, distanceScale: number, sizeType?: ZoomExtentsSizeType): void;
+
 export declare type ZoomExtentsSizeType = "largestAxis" | "calculate";
 
 /**