@needle-tools/engine 4.4.0-beta → 4.4.0-ci.0

package/lib/engine/engine_three_utils.d.ts

@@ -1,201 +1,201 @@
-import { Box3, Camera, Color, Euler, Layers, Material, Mesh, Object3D, Quaternion, Texture, Vector2Like, Vector3 } from "three";
-import { ShaderMaterial } from "three";
-import { Vec3 } from "./engine_types.js";
-/**
- * Slerp between two vectors
- */
-export declare function slerp(vec: Vector3, end: Vector3, t: number): Vector3;
-export declare function lookAtInverse(obj: Object3D, target: Vector3): void;
-/** Better lookAt
- * @param object the object that the lookAt should be applied to
- * @param target the target to look at
- * @param keepUpDirection if true the up direction will be kept
- * @param copyTargetRotation if true the target rotation will be copied so the rotation is not skewed
- */
-export declare function lookAtObject(object: Object3D, target: Object3D, keepUpDirection?: boolean, copyTargetRotation?: boolean): void;
-/**
- * Look at a 2D point in screen space
- * @param object the object to look at the point
- * @param target the target point in 2D screen space XY e.g. from a mouse event
- * @param camera the camera to use for the lookAt
- * @param factor the factor to multiply the distance from the camera to the object. Default is 1
- * @returns the target point in world space
- *
- * @example Needle Engine Component
- * ```ts
- * export class MyLookAtComponent extends Behaviour {
- *   update() {
- *     lookAtScreenPoint(this.gameObject, this.context.input.mousePosition, this.context.mainCamera);
- *   }
- * }
- * ```
- *
- * @example Look at from browser mouse move event
- * ```ts
- * window.addEventListener("mousemove", (e) => {
- *   lookAtScreenPoint(object, new Vector2(e.clientX, e.clientY), camera);
- *  });
- * ```
- */
-export declare function lookAtScreenPoint(object: Object3D, target: Vector2Like, camera: Camera, factor?: number): Vector3 | null;
-/** Gets a temporary vector. If a vector is passed in it will be copied to the temporary vector
- * Temporary vectors are cached and reused internally. Don't store them!
- * @param vec3 the vector to copy or the x value
- * @param y the y value
- * @param z the z value
- * @returns a temporary vector
- *
- * @example
- * ``` javascript
- * const vec = getTempVector(1, 2, 3);
- * const vec2 = getTempVector(vec);
- * const vec3 = getTempVector(new Vector3(1, 2, 3));
- * const vec4 = getTempVector(new DOMPointReadOnly(1, 2, 3));
- * const vec5 = getTempVector();
- * ```
- */
-export declare function getTempVector(): Vector3;
-export declare function getTempVector(vec3: Vector3): Vector3;
-export declare function getTempVector(vec3: [number, number, number]): Vector3;
-export declare function getTempVector(vec3: Vec3): Vector3;
-export declare function getTempVector(dom: DOMPointReadOnly): Vector3;
-export declare function getTempVector(x: number): Vector3;
-export declare function getTempVector(x: number, y: number, z: number): Vector3;
-export declare function getTempColor(color?: Color): Color;
-/**
- * Gets a temporary quaternion. If a quaternion is passed in it will be copied to the temporary quaternion
- * Temporary quaternions are cached and reused internally. Don't store them!
- * @param value the quaternion to copy
- * @returns a temporary quaternion
- */
-export declare function getTempQuaternion(value?: Quaternion | DOMPointReadOnly): Quaternion;
-/**
- * Get the world position of an object
- * @param obj the object to get the world position from
- * @param vec a vector to store the result in. If not passed in a temporary vector will be used
- * @param updateParents if true the parents will be updated before getting the world position
- * @returns the world position
- */
-export declare function getWorldPosition(obj: Object3D, vec?: Vector3 | null, updateParents?: boolean): Vector3;
-/**
- * Set the world position of an object
- * @param obj the object to set the world position of
- * @param val the world position to set
- */
-export declare function setWorldPosition(obj: Object3D, val: Vector3): Object3D;
-/**
- * Set the world position of an object
- * @param obj the object to set the world position of
- * @param x the x position
- * @param y the y position
- * @param z the z position
- */
-export declare function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number): Object3D;
-export declare function getWorldQuaternion(obj: Object3D, target?: Quaternion | null): Quaternion;
-export declare function setWorldQuaternion(obj: Object3D, val: Quaternion): void;
-export declare function setWorldQuaternionXYZW(obj: Object3D, x: number, y: number, z: number, w: number): void;
-export declare function getWorldScale(obj: Object3D, vec?: Vector3 | null): Vector3;
-export declare function setWorldScale(obj: Object3D, vec: Vector3): void;
-export declare function forward(obj: Object3D): Vector3;
-/** Get the world direction. Returns world forward if nothing is passed in.
- * Pass in a relative direction to get it converted to world space (e.g. dir = new Vector3(0, 1, 1))
- * The returned vector will not be normalized
- */
-export declare function getWorldDirection(obj: Object3D, dir?: Vector3): Vector3;
-export declare function getWorldEuler(obj: Object3D): Euler;
-export declare function setWorldEuler(obj: Object3D, val: Euler): void;
-export declare function getWorldRotation(obj: Object3D): Vector3;
-export declare function setWorldRotation(obj: Object3D, val: Vector3): void;
-export declare function setWorldRotationXYZ(obj: Object3D, x: number, y: number, z: number, degrees?: boolean): void;
-export declare function logHierarchy(root: Object3D | null | undefined, collapsible?: boolean): void;
-export declare function getParentHierarchyPath(obj: Object3D): string;
-export declare function isAnimationAction(obj: object): boolean;
-/**
- * Utility class to perform various graphics operations like copying textures to canvas
- */
-export declare class Graphics {
-    private static planeGeometry;
-    private static renderer;
-    private static perspectiveCam;
-    private static scene;
-    private static readonly vertex;
-    private static readonly fragment;
-    private static blitMaterial;
-    /**
-     * Create a blit material for copying textures
-     */
-    static createBlitMaterial(fragment: string): ShaderMaterial;
-    private static mesh;
-    /**
-     * Copy a texture to a new texture
-     * @param texture the texture to copy
-     * @param blitMaterial the material to use for copying (optional)
-     * @returns the newly created, copied texture
-    */
-    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial): Texture;
-    /**
-     * Copy a texture to a HTMLCanvasElement
-     * @param texture the texture convert
-     * @param force if true the texture will be copied to a new texture before converting
-     * @returns the HTMLCanvasElement with the texture or null if the texture could not be copied
-     */
-    static textureToCanvas(texture: Texture, force?: boolean): HTMLCanvasElement | null;
-}
-/**@obsolete use Graphics.copyTexture */
-export declare function copyTexture(texture: Texture): Texture;
-/**@obsolete use Graphics.textureToCanvas */
-export declare function textureToCanvas(texture: Texture, force?: boolean): HTMLCanvasElement | null;
-export declare function setVisibleInCustomShadowRendering(obj: Object3D, enabled: boolean): void;
-export declare function getVisibleInCustomShadowRendering(obj: Object3D): boolean;
-/**
- * Get the axis-aligned bounding box of a list of objects.
- * @param objects The objects to get the bounding box from.
- * @param ignore Objects to ignore when calculating the bounding box. Objects that are invisible (gizmos, helpers, etc.) are excluded by default.
- * @param layers The layers to include. Typically the main camera's layers.
- * @param result The result box to store the bounding box in. Returns a new box if not passed in.
- */
-export declare function getBoundingBox(objects: Object3D | Object3D[], ignore?: ((obj: Object3D) => void | boolean) | Array<Object3D | null | undefined> | undefined, layers?: Layers | undefined | null, result?: Box3 | undefined): Box3;
-/**
- * Fits an object into a bounding volume. The volume is defined by a Box3 in world space.
- * @param obj the object to fit
- * @param volume the volume to fit the object into
- * @param opts options for fitting
- */
-export declare function fitObjectIntoVolume(obj: Object3D, volume: Box3, opts?: {
-    /** Objects to ignore when calculating the obj's bounding box */
-    ignore?: Object3D[];
-    /** when `true` aligns the objects position to the volume ground
-     * @default true
-    */
-    position?: boolean;
-    /** when `true` scales the object to fit the volume
-     * @default true
-    */
-    scale?: boolean;
-}): {
-    /** The object's bounding box before fitting */
-    boundsBefore: Box3;
-    /** The scale that was applied to the object */
-    scale: Vector3;
-};
-declare type PlaceOnSurfaceResult = {
-    /** The offset from the object bounds to the pivot */
-    offset: Vector3;
-    /** The object's bounding box */
-    bounds: Box3;
-};
-/**
- * Place an object on a surface. This will calculate the object bounds which might be an expensive operation for complex objects.
- * The object will be visually placed on the surface (the object's pivot will be ignored).
- * @param obj the object to place on the surface
- * @param point the point to place the object on
- * @returns the offset from the object bounds to the pivot
- */
-export declare function placeOnSurface(obj: Object3D, point: Vector3): PlaceOnSurfaceResult;
-/**
- * Postprocesses the material of an object loaded by {@link FBXLoader}.
- * It will apply necessary color conversions, remap shininess to roughness, and turn everything into {@link MeshStandardMaterial} on the object.
- * This ensures consistent lighting and shading, including environment effects.
- */
-export declare function postprocessFBXMaterials(obj: Mesh, material: Material | Material[], index?: number, array?: Material[]): boolean;
-export {};
+import { Box3, Camera, Color, Euler, Layers, Material, Mesh, Object3D, Quaternion, Texture, Vector2Like, Vector3 } from "three";
+import { ShaderMaterial } from "three";
+import { Vec3 } from "./engine_types.js";
+/**
+ * Slerp between two vectors
+ */
+export declare function slerp(vec: Vector3, end: Vector3, t: number): Vector3;
+export declare function lookAtInverse(obj: Object3D, target: Vector3): void;
+/** Better lookAt
+ * @param object the object that the lookAt should be applied to
+ * @param target the target to look at
+ * @param keepUpDirection if true the up direction will be kept
+ * @param copyTargetRotation if true the target rotation will be copied so the rotation is not skewed
+ */
+export declare function lookAtObject(object: Object3D, target: Object3D, keepUpDirection?: boolean, copyTargetRotation?: boolean): void;
+/**
+ * Look at a 2D point in screen space
+ * @param object the object to look at the point
+ * @param target the target point in 2D screen space XY e.g. from a mouse event
+ * @param camera the camera to use for the lookAt
+ * @param factor the factor to multiply the distance from the camera to the object. Default is 1
+ * @returns the target point in world space
+ *
+ * @example Needle Engine Component
+ * ```ts
+ * export class MyLookAtComponent extends Behaviour {
+ *   update() {
+ *     lookAtScreenPoint(this.gameObject, this.context.input.mousePosition, this.context.mainCamera);
+ *   }
+ * }
+ * ```
+ *
+ * @example Look at from browser mouse move event
+ * ```ts
+ * window.addEventListener("mousemove", (e) => {
+ *   lookAtScreenPoint(object, new Vector2(e.clientX, e.clientY), camera);
+ *  });
+ * ```
+ */
+export declare function lookAtScreenPoint(object: Object3D, target: Vector2Like, camera: Camera, factor?: number): Vector3 | null;
+/** Gets a temporary vector. If a vector is passed in it will be copied to the temporary vector
+ * Temporary vectors are cached and reused internally. Don't store them!
+ * @param vec3 the vector to copy or the x value
+ * @param y the y value
+ * @param z the z value
+ * @returns a temporary vector
+ *
+ * @example
+ * ``` javascript
+ * const vec = getTempVector(1, 2, 3);
+ * const vec2 = getTempVector(vec);
+ * const vec3 = getTempVector(new Vector3(1, 2, 3));
+ * const vec4 = getTempVector(new DOMPointReadOnly(1, 2, 3));
+ * const vec5 = getTempVector();
+ * ```
+ */
+export declare function getTempVector(): Vector3;
+export declare function getTempVector(vec3: Vector3): Vector3;
+export declare function getTempVector(vec3: [number, number, number]): Vector3;
+export declare function getTempVector(vec3: Vec3): Vector3;
+export declare function getTempVector(dom: DOMPointReadOnly): Vector3;
+export declare function getTempVector(x: number): Vector3;
+export declare function getTempVector(x: number, y: number, z: number): Vector3;
+export declare function getTempColor(color?: Color): Color;
+/**
+ * Gets a temporary quaternion. If a quaternion is passed in it will be copied to the temporary quaternion
+ * Temporary quaternions are cached and reused internally. Don't store them!
+ * @param value the quaternion to copy
+ * @returns a temporary quaternion
+ */
+export declare function getTempQuaternion(value?: Quaternion | DOMPointReadOnly): Quaternion;
+/**
+ * Get the world position of an object
+ * @param obj the object to get the world position from
+ * @param vec a vector to store the result in. If not passed in a temporary vector will be used
+ * @param updateParents if true the parents will be updated before getting the world position
+ * @returns the world position
+ */
+export declare function getWorldPosition(obj: Object3D, vec?: Vector3 | null, updateParents?: boolean): Vector3;
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param val the world position to set
+ */
+export declare function setWorldPosition(obj: Object3D, val: Vector3): Object3D;
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param x the x position
+ * @param y the y position
+ * @param z the z position
+ */
+export declare function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number): Object3D;
+export declare function getWorldQuaternion(obj: Object3D, target?: Quaternion | null): Quaternion;
+export declare function setWorldQuaternion(obj: Object3D, val: Quaternion): void;
+export declare function setWorldQuaternionXYZW(obj: Object3D, x: number, y: number, z: number, w: number): void;
+export declare function getWorldScale(obj: Object3D, vec?: Vector3 | null): Vector3;
+export declare function setWorldScale(obj: Object3D, vec: Vector3): void;
+export declare function forward(obj: Object3D): Vector3;
+/** Get the world direction. Returns world forward if nothing is passed in.
+ * Pass in a relative direction to get it converted to world space (e.g. dir = new Vector3(0, 1, 1))
+ * The returned vector will not be normalized
+ */
+export declare function getWorldDirection(obj: Object3D, dir?: Vector3): Vector3;
+export declare function getWorldEuler(obj: Object3D): Euler;
+export declare function setWorldEuler(obj: Object3D, val: Euler): void;
+export declare function getWorldRotation(obj: Object3D): Vector3;
+export declare function setWorldRotation(obj: Object3D, val: Vector3): void;
+export declare function setWorldRotationXYZ(obj: Object3D, x: number, y: number, z: number, degrees?: boolean): void;
+export declare function logHierarchy(root: Object3D | null | undefined, collapsible?: boolean): void;
+export declare function getParentHierarchyPath(obj: Object3D): string;
+export declare function isAnimationAction(obj: object): boolean;
+/**
+ * Utility class to perform various graphics operations like copying textures to canvas
+ */
+export declare class Graphics {
+    private static planeGeometry;
+    private static renderer;
+    private static perspectiveCam;
+    private static scene;
+    private static readonly vertex;
+    private static readonly fragment;
+    private static blitMaterial;
+    /**
+     * Create a blit material for copying textures
+     */
+    static createBlitMaterial(fragment: string): ShaderMaterial;
+    private static mesh;
+    /**
+     * Copy a texture to a new texture
+     * @param texture the texture to copy
+     * @param blitMaterial the material to use for copying (optional)
+     * @returns the newly created, copied texture
+    */
+    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial): Texture;
+    /**
+     * Copy a texture to a HTMLCanvasElement
+     * @param texture the texture convert
+     * @param force if true the texture will be copied to a new texture before converting
+     * @returns the HTMLCanvasElement with the texture or null if the texture could not be copied
+     */
+    static textureToCanvas(texture: Texture, force?: boolean): HTMLCanvasElement | null;
+}
+/**@obsolete use Graphics.copyTexture */
+export declare function copyTexture(texture: Texture): Texture;
+/**@obsolete use Graphics.textureToCanvas */
+export declare function textureToCanvas(texture: Texture, force?: boolean): HTMLCanvasElement | null;
+export declare function setVisibleInCustomShadowRendering(obj: Object3D, enabled: boolean): void;
+export declare function getVisibleInCustomShadowRendering(obj: Object3D): boolean;
+/**
+ * Get the axis-aligned bounding box of a list of objects.
+ * @param objects The objects to get the bounding box from.
+ * @param ignore Objects to ignore when calculating the bounding box. Objects that are invisible (gizmos, helpers, etc.) are excluded by default.
+ * @param layers The layers to include. Typically the main camera's layers.
+ * @param result The result box to store the bounding box in. Returns a new box if not passed in.
+ */
+export declare function getBoundingBox(objects: Object3D | Object3D[], ignore?: ((obj: Object3D) => void | boolean) | Array<Object3D | null | undefined> | undefined, layers?: Layers | undefined | null, result?: Box3 | undefined): Box3;
+/**
+ * Fits an object into a bounding volume. The volume is defined by a Box3 in world space.
+ * @param obj the object to fit
+ * @param volume the volume to fit the object into
+ * @param opts options for fitting
+ */
+export declare function fitObjectIntoVolume(obj: Object3D, volume: Box3, opts?: {
+    /** Objects to ignore when calculating the obj's bounding box */
+    ignore?: Object3D[];
+    /** when `true` aligns the objects position to the volume ground
+     * @default true
+    */
+    position?: boolean;
+    /** when `true` scales the object to fit the volume
+     * @default true
+    */
+    scale?: boolean;
+}): {
+    /** The object's bounding box before fitting */
+    boundsBefore: Box3;
+    /** The scale that was applied to the object */
+    scale: Vector3;
+};
+declare type PlaceOnSurfaceResult = {
+    /** The offset from the object bounds to the pivot */
+    offset: Vector3;
+    /** The object's bounding box */
+    bounds: Box3;
+};
+/**
+ * Place an object on a surface. This will calculate the object bounds which might be an expensive operation for complex objects.
+ * The object will be visually placed on the surface (the object's pivot will be ignored).
+ * @param obj the object to place on the surface
+ * @param point the point to place the object on
+ * @returns the offset from the object bounds to the pivot
+ */
+export declare function placeOnSurface(obj: Object3D, point: Vector3): PlaceOnSurfaceResult;
+/**
+ * Postprocesses the material of an object loaded by {@link FBXLoader}.
+ * It will apply necessary color conversions, remap shininess to roughness, and turn everything into {@link MeshStandardMaterial} on the object.
+ * This ensures consistent lighting and shading, including environment effects.
+ */
+export declare function postprocessFBXMaterials(obj: Mesh, material: Material | Material[], index?: number, array?: Material[]): boolean;
+export {};