@needle-tools/engine 2.38.0-pre.2 → 2.40.0-pre

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [2.40.0-pre] - 2022-11-05
+- Add support for deleting all room state by calling ``context.connection.sendDeleteRemoteStateAll()`` (requires backend to update ``@needle-tools/needle-tiny-networking-ws`` to ``^1.1.0-pre``)
+- Add Hinge joint
+- Add ``Gizmos.DrawLine``, ``DrawRay`` ``DrawWireSphere`` and ``DrawSphere``
+- Add: physics Collision Contacts now contain information about ``impulse`` and ``friction``
+- Add ``physics.raycastPhysicsFast`` as a first method to raycast against physics colliders, the returning object contains the point in worldspace and the collider. This is the most simplest and thus fastest way to raycast using Rapier. More complex options will follow in future versions.
+- Fix joint matrix calculation
+- Fix and improve physics Contacts point calculations  
+- Fix issue in physics event callbacks where ``onCollisionStay`` and ``onCollisionExit`` would only be called when ``onCollisionEnter`` was defined
+
+## [2.39.0-pre] - 2022-11-04
+- Add: physics FixedJoint
+- Change: CharacterController now rotates with camera
+- Change: scaled mesh colliders are now cached
+- Change: disable OrbitControls when in XR
+- Change: first enabled camera component sets itself as rendering camera if no camera is yet assigned (mainCamera still overrides that)
+- Change: package module field now shows to ``src/needle-engine``
+- Change: ``Camera.backgroundColor`` assigning Color without alpha sets alpha to 1 now
+- Fix: improved missing ``serializable`` detection / warning: now only shows warning for members actually declared in script 
+- Fix: wrong light intensity in VR when light is child of WebARSessionRoot [issue 103](https://github.com/needle-tools/needle-engine-support/issues/103) 
+
 ## [2.38.0-pre] - 2022-11-02
 - Add ``context.isInAR`` and ``context.isInVR`` properties
 - Add physics capsule collider support

package/dist/needle-engine.d.ts

@@ -48,6 +48,28 @@ declare module "engine/engine_physics.types" {
         All = -1
     }
 }
+declare module "engine/engine_three_utils" {
+    import * as THREE from "three";
+    import { Vector3 } from "three";
+    export function lookAtInverse(obj: THREE.Object3D, target: Vector3): void;
+    export function getWorldPosition(obj: THREE.Object3D, vec?: THREE.Vector3 | null, updateParents?: boolean): THREE.Vector3;
+    export function setWorldPosition(obj: THREE.Object3D, val: THREE.Vector3): void;
+    export function setWorldPositionXYZ(obj: THREE.Object3D, x: number, y: number, z: number): void;
+    export function getWorldQuaternion(obj: THREE.Object3D, target?: THREE.Quaternion | null): THREE.Quaternion;
+    export function setWorldQuaternion(obj: THREE.Object3D, val: THREE.Quaternion): void;
+    export function setWorldQuaternionXYZW(obj: THREE.Object3D, x: number, y: number, z: number, w: number): void;
+    export function getWorldScale(obj: THREE.Object3D, vec?: THREE.Vector3 | null): THREE.Vector3;
+    export function setWorldScale(obj: THREE.Object3D, vec: THREE.Vector3): void;
+    export function forward(obj: THREE.Object3D): THREE.Vector3;
+    export function getWorldEuler(obj: THREE.Object3D): THREE.Euler;
+    export function setWorldEuler(obj: THREE.Object3D, val: THREE.Euler): void;
+    export function getWorldRotation(obj: THREE.Object3D): THREE.Vector3;
+    export function setWorldRotation(obj: THREE.Object3D, val: THREE.Vector3): void;
+    export function setWorldRotationXYZ(obj: THREE.Object3D, x: number, y: number, z: number, degrees?: boolean): void;
+    export function logHierarchy(root: THREE.Object3D | null | undefined, collapsible?: boolean): void;
+    export function copyTexture(texture: THREE.Texture): THREE.Texture;
+    export function textureToCanvas(texture: THREE.Texture, force?: boolean): HTMLCanvasElement | null;
+}
 declare module "engine/engine_types" {
     import { Camera, Color, Material, Object3D, Vector3, Quaternion } from "three";
     import { RGBAColor } from "engine-components/js-extensions/RGBAColor";
@@ -160,20 +182,26 @@ declare module "engine/engine_types" {
     export type ICollisionContext = {
         getCollider(obj: Object3D): ICollider;
     };
-    export type Vec3 = {
+    export type Vec2 = {
         x: number;
         y: number;
-        z: number;
     };
-    export type Vec2 = {
+    export type Vec3 = {
         x: number;
         y: number;
+        z: number;
     };
     export class ContactPoint {
-        readonly localPoint: Vec3;
+        private readonly _point;
+        private readonly _normal;
         readonly distance: number;
-        readonly normal: Vec3;
-        constructor(localPt: Vec3, dist: number, normal: Vec3);
+        readonly impulse: number;
+        readonly friction: number;
+        /** worldspace point */
+        get point(): Vector3;
+        /** worldspace normal */
+        get normal(): Vector3;
+        constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number);
     }
     export class Collision {
         readonly contacts: ContactPoint[];
@@ -194,6 +222,14 @@ declare module "engine/engine_utils" {
     export const nameofFactory: <T>() => (name: keyof T) => keyof T;
     export function nameof<T>(name: keyof T): keyof T;
     export function isDebugMode(): boolean;
+    export class CircularBuffer<T> {
+        private _factory;
+        private _cache;
+        private _maxSize;
+        private _index;
+        constructor(factory: () => T, maxSize: number);
+        get(): T;
+    }
     export function getUrlParams(): URLSearchParams;
     export function getParam(paramName: string): string | boolean;
     export function setParam(paramName: string, paramValue: string): void;
@@ -346,6 +382,14 @@ declare module "engine/engine_serialization_core" {
     export interface ITypeInformation {
         type?: Constructor<any>;
     }
+    /** holds information if a field was undefined before serialization. This gives us info if we might want to warn the user about missing attributes */
+    export class ImplementationInformation {
+        private isDevMode;
+        private cache;
+        /** only call when assigning values for the very first time */
+        registerDefinedKeys(typeName: string, type: object): void;
+        getDefinedKey(typeName: string, key: string): boolean;
+    }
     export class SerializationContext {
         root: THREE.Object3D;
         gltf?: GLTF;
@@ -357,6 +401,8 @@ declare module "engine/engine_serialization_core" {
         objectToNode?: ObjectToNodeMap;
         context?: Context;
         path?: string;
+        /** holds information if a field was undefined before serialization. This gives us info if we might want to warn the user about missing attributes */
+        implementationInformation?: ImplementationInformation;
         constructor(root: THREE.Object3D);
     }
     export interface ISerializable {
@@ -374,11 +420,12 @@ declare module "engine/engine_serialization_core" {
      * Used for validate decorator to not invoke callbacks on components that are currently in the process of being built */
     export const $isAssigningProperties: unique symbol;
     /** Object.assign behaviour but check if property is writeable (e.g. getter only properties are skipped) */
-    export function assign(target: any, source: any): void;
+    export function assign(target: any, source: any, info?: ImplementationInformation): void;
 }
 declare module "engine/engine_input" {
     import * as THREE from 'three';
     import { Context } from "engine/engine_setup";
+    import { Vec2 } from "engine/engine_types";
     export type PointerEventArgs = {
         button: number;
         clientX: number;
@@ -460,6 +507,7 @@ declare module "engine/engine_input" {
         createPointerDown(args: PointerEventArgs): void;
         createPointerMove(args: PointerEventArgs): void;
         createPointerUp(args: PointerEventArgs): void;
+        convertScreenspaceToRaycastSpace(vec2: Vec2): void;
         constructor(context: Context);
         private onLostFocus;
         private onEndOfFrame;
@@ -570,28 +618,6 @@ declare module "engine/engine_input" {
         F12 = "F12"
     }
 }
-declare module "engine/engine_three_utils" {
-    import * as THREE from "three";
-    import { Vector3 } from "three";
-    export function lookAtInverse(obj: THREE.Object3D, target: Vector3): void;
-    export function getWorldPosition(obj: THREE.Object3D, vec?: THREE.Vector3 | null, updateParents?: boolean): THREE.Vector3;
-    export function setWorldPosition(obj: THREE.Object3D, val: THREE.Vector3): void;
-    export function setWorldPositionXYZ(obj: THREE.Object3D, x: number, y: number, z: number): void;
-    export function getWorldQuaternion(obj: THREE.Object3D, target?: THREE.Quaternion | null): THREE.Quaternion;
-    export function setWorldQuaternion(obj: THREE.Object3D, val: THREE.Quaternion): void;
-    export function setWorldQuaternionXYZW(obj: THREE.Object3D, x: number, y: number, z: number, w: number): void;
-    export function getWorldScale(obj: THREE.Object3D, vec?: THREE.Vector3 | null): THREE.Vector3;
-    export function setWorldScale(obj: THREE.Object3D, vec: THREE.Vector3): void;
-    export function forward(obj: THREE.Object3D): THREE.Vector3;
-    export function getWorldEuler(obj: THREE.Object3D): THREE.Euler;
-    export function setWorldEuler(obj: THREE.Object3D, val: THREE.Euler): void;
-    export function getWorldRotation(obj: THREE.Object3D): THREE.Vector3;
-    export function setWorldRotation(obj: THREE.Object3D, val: THREE.Vector3): void;
-    export function setWorldRotationXYZ(obj: THREE.Object3D, x: number, y: number, z: number, degrees?: boolean): void;
-    export function logHierarchy(root: THREE.Object3D | null | undefined, collapsible?: boolean): void;
-    export function copyTexture(texture: THREE.Texture): THREE.Texture;
-    export function textureToCanvas(texture: THREE.Texture, force?: boolean): HTMLCanvasElement | null;
-}
 declare module "engine/engine_instancing" {
     export const NEED_UPDATE_INSTANCE_KEY: unique symbol;
     export class InstancingUtil {
@@ -739,7 +765,7 @@ declare module "engine/engine_gameobject" {
 declare module "engine/engine_physics" {
     import { Camera, Intersection, Layers, Mesh, Object3D, Ray, Raycaster, Vector2, Vector3 } from 'three';
     import { Context } from "engine/engine_setup";
-    import { IComponent, ICollider, IRigidbody } from "engine/engine_types";
+    import { IComponent, ICollider, IRigidbody, Vec3, Vec2 } from "engine/engine_types";
     import RAPIER, { RigidBody } from '@dimforge/rapier3d-compat';
     export type Rapier = typeof RAPIER;
     export class RaycastOptions {
@@ -776,7 +802,19 @@ declare module "engine/engine_physics" {
         private tempBoundingBox;
         private onSphereOverlap;
         raycastFromRay(ray: Ray, options?: RaycastOptions | null): Array<Intersection>;
+        /** raycast against rendered three objects. This might be very slow depending on your scene complexity.
+         * We recommend setting objects to IgnoreRaycast layer (2) when you don't need them to be raycasted.
+         * Raycasting SkinnedMeshes is specially expensive.
+         */
         raycast(options?: RaycastOptions | null): Array<Intersection>;
+        private rapierRay;
+        private raycastVectorsBuffer;
+        /** raycast against colliders */
+        raycastPhysicsFast(origin: Vec2 | Vec3, direction?: Vec3 | undefined, maxDistance?: number, solid?: boolean): null | {
+            point: Vector3;
+            collider: ICollider;
+        };
+        private getPhysicsRay;
         private _tempPosition;
         private _tempQuaternion;
         private _tempScale;
@@ -817,11 +855,17 @@ declare module "engine/engine_physics" {
         private getRigidbodyRelativeMatrix;
         private static centerConnectionPos;
         private static centerConnectionRot;
-        addFixedJoint(body1: IRigidbody, body2: IRigidbody, rel: {
+        addFixedJoint(body1: IRigidbody, body2: IRigidbody): void;
+        addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: {
+            x: number;
+            y: number;
+            z: number;
+        }, axis: {
             x: number;
             y: number;
             z: number;
         }): void;
+        private calculateJointRelativeMatrices;
     }
 }
 declare module "engine/engine_time" {
@@ -1014,6 +1058,7 @@ declare module "engine/engine_networking" {
         leaveRoom(room?: string | null): void;
         send(key: string | OwnershipEvent, data?: IModel | object | boolean | null | string | number, queue?: SendQueue): void;
         sendDeleteRemoteState(guid: string): void;
+        sendDeleteRemoteStateAll(): void;
         sendBinary(bin: Uint8Array): void;
         private _defaultMessagesBuffer;
         private _defaultMessagesBufferArray;
@@ -1272,10 +1317,15 @@ declare module "engine-components/Component" {
         sourceId?: SourceIdentifier;
         /** called on a component with a map of old to new guids (e.g. when instantiate generated new guids and e.g. timeline track bindings needs to remape them) */
         resolveGuids?(guidsMap: GuidsMap): void;
+        /** called once when the component becomes active for the first time */
         awake(): void;
+        /** called every time when the component gets enabled (this is invoked after awake and before start) */
         onEnable(): void;
         onDisable(): void;
         onDestroy(): void;
+        /** called when you decorate fields with the @validate() decorator
+         * @param field the name of the field that was changed
+         */
         onValidate?(prop?: string): void;
         start?(): void;
         earlyUpdate?(): void;
@@ -1293,18 +1343,31 @@ declare module "engine-components/Component" {
         stopCoroutine(routine: Generator, evt?: FrameEvent): void;
         get destroyed(): boolean;
         destroy(): void;
+        /** @internal */
         protected __didAwake: boolean;
+        /** @internal */
         private __didStart;
+        /** @internal */
         protected __didEnable: boolean;
+        /** @internal */
         protected __isEnabled: boolean | undefined;
+        /** @internal */
         private __destroyed;
+        /** @internal */
         get __internalDidAwakeAndStart(): boolean;
+        /** @internal */
         constructor();
+        /** @internal */
         __internalNewInstanceCreated(): void;
+        /** @internal */
         __internalAwake(): void;
+        /** @internal */
         __internalStart(): void;
+        /** @internal */
         __internalEnable(): boolean;
+        /** @internal */
         __internalDisable(): void;
+        /** @internal */
         __internalDestroy(): void;
         get enabled(): boolean;
         set enabled(val: boolean);
@@ -2371,6 +2434,34 @@ declare module "engine/engine_util_decorator" {
     /** create accessor callbacks for a field */
     export const validate: (set?: setter, get?: getter) => (target: IComponent | any, propertyKey: string, descriptor?: undefined) => void;
 }
+declare module "engine/engine_gizmos" {
+    import * as THREE from 'three';
+    import { ColorRepresentation } from 'three';
+    import { Vec3 } from "engine/engine_types";
+    export class Gizmos {
+        static DrawRay(origin: Vec3, dir: Vec3, color?: ColorRepresentation, duration?: number, depthTest?: boolean): void;
+        static DrawLine(pt0: {
+            x: number;
+            y: number;
+            z: number;
+        }, pt1: {
+            x: number;
+            y: number;
+            z: number;
+        }, color?: ColorRepresentation, duration?: number, depthTest?: boolean): void;
+        static DrawWireSphere(center: {
+            x: number;
+            y: number;
+            z: number;
+        }, radius: number, color?: ColorRepresentation, duration?: number, depthTest?: boolean): void;
+        static DrawSphere(center: {
+            x: number;
+            y: number;
+            z: number;
+        }, radius: number, color?: ColorRepresentation, duration?: number, depthTest?: boolean): void;
+    }
+    export function CreateWireCube(col?: THREE.ColorRepresentation | null): THREE.LineSegments;
+}
 declare module "engine/api" {
     export { InstancingUtil } from "engine/engine_instancing";
     export * from "engine/engine_gameobject";
@@ -2379,6 +2470,7 @@ declare module "engine/api" {
     export { FrameEvent } from "engine/engine_setup";
     export * from "engine/debug/debug";
     export { validate } from "engine/engine_util_decorator";
+    export { Gizmos } from "engine/engine_gizmos";
 }
 declare module "engine-components/AlignmentConstraint" {
     import { Behaviour } from "engine-components/Component";
@@ -2566,10 +2658,6 @@ declare module "engine-components/BasicIKConstraint" {
         update(): void;
     }
 }
-declare module "engine/engine_gizmos" {
-    import * as THREE from 'three';
-    export function CreateWireCube(col?: THREE.ColorRepresentation | null): THREE.LineSegments;
-}
 declare module "engine-components/BoxHelperComponent" {
     import { Behaviour } from "engine-components/Component";
     import * as THREE from "three";
@@ -3917,7 +4005,6 @@ declare module "engine-components/Joints" {
         connectedBody?: Rigidbody;
         get rigidBody(): Rigidbody | null;
         private _rigidBody;
-        connectedAnchor?: Vector3;
         onEnable(): void;
         private create;
         protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
@@ -3925,6 +4012,11 @@ declare module "engine-components/Joints" {
     export class FixedJoint extends Joint {
         protected createJoint(self: Rigidbody, other: Rigidbody): void;
     }
+    export class HingeJoint extends Joint {
+        anchor?: Vector3;
+        axis?: Vector3;
+        protected createJoint(self: Rigidbody, other: Rigidbody): void;
+    }
 }
 declare module "engine-components/Light" {
     import { Behaviour } from "engine-components/Component";
@@ -5453,6 +5545,7 @@ declare module "engine-components/codegen/components" {
     export { Interactable } from "engine-components/Interactable";
     export { UsageMarker } from "engine-components/Interactable";
     export { FixedJoint } from "engine-components/Joints";
+    export { HingeJoint } from "engine-components/Joints";
     export { Light } from "engine-components/Light";
     export { LODModel } from "engine-components/LODGroup";
     export { LODGroup } from "engine-components/LODGroup";