roavatar-renderer 1.5.19 → 1.6.1

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';
 
@@ -252,7 +252,7 @@ export declare class AnimatorWrapper extends InstanceWrapper {
     loadAvatarAnimation(id: bigint, isEmote?: boolean, forceLoop?: boolean): Promise<Response | undefined>;
     /**
      * Switches to new animation
-     * @param name Animation name, such as "idle", "walk", "emote.1234" or "id.1234"
+     * @param name Animation name, such as "idle", "walk", "emote.1234" or "id.1234", can also specify sub animation like "idle:0"
      * @param type
      * @returns If animation sucessfully played
      */
@@ -273,6 +273,7 @@ declare class AnimatorWrapperData {
     toolTracks: AnimationTrack[];
     toolAddedConnection?: Connection;
     toolRemovedConnection?: Connection;
+    forceTransitionTime: number | undefined;
 }
 
 export declare const animNamesR15: AnimationSet;
@@ -315,6 +316,7 @@ export declare const API: {
         WearOutfit: (auth: Authentication, outfit: Outfit, onlyItems: boolean) => Promise<[boolean, boolean]>;
         SaveOutfitNoRetry: (auth: Authentication, outfit: Outfit) => Promise<Response>;
         GetAvatarDetails: (userId: number) => Promise<Response | Outfit>;
+        GetUserAvatarModel: (userId: number) => Promise<Response | OutfitModel>;
         GetAvatarModel: () => Promise<Response | OutfitModel>;
         UpdateAvatarModel: (auth: Authentication, model: OutfitModel, updateTypes?: AvatarModelUpdateType[]) => Promise<Response>;
         GetOutfitModel: (id: number | string, creatorId: number) => Promise<Response | OutfitModel>;
@@ -683,6 +685,73 @@ export declare function awaitTimeout<T>(promise: Promise<T>, time?: number): Pro
  */
 export declare function awaitTimeoutThrows<T>(promise: Promise<T>, time?: number): Promise<T>;
 
+export 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;
+}
+
+export declare type BackgroundRendererErrorType = "avatarCyclorama" | "backgroundData";
+
 /**
  * @category Mesh
  */
@@ -943,6 +1012,8 @@ declare class Cache_2<K, V> {
 }
 export { Cache_2 as Cache }
 
+export declare function calculateBaseDistanceToCamera(fieldOfViewRad: number, minExtent: Vector3, maxExtent: Vector3, marginScale: number): number;
+
 /**
  * @category Mesh
  */
@@ -950,6 +1021,39 @@ export declare function calculateMagnitude3D(x: number, y: number, z: number): n
 
 export declare function calculateMotor6Doffset(motor: Instance, includeTransform?: boolean): CFrame;
 
+export declare type CameraOptions = {
+    optFieldOfView?: number;
+    optFieldOfViewForDistanceScale?: number;
+    minExtent: Vector3;
+    maxExtent: Vector3;
+    extentScale: number;
+    optCameraDistanceScale?: number;
+    targetCFrame: CFrame;
+    optCameraXRot?: number;
+    optCameraYRot?: number;
+};
+
+/**@category DataModelEnum */
+export declare const CameraType: {
+    Fixed: number;
+    Attach: number;
+    Watch: number;
+    Track: number;
+    Follow: number;
+    Custom: number;
+    Scriptable: number;
+    Orbital: number;
+};
+
+/**
+ * @category InstanceWrapper
+ */
+export declare class CameraWrapper extends InstanceWrapper {
+    static className: string;
+    static requiredProperties: string[];
+    setup(): void;
+}
+
 /** @category Outfit */
 export declare const CatalogBundleTypes: string[];
 
@@ -968,6 +1072,7 @@ export declare class CFrame {
     Position: Vec3;
     Orientation: Vec3;
     constructor(x?: number, y?: number, z?: number);
+    static Angles(x: number, y: number, z: number): CFrame;
     clone(): CFrame;
     getTHREEMatrix(): THREE.Matrix4;
     getMatrix(): THREE.Matrix4Tuple;
@@ -977,8 +1082,12 @@ export declare class CFrame {
     upVector(): Vec3;
     static lookAt(eye: Vec3, target: Vec3, up?: Vec3): CFrame;
     static fromEulerAngles(rx: number, ry: number, rz: number, order?: THREE.EulerOrder): CFrame;
+    rotationOnly(): CFrame;
+    toEulerAngles(order?: THREE.EulerOrder): Vec3;
     inverse(): CFrame;
     multiply(cf: CFrame): CFrame;
+    multiplyVector(vector: Vector3): Vector3;
+    removeNaN(newValue?: number): CFrame;
     isSame(other: CFrame): boolean;
 }
 
@@ -1010,6 +1119,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 +1136,7 @@ export declare class Color3uint8 {
     constructor(R?: number, G?: number, B?: number);
     clone(): Color3uint8;
     toColor3(): Color3;
+    toArray(): Vec3;
 }
 
 /**
@@ -1066,6 +1177,21 @@ export declare class Connection {
     Disconnect(): void;
 }
 
+export declare const CONSTANTS_CameraPresetsUtility: {
+    GOLDEN_RATIO: number;
+    UPVECTOR_ORENTATION_TRESHOLD: number;
+    AVATAR_ROTATION_DEGREE: number;
+};
+
+export declare const CONSTANTS_CameraUtility: {
+    DefaultHeadMarginScale: number;
+    DefaultBodyMarginScale: number;
+    DefaultBodyPartMarginScale: number;
+    XRotForFullBody: number;
+    XRotForCloseup: number;
+    DistanceScaleForFullBody: number;
+};
+
 /**
  * @category InstanceWrapper
  */
@@ -1139,6 +1265,8 @@ export declare class COREMESH {
 
 export declare function createContentMap(): void;
 
+export declare function createThumbnailCamera(): Instance;
+
 /**
  * @category Mesh
  */
@@ -1633,12 +1761,26 @@ export declare function generateOutfitModelThumbnail(auth: Authentication, outfi
  * console.log(result)
  * ```
  */
-export declare function generateOutfitThumbnail(auth: Authentication, outfit: Outfit, size?: Vec2, type?: ThumbnailType, quality?: number, gltfAutoDownload?: boolean, includeAnimations?: boolean, renderSceneParam?: RBXRendererScene): Promise<ThumbnailResult>;
+export declare function generateOutfitThumbnail(auth: Authentication, outfit: Outfit | OutfitModel, size?: Vec2, type?: ThumbnailType, quality?: number, gltfAutoDownload?: boolean, includeAnimations?: boolean, renderSceneParam?: RBXRendererScene, thumbnailCameraType?: ThumbnailCameraType): Promise<ThumbnailResult>;
 
 export declare function generateUUIDv4(): string;
 
 export declare function GetAttachedPart(accessory: Instance, rig: Instance): Instance | undefined;
 
+export declare function getAvatarCameraCFrame(character: Instance, applyEmote?: () => void, isFallbackEmoteApplied?: boolean, fieldOfViewDeg?: number, cameraOptionsOverride?: Partial<CameraOptions>): Instance | undefined;
+
+export declare function getCameraCFrame(targetCFrame: CFrame, relativePos: Vector3): CFrame;
+
+/**
+ * Calculates the CFrame the camera should be at when generating a customized avatar thumbnail
+ * @param rig Character
+ * @param fov Customized fov
+ * @param yRot Customized yRot
+ * @returns Thumbnail camera cframe
+ * @category ThumbnailGenerator
+ */
+export declare function getCameraCFrameForAvatarCustomized(rig: Instance, fov: number, yRot: number): CFrame | undefined;
+
 /**
  * @deprecated Use getThumbnailCameraCFrame instead
  * @param rig
@@ -1653,11 +1795,12 @@ export declare function getCameraCFrameForAvatarNonCustomized(rig: Instance): CF
  * @param yRot Customized yRot
  * @param distance Customized distanceScale
  * @returns Thumbnail camera cframe
- * @deprecated Use new Thumbnails category instead
  * @category ThumbnailGenerator
  */
 export declare function getCameraCFrameForHeadshotCustomized(rig: Instance, fov: number, yRot: number, distance: number): CFrame | undefined;
 
+export declare function getCharacterTorsoCFrame(character: Instance): CFrame;
+
 /**
  * @category Mesh
  */
@@ -1678,8 +1821,12 @@ export declare function getExtentsForParts(parts: Instance[], includeTransform?:
 
 export declare function getExtentsWorld(rig: Instance): [Vector3, Vector3];
 
+export declare function getFullBodyCameraCFrame(character: Instance, applyEmote?: () => void, isFallbackEmoteApplied?: boolean, fieldOfViewDeg?: number, characterInitialCFrame?: CFrame, autoZoom?: boolean): CFrame | undefined;
+
 export declare function getHeadExtents(rig: Instance): [Vector3, Vector3] | undefined;
 
+export declare function getHeadshotCameraCFrame(character: Instance, applyEmote?: () => void, isFallbackEmoteApplied?: boolean, fieldOfViewDeg?: number, cameraOptionsOverride?: Partial<CameraOptions>): Instance | undefined;
+
 /**@category API */
 export declare interface GetInfoForId_Result {
     "description": string;
@@ -2041,6 +2188,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;
 }
 
@@ -2055,6 +2203,7 @@ export declare class InstanceWrapper {
     static requiredProperties: string[];
     instance: Instance;
     constructor(instance: Instance);
+    addProp(name: string, type: number, value: unknown): void;
     setup(): void;
     static(): typeof InstanceWrapper;
     static IsA(className: string): any;
@@ -2242,7 +2391,7 @@ export declare class LocalOutfit {
     constructor(outfit: Outfit);
     toJson(): LocalOutfitJson;
     fromJson(data: LocalOutfitJson): this;
-    update(outfit: Outfit): void;
+    update(outfitModel: Outfit | OutfitModel): void;
     /**
      * @deprecated Use toOutfitModel() instead
      */
@@ -2869,7 +3018,7 @@ export declare const OutfitOrigin: {
  *
  * const outfitRenderer = new OutfitRenderer(auth, outfit, renderScene)
  * outfitRenderer.startAnimating()
- * outfitRenderer.setMainAnimation("anim.1234") //animation with id 1234, check documentation for other possible values
+ * outfitRenderer.setMainAnimation("id.1234") //animation with id 1234, check documentation for other possible values
  *
  * outfitRenderer.onRenderSuccess.Connect(() => {
  *     //handle Instance tree + renderDesc being successfuly
@@ -2894,13 +3043,15 @@ export declare const OutfitOrigin: {
  */
 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() */
+    doAddInstance: boolean; /**If outfitRenderer should call RBXRenderer.addInstance(), setting this to false will make OutfitRenderer return success early */
     forceAnimationLoop: boolean; /**If future loaded animations should be set to loop */
+    backgroundRenderer: BackgroundRenderer;
     currentlyChangingRig: boolean;
     currentlyUpdating: boolean;
     hasNewUpdate: boolean;
@@ -2912,6 +3063,7 @@ export declare class OutfitRenderer {
     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
@@ -2938,13 +3090,16 @@ export declare class OutfitRenderer {
      * @returns void
      */
     onRenderError: Event_2;
+    get humanoid(): Instance | undefined;
+    get animator(): Instance | undefined;
+    get animatorW(): AnimatorWrapper | undefined;
     /**
      * 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()
      */
@@ -2957,6 +3112,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
      */
@@ -2973,9 +3132,15 @@ export declare class OutfitRenderer {
      * Stops updating the animation of the outfit per frame
      */
     stopAnimating(): void;
+    /**
+     * Checks if the provided animation set is loaded
+     * @param name The name of the animation, for example "idle", "run", but NOT "emote.1234" or "id.1234" as they are not in the animation set
+     * @returns If the animation is loaded
+     */
+    hasAnimationSetAnimation(name: string): boolean;
     /**
      * Sets the current animation being played
-     * @param name The name of the animation, for example "idle", "run", "emote.1234" or "anim.1234"
+     * @param name The name of the animation, for example "idle", "run", "emote.1234" or "id.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>;
@@ -3011,6 +3176,16 @@ export declare const ParticleEmitterShapeInOut: {
     InAndOut: number;
 };
 
+/**
+ * @category InstanceWrapper
+ */
+export declare class ParticleEmitterWrapper extends InstanceWrapper {
+    static className: string;
+    static requiredProperties: string[];
+    setup(): void;
+    Emit(count?: number): void;
+}
+
 /**@category DataModelEnum */
 export declare const ParticleFlipbookLayout: {
     None: number;
@@ -3133,6 +3308,10 @@ declare class QuantizedTransform {
     clone(): QuantizedTransform;
 }
 
+export declare const R15BodyPartNames: string[];
+
+export declare const R6BodyPartNames: string[];
+
 export declare function rad(degrees: number): number;
 
 /**
@@ -3261,23 +3440,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 */
@@ -3305,15 +3488,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
@@ -3352,7 +3535,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
@@ -3670,6 +3853,14 @@ export declare interface Search_Result {
     }[];
 }
 
+export declare function setupAccessoryCamera(accessoryModel: Instance, camera: Instance): void;
+
+export declare function setupBodyPartCamera(mannequin: Instance, faceRight: boolean, focusPartNames: string[], camera: Instance): void;
+
+export declare function setupCamera(camera: Instance, cameraOptions: CameraOptions): void;
+
+export declare function setupHeadCamera(headModel: Instance, camera: Instance): void;
+
 /**
  * Gives a scene the default appearance for thumbnails
  * @param renderScene RBXRenderScene to setup
@@ -3780,6 +3971,11 @@ export declare const StringBufferProperties: string[];
 
 declare type ThreePoseCorrective = Vec3;
 
+/**
+ * @deprecated Use new Thumbnails category instead
+ * @category ThumbnailGenerator */
+export declare type ThumbnailCameraType = "default" | "avatarHeadshot" | "avatarFullbody" | "fullbody";
+
 export declare class ThumbnailCustomization {
     thumbnailType: number;
     emoteAssetId: number;
@@ -3985,6 +4181,7 @@ export declare class Vector3 {
     normalize(): Vector3;
     clone(): Vector3;
     isSame(other: Vector3): boolean;
+    lerp(other: Vector3, t: number): Vector3;
     static new(X: number, Y: number, Z: number): Vector3;
 }