@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
205 lines (204 loc) • 10.2 kB
TypeScript
import { Box3, Camera, Color, DepthTexture, Euler, Layers, Material, Mesh, Object3D, Quaternion, Texture, Vector2Like, Vector3, WebGLRenderTarget } from "three";
import { ShaderMaterial, WebGLRenderer } 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 readonly planeGeometry;
private static readonly renderer;
private static readonly perspectiveCam;
private static readonly orthographicCam;
private static readonly scene;
private static readonly blitMaterial;
private static readonly 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;
static blit(src: Texture, target: WebGLRenderTarget, options?: {
renderer?: WebGLRenderer;
blitMaterial?: ShaderMaterial;
flipY?: boolean;
depthTexture?: DepthTexture | null;
depthTest?: boolean;
depthWrite?: boolean;
}): void;
/**
* 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 {};