@block_factory/lib 0.0.5 → 0.0.8

package/_module/util/IVector.ts

@@ -0,0 +1,420 @@
+/*  
+**************************************************
+ 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 IVector2 {
+
+    /** Constant zero vector (0, 0) */
+    static ZERO: IVector2 = new IVector2(0, 0);
+
+    /** Up direction (0, 1) */
+    static UP: IVector2 = new IVector2(0, 1);
+
+    /** Down direction (0, -1) */
+    static DOWN: IVector2 = new IVector2(0, -1);
+
+    /** Left direction (-1, 0) */
+    static LEFT: IVector2 = new IVector2(-1, 0);
+
+    /** Right direction (1, 0) */
+    static RIGHT: IVector2 = new IVector2(1, 0);
+
+    /**
+     * Creates a new IVector2.
+     * @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: IVector2, b: IVector2 | number): IVector2 {
+        if (typeof b === 'number') return new IVector2(a.x + b, a.y + b);
+        else return new IVector2(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: IVector2, b: IVector2 | number): IVector2 {
+        if (typeof b === 'number') return new IVector2(a.x - b, a.y - b);
+        else return new IVector2(a.x - b.x, a.y - b.y);
+    }
+
+    /**
+     * Multiplies a vector by another vector (component-wise) or scalar.
+     */
+    static multiply(a: IVector2, b: IVector2 | number): IVector2 {
+        if (typeof b === 'number') return new IVector2(a.x * b, a.y * b);
+        else return new IVector2(a.x * b.x, a.y * b.y);
+    }
+
+    /**
+     * Divides a vector by another vector (component-wise) or scalar.
+     */
+    static divide(a: IVector2, b: IVector2 | number): IVector2 {
+        if (typeof b === 'number') return new IVector2(a.x / b, a.y / b);
+        else return new IVector2(a.x / b.x, a.y / b.y);
+    }
+
+    /**
+     * Linearly interpolates between two vectors.
+     * @param t Interpolation factor (0–1)
+     */
+    static lerp(a: IVector2, b: IVector2, t: number): IVector2 {
+        return new IVector2(
+            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: IVector2, min: IVector2, max: IVector2): IVector2 {
+        return new IVector2(
+            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: IVector2, b: IVector2): number {
+        return a.x * b.x + a.y * b.y;
+    }
+
+    /**
+     * Length (magnitude) of a vector.
+     */
+    static magnitude(a: IVector2): 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: IVector2): IVector2 {
+        const mag = IVector2.magnitude(a);
+        return mag === 0 ? new IVector2(0, 0) : new IVector2(a.x / mag, a.y / mag);
+    }
+
+    /**
+     * Distance between two vectors.
+     */
+    static distance(a: IVector2, b: IVector2): number {
+        return IVector2.magnitude(IVector2.subtract(a, b));
+    }
+
+    /**
+     * Returns the negated vector.
+     */
+    static negate(a: IVector2): IVector2 {
+        return new IVector2(-a.x, -a.y);
+    }
+
+    /**
+     * Checks exact equality between two vectors.
+     */
+    static equals(a: IVector2, b: IVector2): boolean {
+        return a.x === b.x && a.y === b.y;
+    }
+
+    /**
+     * Checks approximate equality between two vectors.
+     * @param epsilon Allowed difference threshold
+     */
+    static approxEquals(a: IVector2, b: IVector2, 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: IVector2, b: IVector2): number {
+        const magA = IVector2.magnitude(a);
+        const magB = IVector2.magnitude(b);
+        const denom = magA * magB;
+        if (denom === 0) return 0;
+
+        let c = IVector2.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: IVector2): IVector2 {
+        return new IVector2(-a.y, a.x);
+    }
+
+    /**
+     * Floors each vector paramater.
+     */
+    static floor(v: IVector2): IVector2 {
+        return new IVector2(Math.floor(v.x), Math.floor(v.y));
+    }
+
+    /**
+     * Return vector as a string
+     * @param format Returns string with x: y: z: format.
+     */
+    static toString(v: IVector2, format = false): string {
+        if (format) return `x:${v.x} y:${v.y}`;
+        return `${v.x} ${v.y}`;
+    }
+}
+
+/**
+ * 3D vector utility class.
+ * Provides common vector math operations for 3D space.
+ */
+export class IVector3 {
+
+    /** Constant zero vector (0, 0, 0) */
+    static ZERO: IVector3 = new IVector3(0, 0, 0);
+
+    /** Up direction (0, 1, 0) */
+    static UP: IVector3 = new IVector3(0, 1, 0);
+
+    /** Down direction (0, -1, 0) */
+    static DOWN: IVector3 = new IVector3(0, -1, 0);
+
+    /** Left direction (-1, 0, 0) */
+    static LEFT: IVector3 = new IVector3(-1, 0, 0);
+
+    /** Right direction (1, 0, 0) */
+    static RIGHT: IVector3 = new IVector3(1, 0, 0);
+
+    /** Forward direction (0, 0, 1) */
+    static FORWARD: IVector3 = new IVector3(0, 0, 1);
+
+    /** Backward direction (0, 0, -1) */
+    static BACK: IVector3 = new IVector3(0, 0, -1);
+
+    /** West direction (-1, 0, 0) */
+    static WEST: IVector3 = new IVector3(-1, 0, 0);
+
+    /** East direction (1, 0, 0) */
+    static EAST: IVector3 = new IVector3(1, 0, 0);
+
+    /** North direction (0, 0, 1) */
+    static NORTH: IVector3 = new IVector3(0, 0, 1);
+
+    /** South direction (0, 0, -1) */
+    static SOUTH: IVector3 = new IVector3(0, 0, -1);
+
+    /**
+     * Creates a new IVector3.
+     * @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: IVector3, b: IVector3 | number): IVector3 {
+        if (typeof b === 'number') return new IVector3(a.x + b, a.y + b, a.z + b);
+        else return new IVector3(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: IVector3, b: IVector3 | number): IVector3 {
+        if (typeof b === 'number') return new IVector3(a.x - b, a.y - b, a.z - b);
+        else return new IVector3(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: IVector3, b: IVector3 | number): IVector3 {
+        if (typeof b === 'number') return new IVector3(a.x * b, a.y * b, a.z * b);
+        else return new IVector3(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: IVector3, b: IVector3 | number): IVector3 {
+        if (typeof b === 'number') return new IVector3(a.x / b, a.y / b, a.z / b);
+        else return new IVector3(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: IVector3, b: IVector3, t: number): IVector3 {
+        return new IVector3(
+            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: IVector3, min: IVector3, max: IVector3): IVector3 {
+        return new IVector3(
+            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: IVector3, b: IVector3): 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: IVector3, b: IVector3): IVector3 {
+        return new IVector3(
+            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: IVector3): 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: IVector3): IVector3 {
+        const mag = IVector3.magnitude(a);
+        return mag === 0
+            ? new IVector3(0, 0, 0)
+            : new IVector3(a.x / mag, a.y / mag, a.z / mag);
+    }
+
+    /**
+     * Distance between two vectors.
+     */
+    static distance(a: IVector3, b: IVector3): number {
+        return IVector3.magnitude(IVector3.subtract(a, b));
+    }
+
+    /**
+     * Returns the negated vector.
+     */
+    static negate(a: IVector3): IVector3 {
+        return new IVector3(-a.x, -a.y, -a.z);
+    }
+
+    /**
+     * Checks exact equality between two vectors.
+     */
+    static equals(a: IVector3, b: IVector3): 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: IVector3, b: IVector3, 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: IVector3, b: IVector3): number {
+        const magA = IVector3.magnitude(a);
+        const magB = IVector3.magnitude(b);
+        const denom = magA * magB;
+        if (denom === 0) return 0;
+
+        let c = IVector3.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: IVector3, onto: IVector3): IVector3 {
+        const denom = IVector3.dot(onto, onto);
+        if (denom === 0) return new IVector3(0, 0, 0);
+
+        const scale = IVector3.dot(a, onto) / denom;
+        return IVector3.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): IVector3 {
+        return new IVector3(
+            radius * Math.sin(phi) * Math.cos(theta),
+            radius * Math.sin(phi) * Math.sin(theta),
+            radius * Math.cos(phi)
+        );
+    }
+
+    /**
+     * Floors each vector paramater.
+     */
+    static floor(v: IVector3): IVector3 {
+        return new IVector3(Math.floor(v.x), Math.floor(v.y), Math.floor(v.z));
+    }
+
+    /**
+     * Return vector as a string
+     * @param format Returns string with x: y: z: format.
+     */
+    static toString(v: IVector3, format = false): string {
+        if (format) return `x:${v.x} y:${v.y} z:${v.z}`;
+        return `${v.x} ${v.y} ${v.z}`;
+    }
+}

package/_module/util/Math.ts

@@ -21,6 +21,7 @@ export namespace MathUtils {
         return radians * (180 / Math.PI);
     };
 
+    /** Converts a Minecraft-style rotation (pitch/yaw in degrees) into a unit direction vector. */
     export function fromRotation(rotation: Vector2): Vector3 {
         const rotationH = toRadians(rotation.y * -1);
         const z0 = Math.cos(rotationH);
@@ -37,6 +38,7 @@ export namespace MathUtils {
         };
     };
 
+    /** Rotates a local-space offset around the Y axis by a yaw angle (degrees)*/
     export function rotateOffset(offset: Vector3, yawDegrees: number): Vector3 {
         const yaw = -yawDegrees * Math.PI / 180;
         const cos = Math.cos(yaw);

package/_module/util/Navigation.ts

@@ -0,0 +1,130 @@
+import { Block, Entity, system, TicksPerSecond } from "@minecraft/server";
+import { Signal } from "./Signal";
+import { IVector3 } from "./IVector";
+import { ICustomEntity, IEntity } from "../BlockFactory";
+
+export type OnNavPointReachedEvent<T extends ICustomEntity = ICustomEntity> = {
+    entity: IEntity<T>;
+    targetLocation: IVector3;
+    originLocation: IVector3;
+};
+
+export type OnNavigatingEntityStuckEvent<T extends ICustomEntity = ICustomEntity> = {
+    entity: IEntity<T>;
+    targetLocation: IVector3;
+    originLocation: IVector3;
+};
+
+const MAX_NAV_INSTS: number = 2;
+const NAV_CYCLE_TAG_ID: string = "e547e9b28165";
+
+export class Navigation<T extends ICustomEntity = ICustomEntity> {
+    public static onNavPointReachedEvent = new Signal<OnNavPointReachedEvent>();
+    public static onNavigatingEntityStuck = new Signal<OnNavigatingEntityStuckEvent>();
+    private source: IEntity<T>;
+    private targetId: string;
+    private static instanceIndex = new Map<string, number>();
+    private instanceId: number | undefined;
+    private typeId: string;
+    private intervalId: number = -1;
+    private navTarget: Entity | undefined
+    private originLocation: IVector3 = IVector3.ZERO;
+
+
+    public constructor(source: IEntity<T>, targetId: string) {
+        this.source = source;
+        this.targetId = targetId;
+        this.typeId = source.typeId;
+    }
+    private obstructionFix(location: IVector3): IVector3 {
+        let block: Block | undefined = this.source.dimension.getBlock(location);
+        if (block === undefined) throw new Error("obstructionFix error");
+        if (block.isAir) return location;
+        const ray = this.source.dimension.getBlockFromRay(new IVector3(location.x, 300, location.z), IVector3.DOWN);
+        if (!ray?.block) throw new Error("obstructionFix raycast error");
+        return new IVector3(ray.block.x, ray.block.y +1, ray.block.z);
+
+    }
+
+    public async setNavPoint(location: IVector3): Promise<void> {
+        console.warn(`Trying to set nav point @${IVector3.toString(IVector3.floor(location))}`);
+        if (!this.source || !this.source.dimension) throw Error("Critical source error");
+        if (this.instanceId !== undefined) {
+            return;
+        }
+        const i: number = Navigation.instanceIndex.get(this.source.typeId) || 0;
+        this.instanceId = i;
+        if (i === MAX_NAV_INSTS) {
+            console.warn(`Max navigation instances exeded. | Tried: ${i} - Max: ${MAX_NAV_INSTS}`);
+            return;
+        };
+        Navigation.instanceIndex.set(this.source.typeId, i + 1);
+        location = this.obstructionFix(location);
+        const target: Entity = this.source.dimension.spawnEntity(this.targetId, location);
+        this.navTarget = target;
+        const startDist: number = IVector3.distance(this.source.location, target.location);
+        if (startDist > 64) {
+            this.clearNavPoint();
+            return;
+        }
+        await system.waitTicks(1);
+        const tagId: string = `${NAV_CYCLE_TAG_ID}_${this.instanceId}`;
+        target.addTag(tagId);
+        this.source.addTag(tagId);
+        this.source.isNavigating = true;
+        this.processNavCycle(target, location);
+        this.originLocation = this.source.location;
+
+    }
+
+    private processNavCycle(target: Entity, location: IVector3): void {
+        let cycles = 0;
+        const maxCycles: number = 10;
+
+        const intervalId: number = system.runInterval(() => {
+            try {
+                if (!this.source.isValid || !target.isValid) {
+                    this.clearNavPoint();
+                    return;
+                }
+                const v = this.source.getVelocity();
+                const horizSpeed = Math.hypot(v.x, v.z);
+
+                if (horizSpeed < 0.05) {
+                    cycles++;
+
+                    if (cycles >= maxCycles) {
+                        Navigation.onNavigatingEntityStuck.emit({ entity: this.source, targetLocation: location, originLocation: this.originLocation })
+                        this.clearNavPoint();
+                        return;
+                    }
+                } else cycles = 0;
+
+                const distance = IVector3.distance(this.source.location, target.location);
+                if (distance > 2) return;
+
+                Navigation.onNavPointReachedEvent.emit({ entity: this.source, targetLocation: location, originLocation: this.originLocation });
+                this.clearNavPoint();
+            } catch (e) {
+                console.warn(e);
+                this.clearNavPoint();
+            }
+        }, TicksPerSecond / 4);
+        this.intervalId = intervalId;
+    }
+
+    public clearNavPoint(): void {
+        if (this.intervalId === -1 || !this.navTarget) return;
+        this.instanceId = undefined;
+        const i: number = Navigation.instanceIndex.get(this.typeId) || 0;
+        if (i > 0) Navigation.instanceIndex.set(this.typeId, i - 1);
+        if (this.source.isValid) {
+            this.source.isNavigating = false;
+            this.source.removeTag(`${NAV_CYCLE_TAG_ID}_${this.instanceId}`);
+        }
+        if (this.navTarget.isValid) this.navTarget.remove();
+        system.clearRun(this.intervalId);
+        this.intervalId = -1;
+        this.navTarget = undefined;
+    }
+}

package/_module/util/Signal.ts

@@ -1,33 +1,97 @@
-export type Callback<T> = (data: T) => void;
+/**
+ * Function signature for signal subscription callbacks.
+ *
+ * @template T Payload type emitted by the signal
+ */
+export type SubscriptionCallback<T> = (data: T) => void;
 
+/**
+ * Lightweight signal / event dispatcher inspired by Godot's signal system.
+ *
+ * Signals allow decoupled communication by emitting typed payloads to
+ * subscribed listeners.
+ *
+ * @template T Payload type (use `void` for no data)
+ */
 export class Signal<T = void> {
-    private readonly listeners = new Set<Callback<T>>();
+    /**
+     * Registered signal listeners.
+     */
+    private readonly listeners = new Set<SubscriptionCallback<T>>();
 
+    /**
+     * Number of currently subscribed listeners.
+     */
     public get count(): number {
         return this.listeners.size;
     }
 
-    public connect(callback: Callback<T>): void {
+    /**
+     * Subscribes a callback to this signal.
+     *
+     * The callback will be invoked every time the signal is emitted
+     * until it is explicitly unsubscribed or the signal is cleared.
+     *
+     * @param callback Function invoked on signal emission
+     */
+    public subscribe(callback: SubscriptionCallback<T>): void {
         this.listeners.add(callback);
     }
 
-    public disconnect(callback: Callback<T>): boolean {
+    /**
+     * Unsubscribes a previously registered callback.
+     *
+     * @param callback Callback to remove
+     * @returns `true` if the callback was removed, `false` otherwise
+     */
+    public unsubscribe(callback: SubscriptionCallback<T>): boolean {
         return this.listeners.delete(callback);
     }
 
+    /**
+     * Removes all subscribed listeners from this signal.
+     */
     public clear(): void {
         this.listeners.clear();
     }
 
-    public isConnected(callback: Callback<T>): boolean {
+    /**
+     * Checks whether a callback is currently subscribed.
+     *
+     * @param callback Callback to test
+     * @returns `true` if the callback is subscribed
+     */
+    public isSubscribed(callback: SubscriptionCallback<T>): boolean {
         return this.listeners.has(callback);
     }
 
+    /**
+     * Emits the signal immediately, invoking all subscribed callbacks.
+     *
+     * Listener errors are caught and logged to prevent a single failure
+     * from interrupting signal propagation.
+     *
+     * @param data Payload to pass to listeners
+     */
     public emit(data: T): void {
         for (const callback of Array.from(this.listeners)) {
-            try { callback(data) } catch (err) {
-                console.error("BFLIB: Signal listener error:", err);
+            try {
+                callback(data);
+            } catch (err) {
+                console.error("BFLIB: Subscription listener error:", err);
             }
         }
     }
+
+    /**
+     * Emits the signal asynchronously on the microtask queue.
+     *
+     * Useful for deferring execution to avoid re-entrancy issues
+     * or emitting during unsafe execution phases.
+     *
+     * @param data Payload to pass to listeners
+     */
+    public emitDeferred(data: T): void {
+        queueMicrotask(() => this.emit(data));
+    }
 }