@block_factory/lib 0.0.4 → 0.0.6

package/_module/BlockFactory.ts

@@ -15,4 +15,7 @@ export { Inventory, ContainerWrapper } from "./util/Wrapper/Container";
 export { type IEntity, IEntityWrapper } from "./util/Wrapper/IEntity";
 export { type IPlayer, IPlayerWrapper } from "./util/Wrapper/IPlayer";
 
-export { _THREAD_ } from "./sys/Threads";
+export { Thread } from "./Framework/Threads";
+export { PlayerHandler } from "./Framework/PlayerTasks";
+export { EntityHandler,  type EntityEmissionEvent } from "./Framework/EntityTasks";
+export { ItemHandler, type ItemRegistration, type OnItemHeldEvent, type OnItemUnheldEvent, type WhileHoldingItemEvent } from "./Framework/ItemTasks";

package/_module/DataTypes.ts

@@ -0,0 +1,10 @@
+export type Sound = {
+    id: string,
+    length: number
+}
+
+export type Animation = {
+    id: string,
+    length: number,
+    loop?: boolean,
+}

package/_module/Framework/EntityTasks.ts

@@ -0,0 +1,164 @@
+import { Entity, system, ScriptEventCommandMessageAfterEvent, ScriptEventCommandMessageAfterEventSignal, world, WorldLoadAfterEventSignal, WorldLoadAfterEvent, EntitySpawnAfterEventSignal, EntitySpawnAfterEvent, EntityRemoveBeforeEvent, EntityRemoveBeforeEventSignal } from "@minecraft/server";
+
+import { Signal } from "../util/Signal";
+import { IEntityWrapper, IEntity } from "../util/Wrapper/IEntity";
+
+export type EntityEmissionEvent = {
+    iEntity: IEntity;
+    parms: any;
+};
+
+class SingletonEntityHandler {
+    private PACK_ID: string | undefined;
+    
+    public readonly onEntityEmission = new Signal<EntityEmissionEvent>();
+    private readonly GLOBAL_MEMORY_ID = "GLB_MEM.ENTITY";
+
+    private readonly scriptEventSignal: ScriptEventCommandMessageAfterEventSignal = system.afterEvents.scriptEventReceive;
+    private readonly loadEventSignal: WorldLoadAfterEventSignal = world.afterEvents.worldLoad;
+    private readonly spawnEventSignal: EntitySpawnAfterEventSignal = world.afterEvents.entitySpawn;
+    private readonly removeBeforeEventSignal: EntityRemoveBeforeEventSignal = world.beforeEvents.entityRemove;
+
+    private readonly EM_INDEX = new Map<string, Entity>();
+    private readonly EM_KEYS: string[] = [];
+    private readonly SEARCH_TYPES = new Set<string>();
+
+    private _started: boolean = false;
+    private _wired: boolean = false;
+
+    public registerEntity(typeId: string | string[]): void {
+        if (Array.isArray(typeId)) typeId.forEach((t) => this.SEARCH_TYPES.add(t));
+        else this.SEARCH_TYPES.add(typeId);
+    }
+
+    public start(packId: string): void {
+        if (this._started) throw new Error("BFLIB: EntityHandler already started;");
+        this._started = true;
+        this.PACK_ID = packId;
+        this.loadEventSignal.subscribe(this.onWorldLoad);
+    }
+
+    public stop(): void {
+        if (!this._started) return;
+
+        this.loadEventSignal.unsubscribe(this.onWorldLoad);
+        if (this._wired) {
+            this.scriptEventSignal.unsubscribe(this.processScriptEvents);
+            this.spawnEventSignal.unsubscribe(this.onEntitySpawned);
+            this.removeBeforeEventSignal.unsubscribe(this.onEntityRemovedBefore);
+            this._wired = false;
+        }
+
+        this._started = false;
+    }
+
+    /* ------------------------------------------------------------------------ */
+    /* Event Wiring                                                             */
+    /* ------------------------------------------------------------------------ */
+
+    private onWorldLoad = (): void => {
+        this.scriptEventSignal.subscribe(this.processScriptEvents);
+
+        if (this.SEARCH_TYPES.size > 0) {
+            this.spawnEventSignal.subscribe(this.onEntitySpawned);
+            this.removeBeforeEventSignal.subscribe(this.onEntityRemovedBefore);
+        }
+
+        this._wired = true;
+        this.reloadEntityMemory();
+        this.loadEventSignal.unsubscribe(this.onWorldLoad);
+    };
+
+    private processScriptEvents = (event: ScriptEventCommandMessageAfterEvent): void => {
+        if (!event.sourceEntity) return;
+        if (event.id !== `${this.PACK_ID}:entity_emitter`) return;
+
+        let parms: any;
+        try {
+            parms = JSON.parse(event.message);
+        } catch (e) {
+            console.error(`BFLIB: entity_emitter JSON parse failed:`, e);
+            return;
+        }
+
+        this.onEntityEmission.emit({ iEntity: IEntityWrapper.wrap(event.sourceEntity), parms });
+    };
+
+    /* ------------------------------------------------------------------------ */
+    /* Filters                                                                  */
+    /* ------------------------------------------------------------------------ */
+
+    private isValidType(typeId: string): boolean {
+        if (this.PACK_ID && !typeId.startsWith(this.PACK_ID)) return false;
+        return this.SEARCH_TYPES.has(typeId);
+    }
+
+    private onEntitySpawned = (event: EntitySpawnAfterEvent): void => {
+        const entity = event.entity;
+        if (!this.isValidType(entity.typeId)) return;
+        this.saveEntityInMemory(entity);
+    };
+
+    private onEntityRemovedBefore = (event: EntityRemoveBeforeEvent): void => {
+        const entity = event.removedEntity;
+        if (!this.isValidType(entity.typeId)) return;
+        this.deleteEntityInMemory(entity);
+    };
+
+    /* ------------------------------------------------------------------------ */
+    /* Persistence                                                              */
+    /* ------------------------------------------------------------------------ */
+
+    private reloadEntityMemory(): void {
+        this.EM_INDEX.clear();
+        this.EM_KEYS.length = 0;
+
+        const raw = world.getDynamicProperty(this.GLOBAL_MEMORY_ID) as string | undefined;
+        if (!raw) return;
+
+        let parsed: string[];
+        try {
+            parsed = JSON.parse(raw) as string[];
+        } catch (e) {
+            console.error(`BFLIB: Failed to parse ${this.GLOBAL_MEMORY_ID}:`, e);
+            return;
+        }
+
+        for (const id of parsed) {
+            this.EM_KEYS.push(id);
+            const entity = world.getEntity(id);
+            if (entity) this.EM_INDEX.set(entity.id, entity);
+        }
+    }
+
+    private persistKeys(): void {
+        world.setDynamicProperty(this.GLOBAL_MEMORY_ID, JSON.stringify(this.EM_KEYS));
+    }
+
+    public saveEntityInMemory(entity: Entity): boolean {
+        if (this.EM_INDEX.has(entity.id)) return false;
+        this.EM_KEYS.push(entity.id);
+        this.EM_INDEX.set(entity.id, entity);
+        this.persistKeys();
+
+        return true;
+    }
+
+    public deleteEntityInMemory(entity: Entity): boolean {
+        const existed = this.EM_INDEX.delete(entity.id);
+        if (!existed) return false;
+
+        const idx = this.EM_KEYS.indexOf(entity.id);
+        if (idx !== -1) this.EM_KEYS.splice(idx, 1);
+
+        this.persistKeys();
+
+        return true;
+    }
+
+    public getEntitiesInMemory(): Entity[] {
+        return Array.from(this.EM_INDEX.values());
+    }
+}
+
+export const EntityHandler = new SingletonEntityHandler();

package/_module/Framework/ItemTasks.ts

@@ -0,0 +1,157 @@
+import { Signal } from "../util/Signal.js";
+import { ItemCompleteUseAfterEvent, ItemCompleteUseAfterEventSignal, ItemReleaseUseAfterEvent, ItemReleaseUseAfterEventSignal, ItemStack, ItemStartUseAfterEvent, ItemStartUseAfterEventSignal, ItemStartUseOnAfterEvent, ItemStartUseOnAfterEventSignal, ItemStopUseAfterEvent, ItemStopUseAfterEventSignal, ItemStopUseOnAfterEvent, ItemStopUseOnAfterEventSignal, ItemUseAfterEvent, ItemUseAfterEventSignal, ItemUseBeforeEvent, ItemUseBeforeEventSignal, Player, PlayerHotbarSelectedSlotChangeAfterEvent, PlayerHotbarSelectedSlotChangeAfterEventSignal, PlayerInventoryItemChangeAfterEvent, PlayerInventoryItemChangeAfterEventSignal, system, world, WorldLoadAfterEvent, WorldLoadAfterEventSignal } from "@minecraft/server";
+
+export type ItemRegistration = {
+    typeId: string;
+    emitWhileHolding?: boolean
+    emitOnUse?: boolean;
+}
+
+export type WhileHoldingItemEvent = { player: Player; itemStack: ItemStack };
+export type OnItemHeldEvent = { player: Player; itemStack: ItemStack };
+export type OnItemUnheldEvent = { player: Player; itemStack: ItemStack | undefined };
+export type OnItemUsedEvent = { player: Player; itemStack: ItemStack };
+
+interface HoldData {
+    instanceId: number;
+    itemStack: ItemStack;
+}
+
+class SingletonItemHandler {
+    private PACK_ID: string | undefined;
+
+    public readonly whileHoldingItemEvent = new Signal<WhileHoldingItemEvent>();
+    public readonly onItemHeldEvent = new Signal<OnItemHeldEvent>();
+    public readonly onItemUnheldEvent = new Signal<OnItemUnheldEvent>();
+    public readonly onItemUsedEvent = new Signal<OnItemUsedEvent>();
+
+    private readonly loadEventSignal: WorldLoadAfterEventSignal = world.afterEvents.worldLoad;
+    private readonly useBeforeSignal: ItemUseBeforeEventSignal = world.beforeEvents.itemUse;
+    private readonly useAfterSignal: ItemUseAfterEventSignal = world.afterEvents.itemUse;
+    private readonly completeUseSignal: ItemCompleteUseAfterEventSignal = world.afterEvents.itemCompleteUse;
+    private readonly releaseUseSignal: ItemReleaseUseAfterEventSignal = world.afterEvents.itemReleaseUse;
+    private readonly startUseSignal: ItemStartUseAfterEventSignal = world.afterEvents.itemStartUse;
+    private readonly startUseOnSignal: ItemStartUseOnAfterEventSignal = world.afterEvents.itemStartUseOn;
+    private readonly stopUseSignal: ItemStopUseAfterEventSignal = world.afterEvents.itemStopUse;
+    private readonly stopUseOnSignal: ItemStopUseOnAfterEventSignal = world.afterEvents.itemStopUseOn;
+    private readonly inventoryItemChangeSignal: PlayerInventoryItemChangeAfterEventSignal = world.afterEvents.playerInventoryItemChange;
+    private readonly hotbarChangeSignal: PlayerHotbarSelectedSlotChangeAfterEventSignal = world.afterEvents.playerHotbarSelectedSlotChange;
+
+    private readonly IM_INDEX = new Map<string, ItemRegistration>();
+    private readonly HOLD_INDEX: Map<string, HoldData> = new Map<string, HoldData>();
+
+    private _started = false;
+    private _wired = false;
+
+    public registerItem(itemRegistration: ItemRegistration | ItemRegistration[]): void {
+        if (Array.isArray(itemRegistration)) itemRegistration.forEach(i => this.IM_INDEX.set(i.typeId, i));
+        else this.IM_INDEX.set(itemRegistration.typeId, itemRegistration);
+    }
+
+    public start(packId: string): void {
+        if (this._started) throw new Error("BFLIB: ItemHandler already started;");
+        this._started = true;
+        this.PACK_ID = packId;
+        this.loadEventSignal.subscribe(this.onWorldLoad);
+    }
+
+    public stop(): void {
+        if (!this._started) return;
+
+        this.loadEventSignal.unsubscribe(this.onWorldLoad);
+
+        if (this._wired) {
+            this.useBeforeSignal.unsubscribe(this.onUseBefore);
+            this.useAfterSignal.unsubscribe(this.onUseAfter);
+            this.completeUseSignal.unsubscribe(this.onCompleteUse);
+            this.releaseUseSignal.unsubscribe(this.onReleaseUse);
+            this.startUseSignal.unsubscribe(this.onStartUse);
+            this.startUseOnSignal.unsubscribe(this.onStartUseOn);
+            this.stopUseSignal.unsubscribe(this.onStopUse);
+            this.stopUseOnSignal.unsubscribe(this.onStopUseOn);
+            this.hotbarChangeSignal.unsubscribe(this.onHotbarChange);
+            this.inventoryItemChangeSignal.unsubscribe(this.onInventoryItemChange);
+
+            this._wired = false;
+        }
+
+        this._started = false;
+    }
+
+
+    private onWorldLoad = (): void => {
+        if (this.IM_INDEX.size > 0) {
+            this.useBeforeSignal.subscribe(this.onUseBefore);
+            this.useAfterSignal.subscribe(this.onUseAfter);
+            this.completeUseSignal.subscribe(this.onCompleteUse);
+            this.releaseUseSignal.subscribe(this.onReleaseUse);
+            this.startUseSignal.subscribe(this.onStartUse);
+            this.startUseOnSignal.subscribe(this.onStartUseOn);
+            this.stopUseSignal.subscribe(this.onStopUse);
+            this.stopUseOnSignal.subscribe(this.onStopUseOn);
+            this.hotbarChangeSignal.subscribe(this.onHotbarChange);
+            this.inventoryItemChangeSignal.subscribe(this.onInventoryItemChange);
+
+            this._wired = true;
+        }
+
+        this.loadEventSignal.unsubscribe(this.onWorldLoad);
+    };
+
+
+    private onUseBefore = (event: ItemUseBeforeEvent): void => {
+        const itemStack: ItemStack = event.itemStack;
+        if (!this.isValidType(itemStack.typeId)) return;
+        const i: ItemRegistration | undefined = this.IM_INDEX.get(itemStack.typeId);
+        if (!i || !i.emitOnUse) return;
+        const runId: number = system.run(() => {
+            try { this.onItemUsedEvent.emit({ player: event.source, itemStack: event.itemStack }) }
+            catch (error) { throw new Error(`${error}`) }
+            finally { system.clearRun(runId) }
+        })
+
+    };
+    private onUseAfter = (_event: ItemUseAfterEvent): void => { };
+    private onCompleteUse = (_event: ItemCompleteUseAfterEvent): void => { };
+    private onReleaseUse = (_event: ItemReleaseUseAfterEvent): void => { };
+    private onStartUse = (_event: ItemStartUseAfterEvent): void => { };
+    private onStartUseOn = (_event: ItemStartUseOnAfterEvent): void => { };
+    private onStopUse = (_event: ItemStopUseAfterEvent): void => { };
+    private onStopUseOn = (_event: ItemStopUseOnAfterEvent): void => { };
+    private onInventoryItemChange = (_event: PlayerInventoryItemChangeAfterEvent): void => { };
+
+    private onHotbarChange = (event: PlayerHotbarSelectedSlotChangeAfterEvent): void => {
+        const itemStack: ItemStack | undefined = event.itemStack;
+        if (this.HOLD_INDEX.has(event.player.id)) this.releaseHold(event.player);
+        if (!itemStack || (itemStack && !this.isValidType(itemStack.typeId))) return;
+        this.setNewHold(itemStack, event.player);
+    };
+
+    private setNewHold(itemStack: ItemStack, player: Player) {
+        this.onItemHeldEvent.emit({ player: player, itemStack: itemStack });
+
+        const i: ItemRegistration | undefined = this.IM_INDEX.get(itemStack.typeId);
+        let instanceId: number = -1
+        if (i && i.emitWhileHolding) {
+            instanceId = system.runInterval(() => {
+                this.whileHoldingItemEvent.emit({ player: player, itemStack: itemStack });
+            })
+        }
+        this.HOLD_INDEX.set(player.id, { instanceId: instanceId, itemStack: itemStack });
+    }
+
+    private releaseHold(player: Player) {
+        const holdData: HoldData | undefined = this.HOLD_INDEX.get(player.id);
+        if (!holdData) return;
+        this.onItemUnheldEvent.emit({ player: player, itemStack: holdData.itemStack });
+        if (holdData.instanceId !== -1) system.clearRun(holdData.instanceId);
+        this.HOLD_INDEX.delete(player.id);
+    }
+
+    private isValidType(typeId: string): boolean {
+        if (this.PACK_ID && !typeId.startsWith(this.PACK_ID)) return false;
+        return this.IM_INDEX.has(typeId);
+    }
+}
+
+export const ItemHandler = new SingletonItemHandler();

package/_module/Framework/PlayerTasks.ts

@@ -0,0 +1,125 @@
+import { IPlayerWrapper, IPlayer } from "../util/Wrapper/IPlayer";
+import { ButtonState, InputButton, Player, PlayerButtonInputAfterEvent, PlayerButtonInputAfterEventSignal, PlayerLeaveBeforeEvent, PlayerLeaveBeforeEventSignal, PlayerSpawnAfterEvent, PlayerSpawnAfterEventSignal, world, WorldLoadAfterEvent, WorldLoadAfterEventSignal } from "@minecraft/server";
+
+class SingletonPlayerHandler {
+    private readonly GLOBAL_MEMORY_ID = "GLB_MEM.PLAYER";
+
+    private readonly loadEventSignal: WorldLoadAfterEventSignal = world.afterEvents.worldLoad;
+    private readonly playerSpawnSignal: PlayerSpawnAfterEventSignal = world.afterEvents.playerSpawn;
+    private readonly playerLeaveBeforeSignal: PlayerLeaveBeforeEventSignal = world.beforeEvents.playerLeave;
+    private readonly buttonInputSignal: PlayerButtonInputAfterEventSignal = world.afterEvents.playerButtonInput;
+
+    private readonly PR_INDEX = new Map<string, Player>();
+    private readonly PR_KEYS: string[] = [];
+
+    private _started: boolean = false;
+    private _wired: boolean = false;
+
+    public start(): void {
+        if (this._started) throw new Error("BFLIB: PlayerHandler already started;");
+        this._started = true;
+        this.onSystemLoad();
+        this.loadEventSignal.subscribe(this.onWorldLoad);
+        this.buttonInputSignal.subscribe(this.onButtonPress);
+    }
+
+    public stop(): void {
+        if (!this._started) return;
+        if (this._wired) {
+            this.playerSpawnSignal.unsubscribe(this.onPlayerSpawned);
+            this.playerLeaveBeforeSignal.unsubscribe(this.onPlayerLeaveBefore);
+            this.buttonInputSignal.unsubscribe(this.onButtonPress);
+            this._wired = false;
+        }
+        this._started = false;
+    }
+
+    private onWorldLoad = (): void => {
+        this.reloadPlayerMemory();
+        this.loadEventSignal.unsubscribe(this.onWorldLoad);
+    };
+
+    private onSystemLoad(): void {
+        this.playerSpawnSignal.subscribe(this.onPlayerSpawned);
+        this.playerLeaveBeforeSignal.subscribe(this.onPlayerLeaveBefore);
+        this._wired = true;
+    }
+
+    private onPlayerSpawned = (event: PlayerSpawnAfterEvent): void => {
+        if (!event) return;
+        if (this.hasPlayer(event.player.id)) return;
+        this.savePlayerInMemory(event.player);
+    };
+
+    private onPlayerLeaveBefore = (event: PlayerLeaveBeforeEvent): void => {
+        if (!this.hasPlayer(event.player.id)) return;
+        this.deletePlayerInMemory(event.player);
+    };
+
+    private onButtonPress = (event: PlayerButtonInputAfterEvent): void => {
+        if (event.button === InputButton.Jump) {
+
+        }
+        else if (event.button === InputButton.Sneak) {
+
+        }
+        console.warn(`Player ${event.player.name} pressed button ${InputButton[event.button]}: ${ButtonState[event.newButtonState]}`);
+    };
+
+    public hasPlayer(playerId: string): boolean {
+        return this.PR_INDEX.has(playerId);
+    }
+
+    /* ------------------------------------------------------------------------ */
+    /* Persistence                                                              */
+    /* ------------------------------------------------------------------------ */
+
+    private reloadPlayerMemory(): void {
+        this.PR_INDEX.clear();
+        this.PR_KEYS.length = 0;
+
+        const players: Player[] = world.getAllPlayers();
+        for (const player of players) {
+            this.PR_INDEX.set(player.id, player);
+            this.PR_KEYS.push(player.id);
+        }
+    }
+
+
+
+    private persistKeys(): void {
+        world.setDynamicProperty(this.GLOBAL_MEMORY_ID, JSON.stringify(this.PR_KEYS));
+    }
+
+    public savePlayerInMemory(player: Player): boolean {
+        if (this.PR_INDEX.has(player.id)) return false;
+        this.PR_KEYS.push(player.id);
+        this.PR_INDEX.set(player.id, player);
+        this.persistKeys();
+
+        return true;
+    }
+
+    public deletePlayerInMemory(player: Player): boolean {
+        const existed = this.PR_INDEX.delete(player.id);
+        if (!existed) return false;
+
+        const idx = this.PR_KEYS.indexOf(player.id);
+        if (idx !== -1) this.PR_KEYS.splice(idx, 1);
+
+        this.persistKeys();
+
+        return true;
+    }
+
+    public getPlayersInMemory(): Player[] {
+        return Array.from(this.PR_INDEX.values());
+    }
+
+    public getIPlayersInMemory(): IPlayer[] {
+        return Array.from(this.PR_INDEX.values())
+            .map(player => IPlayerWrapper.wrap(player));
+    }
+}
+
+export const PlayerHandler = new SingletonPlayerHandler();

package/_module/Framework/Threads.ts

@@ -0,0 +1,72 @@
+import { system, TicksPerSecond } from "@minecraft/server";
+import { Signal } from "../util/Signal";
+
+export type ThreadConfig = {
+    mainRate?: number; // interval ticks
+    lateRate?: number; // interval ticks
+};
+
+class SingletonThreadManager {
+    public readonly MAIN = new Signal<number>();
+    public readonly LATE = new Signal<void>();
+
+    private _mainRate = 0;
+    private _lateRate = TicksPerSecond;
+
+    private _MAIN_ID: number | undefined;
+    private _LATE_ID: number | undefined;
+
+    private _delta = this.createDeltaTimer();
+    private _started = false;
+
+    public configure(cfg: ThreadConfig) {
+        if (this._started) throw new Error("BFLIB: _THREAD_ already started; configure before start().");
+        if (cfg.mainRate !== undefined) this._mainRate = cfg.mainRate;
+        if (cfg.lateRate !== undefined) this._lateRate = cfg.lateRate;
+    }
+
+    public start() {
+        if (this._started) return; // idempotent
+        this._started = true;
+
+        this._MAIN_ID = system.runInterval(() => {
+            if (this.MAIN.count <= 0) return;
+            try {
+                const delta = this._delta();
+                this.MAIN.emit(delta);
+            } catch (e) {
+                console.error(`ERROR: _THREAD_.MAIN:${this._MAIN_ID} |`, e);
+            }
+        }, this._mainRate);
+
+        this._LATE_ID = system.runInterval(() => {
+            if (this.LATE.count <= 0) return;
+            try {
+                this.LATE.emit();
+            } catch (e) {
+                console.error(`ERROR: _THREAD_.LATE:${this._LATE_ID} |`, e);
+            }
+        }, this._lateRate);
+    }
+
+    public stop() {
+        if (this._MAIN_ID !== undefined) system.clearRun(this._MAIN_ID);
+        if (this._LATE_ID !== undefined) system.clearRun(this._LATE_ID);
+        this._MAIN_ID = undefined;
+        this._LATE_ID = undefined;
+        this._started = false;
+        this._delta = this.createDeltaTimer(); // reset delta timing
+    }
+
+    private createDeltaTimer() {
+        let last = Date.now();
+        return () => {
+            const now = Date.now();
+            const delta = (now - last) / 1000;
+            last = now;
+            return delta;
+        };
+    }
+}
+
+export const Thread = new SingletonThreadManager();

package/_module/util/Signal.ts

@@ -1,31 +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 cb of Array.from(this.listeners)) {
-            cb(data);
+        for (const callback of Array.from(this.listeners)) {
+            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));
+    }
 }

package/_module/util/Wrapper/IEntity.ts

@@ -1,6 +1,7 @@
-import { Entity, EntityInventoryComponent } from "@minecraft/server";
+import { Entity, EntityInventoryComponent, PlayAnimationOptions, system, TicksPerSecond } from "@minecraft/server";
 import { ContainerWrapper, Inventory } from "./Container";
 import { System } from "../System";
+import { Animation } from "../../DataTypes";
 
 export type IEntity = IEntityWrapper & Entity;
 
@@ -17,9 +18,8 @@ export class IEntityWrapper {
     }
 
     //======================== Interal ========================
-    public isAlive: boolean = false;
 
-    public get inventory(): Inventory {
+    public get inventory(): Inventory | undefined {
         const i = this.source.getComponent(
             EntityInventoryComponent.componentId
         ) as EntityInventoryComponent;
@@ -27,8 +27,9 @@ export class IEntityWrapper {
         return ContainerWrapper.wrap(i.container);
     }
 
-    public test(): void {
-        //this.source.sendMessage(`${this.source.name} was tested`);
+    public async playAnimationAsync(animation: Animation, options: PlayAnimationOptions): Promise<void> {
+        this.source.playAnimation(animation.id, options);
+        await system.waitTicks(animation.length * TicksPerSecond);
     }
 
 }