@block_factory/lib 0.0.1

package/util/Signal.ts

@@ -0,0 +1,73 @@
+export type Callback<T = void> = (data: T) => void;
+
+/**
+ * Signal class for event handling.
+ * Allows connecting, disconnecting, and emitting events to listeners.
+ *
+ * @template T - Type of data passed to listeners.
+ *
+ * @example
+ * ```typescript
+ * import { Signal } from "./_lib/signal";
+ *
+ * interface ExampleEvent {
+ *   n: number;
+ *   s: string;
+ *   b: boolean;
+ * }
+ *
+ * class TestObject {
+ *   example = new Signal<ExampleEvent>();
+ * }
+ *
+ * const tstObject = new TestObject();
+ * tstObject.example.connect(({n, s, b}) => console.warn(`n: ${n}, s: ${s}, b: ${b}`));
+ *
+ * for (let i = 0; i < 4; i++) {
+ *   let n: number = 1;
+ *   let s: string = "example";
+ *   let b: boolean = true;
+ *   tstObject.example.emit({n, s, b});
+ *   if (i === 3) { // Disconnect after 4th emit
+ *     tstObject.example.disconnect();
+ *     tstObject.example.emit({n, s, b});
+ *   }
+ * }
+ * ```
+ */
+
+export class Signal<T = void> {
+    private listeners: Set<Callback<T>> = new Set();
+
+    /** Connect a listener */
+    public connect(callback: Callback<T>): void {
+        this.listeners.add(callback);
+    }
+
+    /** Disconnect a listener */
+    public disconnect(callback?: Callback<T>): boolean {
+        if (callback) {
+            this.listeners.delete(callback);
+            return true;
+        } else {
+            this.listeners.clear();
+            return false;
+        }
+    }
+
+    /** Connect a listener that runs only once */
+    public once(callback: Callback<T>) {
+        const wrapper: Callback<T> = (data) => {
+            this.disconnect(wrapper);
+            callback(data);
+        };
+        this.connect(wrapper);
+    }
+
+    /** Emit signal to all listeners */
+    public emit(data: T) {
+        for (const cb of [...this.listeners]) {
+            cb(data);
+        }
+    }
+}

package/util/Vector.d.ts

@@ -0,0 +1,60 @@
+export declare class Vec2 {
+    x: number;
+    y: number;
+    static ZERO: Vec2;
+    static UP: Vec2;
+    static DOWN: Vec2;
+    static LEFT: Vec2;
+    static RIGHT: Vec2;
+    constructor(x: number, y: number);
+    static add(a: Vec2, b: Vec2 | number): Vec2;
+    static subtract(a: Vec2, b: Vec2 | number): Vec2;
+    static multiply(a: Vec2, b: Vec2 | number): Vec2;
+    static divide(a: Vec2, b: Vec2 | number): Vec2;
+    static lerp(a: Vec2, b: Vec2, t: number): Vec2;
+    static clamp(v: Vec2, min: Vec2, max: Vec2): Vec2;
+    static dot(a: Vec2, b: Vec2): number;
+    static magnitude(a: Vec2): number;
+    static normalize(a: Vec2): Vec2;
+    static distance(a: Vec2, b: Vec2): number;
+    static negate(a: Vec2): Vec2;
+    static equals(a: Vec2, b: Vec2): boolean;
+    static approxEquals(a: Vec2, b: Vec2, epsilon?: number): boolean;
+    static angle(a: Vec2, b: Vec2): number;
+    static perpendicular(a: Vec2): Vec2;
+}
+export declare class Vec3 {
+    x: number;
+    y: number;
+    z: number;
+    static ZERO: Vec3;
+    static UP: Vec3;
+    static DOWN: Vec3;
+    static LEFT: Vec3;
+    static RIGHT: Vec3;
+    static FORWARD: Vec3;
+    static BACK: Vec3;
+    static WEST: Vec3;
+    static EAST: Vec3;
+    static NORTH: Vec3;
+    static SOUTH: Vec3;
+    constructor(x: number, y: number, z: number);
+    static add(a: Vec3, b: Vec3 | number): Vec3;
+    static subtract(a: Vec3, b: Vec3 | number): Vec3;
+    static multiply(a: Vec3, b: Vec3 | number): Vec3;
+    static divide(a: Vec3, b: Vec3 | number): Vec3;
+    static lerp(a: Vec3, b: Vec3, t: number): Vec3;
+    static clamp(v: Vec3, min: Vec3, max: Vec3): Vec3;
+    static dot(a: Vec3, b: Vec3): number;
+    static cross(a: Vec3, b: Vec3): Vec3;
+    static magnitude(a: Vec3): number;
+    static normalize(a: Vec3): Vec3;
+    static distance(a: Vec3, b: Vec3): number;
+    static negate(a: Vec3): Vec3;
+    static equals(a: Vec3, b: Vec3): boolean;
+    static approxEquals(a: Vec3, b: Vec3, epsilon?: number): boolean;
+    static angle(a: Vec3, b: Vec3): number;
+    static project(a: Vec3, onto: Vec3): Vec3;
+    static cartesian(radius: number, theta: number, phi: number): Vec3;
+}
+//# sourceMappingURL=Vector.d.ts.map

package/util/Vector.ts

@@ -0,0 +1,388 @@
+/*  
+**************************************************
+ Copyright (c) Block Factory - All rights reserved.
+**************************************************
+ Author: Donthedev <https://github.com/voxeldon> 
+**************************************************
+*/
+
+/**
+ * 2D vector utility class.
+ * Provides common vector math operations for 2D space.
+ */
+export class Vec2 {
+
+    /** Constant zero vector (0, 0) */
+    static ZERO: Vec2 = new Vec2(0, 0);
+
+    /** Up direction (0, 1) */
+    static UP: Vec2 = new Vec2(0, 1);
+
+    /** Down direction (0, -1) */
+    static DOWN: Vec2 = new Vec2(0, -1);
+
+    /** Left direction (-1, 0) */
+    static LEFT: Vec2 = new Vec2(-1, 0);
+
+    /** Right direction (1, 0) */
+    static RIGHT: Vec2 = new Vec2(1, 0);
+
+    /**
+     * Creates a new Vec2.
+     * @param x X component
+     * @param y Y component
+     */
+    constructor(public x: number, public y: number) { }
+
+    /**
+     * Adds a vector or scalar to a vector.
+     * @param a Base vector
+     * @param b Vector or scalar to add
+     */
+    static add(a: Vec2, b: Vec2 | number): Vec2 {
+        if (typeof b === 'number') return new Vec2(a.x + b, a.y + b);
+        else return new Vec2(a.x + b.x, a.y + b.y);
+    }
+
+    /**
+     * Subtracts a vector or scalar from a vector.
+     * @param a Base vector
+     * @param b Vector or scalar to subtract
+     */
+    static subtract(a: Vec2, b: Vec2 | number): Vec2 {
+        if (typeof b === 'number') return new Vec2(a.x - b, a.y - b);
+        else return new Vec2(a.x - b.x, a.y - b.y);
+    }
+
+    /**
+     * Multiplies a vector by another vector (component-wise) or scalar.
+     */
+    static multiply(a: Vec2, b: Vec2 | number): Vec2 {
+        if (typeof b === 'number') return new Vec2(a.x * b, a.y * b);
+        else return new Vec2(a.x * b.x, a.y * b.y);
+    }
+
+    /**
+     * Divides a vector by another vector (component-wise) or scalar.
+     */
+    static divide(a: Vec2, b: Vec2 | number): Vec2 {
+        if (typeof b === 'number') return new Vec2(a.x / b, a.y / b);
+        else return new Vec2(a.x / b.x, a.y / b.y);
+    }
+
+    /**
+     * Linearly interpolates between two vectors.
+     * @param t Interpolation factor (0–1)
+     */
+    static lerp(a: Vec2, b: Vec2, t: number): Vec2 {
+        return new Vec2(
+            a.x + (b.x - a.x) * t,
+            a.y + (b.y - a.y) * t
+        );
+    }
+
+    /**
+     * Clamps a vector between a minimum and maximum vector.
+     */
+    static clamp(v: Vec2, min: Vec2, max: Vec2): Vec2 {
+        return new Vec2(
+            Math.min(Math.max(v.x, min.x), max.x),
+            Math.min(Math.max(v.y, min.y), max.y)
+        );
+    }
+
+    /**
+     * Dot product of two vectors.
+     */
+    static dot(a: Vec2, b: Vec2): number {
+        return a.x * b.x + a.y * b.y;
+    }
+
+    /**
+     * Length (magnitude) of a vector.
+     */
+    static magnitude(a: Vec2): number {
+        return Math.sqrt(a.x * a.x + a.y * a.y);
+    }
+
+    /**
+     * Returns a normalized (unit length) vector.
+     * If magnitude is zero, returns (0, 0).
+     */
+    static normalize(a: Vec2): Vec2 {
+        const mag = Vec2.magnitude(a);
+        return mag === 0 ? new Vec2(0, 0) : new Vec2(a.x / mag, a.y / mag);
+    }
+
+    /**
+     * Distance between two vectors.
+     */
+    static distance(a: Vec2, b: Vec2): number {
+        return Vec2.magnitude(Vec2.subtract(a, b));
+    }
+
+    /**
+     * Returns the negated vector.
+     */
+    static negate(a: Vec2): Vec2 {
+        return new Vec2(-a.x, -a.y);
+    }
+
+    /**
+     * Checks exact equality between two vectors.
+     */
+    static equals(a: Vec2, b: Vec2): boolean {
+        return a.x === b.x && a.y === b.y;
+    }
+
+    /**
+     * Checks approximate equality between two vectors.
+     * @param epsilon Allowed difference threshold
+     */
+    static approxEquals(a: Vec2, b: Vec2, epsilon = 0.0001): boolean {
+        return (
+            Math.abs(a.x - b.x) < epsilon &&
+            Math.abs(a.y - b.y) < epsilon
+        );
+    }
+
+    /**
+     * Returns the angle (in radians) between two vectors.
+     * Returns 0 if either vector has zero length.
+     */
+    static angle(a: Vec2, b: Vec2): number {
+        const magA = Vec2.magnitude(a);
+        const magB = Vec2.magnitude(b);
+        const denom = magA * magB;
+        if (denom === 0) return 0;
+
+        let c = Vec2.dot(a, b) / denom;
+        c = Math.max(-1, Math.min(1, c));
+        return Math.acos(c);
+    }
+
+    /**
+     * Returns a perpendicular vector (-y, x).
+     */
+    static perpendicular(a: Vec2): Vec2 {
+        return new Vec2(-a.y, a.x);
+    }
+}
+
+/**
+ * 3D vector utility class.
+ * Provides common vector math operations for 3D space.
+ */
+export class Vec3 {
+
+    /** Constant zero vector (0, 0, 0) */
+    static ZERO: Vec3 = new Vec3(0, 0, 0);
+
+    /** Up direction (0, 1, 0) */
+    static UP: Vec3 = new Vec3(0, 1, 0);
+
+    /** Down direction (0, -1, 0) */
+    static DOWN: Vec3 = new Vec3(0, -1, 0);
+
+    /** Left direction (-1, 0, 0) */
+    static LEFT: Vec3 = new Vec3(-1, 0, 0);
+
+    /** Right direction (1, 0, 0) */
+    static RIGHT: Vec3 = new Vec3(1, 0, 0);
+
+    /** Forward direction (0, 0, 1) */
+    static FORWARD: Vec3 = new Vec3(0, 0, 1);
+
+    /** Backward direction (0, 0, -1) */
+    static BACK: Vec3 = new Vec3(0, 0, -1);
+
+    /** West direction (-1, 0, 0) */
+    static WEST: Vec3 = new Vec3(-1, 0, 0);
+
+    /** East direction (1, 0, 0) */
+    static EAST: Vec3 = new Vec3(1, 0, 0);
+
+    /** North direction (0, 0, 1) */
+    static NORTH: Vec3 = new Vec3(0, 0, 1);
+
+    /** South direction (0, 0, -1) */
+    static SOUTH: Vec3 = new Vec3(0, 0, -1);
+
+    /**
+     * Creates a new Vec3.
+     * @param x X component
+     * @param y Y component
+     * @param z Z component
+     */
+    constructor(public x: number, public y: number, public z: number) { }
+
+    /**
+     * Adds a vector or scalar to a vector.
+     * @param a Base vector
+     * @param b Vector or scalar to add
+     */
+    static add(a: Vec3, b: Vec3 | number): Vec3 {
+        if (typeof b === 'number') return new Vec3(a.x + b, a.y + b, a.z + b);
+        else return new Vec3(a.x + b.x, a.y + b.y, a.z + b.z);
+    }
+
+    /**
+     * Subtracts a vector or scalar from a vector.
+     * @param a Base vector
+     * @param b Vector or scalar to subtract
+     */
+    static subtract(a: Vec3, b: Vec3 | number): Vec3 {
+        if (typeof b === 'number') return new Vec3(a.x - b, a.y - b, a.z - b);
+        else return new Vec3(a.x - b.x, a.y - b.y, a.z - b.z);
+    }
+
+    /**
+     * Multiplies a vector by another vector (component-wise) or scalar.
+     */
+    static multiply(a: Vec3, b: Vec3 | number): Vec3 {
+        if (typeof b === 'number') return new Vec3(a.x * b, a.y * b, a.z * b);
+        else return new Vec3(a.x * b.x, a.y * b.y, a.z * b.z);
+    }
+
+    /**
+     * Divides a vector by another vector (component-wise) or scalar.
+     */
+    static divide(a: Vec3, b: Vec3 | number): Vec3 {
+        if (typeof b === 'number') return new Vec3(a.x / b, a.y / b, a.z / b);
+        else return new Vec3(a.x / b.x, a.y / b.y, a.z / b.z);
+    }
+
+    /**
+     * Linearly interpolates between two vectors.
+     * @param t Interpolation factor (0–1)
+     */
+    static lerp(a: Vec3, b: Vec3, t: number): Vec3 {
+        return new Vec3(
+            a.x + (b.x - a.x) * t,
+            a.y + (b.y - a.y) * t,
+            a.z + (b.z - a.z) * t
+        );
+    }
+
+    /**
+     * Clamps a vector between a minimum and maximum vector.
+     */
+    static clamp(v: Vec3, min: Vec3, max: Vec3): Vec3 {
+        return new Vec3(
+            Math.min(Math.max(v.x, min.x), max.x),
+            Math.min(Math.max(v.y, min.y), max.y),
+            Math.min(Math.max(v.z, min.z), max.z)
+        );
+    }
+
+    /**
+     * Dot product of two vectors.
+     */
+    static dot(a: Vec3, b: Vec3): number {
+        return a.x * b.x + a.y * b.y + a.z * b.z;
+    }
+
+    /**
+     * Cross product of two vectors.
+     * Returns a vector perpendicular to both inputs.
+     */
+    static cross(a: Vec3, b: Vec3): Vec3 {
+        return new Vec3(
+            a.y * b.z - a.z * b.y,
+            a.z * b.x - a.x * b.z,
+            a.x * b.y - a.y * b.x
+        );
+    }
+
+    /**
+     * Length (magnitude) of a vector.
+     */
+    static magnitude(a: Vec3): number {
+        return Math.sqrt(a.x * a.x + a.y * a.y + a.z * a.z);
+    }
+
+    /**
+     * Returns a normalized (unit length) vector.
+     * If magnitude is zero, returns (0, 0, 0).
+     */
+    static normalize(a: Vec3): Vec3 {
+        const mag = Vec3.magnitude(a);
+        return mag === 0
+            ? new Vec3(0, 0, 0)
+            : new Vec3(a.x / mag, a.y / mag, a.z / mag);
+    }
+
+    /**
+     * Distance between two vectors.
+     */
+    static distance(a: Vec3, b: Vec3): number {
+        return Vec3.magnitude(Vec3.subtract(a, b));
+    }
+
+    /**
+     * Returns the negated vector.
+     */
+    static negate(a: Vec3): Vec3 {
+        return new Vec3(-a.x, -a.y, -a.z);
+    }
+
+    /**
+     * Checks exact equality between two vectors.
+     */
+    static equals(a: Vec3, b: Vec3): boolean {
+        return a.x === b.x && a.y === b.y && a.z === b.z;
+    }
+
+    /**
+     * Checks approximate equality between two vectors.
+     * @param epsilon Allowed difference threshold
+     */
+    static approxEquals(a: Vec3, b: Vec3, epsilon = 0.0001): boolean {
+        return (
+            Math.abs(a.x - b.x) < epsilon &&
+            Math.abs(a.y - b.y) < epsilon &&
+            Math.abs(a.z - b.z) < epsilon
+        );
+    }
+
+    /**
+     * Returns the angle (in radians) between two vectors.
+     * Returns 0 if either vector has zero length.
+     */
+    static angle(a: Vec3, b: Vec3): number {
+        const magA = Vec3.magnitude(a);
+        const magB = Vec3.magnitude(b);
+        const denom = magA * magB;
+        if (denom === 0) return 0;
+
+        let c = Vec3.dot(a, b) / denom;
+        c = Math.max(-1, Math.min(1, c));
+        return Math.acos(c);
+    }
+
+    /**
+     * Projects vector `a` onto vector `onto`.
+     * If `onto` has zero length, returns (0, 0, 0).
+     */
+    static project(a: Vec3, onto: Vec3): Vec3 {
+        const denom = Vec3.dot(onto, onto);
+        if (denom === 0) return new Vec3(0, 0, 0);
+
+        const scale = Vec3.dot(a, onto) / denom;
+        return Vec3.multiply(onto, scale);
+    }
+
+    /**
+     * Converts spherical coordinates to cartesian coordinates.
+     * @param radius Distance from origin
+     * @param theta Azimuth angle (radians)
+     * @param phi Polar angle (radians)
+     */
+    static cartesian(radius: number, theta: number, phi: number): Vec3 {
+        return new Vec3(
+            radius * Math.sin(phi) * Math.cos(theta),
+            radius * Math.sin(phi) * Math.sin(theta),
+            radius * Math.cos(phi)
+        );
+    }
+}