@needle-tools/engine 3.28.7-beta → 3.28.7-beta.1

package/src/engine/engine_types.ts

@@ -1,489 +1,489 @@
-import { RenderTexture } from "./engine_texture.js";
-import type { Camera, Color, Material, Object3D, Quaternion, Ray, Scene, WebGLRenderer, Mesh } from "three";
-import { Vector3 } from "three";
-import { RGBAColor } from "../engine-components/js-extensions/RGBAColor.js";
-import { CollisionDetectionMode, type PhysicsMaterial, RigidbodyConstraints } from "./engine_physics.types.js";
-import { CircularBuffer } from "./engine_utils.js";
-import { type GLTF as GLTF3 } from "three/examples/jsm/loaders/GLTFLoader.js";
-
-export type GLTF = GLTF3 & {
-    // asset: { generator: string, version: string }
-    // animations: AnimationClip[];
-    // cameras: Camera[];
-    // scene: Object3D;
-    // scenes: Object3D[];
-    // userData: object;
-    // parser: any;
-}
-
-export type LoadedGLTF = {
-    src: string;
-    file: GLTF;
-}
-
-/** used to find data registered via gltf files e.g. find lightmaps for a Renderer component that were shipped inside a gltf */
-export declare type SourceIdentifier = string;
-
-// TODO: figure out what is best here!
-// https://stackoverflow.com/a/67229348
-// https://stackoverflow.com/questions/36886082/abstract-constructor-type-in-typescript
-// type Constructor<T> = Function & { prototype: T } // << this includes abstract constructor types
-export type Constructor<T> = abstract new (...args: any[]) => T; // abstract to support @serializable and also getComponent with abstract types
-export type ConstructorConcrete<T> = new (...args: any[]) => T;
-export type GuidsMap = { [key: string]: string };
-
-export interface UIDProvider {
-    seed: number;
-    generateUUID(): string;
-}
-
-export declare type CoroutineData = {
-    comp: IComponent,
-    main: Generator,
-    chained?: Array<Generator>
-}
-
-export interface ITime {
-    get time(): number;
-}
-
-export interface IInput {
-    convertScreenspaceToRaycastSpace(vec: Vec2): void;
-    getPointerPosition(i: number): Vec2 | null;
-}
-
-export interface IPhysics {
-    engine?: IPhysicsEngine;
-}
-
-export interface IContext {
-    alias?: string | null;
-    hash?: string;
-
-    scene: Scene;
-    renderer: WebGLRenderer;
-    mainCamera: Camera | null;
-    mainCameraComponent: ICamera | undefined;
-    domElement: HTMLElement;
-
-    time: ITime;
-    input: IInput;
-    physics: IPhysics;
-
-    scripts: IComponent[];
-    scripts_pausedChanged: IComponent[];
-    // scripts with update event
-    scripts_earlyUpdate: IComponent[];
-    scripts_update: IComponent[];
-    scripts_lateUpdate: IComponent[];
-    scripts_onBeforeRender: IComponent[];
-    scripts_onAfterRender: IComponent[];
-    scripts_WithCorroutines: IComponent[];
-    coroutines: { [FrameEvent: number]: Array<CoroutineData> };
-
-    post_setup_callbacks: Function[];
-    pre_update_callbacks: Function[];
-    pre_render_callbacks: Function[];
-    post_render_callbacks: Function[];
-
-    new_scripts: IComponent[];
-    new_script_start: IComponent[];
-    new_scripts_pre_setup_callbacks: Function[];
-    new_scripts_post_setup_callbacks: Function[];
-
-    stopAllCoroutinesFrom(script: IComponent);
-}
-
-export declare interface INeedleEngineComponent extends HTMLElement {
-    getAROverlayContainer(): HTMLElement;
-    onEnterAR(session: XRSession, overlayContainer: HTMLElement);
-    onExitAR(session: XRSession);
-}
-
-export declare interface IGameObject extends Object3D {
-
-    /** the object's unique identifier */
-    guid: string | undefined;
-
-    /** if the object is enabled in the hierarchy (usually equivalent to `visible`) */
-    activeSelf: boolean;
-
-    /** call to destroy this object including all components that are attached to it. Will destroy all children recursively */
-    destroy(): void;
-
-    /** NOTE: this is just a wrapper for devs coming from Unity. Please use this.gameObject instead. In Needle Engine this.gameObject is the same as this.gameObject.transform. See the tutorial link below for more information
-     * @augments Object3D
-     * @tutorial https://fwd.needle.tools/needle-engine/docs/transform
-     * */
-    get transform(): IGameObject;
-
-    /** Add a new component to this object. Expects a component type (e.g. `addNewComponent(Animator)`) */
-    addNewComponent<T>(type: Constructor<T>): T | null;
-    /** Remove a component from this object. Expected a component instance
-     * @returns the removed component (equal to the passed in component)
-     */
-    removeComponent(comp: IComponent): IComponent;
-    /** Searches for a component type on this object. If no component of the searched type exists yet a new instance will be created and returned */
-    getOrAddComponent<T>(typeName: Constructor<T> | null): T;
-    /** Tries to find a component of a type on this object. 
-     * @returns the first instance of a component on this object that matches the passed in type or null if no component of this type (or a subtype) exists */
-    getComponent<T>(type: Constructor<T>): T | null;
-    /** @returns all components of a certain type on this object */
-    getComponents<T>(type: Constructor<T>, arr?: T[]): Array<T>;
-    /** Finds a component of a certain type on this object OR a child object if any exists */
-    getComponentInChildren<T>(type: Constructor<T>): T | null;
-    /** Finds all components of a certain type on this object AND all children (recursively) */
-    getComponentsInChildren<T>(type: Constructor<T>, arr?: T[]): Array<T>;
-    /** Finds a component of a certain type on this object OR a parent object if any exists */
-    getComponentInParent<T>(type: Constructor<T>): T | null;
-    /** Finds all components of a certain type on this object AND all parents (recursively) */
-    getComponentsInParent<T>(type: Constructor<T>, arr?: T[]): Array<T>;
-
-    get worldPosition(): Vector3;
-    set worldPosition(val: Vector3);
-    get worldQuaternion(): Quaternion;
-    set worldQuaternion(val: Quaternion);
-    get worldRotation(): Vector3;
-    set worldRotation(val: Vector3);
-    get worldScale(): Vector3;
-    set worldScale(val: Vector3);
-
-    get worldForward(): Vector3;
-    get worldRight(): Vector3;
-    get worldUp(): Vector3;
-}
-
-export interface IHasGuid {
-    guid: string;
-}
-
-export interface IComponent extends IHasGuid {
-    get isComponent(): boolean;
-
-    /** the object this component is attached to */
-    gameObject: IGameObject;
-    // guid: string;
-    enabled: boolean;
-    sourceId?: SourceIdentifier;
-
-    get name(): string;
-    get layer(): number;
-    get destroyed(): boolean;
-    get tag(): string;
-
-    context: any;
-
-    get activeAndEnabled(): boolean;
-
-    /** @internal */
-    __internalNewInstanceCreated();
-    /** @internal */
-    __internalAwake();
-    /** @internal */
-    __internalStart();
-    /** @internal */
-    __internalEnable(isAddingOrRemovingFromScene?: boolean);
-    /** @internal */
-    __internalDisable(isAddingOrRemovingFromScene?: boolean);
-    /** @internal */
-    __internalDestroy();
-    /** @internal */
-    resolveGuids?(guidsMap: GuidsMap): void;
-
-    /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
-    registering?();
-    awake();
-    onEnable();
-    onDisable();
-    onDestroy();
-    destroy();
-
-    /** called for properties decorated with the @validate decorator */
-    onValidate?(property?: string);
-    /** called when this.context.isPaused changes or when rendering loop changes due to changing DOM element visibility
-     * e.g. when the DOM element becomes hidden or out ot view
-     */
-    onPausedChanged?(isPaused: boolean, wasPaused: boolean);
-
-    start?(): void;
-    earlyUpdate?(): void;
-    update?(): void;
-    lateUpdate?(): void;
-    onBeforeRender?(frame: XRFrame | null): void;
-    onAfterRender?(): void;
-
-    onCollisionEnter?(col: Collision);
-    onCollisionExit?(col: Collision);
-    onCollisionStay?(col: Collision);
-
-    onTriggerEnter?(col: ICollider);
-    onTriggerStay?(col: ICollider);
-    onTriggerExit?(col: ICollider);
-
-    get forward(): Vector3;
-    get worldPosition(): Vector3;
-    get worldQuaternion(): Quaternion;
-}
-
-
-export declare interface ICamera extends IComponent {
-    get isCamera(): boolean;
-    applyClearFlagsIfIsActiveCamera(): unknown;
-    applyClearFlags();
-    buildCamera();
-    get cam(): Camera;
-    nearClipPlane: number;
-    farClipPlane: number;
-    backgroundColor: RGBAColor | null;
-    backgroundBlurriness: number | undefined;
-    environmentIntensity: number | undefined;
-    clearFlags: number;
-    cullingMask: number;
-    aspect: number;
-    fieldOfView?: number;
-    /** x and y are in pixel on the canvas / dom element */
-    screenPointToRay(x: number, y: number, ray?: Ray): Ray;
-    targetTexture: RenderTexture | null;
-}
-
-export declare interface ICameraController {
-    get isCameraController(): boolean;
-}
-
-export declare interface ILight extends IComponent {
-    intensity: number;
-    color: Color;
-}
-
-export declare interface ISharedMaterials {
-    [num: number]: Material;
-    get length(): number;
-}
-
-export declare interface IRenderer extends IComponent {
-    sharedMaterial: Material;
-    get sharedMaterials(): ISharedMaterials;
-}
-
-// export declare interface IPhysicsComponent extends IComponent {
-//     get type() : string;
-// }
-
-export declare interface ICollider extends IComponent {
-    get isCollider();
-    attachedRigidbody: IRigidbody | null;
-    isTrigger: boolean;
-    sharedMaterial?: PhysicsMaterial;
-    center?: Vec3 & { multiply(vec: Vec3) };
-    updateProperties(): void;
-    updatePhysicsMaterial(): void;
-}
-
-export declare interface ISphereCollider extends ICollider {
-    radius: number;
-}
-
-export declare interface IBoxCollider extends ICollider {
-    size: Vec3;
-}
-
-export declare interface IRigidbody extends IComponent {
-    constraints: RigidbodyConstraints;
-    isKinematic: boolean;
-    /** When true the mass will automatically calculated by attached colliders */
-    autoMass: boolean;
-    mass: number;
-    drag: number;
-    angularDrag: number;
-    useGravity: boolean;
-    gravityScale: number;
-    dominanceGroup: number;
-
-    collisionDetectionMode: CollisionDetectionMode;
-
-    lockPositionX: boolean;
-    lockPositionY: boolean;
-    lockPositionZ: boolean;
-    lockRotationX: boolean;
-    lockRotationY: boolean;
-    lockRotationZ: boolean;
-}
-
-
-export const $physicsKey = Symbol("object");
-
-
-export declare type ICollisionContext = {
-    getCollider(obj: Object3D): ICollider;
-}
-
-
-export type Vec2 = {
-    x: number,
-    y: number
-}
-
-export type Vec3 = {
-    x: number,
-    y: number,
-    z: number,
-}
-
-export type Vec4 = {
-    x: number,
-    y: number,
-    z: number,
-    w: number,
-}
-
-const contactsVectorBuffer = new CircularBuffer(() => new Vector3(), 20);
-
-export class ContactPoint {
-
-    private readonly _point: Vec3;
-    private readonly _normal: Vec3;
-    private readonly _tangentVelocity: Vec3;
-
-    /** the distance of the collision point */
-    readonly distance: number;
-    /** the impulse velocity */
-    readonly impulse: number;
-    readonly friction: number;
-
-    /** worldspace point */
-    get point() {
-        const target = contactsVectorBuffer.get();
-        return target.set(this._point.x, this._point.y, this._point.z);
-    }
-
-    /** worldspace normal */
-    get normal() {
-        const target = contactsVectorBuffer.get();
-        return target.set(this._normal.x, this._normal.y, this._normal.z);
-    }
-
-    /** worldspace tangent */
-    get tangentVelocity() {
-        const target = contactsVectorBuffer.get();
-        return target.set(this._tangentVelocity.x, this._tangentVelocity.y, this._tangentVelocity.z);
-    }
-
-    constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number, tangentVelocity: Vec3) {
-        this._point = point;
-        this.distance = dist;
-        this._normal = normal;
-        this.impulse = impulse;
-        this.friction = friction;
-        this._tangentVelocity = tangentVelocity;
-    }
-}
-
-/// all info in here must be readonly because the object is only created once per started collision
-export class Collision {
-
-    /** The contact points of this collision. Contains information about positions, normals, distance, friction, impulse... */
-    readonly contacts: ContactPoint[];
-
-    constructor(obj: IGameObject, otherCollider: ICollider, contacts: ContactPoint[]) {
-        this.me = obj;
-        this._collider = otherCollider;
-        this._gameObject = otherCollider.gameObject;
-        this.contacts = contacts;
-    }
-
-    /** the gameobject this collision event belongs to (e.g. if onCollisionEnter is called then `me` is the same as `this.gameObject`) */
-    readonly me: IGameObject;
-
-    private _collider: ICollider;
-    /** the other collider the collision happened with */
-    get collider(): ICollider {
-        return this._collider;
-    }
-
-    private _gameObject: IGameObject;
-    /** the other object the collision happened with */
-    get gameObject(): IGameObject {
-        return this._gameObject;
-    }
-
-    /** the other rigidbody we hit, null if none attached */
-    get rigidBody(): IRigidbody | null {
-        return this.collider?.attachedRigidbody;
-    }
-}
-
-export type RaycastResult = null | { point: Vector3, collider: ICollider, normal?: Vector3 };
-
-export class SphereOverlapResult {
-    object: Object3D;
-    collider: ICollider;
-    constructor(object: Object3D, collider: ICollider) {
-        this.object = object;
-        this.collider = collider;
-    }
-}
-
-
-export interface IPhysicsEngine {
-    initialize(ctx: IContext): Promise<boolean>;
-    step(dt: number): void;
-    postStep();
-    get isUpdating(): boolean;
-    /** clear all possibly cached data (e.g. mesh data when creating scaled mesh colliders) */
-    clearCaches();
-
-    enabled: boolean;
-    get world(): any;
-
-    set gravity(vec3: Vec3);
-    get gravity(): Vec3;
-    
-    /** Get the rapier body for a Needle component */
-    getBody(obj: ICollider | IRigidbody): null | any;
-    /** Get the Needle Engine component for a rapier object */
-    getComponent(rapierObject:object) : IComponent | null;
-
-    // raycasting
-    /** Fast raycast against physics colliders
-     * @param origin ray origin in screen or worldspace
-     * @param direction ray direction in worldspace
-     * @param maxDistance max distance to raycast
-     * @param solid if true it will also hit the collider if origin is already inside it
-     */
-    raycast(origin?: Vec2 | Vec3, direction?: Vec3, maxDistance?: number, solid?: boolean): RaycastResult;
-    /** raycast that also gets the normal vector. If you don't need it use raycast() */
-    raycastAndGetNormal(origin?: Vec2 | Vec3, direction?: Vec3, maxDistance?: number, solid?: boolean): RaycastResult;
-    sphereOverlap(point: Vector3, radius: number): Array<SphereOverlapResult>;
-
-    // Collider methods
-    addSphereCollider(collider: ICollider);
-    addBoxCollider(collider: ICollider, size: Vector3);
-    addCapsuleCollider(collider: ICollider, radius: number, height: number);
-    addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, scale: Vector3);
-
-    updatePhysicsMaterial(collider:ICollider);
-
-    // Rigidbody methods
-    wakeup(rb: IRigidbody);
-    updateProperties(rb: IRigidbody | ICollider);
-    resetForces(rb: IRigidbody, wakeup: boolean);
-    resetTorques(rb: IRigidbody, wakeup: boolean);
-    addForce(rb: IRigidbody, vec: Vec3, wakeup: boolean);
-    applyImpulse(rb: IRigidbody, vec: Vec3, wakeup: boolean);
-    /** Returns the linear velocity of a rigidbody or the rigidbody of a collider */
-    getLinearVelocity(rb: IRigidbody | ICollider): Vec3 | null;
-    getAngularVelocity(rb: IRigidbody): Vec3 | null;
-    setAngularVelocity(rb: IRigidbody, vec: Vec3, wakeup: boolean);
-    setLinearVelocity(rb: IRigidbody, vec: Vec3, wakeup: boolean);
-
-    updateBody(comp: ICollider | IRigidbody, translation: boolean, rotation: boolean);
-    removeBody(body: IComponent);
-    getBody(obj: ICollider | IRigidbody): null | any;
-
-    // Joints
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody);
-    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3);
-
-    /** Enable to render collider shapes */
-    debugRenderColliders: boolean;
-}
+import { RenderTexture } from "./engine_texture.js";
+import type { Camera, Color, Material, Object3D, Quaternion, Ray, Scene, WebGLRenderer, Mesh } from "three";
+import { Vector3 } from "three";
+import { RGBAColor } from "../engine-components/js-extensions/RGBAColor.js";
+import { CollisionDetectionMode, type PhysicsMaterial, RigidbodyConstraints } from "./engine_physics.types.js";
+import { CircularBuffer } from "./engine_utils.js";
+import { type GLTF as GLTF3 } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+export type GLTF = GLTF3 & {
+    // asset: { generator: string, version: string }
+    // animations: AnimationClip[];
+    // cameras: Camera[];
+    // scene: Object3D;
+    // scenes: Object3D[];
+    // userData: object;
+    // parser: any;
+}
+
+export type LoadedGLTF = {
+    src: string;
+    file: GLTF;
+}
+
+/** used to find data registered via gltf files e.g. find lightmaps for a Renderer component that were shipped inside a gltf */
+export declare type SourceIdentifier = string;
+
+// TODO: figure out what is best here!
+// https://stackoverflow.com/a/67229348
+// https://stackoverflow.com/questions/36886082/abstract-constructor-type-in-typescript
+// type Constructor<T> = Function & { prototype: T } // << this includes abstract constructor types
+export type Constructor<T> = abstract new (...args: any[]) => T; // abstract to support @serializable and also getComponent with abstract types
+export type ConstructorConcrete<T> = new (...args: any[]) => T;
+export type GuidsMap = { [key: string]: string };
+
+export interface UIDProvider {
+    seed: number;
+    generateUUID(): string;
+}
+
+export declare type CoroutineData = {
+    comp: IComponent,
+    main: Generator,
+    chained?: Array<Generator>
+}
+
+export interface ITime {
+    get time(): number;
+}
+
+export interface IInput {
+    convertScreenspaceToRaycastSpace(vec: Vec2): void;
+    getPointerPosition(i: number): Vec2 | null;
+}
+
+export interface IPhysics {
+    engine?: IPhysicsEngine;
+}
+
+export interface IContext {
+    alias?: string | null;
+    hash?: string;
+
+    scene: Scene;
+    renderer: WebGLRenderer;
+    mainCamera: Camera | null;
+    mainCameraComponent: ICamera | undefined;
+    domElement: HTMLElement;
+
+    time: ITime;
+    input: IInput;
+    physics: IPhysics;
+
+    scripts: IComponent[];
+    scripts_pausedChanged: IComponent[];
+    // scripts with update event
+    scripts_earlyUpdate: IComponent[];
+    scripts_update: IComponent[];
+    scripts_lateUpdate: IComponent[];
+    scripts_onBeforeRender: IComponent[];
+    scripts_onAfterRender: IComponent[];
+    scripts_WithCorroutines: IComponent[];
+    coroutines: { [FrameEvent: number]: Array<CoroutineData> };
+
+    post_setup_callbacks: Function[];
+    pre_update_callbacks: Function[];
+    pre_render_callbacks: Function[];
+    post_render_callbacks: Function[];
+
+    new_scripts: IComponent[];
+    new_script_start: IComponent[];
+    new_scripts_pre_setup_callbacks: Function[];
+    new_scripts_post_setup_callbacks: Function[];
+
+    stopAllCoroutinesFrom(script: IComponent);
+}
+
+export declare interface INeedleEngineComponent extends HTMLElement {
+    getAROverlayContainer(): HTMLElement;
+    onEnterAR(session: XRSession, overlayContainer: HTMLElement);
+    onExitAR(session: XRSession);
+}
+
+export declare interface IGameObject extends Object3D {
+
+    /** the object's unique identifier */
+    guid: string | undefined;
+
+    /** if the object is enabled in the hierarchy (usually equivalent to `visible`) */
+    activeSelf: boolean;
+
+    /** call to destroy this object including all components that are attached to it. Will destroy all children recursively */
+    destroy(): void;
+
+    /** NOTE: this is just a wrapper for devs coming from Unity. Please use this.gameObject instead. In Needle Engine this.gameObject is the same as this.gameObject.transform. See the tutorial link below for more information
+     * @augments Object3D
+     * @tutorial https://fwd.needle.tools/needle-engine/docs/transform
+     * */
+    get transform(): IGameObject;
+
+    /** Add a new component to this object. Expects a component type (e.g. `addNewComponent(Animator)`) */
+    addNewComponent<T>(type: Constructor<T>): T | null;
+    /** Remove a component from this object. Expected a component instance
+     * @returns the removed component (equal to the passed in component)
+     */
+    removeComponent(comp: IComponent): IComponent;
+    /** Searches for a component type on this object. If no component of the searched type exists yet a new instance will be created and returned */
+    getOrAddComponent<T>(typeName: Constructor<T> | null): T;
+    /** Tries to find a component of a type on this object. 
+     * @returns the first instance of a component on this object that matches the passed in type or null if no component of this type (or a subtype) exists */
+    getComponent<T>(type: Constructor<T>): T | null;
+    /** @returns all components of a certain type on this object */
+    getComponents<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+    /** Finds a component of a certain type on this object OR a child object if any exists */
+    getComponentInChildren<T>(type: Constructor<T>): T | null;
+    /** Finds all components of a certain type on this object AND all children (recursively) */
+    getComponentsInChildren<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+    /** Finds a component of a certain type on this object OR a parent object if any exists */
+    getComponentInParent<T>(type: Constructor<T>): T | null;
+    /** Finds all components of a certain type on this object AND all parents (recursively) */
+    getComponentsInParent<T>(type: Constructor<T>, arr?: T[]): Array<T>;
+
+    get worldPosition(): Vector3;
+    set worldPosition(val: Vector3);
+    get worldQuaternion(): Quaternion;
+    set worldQuaternion(val: Quaternion);
+    get worldRotation(): Vector3;
+    set worldRotation(val: Vector3);
+    get worldScale(): Vector3;
+    set worldScale(val: Vector3);
+
+    get worldForward(): Vector3;
+    get worldRight(): Vector3;
+    get worldUp(): Vector3;
+}
+
+export interface IHasGuid {
+    guid: string;
+}
+
+export interface IComponent extends IHasGuid {
+    get isComponent(): boolean;
+
+    /** the object this component is attached to */
+    gameObject: IGameObject;
+    // guid: string;
+    enabled: boolean;
+    sourceId?: SourceIdentifier;
+
+    get name(): string;
+    get layer(): number;
+    get destroyed(): boolean;
+    get tag(): string;
+
+    context: any;
+
+    get activeAndEnabled(): boolean;
+
+    /** @internal */
+    __internalNewInstanceCreated();
+    /** @internal */
+    __internalAwake();
+    /** @internal */
+    __internalStart();
+    /** @internal */
+    __internalEnable(isAddingOrRemovingFromScene?: boolean);
+    /** @internal */
+    __internalDisable(isAddingOrRemovingFromScene?: boolean);
+    /** @internal */
+    __internalDestroy();
+    /** @internal */
+    resolveGuids?(guidsMap: GuidsMap): void;
+
+    /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
+    registering?();
+    awake();
+    onEnable();
+    onDisable();
+    onDestroy();
+    destroy();
+
+    /** called for properties decorated with the @validate decorator */
+    onValidate?(property?: string);
+    /** called when this.context.isPaused changes or when rendering loop changes due to changing DOM element visibility
+     * e.g. when the DOM element becomes hidden or out ot view
+     */
+    onPausedChanged?(isPaused: boolean, wasPaused: boolean);
+
+    start?(): void;
+    earlyUpdate?(): void;
+    update?(): void;
+    lateUpdate?(): void;
+    onBeforeRender?(frame: XRFrame | null): void;
+    onAfterRender?(): void;
+
+    onCollisionEnter?(col: Collision);
+    onCollisionExit?(col: Collision);
+    onCollisionStay?(col: Collision);
+
+    onTriggerEnter?(col: ICollider);
+    onTriggerStay?(col: ICollider);
+    onTriggerExit?(col: ICollider);
+
+    get forward(): Vector3;
+    get worldPosition(): Vector3;
+    get worldQuaternion(): Quaternion;
+}
+
+
+export declare interface ICamera extends IComponent {
+    get isCamera(): boolean;
+    applyClearFlagsIfIsActiveCamera(): unknown;
+    applyClearFlags();
+    buildCamera();
+    get cam(): Camera;
+    nearClipPlane: number;
+    farClipPlane: number;
+    backgroundColor: RGBAColor | null;
+    backgroundBlurriness: number | undefined;
+    environmentIntensity: number | undefined;
+    clearFlags: number;
+    cullingMask: number;
+    aspect: number;
+    fieldOfView?: number;
+    /** x and y are in pixel on the canvas / dom element */
+    screenPointToRay(x: number, y: number, ray?: Ray): Ray;
+    targetTexture: RenderTexture | null;
+}
+
+export declare interface ICameraController {
+    get isCameraController(): boolean;
+}
+
+export declare interface ILight extends IComponent {
+    intensity: number;
+    color: Color;
+}
+
+export declare interface ISharedMaterials {
+    [num: number]: Material;
+    get length(): number;
+}
+
+export declare interface IRenderer extends IComponent {
+    sharedMaterial: Material;
+    get sharedMaterials(): ISharedMaterials;
+}
+
+// export declare interface IPhysicsComponent extends IComponent {
+//     get type() : string;
+// }
+
+export declare interface ICollider extends IComponent {
+    get isCollider();
+    attachedRigidbody: IRigidbody | null;
+    isTrigger: boolean;
+    sharedMaterial?: PhysicsMaterial;
+    center?: Vec3 & { multiply(vec: Vec3) };
+    updateProperties(): void;
+    updatePhysicsMaterial(): void;
+}
+
+export declare interface ISphereCollider extends ICollider {
+    radius: number;
+}
+
+export declare interface IBoxCollider extends ICollider {
+    size: Vec3;
+}
+
+export declare interface IRigidbody extends IComponent {
+    constraints: RigidbodyConstraints;
+    isKinematic: boolean;
+    /** When true the mass will automatically calculated by attached colliders */
+    autoMass: boolean;
+    mass: number;
+    drag: number;
+    angularDrag: number;
+    useGravity: boolean;
+    gravityScale: number;
+    dominanceGroup: number;
+
+    collisionDetectionMode: CollisionDetectionMode;
+
+    lockPositionX: boolean;
+    lockPositionY: boolean;
+    lockPositionZ: boolean;
+    lockRotationX: boolean;
+    lockRotationY: boolean;
+    lockRotationZ: boolean;
+}
+
+
+export const $physicsKey = Symbol("object");
+
+
+export declare type ICollisionContext = {
+    getCollider(obj: Object3D): ICollider;
+}
+
+
+export type Vec2 = {
+    x: number,
+    y: number
+}
+
+export type Vec3 = {
+    x: number,
+    y: number,
+    z: number,
+}
+
+export type Vec4 = {
+    x: number,
+    y: number,
+    z: number,
+    w: number,
+}
+
+const contactsVectorBuffer = new CircularBuffer(() => new Vector3(), 20);
+
+export class ContactPoint {
+
+    private readonly _point: Vec3;
+    private readonly _normal: Vec3;
+    private readonly _tangentVelocity: Vec3;
+
+    /** the distance of the collision point */
+    readonly distance: number;
+    /** the impulse velocity */
+    readonly impulse: number;
+    readonly friction: number;
+
+    /** worldspace point */
+    get point() {
+        const target = contactsVectorBuffer.get();
+        return target.set(this._point.x, this._point.y, this._point.z);
+    }
+
+    /** worldspace normal */
+    get normal() {
+        const target = contactsVectorBuffer.get();
+        return target.set(this._normal.x, this._normal.y, this._normal.z);
+    }
+
+    /** worldspace tangent */
+    get tangentVelocity() {
+        const target = contactsVectorBuffer.get();
+        return target.set(this._tangentVelocity.x, this._tangentVelocity.y, this._tangentVelocity.z);
+    }
+
+    constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number, tangentVelocity: Vec3) {
+        this._point = point;
+        this.distance = dist;
+        this._normal = normal;
+        this.impulse = impulse;
+        this.friction = friction;
+        this._tangentVelocity = tangentVelocity;
+    }
+}
+
+/// all info in here must be readonly because the object is only created once per started collision
+export class Collision {
+
+    /** The contact points of this collision. Contains information about positions, normals, distance, friction, impulse... */
+    readonly contacts: ContactPoint[];
+
+    constructor(obj: IGameObject, otherCollider: ICollider, contacts: ContactPoint[]) {
+        this.me = obj;
+        this._collider = otherCollider;
+        this._gameObject = otherCollider.gameObject;
+        this.contacts = contacts;
+    }
+
+    /** the gameobject this collision event belongs to (e.g. if onCollisionEnter is called then `me` is the same as `this.gameObject`) */
+    readonly me: IGameObject;
+
+    private _collider: ICollider;
+    /** the other collider the collision happened with */
+    get collider(): ICollider {
+        return this._collider;
+    }
+
+    private _gameObject: IGameObject;
+    /** the other object the collision happened with */
+    get gameObject(): IGameObject {
+        return this._gameObject;
+    }
+
+    /** the other rigidbody we hit, null if none attached */
+    get rigidBody(): IRigidbody | null {
+        return this.collider?.attachedRigidbody;
+    }
+}
+
+export type RaycastResult = null | { point: Vector3, collider: ICollider, normal?: Vector3 };
+
+export class SphereOverlapResult {
+    object: Object3D;
+    collider: ICollider;
+    constructor(object: Object3D, collider: ICollider) {
+        this.object = object;
+        this.collider = collider;
+    }
+}
+
+
+export interface IPhysicsEngine {
+    initialize(ctx: IContext): Promise<boolean>;
+    step(dt: number): void;
+    postStep();
+    get isUpdating(): boolean;
+    /** clear all possibly cached data (e.g. mesh data when creating scaled mesh colliders) */
+    clearCaches();
+
+    enabled: boolean;
+    get world(): any;
+
+    set gravity(vec3: Vec3);
+    get gravity(): Vec3;
+    
+    /** Get the rapier body for a Needle component */
+    getBody(obj: ICollider | IRigidbody): null | any;
+    /** Get the Needle Engine component for a rapier object */
+    getComponent(rapierObject:object) : IComponent | null;
+
+    // raycasting
+    /** Fast raycast against physics colliders
+     * @param origin ray origin in screen or worldspace
+     * @param direction ray direction in worldspace
+     * @param maxDistance max distance to raycast
+     * @param solid if true it will also hit the collider if origin is already inside it
+     */
+    raycast(origin?: Vec2 | Vec3, direction?: Vec3, maxDistance?: number, solid?: boolean): RaycastResult;
+    /** raycast that also gets the normal vector. If you don't need it use raycast() */
+    raycastAndGetNormal(origin?: Vec2 | Vec3, direction?: Vec3, maxDistance?: number, solid?: boolean): RaycastResult;
+    sphereOverlap(point: Vector3, radius: number): Array<SphereOverlapResult>;
+
+    // Collider methods
+    addSphereCollider(collider: ICollider);
+    addBoxCollider(collider: ICollider, size: Vector3);
+    addCapsuleCollider(collider: ICollider, radius: number, height: number);
+    addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, scale: Vector3);
+
+    updatePhysicsMaterial(collider:ICollider);
+
+    // Rigidbody methods
+    wakeup(rb: IRigidbody);
+    updateProperties(rb: IRigidbody | ICollider);
+    resetForces(rb: IRigidbody, wakeup: boolean);
+    resetTorques(rb: IRigidbody, wakeup: boolean);
+    addForce(rb: IRigidbody, vec: Vec3, wakeup: boolean);
+    applyImpulse(rb: IRigidbody, vec: Vec3, wakeup: boolean);
+    /** Returns the linear velocity of a rigidbody or the rigidbody of a collider */
+    getLinearVelocity(rb: IRigidbody | ICollider): Vec3 | null;
+    getAngularVelocity(rb: IRigidbody): Vec3 | null;
+    setAngularVelocity(rb: IRigidbody, vec: Vec3, wakeup: boolean);
+    setLinearVelocity(rb: IRigidbody, vec: Vec3, wakeup: boolean);
+
+    updateBody(comp: ICollider | IRigidbody, translation: boolean, rotation: boolean);
+    removeBody(body: IComponent);
+    getBody(obj: ICollider | IRigidbody): null | any;
+
+    // Joints
+    addFixedJoint(body1: IRigidbody, body2: IRigidbody);
+    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3);
+
+    /** Enable to render collider shapes */
+    debugRenderColliders: boolean;
+}