@gg-web-engine/core 0.0.2 → 0.0.4

package/dist/base/inputs/input.d.ts

@@ -0,0 +1,50 @@
+import { Subject } from 'rxjs';
+/**
+ * An abstract class that provides basic implementation for Input class.
+ * Input is an entity for handling input from user, such as mouse movements, key presses etc.
+ * Inputs are not bound to World-s and working independently by design.
+ *
+ * TStartParams - A type representing an array of input arguments for the start method. Items are recommended to be named.
+ *
+ * TStopParams - A type representing an array of input arguments for the stop method. Items are recommended to be named.
+ */
+export declare abstract class Input<TStartParams extends any[] = [], TStopParams extends any[] = []> {
+    /**
+     * A private boolean that represents the running state of the process.
+     */
+    private _running;
+    /**
+     * A protected subject that emits a void value when the process is stopped.
+     * Subclasses, when subscribing to something using rxjs, have to add pipe takeUntil(this.stop$),
+     * so everything will be unsubscribed when stopping input
+     */
+    protected readonly stop$: Subject<void>;
+    /**
+     * A public getter that returns the running state of the Input.
+     */
+    get running(): boolean;
+    /**
+     * An asynchronous method that starts the input. Do not override it
+     * @param args - An array of input arguments for the start method.
+     * @returns A Promise that resolves when the input is started.
+     */
+    start(...args: TStartParams): Promise<void>;
+    /**
+     * An asynchronous method that stops the input. Do not override it
+     * @param args - An array of input arguments for the stop method.
+     * @returns A Promise that resolves when the input is stopped.
+     */
+    stop(...args: TStopParams): Promise<void>;
+    /**
+     * An abstract asynchronous method that starts the input.
+     * @param args - An array of input arguments for the start method.
+     * @returns A Promise that resolves when the process is started.
+     */
+    protected abstract startInternal(...args: TStartParams): Promise<void>;
+    /**
+     * An asynchronous method that stops the input.
+     * @param args - An array of input arguments for the stop method.
+     * @returns A Promise that resolves when the process is stopped.
+     */
+    protected stopInternal(...args: TStopParams): Promise<void>;
+}

package/dist/base/inputs/input.js

@@ -0,0 +1,80 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Input = void 0;
+const rxjs_1 = require("rxjs");
+/**
+ * An abstract class that provides basic implementation for Input class.
+ * Input is an entity for handling input from user, such as mouse movements, key presses etc.
+ * Inputs are not bound to World-s and working independently by design.
+ *
+ * TStartParams - A type representing an array of input arguments for the start method. Items are recommended to be named.
+ *
+ * TStopParams - A type representing an array of input arguments for the stop method. Items are recommended to be named.
+ */
+class Input {
+    constructor() {
+        /**
+         * A private boolean that represents the running state of the process.
+         */
+        this._running = false;
+        /**
+         * A protected subject that emits a void value when the process is stopped.
+         * Subclasses, when subscribing to something using rxjs, have to add pipe takeUntil(this.stop$),
+         * so everything will be unsubscribed when stopping input
+         */
+        this.stop$ = new rxjs_1.Subject();
+    }
+    /**
+     * A public getter that returns the running state of the Input.
+     */
+    get running() {
+        return this._running;
+    }
+    /**
+     * An asynchronous method that starts the input. Do not override it
+     * @param args - An array of input arguments for the start method.
+     * @returns A Promise that resolves when the input is started.
+     */
+    start(...args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.running) {
+                return;
+            }
+            yield this.startInternal(...args);
+            this._running = true;
+        });
+    }
+    /**
+     * An asynchronous method that stops the input. Do not override it
+     * @param args - An array of input arguments for the stop method.
+     * @returns A Promise that resolves when the input is stopped.
+     */
+    stop(...args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.running) {
+                return;
+            }
+            this.stop$.next();
+            yield this.stopInternal(...args);
+            this._running = false;
+        });
+    }
+    /**
+     * An asynchronous method that stops the input.
+     * @param args - An array of input arguments for the stop method.
+     * @returns A Promise that resolves when the process is stopped.
+     */
+    stopInternal(...args) {
+        return __awaiter(this, void 0, void 0, function* () { });
+    }
+}
+exports.Input = Input;

package/dist/base/inputs/keyboard.input.d.ts

@@ -0,0 +1,45 @@
+import { Input } from './input';
+import { Observable } from 'rxjs';
+/**
+ * A main keyboard input: it does not have own key bindings, but provides an API to bind keys.
+ * It is responsible for listening key up/down events (when running!) and emit the events to subscribers.
+ * Every World entity has its own dedicated instance of Keyboard input, which is running only when the world is running
+ */
+export declare class KeyboardInput extends Input {
+    private bindings;
+    /**
+     * Creates a new instance of the `KeyboardInput` class.
+     */
+    constructor();
+    protected startInternal(): Promise<void>;
+    protected stopInternal(): Promise<void>;
+    /**
+     * Creates an observable that emits a boolean whenever a key with the given code is pressed or released
+     * @param code The key code to bind the observable to
+     * @returns An observable that emits true when the key is pressed and false when it's released
+     */
+    bind(code: string): Observable<boolean>;
+    /**
+     * Creates an observable that emits a boolean indicating whether any of the keys with the given codes are pressed or released.
+     * Should be used when you have more than one keys, responsible for the same action.
+     * @param codes The key codes to bind the observable to
+     * @returns An observable that emits true when any of the keys are pressed and false when they're all released
+     */
+    bindMany(...codes: string[]): Observable<boolean>;
+    /**
+     * Emulates a key down event for the given key code
+     * @param code The key code to emulate
+     */
+    emulateKeyDown(code: string): void;
+    /**
+     * Emulates a key up event for the given key code
+     * @param code The key code to emulate
+     */
+    emulateKeyUp(code: string): void;
+    /**
+     * Emulates a key press event (down and up) for the given key code
+     * @param code The key code to emulate
+     */
+    emulateKeyPress(code: string): void;
+    private handleKeys;
+}

package/dist/base/inputs/keyboard.input.js

@@ -0,0 +1,130 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyboardInput = void 0;
+const input_1 = require("./input");
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+/**
+ * A main keyboard input: it does not have own key bindings, but provides an API to bind keys.
+ * It is responsible for listening key up/down events (when running!) and emit the events to subscribers.
+ * Every World entity has its own dedicated instance of Keyboard input, which is running only when the world is running
+ */
+class KeyboardInput extends input_1.Input {
+    /**
+     * Creates a new instance of the `KeyboardInput` class.
+     */
+    constructor() {
+        super();
+        this.bindings = {};
+        this.handleKeys = this.handleKeys.bind(this);
+    }
+    startInternal() {
+        return __awaiter(this, void 0, void 0, function* () {
+            window.addEventListener('keydown', this.handleKeys);
+            window.addEventListener('keyup', this.handleKeys);
+        });
+    }
+    stopInternal() {
+        return __awaiter(this, void 0, void 0, function* () {
+            window.removeEventListener('keydown', this.handleKeys);
+            window.removeEventListener('keyup', this.handleKeys);
+        });
+    }
+    /**
+     * Creates an observable that emits a boolean whenever a key with the given code is pressed or released
+     * @param code The key code to bind the observable to
+     * @returns An observable that emits true when the key is pressed and false when it's released
+     */
+    bind(code) {
+        if (!this.bindings[code]) {
+            this.bindings[code] = [];
+        }
+        const subj = new rxjs_1.BehaviorSubject(false);
+        this.bindings[code].push(subj);
+        return subj.pipe((0, rxjs_1.finalize)(() => {
+            this.bindings[code].splice(this.bindings[code].indexOf(subj), 1);
+            subj.complete();
+        }));
+    }
+    /**
+     * Creates an observable that emits a boolean indicating whether any of the keys with the given codes are pressed or released.
+     * Should be used when you have more than one keys, responsible for the same action.
+     * @param codes The key codes to bind the observable to
+     * @returns An observable that emits true when any of the keys are pressed and false when they're all released
+     */
+    bindMany(...codes) {
+        if (codes.length == 0) {
+            console.warn('[KeyboardController] bindMany called without any key code');
+            return rxjs_1.NEVER;
+        }
+        if (codes.length == 1) {
+            return this.bind(codes[0]);
+        }
+        const subjects = [];
+        for (const code of codes) {
+            if (!this.bindings[code]) {
+                this.bindings[code] = [];
+            }
+            const subj = new rxjs_1.BehaviorSubject(false);
+            this.bindings[code].push(subj);
+            subjects.push(subj);
+        }
+        return (0, rxjs_1.combineLatest)(subjects).pipe((0, rxjs_1.finalize)(() => {
+            for (let i = 0; i < codes.length; i++) {
+                this.bindings[codes[i]].splice(this.bindings[codes[i]].indexOf(subjects[i]), 1);
+                subjects[i].complete();
+            }
+        }), (0, operators_1.map)(values => values.includes(true)));
+    }
+    /**
+     * Emulates a key down event for the given key code
+     * @param code The key code to emulate
+     */
+    emulateKeyDown(code) {
+        if (!this.running) {
+            return;
+        }
+        for (const subj of this.bindings[code] || []) {
+            subj.next(true);
+        }
+    }
+    /**
+     * Emulates a key up event for the given key code
+     * @param code The key code to emulate
+     */
+    emulateKeyUp(code) {
+        if (!this.running) {
+            return;
+        }
+        for (const subj of this.bindings[code] || []) {
+            subj.next(false);
+        }
+    }
+    /**
+     * Emulates a key press event (down and up) for the given key code
+     * @param code The key code to emulate
+     */
+    emulateKeyPress(code) {
+        this.emulateKeyDown(code);
+        this.emulateKeyUp(code);
+    }
+    handleKeys(e) {
+        if (e.type != 'keydown' && e.type != 'keyup') {
+            return;
+        }
+        const pressed = e.type == 'keydown';
+        for (const subj of this.bindings[e.code] || []) {
+            subj.next(pressed);
+        }
+    }
+}
+exports.KeyboardInput = KeyboardInput;

package/dist/base/inputs/mouse.input.d.ts

@@ -0,0 +1,57 @@
+import { Input } from './input';
+import { Observable } from 'rxjs';
+import { Point2 } from '../models/points';
+/**
+ * Options for pointer lock in a MouseInput.
+ *
+ * ignoreMovementWhenNotLocked: Whether to ignore mouse movement when pointer lock is not active.
+ *
+ * canvas: The canvas element to request pointer lock on.
+ */
+export declare type MouseInputPointLockOptions = {
+    ignoreMovementWhenNotLocked: boolean;
+    canvas: HTMLCanvasElement;
+};
+/**
+ * Options for a MouseInput.
+ *
+ * pointerLock: The options for pointer lock. Do not provide it to disable pointer lock functionality
+ */
+export declare type MouseInputOptions = {
+    pointerLock?: MouseInputPointLockOptions;
+};
+/**
+ * A class representing mouse input.
+ */
+export declare class MouseInput extends Input<[], [unlockPointer?: boolean]> {
+    private readonly options;
+    /**
+     * An observable of the change in the x position of the mouse.
+     */
+    get deltaX$(): Observable<number>;
+    /**
+     * An observable of the change in the y position of the mouse.
+     */
+    get deltaY$(): Observable<number>;
+    /**
+     An observable of the change in the position of the mouse.
+     */
+    get delta$(): Observable<Point2>;
+    private _delta$;
+    private stopped$;
+    /**
+     Creates an instance of MouseInput.
+     @param {MouseInputOptions} options - The options for the MouseInput.
+     */
+    constructor(options?: MouseInputOptions);
+    protected startInternal(): Promise<void>;
+    /**
+     Stop listening for mouse movement events.
+     @param {boolean} [unlockPointer=true] - Whether to exit pointer lock.
+     */
+    protected stopInternal(unlockPointer?: boolean): Promise<void>;
+    /**
+     Request pointer lock on the canvas element.
+     */
+    private canvasClickListener;
+}

package/dist/base/inputs/mouse.input.js

@@ -0,0 +1,81 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MouseInput = void 0;
+const input_1 = require("./input");
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+/**
+ * A class representing mouse input.
+ */
+class MouseInput extends input_1.Input {
+    /**
+     Creates an instance of MouseInput.
+     @param {MouseInputOptions} options - The options for the MouseInput.
+     */
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        this._delta$ = new rxjs_1.Subject();
+        this.stopped$ = new rxjs_1.Subject();
+        this.canvasClickListener = this.canvasClickListener.bind(this);
+    }
+    /**
+     * An observable of the change in the x position of the mouse.
+     */
+    get deltaX$() {
+        return this._delta$.pipe((0, operators_1.map)(d => d.x));
+    }
+    /**
+     * An observable of the change in the y position of the mouse.
+     */
+    get deltaY$() {
+        return this._delta$.pipe((0, operators_1.map)(d => d.y));
+    }
+    /**
+     An observable of the change in the position of the mouse.
+     */
+    get delta$() {
+        return this._delta$.asObservable();
+    }
+    startInternal() {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, rxjs_1.fromEvent)(window, 'mousemove')
+                .pipe((0, rxjs_1.takeUntil)(this.stopped$), (0, rxjs_1.filter)(() => !this.options.pointerLock ||
+                !this.options.pointerLock.ignoreMovementWhenNotLocked ||
+                !!document.pointerLockElement), (0, operators_1.map)((e) => ({ x: e.movementX, y: e.movementY })))
+                .subscribe(v => this._delta$.next(v));
+            if (!!this.options.pointerLock) {
+                this.options.pointerLock.canvas.addEventListener('click', this.canvasClickListener);
+            }
+        });
+    }
+    /**
+     Stop listening for mouse movement events.
+     @param {boolean} [unlockPointer=true] - Whether to exit pointer lock.
+     */
+    stopInternal(unlockPointer = true) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.stopped$.next();
+            if (unlockPointer && !!this.options.pointerLock) {
+                this.options.pointerLock.canvas.removeEventListener('click', this.canvasClickListener);
+                document.exitPointerLock();
+            }
+        });
+    }
+    /**
+     Request pointer lock on the canvas element.
+     */
+    canvasClickListener() {
+        this.options.pointerLock.canvas.requestPointerLock();
+    }
+}
+exports.MouseInput = MouseInput;

package/dist/base/math/matrix4.js

@@ -8,7 +8,7 @@ class Mtrx4 {
         let z = point3_1.Pnt3.sub(eye, target);
         if (point3_1.Pnt3.lenSq(z) === 0) {
             // same position
-            z.z = 1;
+            z = Object.assign(Object.assign({}, z), { z: 1 });
         }
         else {
             z = point3_1.Pnt3.norm(z);
@@ -17,10 +17,10 @@ class Mtrx4 {
         if (point3_1.Pnt3.lenSq(x) === 0) {
             // up and z are parallel
             if (Math.abs(up.z) === 1) {
-                z.x += 0.0001;
+                z = Object.assign(Object.assign({}, z), { x: z.x + 0.0001 });
             }
             else {
-                z.z += 0.0001;
+                z = Object.assign(Object.assign({}, z), { z: z.z + 0.0001 });
             }
             z = point3_1.Pnt3.norm(z);
             x = point3_1.Pnt3.cross(up, z);

package/dist/base/math/point2.js

@@ -4,7 +4,7 @@ exports.Pnt2 = void 0;
 class Pnt2 {
     /** clone point */
     static clone(p) {
-        return Object.assign({}, p);
+        return { x: p.x, y: p.y };
     }
     /** add point b to point a */
     static add(a, b) {

package/dist/base/math/point3.js

@@ -5,7 +5,7 @@ const quaternion_1 = require("./quaternion");
 class Pnt3 {
     /** clone point */
     static clone(p) {
-        return Object.assign({}, p);
+        return { x: p.x, y: p.y, z: p.z };
     }
     /** add point b to point a */
     static add(a, b) {

package/dist/base/math/quaternion.d.ts

@@ -1,28 +1,102 @@
 import { Point3, Point4 } from '../models/points';
+/**
+ * Helper class with static functions, containing util functions, related to Quaternion (represented as Point4 type).
+ * In terms of rotation, a quaternion is a mathematical representation of an orientation or rotation in 3D space.
+ * It consists of a scalar component and a vector component, and can be written as q = w + xi + yj + zk, where w is the
+ * scalar component, and i, j, and k are the vector components. The scalar component, w, represents the amount of
+ * rotation, and the vector component, (x, y, z), represents the axis of rotation. The length of the vector component
+ * represents the amount of rotation around the axis. Quaternions are often used in 3D computer graphics and animation
+ * because they can be used to interpolate between two rotations, and they can avoid some of the issues with using
+ * Euler angles (such as gimbal lock).
+ */
 export declare class Qtrn {
-    /** clone quaternion */
+    /**
+     * Returns a new quaternion instance with the same values as the given quaternion object.
+     * @param q The Point4 object to clone.
+     * @returns A new Point4 instance with the same values as the given Point4 object.
+     */
     static clone(q: Point4): Point4;
-    /** add quaternion b to quaternion a */
+    /**
+     * Returns the sum of two Point4 objects.
+     * @param a The first Point4 object to add.
+     * @param b The second Point4 object to add.
+     * @returns The sum of the two Point4 objects.
+     */
     static add(a: Point4, b: Point4): Point4;
+    /**
+     * Returns the result of multiplying two Point4 objects. This can be used for combining rotations
+     * @param a The first Point4 object to multiply.
+     * @param b The second Point4 object to multiply.
+     * @returns The product of the two Point4 objects.
+     */
     static mult(a: Point4, b: Point4): Point4;
+    /**
+     * Combines an arbitrary number of quaternions by multiplying them together in order.
+     * @param quaternions The quaternions to combine.
+     * @returns The combined quaternion.
+     */
     static combineRotations(...quaternions: Point4[]): Point4;
-    /** linear interpolation */
+    /**
+     * Performs a linear interpolation between two Point4 objects.
+     * @param a The first Point4 object.
+     * @param b The second Point4 object.
+     * @param t The interpolation factor.
+     * @returns The interpolated Point4 object.
+     */
     static lerp(a: Point4, b: Point4, t: number): Point4;
-    /** spherical interpolation */
+    /**
+     * Performs a spherical linear interpolation between two Point4 objects.
+     * @param a The first Point4 object.
+     * @param b The second Point4 object.
+     * @param t The interpolation factor.
+     * @returns The interpolated Point4 object.
+     */
     static slerp(a: Point4, b: Point4, t: number): Point4;
-    /** creates quaternion from simple angle around axis. Assumes that axis vector is normalized */
+    /**
+     * Converts an angle and an axis of rotation into a quaternion
+     * @param axis the axis of rotation
+     * @param angle the angle of rotation in radians
+     * @returns a quaternion representing the rotation
+     */
     static fromAngle(axis: Point3, angle: number): {
         w: number;
         x: number;
         y: number;
         z: number;
     };
-    /** creates quaternion from 4-dimension rotation matrix */
+    /**
+     * Converts a 4x4 matrix representing a rotation into a quaternion
+     * @param m the matrix representing the rotation
+     * @returns a quaternion representing the rotation
+     */
     static fromMatrix4(m: number[]): Point4;
-    /** creates a quaternion from euler */
+    /**
+     * Creates a quaternion from euler
+     * @param e the euler vector
+     * @returns a quaternion representing the rotation
+     */
     static fromEuler(e: Point3): Point4;
-    /** converts a quaternion to euler */
+    /**
+     * Converts a quaternion to euler
+     * @param q Point4 object
+     * @returns an Euler vector, representing the same rotation
+     */
     static toEuler(q: Point4): Point3;
-    /** creates a rotation for object, so it will look at some point in space */
+    /**
+     * Returns a quaternion that represents the rotation required to align an object to face towards a target point.
+     * @param eye - The position of the camera or object that needs to be rotated to face the target point.
+     * @param target - The target point to look at
+     * @param up - The up direction of the object
+     * @returns A new quaternion representing the rotation required to face towards the target point.
+     */
     static lookAt(eye: Point3, target: Point3, up: Point3): Point4;
+    /**
+     * Returns a quaternion that represents the input quaternion, rotated around provided axis vector by provided angle.
+     * Assumes that axis vector is already normalized
+     * @param q - Input quaternion.
+     * @param axis - Axis vector
+     * @param angle - Angle
+     * @returns A new quaternion representing the updated rotation.
+     */
+    static rotAround(q: Point4, axis: Point3, angle: number): Point4;
 }