@block_factory/lib 0.0.5 → 0.0.8

package/_module/util/TempLeaker.ts

@@ -0,0 +1,137 @@
+import { Entity, Player, system } from "@minecraft/server";
+
+/**
+ * Relay utility that abuses `playAnimation(... stopExpression ...)`
+ * to write values into Molang temps (`t.*`) on the client.
+ *
+ * - Always includes `t.source_name` and `t.__nonce__`
+ * - Values are serialized into a single `stopExpression` string
+ * - Intended for lightweight HUD / animation-controller syncing
+ *
+ * @external @example
+ *
+ * Client json relay example
+ *
+ * "scripts": {
+ *   "initialize": [
+ *     "v._nonce_swing = -1;",
+ *     "v.swing = 0;"
+ *   ],
+ *   "pre_animation": [
+ *     "q.is_name_any(t.source_name??'') && (t.__nonce__??-1) != v._nonce_swing ? { v._nonce_swing = t.__nonce__??-1; v.swing = (t.swing??0); };"
+ *   ]
+ * }
+ */
+export class TempLeak {
+  private static readonly ANIM = "5bb1702b_252a_4133_8aff_8ed11f168e4e";
+  private static readonly CTRL = "2ca2eabb_c7d9_4777_8497_57444ea2cd50";
+
+  private static nonceBySource = new Map<string, number>();
+
+  private static nextNonce(source: Player | Entity): number {
+    const n = (this.nonceBySource.get(source.id) ?? 0) + 1;
+    this.nonceBySource.set(source.id, n);
+    return n;
+  }
+
+  private static esc(str: string): string {
+    return str.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  }
+
+  private static fmt(value: unknown): string {
+    if (typeof value === "number") return Number.isFinite(value) ? String(value) : "0";
+    if (typeof value === "boolean") return value ? "1" : "0";
+    if (typeof value === "string") return `'${this.esc(value)}'`;
+    return `'${this.esc(String(value))}'`;
+  }
+
+  private static isPlayer(e: Player | Entity): e is Player {
+    return e instanceof Player;
+  }
+
+  private static buildStopExp(
+    source: Player | Entity,
+    nonce: number,
+    fields: Record<string, unknown>
+  ): string {
+    const sourceName = this.isPlayer(source) ? source.name : source.typeId;
+
+    let exp =
+      `t.source_name='${this.esc(sourceName)}';` +
+      `t.__nonce__=${nonce};`;
+
+    for (const [k, v] of Object.entries(fields)) {
+      const key = k.includes(".") ? k : `t.${k}`;
+      exp += `${key}=${this.fmt(v)};`;
+    }
+
+    exp += "return 0;";
+    return exp;
+  }
+
+  /**
+   * Sends a “no-op” update that only bumps `t.__nonce__` (and sets `t.source_name`).
+   *
+   *
+   * @param source Target source to receive the update.
+   */
+  public static refresh(source: Player | Entity): void {
+    TempLeak.send(source, {});
+  }
+
+  /**
+   * Emits a single payload update to the client by playing a hidden animation
+   * whose `stopExpression` assigns values into `t.*`.
+   *
+   * Notes:
+   * - A per-source monotonic nonce is included as `t.__nonce__`.
+   * - Keys in `fields` are written as `t.<key>` unless you pass a dotted path
+   *   (e.g. `"t.swing"` or `"t.ui.swing"`).
+   * - Numbers are clamped to finite values, booleans become `1/0`, and strings
+   *   are escaped.
+   *
+   * @param source Target source to receive the update.
+   * @param fields Key/value pairs to assign into `t.*` on the client.
+   */
+  public static send(source: Player | Entity, fields: Record<string, unknown>): void {
+    const nonce = this.nextNonce(source);
+    source.playAnimation(this.ANIM, {
+      controller: this.CTRL,
+      stopExpression: this.buildStopExp(source, nonce, fields),
+    });
+  }
+
+  /**
+  * Convenience helper for impulse leaks.
+  *
+  * This sends `setFields` immediately, then (optionally) sends `clearFields`
+  * after `clearDelayTicks`.
+  *
+  * If `clearFields` is provided, it is used as-is.
+  *
+  * Intended use:
+  * - Fire-and-forget booleans like `t.swing = 1` then clear back to `0`
+  * - Short pulses for UI triggers where the client watches for nonce changes
+  *
+  * @param source Target source to receive the update(s).
+  * @param setFields Fields to set immediately.
+  * @param clearFields Fields to send after the delay (optional).
+  * @param clearDelayTicks Tick delay before sending `clearFields` (default: 1).
+  */
+  public static pulse(source: Player | Entity,setFields: Record<string, unknown>,clearFields?: Record<string, unknown>,clearDelayTicks: number = 1): void {
+    this.send(source, setFields);
+    if (!clearFields) return;
+    system.runTimeout(() => {
+      const autoClear: Record<string, unknown> = {};
+      if (!clearFields) {
+        for (const [k, v] of Object.entries(setFields)) {
+          if (typeof v === "string") autoClear[k] = "";
+          else autoClear[k] = 0;
+        }
+        clearFields = autoClear;
+      }
+
+      this.send(source, clearFields);
+    }, clearDelayTicks);
+  }
+}

package/_module/util/Wrapper/IEntity.ts

@@ -1,35 +1,103 @@
-import { Entity, EntityInventoryComponent, PlayAnimationOptions, system, TicksPerSecond } from "@minecraft/server";
-import { ContainerWrapper, Inventory } from "./Container";
-import { System } from "../System";
-import { Animation } from "../../Types";
+import { Entity, EntityRemoveBeforeEvent, PlayAnimationOptions, system, world } from "@minecraft/server";
+import { Inventory } from "./_Container";
+import { iSystem } from "../ISystem";
+import { MinecraftDimensionTypes } from "@minecraft/vanilla-data";
+import { Ctor, PropertyRecord } from "../Globals";
+import { CLASS_I_UUID, WrapperCore } from "./_Common";
 
-export type IEntity = IEntityWrapper & Entity;
+export type IEntity<T extends ICustomEntity> = T & Entity;
 
-export class IEntityWrapper {
-    public readonly source: Entity;
+export abstract class ICustomEntity {
+  protected readonly source: Entity;
+  private intervalId: number = -1;
+  public isNavigating: boolean = false;
 
-    private constructor(source: Entity) {
-        this.source = source;
-        return System.ProxyConstructor(this, source);
-    }
+  public constructor(source: Entity) {
+    this.source = source;
+  }
+  public static wrap<T extends ICustomEntity>(source: Entity, Ctor: Ctor<T>): IEntity<T> {
+    return EntityWrapper.wrap(source, Ctor);
+  }
 
-    public static wrap(source: Entity): IEntity {
-        return new IEntityWrapper(source) as IEntity;
-    }
+  public get inventory(): Inventory | undefined { return WrapperCore.getInventory(this.source); }
 
-    //======================== Interal ========================
+  public loadData(): void { WrapperCore.loadDynData(this as any); }
+  public saveData(): void { WrapperCore.saveDynData(this as any); }
 
-    public get inventory(): Inventory | undefined {
-        const i = this.source.getComponent(
-            EntityInventoryComponent.componentId
-        ) as EntityInventoryComponent;
+  public async playAnimationAsync(id: string, length: number, options?: PlayAnimationOptions): Promise<void> {
+    await WrapperCore.playAnimationAsync(this.source, id, length, options);
+  }
 
-        return ContainerWrapper.wrap(i.container);
-    }
+  public startInterval(tickInterval?: number): number {
+    //TODO
+    //add simulation distance range to pause intervals
+    this.intervalId = system.runInterval(() => {
+      if (!this.source.isValid) { system.clearRun(this.intervalId); return; }
+      this.interval?.();
+    }, tickInterval);
+    return this.intervalId;
+  }
 
-    public async playAnimationAsync(animation: Animation, options: PlayAnimationOptions): Promise<void> {
-        this.source.playAnimation(animation.id, options);
-        await system.waitTicks(animation.length * TicksPerSecond);
-    }
+  public data?(): PropertyRecord;
+  public onReady?(): void;
+  public onRemove?(): void;
+  public interval?(): void;
+}
+
+const cache = new Map<string, Map<Function, any>>();
+
+class EntityWrapper {
+  public static wrap<T extends ICustomEntity>(source: Entity, Ctor: Ctor<T>): IEntity<T> {
+    if (iSystem.packId === "undefined") throw Error(`${this.name} - System.PackId is undefined.`);
+    return WrapperCore.wrap<Entity, IEntity<T>>(cache, source, Ctor);
+  }
 
+  public static repopulateEntity(entity: Entity): void {
+    if (!entity.typeId.startsWith(iSystem.packId)) return;
+    WrapperCore.repopulate(cache, entity, iSystem.iClassRegistry, ICustomEntity.wrap);
+  }
+
+  public static getAll<T extends ICustomEntity>(Ctor: Ctor<T>): IterableIterator<IEntity<T>> {
+    return WrapperCore.iterateByCtor<IEntity<T>>(cache, Ctor);
+  }
 }
+
+world.beforeEvents.entityRemove.subscribe((event) => {
+  const e: Entity = event.removedEntity;
+  const classId = e.getDynamicProperty(CLASS_I_UUID) as string | undefined;
+  system.run(() => {
+    if (!classId) return;
+    const Ctor = iSystem.iClassRegistry.get(classId);
+    if (!Ctor) return;
+    const wrapped = ICustomEntity.wrap(e, Ctor);
+    wrapped.onRemove?.();
+  })
+});
+
+//Delete from cache on remove
+world.afterEvents.entityRemove.subscribe(({ removedEntityId, typeId }) => {
+  if (!typeId.startsWith(iSystem.packId) || !cache.has(removedEntityId)) return;
+  cache.delete(removedEntityId);
+})
+
+//Save entity data on shutdown or reset
+system.beforeEvents.shutdown.subscribe(() => {
+  for (const ent of WrapperCore.iterateAll<IEntity<any>>(cache)) {
+    ent.saveData();
+  }
+});
+
+//Repopulate Entity data on load
+world.afterEvents.entityLoad.subscribe(({ entity }) => {
+  EntityWrapper.repopulateEntity(entity);
+});
+
+//Repopulate All Entity data on reload
+world.afterEvents.worldLoad.subscribe(() => {
+  //TODO
+  //Replace dimension check with stored id array to improve init cycle speed
+  for (const dimensionId of Object.values(MinecraftDimensionTypes)) {
+    const entities = world.getDimension(dimensionId).getEntities();
+    entities.forEach((entity: Entity) => EntityWrapper.repopulateEntity(entity));
+  }
+});

package/_module/util/Wrapper/IItemStack.ts

@@ -0,0 +1,63 @@
+import { ItemStack, system } from "@minecraft/server";
+import { iSystem } from "../ISystem";
+import { Ctor, PropertyRecord } from "../Globals";
+import { WrapperCore, CLASS_I_UUID } from "./_Common";
+
+type DynPropsRW = { getDynamicProperty(k: string): any; setDynamicProperty(k: string, v: any): void };
+type DynPropsW = { setDynamicProperty(k: string, v: any): void };
+type WrapperLike = { loadData(): void; onReady?: () => void };
+
+export type IItemStack<T extends ICustomItemStack> = T & ItemStack;
+
+export abstract class ICustomItemStack {
+    protected readonly source: ItemStack;
+    private intervalId: number = -1;
+
+    public constructor(source: ItemStack) {
+        this.source = source;
+    }
+
+    public loadData(): void { WrapperCore.loadDynData(this as any); }
+    public saveData(): void { WrapperCore.saveDynData(this as any); }
+
+    public static wrap<T extends ICustomItemStack>(source: ItemStack, Ctor: Ctor<T>): IItemStack<T> {
+        return ItemStackWrapper.wrap(source, Ctor);
+    }
+
+    public startInterval(tickInterval?: number): number {
+        this.intervalId = system.runInterval(() => {
+            if (!this.source) { system.clearRun(this.intervalId); return; }
+            this.interval?.();
+        }, tickInterval);
+        return this.intervalId;
+    }
+
+    public data?(): PropertyRecord;
+    public onReady?(): void;
+    public interval?(): void;
+}
+
+class ItemStackWrapper {
+    public static wrap<S extends DynPropsW, W extends WrapperLike>(source: S, Ctor: Ctor<any>): W {
+        const inst = new (Ctor as any)(source);
+        const proxied = iSystem.ProxyConstructor(inst, source) as W;
+
+        proxied.loadData();
+        proxied.onReady?.();
+
+        source.setDynamicProperty(CLASS_I_UUID, Ctor.name);
+        return proxied;
+    }
+
+    public static repopulateItemStack<S extends DynPropsRW, W extends WrapperLike>(source: S): W | undefined {
+        const classId = source.getDynamicProperty(CLASS_I_UUID) as string | undefined;
+        if (!classId) return undefined;
+
+        const Ctor = iSystem.iClassRegistry.get(classId);
+        if (!Ctor) return undefined;
+
+        return ItemStackWrapper.wrap<S, W>(source as any, Ctor);
+    }
+}
+
+

package/_module/util/Wrapper/IPlayer.ts

@@ -1,40 +1,84 @@
-import { EntityInventoryComponent, PlayAnimationOptions, Player, PlayerSoundOptions, system, TicksPerSecond } from "@minecraft/server";
-import { ContainerWrapper, Inventory } from "./Container";
-import { System } from "../System";
-import { Animation, Sound } from "../../Types";
+import { Player, EntityInventoryComponent, PlayAnimationOptions, system, world, TicksPerSecond } from "@minecraft/server";
+import { IContainer, Inventory } from "./_Container";
+import { iSystem } from "../ISystem";
+import { Ctor, PropertyRecord } from "../Globals";
+import { WrapperCore } from "./_Common";
 
-export type IPlayer = IPlayerWrapper & Player;
+export type IPlayer<T extends ICustomPlayer> = T & Player;
 
-export class IPlayerWrapper {
-    public readonly source: Player;
+export abstract class ICustomPlayer {
+  protected readonly source: Player;
+  private intervalId: number = -1;
 
-    private constructor(source: Player) {
-        this.source = source;
-        return System.ProxyConstructor(this, source);
-    }
+  public constructor(source: Player) { this.source = source; }
 
-    public static wrap(player: Player): IPlayer {
-        return new IPlayerWrapper(player) as IPlayer;
-    }
+  public loadData(): void { WrapperCore.loadDynData(this as any); }
+  public saveData(): void { WrapperCore.saveDynData(this as any); }
 
-    //======================== Interal ========================
+  public static wrap<T extends ICustomPlayer>(source: Player, Ctor: Ctor<T>): IPlayer<T> {
+    return PlayerWrapper.wrap(source, Ctor);
+  }
 
-    public get inventory(): Inventory {
-        const i = this.source.getComponent(
-            EntityInventoryComponent.componentId
-        ) as EntityInventoryComponent;
+  public get inventory(): Inventory | undefined {
+    const i = this.source.getComponent(EntityInventoryComponent.componentId) as EntityInventoryComponent | undefined;
+    if (!i?.container) return undefined;
+    return IContainer.wrap(i.container);
+  }
 
-        return ContainerWrapper.wrap(i.container);
-    }
+  public async playAnimationAsync(id: string, length: number, options?: PlayAnimationOptions): Promise<void> {
+    this.source.playAnimation(id, options);
+    await system.waitTicks(Math.round(length * TicksPerSecond));
+  }
 
-    public async playSoundAsync(sound:Sound, options: PlayerSoundOptions): Promise<void>{
-        this.source.playSound(sound.id, options);
-        await system.waitTicks(sound.length * TicksPerSecond);
-    }
+  public startInterval(tickInterval?: number): number {
+    this.intervalId = system.runInterval(() => {
+      if (!this.source.isValid) { system.clearRun(this.intervalId); return; }
+      this.interval?.();
+    }, tickInterval);
+    return this.intervalId;
+  }
 
-    public async playAnimationAsync(animation: Animation, options: PlayAnimationOptions): Promise<void> {
-        this.source.playAnimation(animation.id, options);
-        await system.waitTicks(animation.length * TicksPerSecond);
-    }
+  public data?(): PropertyRecord;
+  public onReady?(): void;
+  public interval?(): void;
+}
+
+const cache = new Map<string, Map<Function, any>>();
+
+class PlayerWrapper {
+  public static wrap<T extends ICustomPlayer>(source: Player, Ctor: Ctor<T>): IPlayer<T> {
+    return WrapperCore.wrap<Player, IPlayer<T>>(cache, source, Ctor);
+  }
+
+  public static repopulatePlayer(player: Player): void {
+    WrapperCore.repopulate(cache, player, iSystem.iClassRegistry, ICustomPlayer.wrap);
+  }
 
+  public static getAll<T extends ICustomPlayer>(Ctor: Ctor<T>): IterableIterator<IPlayer<T>> {
+    return WrapperCore.iterateByCtor<IPlayer<T>>(cache, Ctor);
+  }
 }
+
+//Delete from cache on remove
+world.afterEvents.playerLeave.subscribe(({ playerId }) => {
+  if (!cache.has(playerId)) return;
+  cache.delete(playerId);
+})
+
+//Save Player data on shutdown or reset
+system.beforeEvents.shutdown.subscribe(() => {
+  for (const p of WrapperCore.iterateAll<IPlayer<any>>(cache)) {
+    p.saveData();
+  }
+});
+
+//Repopulate Player data on load
+world.afterEvents.playerSpawn.subscribe(({ player }) => {
+  PlayerWrapper.repopulatePlayer(player);
+});
+
+//Repopulate All Player data on reload
+world.afterEvents.worldLoad.subscribe(() => {
+  const players = world.getAllPlayers();
+  players.forEach((player: Player) => PlayerWrapper.repopulatePlayer(player));
+});

package/_module/util/Wrapper/_Common.ts

@@ -0,0 +1,130 @@
+import type { Ctor, PropertyRecord, PropertyValue } from "../Globals";
+import { Entity, EntityInventoryComponent, PlayAnimationOptions, Player, system, TicksPerSecond } from "@minecraft/server";
+import { IContainer } from "./_Container";
+import { Inventory } from "./_Container";
+import { iSystem } from "../ISystem";
+
+export const CLASS_I_UUID = "269160b9a432";
+
+export type DynStore = {
+  /** schema builder */
+  data?(): PropertyRecord;
+  getDynamicProperty(key: string): PropertyValue | undefined;
+  setDynamicProperty(key: string, value: PropertyValue | undefined): void;
+  [key: string]: any;
+};
+
+/**
+ * Shared wrapper core for Entity + Player.
+ */
+export class WrapperCore {
+  public static wrap<S extends { id: string; setDynamicProperty(k: string, v: any): void }, W extends { loadData(): void; onReady?: () => void }>(
+    cache: Map<string, Map<Function, any>>,
+    source: S,
+    Ctor: Ctor<any>
+  ): W {
+    let byCtor = cache.get(source.id);
+    if (!byCtor) { byCtor = new Map(); cache.set(source.id, byCtor); }
+
+    const existing = byCtor.get(Ctor) as W | undefined;
+    if (existing) return existing;
+
+    const inst = new (Ctor as any)(source);
+    const proxied = iSystem.ProxyConstructor(inst, source) as W;
+
+    proxied.loadData();
+    proxied.onReady?.();
+
+    byCtor.set(Ctor, proxied);
+    source.setDynamicProperty(CLASS_I_UUID, Ctor.name);
+
+    return proxied;
+  }
+
+  public static repopulate<S extends { id: string; getDynamicProperty(k: string): any, isValid: boolean }>(
+    cache: Map<string, Map<Function, any>>,
+    source: S,
+    registry: Map<string, Ctor<any>>,
+    wrapFn: (source: any, ctor: Ctor<any>) => any
+  ): void {
+    if (cache.has(source.id) || !source.isValid) return;
+
+    const classId = source.getDynamicProperty(CLASS_I_UUID) as string | undefined;
+    if (!classId) return;
+
+    const Ctor = registry.get(classId);
+    if (!Ctor) return;
+
+    wrapFn(source as any, Ctor);
+  }
+
+  public static *iterateAll<W>(
+    cache: Map<string, Map<Function, any>>
+  ): IterableIterator<W> {
+    for (const [, byCtor] of cache) {
+      for (const [, instance] of byCtor) {
+        yield instance as W;
+      }
+    }
+  }
+
+  public static *iterateByCtor<W>(
+    cache: Map<string, Map<Function, any>>,
+    Ctor: Function
+  ): IterableIterator<W> {
+    for (const [, byCtor] of cache) {
+      const inst = byCtor.get(Ctor);
+      if (inst) yield inst as W;
+    }
+  }
+
+  public static getAllByCtor<W>(
+    cache: Map<string, Map<Function, any>>,
+    Ctor: Function
+  ): W[] {
+    const out: W[] = [];
+    for (const [, byCtor] of cache) {
+      const inst = byCtor.get(Ctor);
+      if (inst) out.push(inst as W);
+    }
+    return out;
+  }
+
+  public static getAll<W>(cache: Map<string, Map<Function, any>>): W[] {
+    const out: W[] = [];
+    for (const [, byCtor] of cache) {
+      for (const [, inst] of byCtor) out.push(inst as W);
+    }
+    return out;
+  }
+
+  public static loadDynData(target: DynStore): void {
+    if (!target.data) return;
+
+    const schema = target.data() as Record<string, unknown>;
+    for (const key of Object.keys(schema)) {
+      const v = target.getDynamicProperty(key);
+      if (v !== undefined) (target as any)[key] = v;
+    }
+  }
+
+  public static saveDynData(target: DynStore): void {
+    if (!target.isValid || !target.data) return;
+
+    const saveData = target.data() as Record<string, unknown>;
+    for (const [key, value] of Object.entries(saveData)) {
+      target.setDynamicProperty(key, value as PropertyValue);
+    }
+  }
+
+  public static getInventory(source: Entity | Player): Inventory | undefined {
+    const i = source.getComponent(EntityInventoryComponent.componentId) as EntityInventoryComponent | undefined;
+    if (!i?.container) return undefined;
+    return IContainer.wrap(i.container);
+  }
+
+  public static async playAnimationAsync(source: Entity | Player, id: string, length: number, options?: PlayAnimationOptions): Promise<void> {
+    source.playAnimation(id, options);
+    await system.waitTicks(Math.round(length * TicksPerSecond));
+  }
+}

package/_module/util/Wrapper/{Container.ts → _Container.ts}

@@ -1,18 +1,18 @@
 import { Container, ItemStack} from "@minecraft/server";
-import { System } from "../System";
+import { iSystem } from "../ISystem";
 
-export type Inventory = ContainerWrapper & Container;
+export type Inventory = IContainer & Container;
 
-export class ContainerWrapper {
+export class IContainer {
    public readonly source: Container;
 
     private constructor(source: Container) {
         this.source = source;
-        return System.ProxyConstructor(this, source);
+        return iSystem.ProxyConstructor(this, source);
     }
 
     public static wrap(source: Container): Inventory {
-        return new ContainerWrapper(source) as Inventory;
+        return new IContainer(source) as Inventory;
     }
 
     //======================== Interal ========================