@block_factory/lib 0.0.1 → 0.0.3

package/sys/Threads.ts

@@ -0,0 +1,43 @@
+import { system, TicksPerSecond } from "@minecraft/server";
+import { Signal } from "../util/Signal";
+
+class Threads {
+    public static create(): Threads { return new Threads() }
+    public readonly MAIN = new Signal<number>();
+    public readonly LATE = new Signal();
+    public MAIN_INTERVAL_RATE: number = 0;
+    public LATE_INTERVAL_RATE: number = TicksPerSecond;
+
+    private _MAIN_ID: number;
+    private _LATE_ID: number;
+    private _delta = this.createDeltaTimer();
+
+    private constructor() {
+        this._MAIN_ID = system.runInterval(() => {
+            if (this.MAIN.count <= 0) return;
+            try { const delta = this._delta(); this.MAIN.emit(delta) }
+            catch (error) {
+                throw Error(`ERROR: _THREAD_.MAIN:${this._MAIN_ID} | ${error}`)
+            }
+        }, this.MAIN_INTERVAL_RATE);
+
+        this._LATE_ID = system.runInterval(() => {
+            if (this.LATE.count <= 0) return;
+            try { this.LATE.emit() }
+            catch (error) { throw Error(`ERROR: _THREAD_.LATE:${this._LATE_ID} | ${error}`) }
+        }, this.LATE_INTERVAL_RATE);
+    }
+
+    private createDeltaTimer() {
+        let last = Date.now();
+
+        return function nextDelta(): number {
+            const now = Date.now();
+            const delta = (now - last) / 1000; // seconds
+            last = now;
+            return delta;
+        };
+    }
+}
+
+export const _THREAD_ = Threads.create();

package/tsconfig.types.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/util/Forms/Form.d.ts

@@ -0,0 +1,16 @@
+import { Player, RawMessage } from "@minecraft/server";
+
+export declare type IFormValue =
+    | string
+    | boolean
+    | number
+    | undefined;
+
+export declare abstract class IForm {
+    static returnText: RawMessage | string;
+    static isOccupied(player: Player): boolean;
+    static closeForms(player: Player): void;
+    static closeOccupiedForms(): void;
+    protected setOccupied(player: Player, occupied: boolean): void;
+    protected abstract build(player: Player): void;
+}

package/util/Forms/Form.ts

@@ -0,0 +1,31 @@
+import { Player, RawMessage, world } from "@minecraft/server";
+import { uiManager } from "@minecraft/server-ui";
+
+export declare type IFormValue = string | boolean | number | undefined;
+
+export abstract class IForm {
+    private static readonly occupiedPlayers: Set<string> = new Set();
+    public static returnText: RawMessage | string = "Back";
+
+    public static isOccupied(player: Player): boolean {
+        return IForm.occupiedPlayers.has(player.id);
+    }
+
+    public static closeForms(player: Player): void {
+        uiManager.closeAllForms(player);
+    }
+
+    public static closeOccupiedForms(): void {
+        for (const playerId of IForm.occupiedPlayers) {
+            const player = world.getEntity(playerId) as Player | undefined;
+            if (player) uiManager.closeAllForms(player);
+        }
+    }
+
+    protected setOccupied(player: Player, occupied: boolean): void {
+        if (occupied) IForm.occupiedPlayers.add(player.id);
+        else IForm.occupiedPlayers.delete(player.id);
+    }
+
+    protected abstract build(player: Player): void;
+}

package/util/Forms/FormAction.d.ts

@@ -0,0 +1,41 @@
+import { IForm } from "./Form";
+import { Player, RawMessage } from "@minecraft/server";
+import { ActionFormData, FormCancelationReason } from "@minecraft/server-ui";
+
+export declare type ActionFormCtor<T extends IActionFormData = IActionFormData> = new () => T;
+
+export declare interface IButtonOptions {
+    id?: string | number;
+    iconPath?: string;
+    subForm?: ActionFormCtor;
+    allowReturn?: boolean;
+}
+
+export declare interface IActionFormResponse {
+    readonly cancelationReason?: FormCancelationReason;
+    readonly canceled: boolean;
+    readonly selection?: number;
+    readonly id?: string | number;
+}
+
+export declare abstract class IActionFormData extends IForm {
+    protected form: ActionFormData;
+
+    protected abstract build(player: Player): void;
+
+    protected abstract onSubmit(player: Player, response: IActionFormResponse): void;
+
+    protected onCancel?(player: Player, response: IActionFormResponse): void;
+
+    title(titleText: RawMessage | string): this;
+    body(bodyText: RawMessage | string): this;
+    divider(): this;
+    header(text: RawMessage | string): this;
+    label(text: RawMessage | string): this;
+
+    button(text: RawMessage | string, options?: IButtonOptions): this;
+
+    show(player: Player): Promise<IActionFormResponse>;
+
+    protected _showChained(player: Player, returnStack: ActionFormCtor[]): Promise<IActionFormResponse>;
+}

package/util/Forms/FormAction.ts

@@ -0,0 +1,196 @@
+import { IForm } from "./Form";
+import { Player, RawMessage } from "@minecraft/server";
+import { ActionFormData, ActionFormResponse, FormCancelationReason } from "@minecraft/server-ui";
+
+const RETURN_ID = "d7213196-4cb6-4199-a40b-22fbf2d944ef";
+
+/**
+ * Constructor type for ActionForm classes.
+ * Used for sub-form navigation and chaining.
+ */
+export type ActionFormCtor<T extends IActionFormData = IActionFormData> = new () => T;
+
+/**
+ * Options used when adding a button to an ActionForm.
+ */
+export interface IButtonOptions {
+    /**
+     * Logical identifier returned in the form response.
+     * If omitted, the numeric button index is used.
+     */
+    id?: string | number;
+
+    /**
+     * Optional icon path from a resource pack.
+     */
+    iconPath?: string;
+
+    /**
+     * Form class to open when this button is selected.
+     */
+    subForm?: ActionFormCtor;
+
+    /**
+     * Whether the sub-form is allowed to return to this form.
+     * Defaults to true.
+     */
+    allowReturn?: boolean;
+}
+
+type ButtonMeta = {
+    id: string | number;
+    subForm?: ActionFormCtor;
+    allowReturn: boolean;
+};
+
+/**
+ * Normalized response object returned by IActionFormData.
+ */
+export interface IActionFormResponse {
+    /**Reason the form was canceled, if applicable.*/
+    readonly cancelationReason?: FormCancelationReason;
+    /** Whether the form was canceled by the player.*/
+    readonly canceled: boolean;
+    /**Raw button index selected by the player.*/
+    readonly selection?: number;
+    /**Logical button id associated with the selection.*/
+    readonly id?: string | number;
+}
+
+/**
+ * Abstract base class for ActionForm-based menus.
+ *
+ * Provides:
+ * - Button id mapping
+ * - Occupied player handling
+ * - Sub-form chaining with automatic Back navigation
+ * - Normalized response objects
+ */
+export abstract class IActionFormData extends IForm {
+    protected form: ActionFormData = new ActionFormData();
+
+    private _buttons = new Map<number, ButtonMeta>();
+    private _nextButtonIndex = 0;
+    private _id: string = "untitled";
+
+    protected abstract build(player: Player): void;
+
+    protected abstract onSubmit(player: Player, response: IActionFormResponse): void;
+
+    protected onCancel?(player: Player, response: IActionFormResponse): void;
+
+    public title(titleText: RawMessage | string): this {
+        this.form.title(titleText);
+        this._id = typeof titleText === "string" ? titleText : JSON.stringify(titleText);
+        return this;
+    }
+
+    public body(bodyText: RawMessage | string): this { this.form.body(bodyText); return this; }
+
+    public divider(): this { this.form.divider(); return this; }
+
+    public header(text: RawMessage | string): this { this.form.header(text); return this; }
+
+    public label(text: RawMessage | string): this { this.form.label(text); return this; }
+
+    public button(text: RawMessage | string, options: IButtonOptions = {}): this {
+        if (options.iconPath) this.form.button(text, options.iconPath);
+        else this.form.button(text);
+
+        const id: string | number = options.id ?? this._nextButtonIndex;
+        const allowReturn = options.allowReturn ?? true;
+
+        this._buttons.set(this._nextButtonIndex, {
+            id,
+            subForm: options.subForm,
+            allowReturn,
+        });
+
+        this._nextButtonIndex++;
+        return this;
+    }
+
+    public async show(player: Player): Promise<IActionFormResponse> {
+        if (IForm.isOccupied(player)) {
+            throw new Error(`Player ${player.id} is already occupied by form: ${this._id}`);
+        }
+
+        this.setOccupied(player, true);
+
+        try {
+            return await this._showInternal(player, []);
+        } finally {
+            this.setOccupied(player, false);
+        }
+    }
+
+    protected async _showChained(player: Player, returnStack: ActionFormCtor[]): Promise<IActionFormResponse> {
+        return await this._showInternal(player, returnStack);
+    }
+
+    private _wrapResponse(response: ActionFormResponse, id?: string | number): IActionFormResponse {
+        return {
+            canceled: response.canceled,
+            cancelationReason: response.cancelationReason,
+            selection: response.selection,
+            id,
+        };
+    }
+
+    private async _showInternal(player: Player, returnStack: ActionFormCtor[]): Promise<IActionFormResponse> {
+
+        this.form = new ActionFormData();
+
+        this._buttons.clear();
+        this._nextButtonIndex = 0;
+
+        this.build(player);
+
+        if (returnStack.length > 0) {
+            this.form.button(IForm.returnText);
+            this._buttons.set(this._nextButtonIndex, {
+                id: RETURN_ID,
+                subForm: returnStack[returnStack.length - 1],
+                allowReturn: true,
+            });
+            this._nextButtonIndex++;
+        }
+
+        const response = await this.form.show(player);
+
+        if (response.canceled) {
+            const wrapped = this._wrapResponse(response, undefined);
+            this.onCancel?.(player, wrapped);
+            return wrapped;
+        }
+
+        const meta =
+            response.selection !== undefined
+                ? this._buttons.get(response.selection)
+                : undefined;
+
+        if (meta?.id === RETURN_ID && meta.subForm) {
+            const prevCtor = returnStack[returnStack.length - 1];
+            const newStack = returnStack.slice(0, -1);
+            const prev = new prevCtor();
+            return await prev._showChained(player, newStack);
+        }
+
+        const wrapped = this._wrapResponse(response, meta?.id);
+
+        this.onSubmit(player, wrapped);
+
+        if (meta?.subForm) {
+            const next = new meta.subForm();
+            const allowReturn = meta.allowReturn ?? true;
+
+            const nextStack = allowReturn
+                ? [...returnStack, this.constructor as ActionFormCtor]
+                : [...returnStack];
+
+            return await next._showChained(player, nextStack);
+        }
+
+        return wrapped;
+    }
+}

package/util/Forms/FormMessage.d.ts

@@ -0,0 +1,30 @@
+import { IForm } from "./Form";
+import { Player, RawMessage } from "@minecraft/server";
+import { MessageFormData, MessageFormResponse } from "@minecraft/server-ui";
+
+export declare abstract class IMessageFormData extends IForm {
+    protected form: MessageFormData;
+
+    private _id: string;
+
+    protected abstract build(player: Player): void;
+
+    protected abstract onSubmit(
+        player: Player,
+        response: MessageFormResponse
+    ): void;
+
+    protected onCancel?(player: Player, response: MessageFormResponse): void;
+
+    title(titleText: RawMessage | string): this;
+
+    body(bodyText: RawMessage | string): this;
+
+    button0(text: RawMessage | string, id?: string | number): this;
+
+    button1(text: RawMessage | string, id?: string | number): this;
+
+    show(player: Player): Promise<MessageFormResponse>;
+
+    private _showInternal(player: Player): Promise<MessageFormResponse>;
+}

package/util/Forms/FormMessage.ts

@@ -0,0 +1,87 @@
+import { IForm } from "./Form";
+import { Player, RawMessage } from "@minecraft/server";
+import {
+    MessageFormData,
+    MessageFormResponse,
+} from "@minecraft/server-ui";
+
+/**
+ * Abstract base class for MessageFormData.
+ *
+ * Provides:
+ * - occupied player handling
+ */
+
+export type IMessageFormResponse = MessageFormResponse; // re-export wrapper for consistency
+
+export abstract class IMessageFormData extends IForm {
+    protected form: MessageFormData = new MessageFormData();
+
+    private _id: string = "untitled";
+
+    protected abstract build(player: Player): void;
+
+    protected abstract onSubmit(
+        player: Player,
+        response: IMessageFormResponse
+    ): void;
+
+    protected onCancel?(player: Player, response: IMessageFormResponse): void;
+
+    public title(titleText: RawMessage | string): this {
+        this.form.title(titleText);
+        this._id =
+            typeof titleText === "string"
+                ? titleText
+                : JSON.stringify(titleText);
+        return this;
+    }
+
+    public body(bodyText: RawMessage | string): this {
+        this.form.body(bodyText);
+        return this;
+    }
+    public button0(text: RawMessage | string,id: string | number = 0): this {
+        this.form.button1(text);
+        return this;
+    }
+
+    public button1(text: RawMessage | string,id: string | number = 1): this {
+        this.form.button2(text);
+        return this;
+    }
+
+    public async show(player: Player): Promise<IMessageFormResponse> {
+        if (IForm.isOccupied(player)) {
+            throw new Error(
+                `Player ${player.id} is already occupied by form: ${this._id}`
+            );
+        }
+
+        this.setOccupied(player, true);
+
+        try {
+            return await this._showInternal(player);
+        } finally {
+            this.setOccupied(player, false);
+        }
+    }
+
+    private async _showInternal(
+        player: Player
+    ): Promise<IMessageFormResponse> {
+        this.form = new MessageFormData();
+
+        this.build(player);
+
+        const res = await this.form.show(player);
+
+        if (res.canceled || res.selection === undefined) {
+            this.onCancel?.(player, res);
+            return res;
+        }
+
+        this.onSubmit(player, res);
+        return res;
+    }
+}

package/util/Forms/FormModal.d.ts

@@ -0,0 +1,57 @@
+import { IForm, IFormValue } from "./Form";
+import { Player, RawMessage } from "@minecraft/server";
+import { ModalFormData, FormCancelationReason } from "@minecraft/server-ui";
+
+export declare interface IModalFormResponse {
+    readonly cancelationReason?: FormCancelationReason;
+    readonly canceled: boolean;
+    readonly formValues?: IFormValue[];
+    readonly widget?: Map<string, IFormValue>;
+}
+
+export declare interface ITextFieldOptions {
+    id: string;
+    placeholder: string | RawMessage;
+    defaultValue?: string;
+}
+
+export declare interface IDropdownOptions {
+    id: string;
+    choices: string[];
+    defaultValueIndex?: number;
+}
+
+export declare interface ISliderOptions {
+    id: string;
+    min: number;
+    max: number;
+    step: number;
+    defaultValue?: number;
+}
+
+export declare interface IToggleOptions {
+    id: string;
+    defaultValue?: boolean;
+}
+
+export declare abstract class IModalFormData extends IForm {
+    protected form: ModalFormData;
+
+    protected abstract build(player: Player): void;
+
+    protected abstract onSubmit(player: Player, response: IModalFormResponse): void;
+
+    protected onCancel?(player: Player, response: IModalFormResponse): void;
+
+    title(titleText: RawMessage | string): this;
+    divider(): this;
+    header(text: RawMessage | string): this;
+    label(text: RawMessage | string): this;
+
+    textField(label: string | RawMessage, options: ITextFieldOptions): this;
+    dropdown(label: string | RawMessage, options: IDropdownOptions): this;
+    slider(label: string | RawMessage, options: ISliderOptions): this;
+    toggle(label: string | RawMessage, options: IToggleOptions): this;
+
+    show(player: Player): Promise<IModalFormResponse>;
+}

package/util/Forms/FormModal.ts

@@ -0,0 +1,183 @@
+import { IForm } from "./Form";
+import { Player, RawMessage } from "@minecraft/server";
+import {
+    ModalFormData,
+    ModalFormResponse,
+    FormCancelationReason,
+    ModalFormDataDropdownOptions,
+    ModalFormDataSliderOptions,
+    ModalFormDataTextFieldOptions,
+    ModalFormDataToggleOptions,
+} from "@minecraft/server-ui";
+
+export type FormValue = string | boolean | number | undefined;
+
+/** Normalized response for Modal forms */
+export interface IModalFormResponse {
+    /**Reason the form was canceled, if applicable.*/
+    readonly cancelationReason?: FormCancelationReason;
+    /** Whether the form was canceled by the player.*/
+    readonly canceled: boolean;
+    /** Raw values array from the form */
+    readonly formValues?: FormValue[];
+    /** Mapped values by widget id */
+    readonly widget?: Map<string, FormValue>;
+}
+
+/** Options for each widget type */
+export interface ITextFieldOptions {
+    id: string;
+    placeholder: string | RawMessage;
+    defaultValue?: string;
+}
+export interface IDropdownOptions {
+    id: string;
+    choices: string[];
+    defaultValueIndex?: number;
+}
+export interface ISliderOptions {
+    id: string;
+    min: number;
+    max: number;
+    step: number;
+    defaultValue?: number;
+}
+export interface IToggleOptions {
+    id: string;
+    defaultValue?: boolean;
+}
+
+type WidgetMeta =
+    | { type: "textField"; id: string }
+    | { type: "dropdown"; id: string }
+    | { type: "slider"; id: string }
+    | { type: "toggle"; id: string };
+
+/**
+ * Abstract base class for ModalFormData-based menus.
+ *
+ * Provides:
+ * - Occupied player handling
+ * - Widget id mapping into a Map<string, FormValue>
+ * - Normalized response object
+ */
+export abstract class IModalFormData extends IForm {
+    protected form: ModalFormData = new ModalFormData();
+
+    private _id: string = "untitled";
+    private _widgetMeta: WidgetMeta[] = [];
+
+    protected abstract build(player: Player): void;
+
+    protected abstract onSubmit(player: Player, response: IModalFormResponse): void;
+
+    protected onCancel?(player: Player, response: IModalFormResponse): void;
+
+    public title(titleText: RawMessage | string): this {
+        this.form.title(titleText);
+        this._id = typeof titleText === "string" ? titleText : JSON.stringify(titleText);
+        return this;
+    }
+
+    public divider(): this {
+        this.form.divider();
+        return this;
+    }
+
+    public header(text: RawMessage | string): this {
+        this.form.header(text);
+        return this;
+    }
+
+    public label(text: RawMessage | string): this {
+        this.form.label(text);
+        return this;
+    }
+
+    public textField(label: string | RawMessage, options: ITextFieldOptions): this {
+        const opts: ModalFormDataTextFieldOptions = { defaultValue: options.defaultValue };
+        this.form.textField(label, options.placeholder, opts);
+        this._widgetMeta.push({ type: "textField", id: options.id });
+        return this;
+    }
+
+    public dropdown(label: string | RawMessage, options: IDropdownOptions): this {
+        const opts: ModalFormDataDropdownOptions = { defaultValueIndex: options.defaultValueIndex };
+        this.form.dropdown(label, options.choices, opts);
+        this._widgetMeta.push({ type: "dropdown", id: options.id });
+        return this;
+    }
+
+    public slider(label: string | RawMessage, options: ISliderOptions): this {
+        const opts: ModalFormDataSliderOptions = {
+            defaultValue: options.defaultValue,
+            valueStep: options.step,
+        };
+        this.form.slider(label, options.min, options.max, opts);
+        this._widgetMeta.push({ type: "slider", id: options.id });
+        return this;
+    }
+
+    public toggle(label: string | RawMessage, options: IToggleOptions): this {
+        const opts: ModalFormDataToggleOptions = { defaultValue: options.defaultValue };
+        this.form.toggle(label, opts);
+        this._widgetMeta.push({ type: "toggle", id: options.id });
+        return this;
+    }
+
+    public async show(player: Player): Promise<IModalFormResponse> {
+        if (IForm.isOccupied(player)) {
+            throw new Error(`Player ${player.id} is already occupied by form: ${this._id}`);
+        }
+
+        this.setOccupied(player, true);
+
+        try {
+            return await this._showInternal(player);
+        } finally {
+            this.setOccupied(player, false);
+        }
+    }
+
+    private _wrapResponse(res: ModalFormResponse, values?: Map<string, FormValue>): IModalFormResponse {
+        return {
+            canceled: res.canceled,
+            cancelationReason: res.cancelationReason,
+            formValues: res.formValues as FormValue[] | undefined,
+            widget: values,
+        };
+    }
+
+    private _mapValues(formValues: FormValue[] | undefined): Map<string, FormValue> | undefined {
+        if (!formValues) return undefined;
+
+        const out = new Map<string, FormValue>();
+        for (let i = 0; i < formValues.length; i++) {
+            const meta = this._widgetMeta[i];
+            if (!meta) continue;
+            out.set(meta.id, formValues[i]);
+        }
+        return out;
+    }
+
+    private async _showInternal(player: Player): Promise<IModalFormResponse> {
+        this.form = new ModalFormData();
+        this._widgetMeta = [];
+
+        this.build(player);
+
+        const res = await this.form.show(player);
+
+        if (res.canceled) {
+            const wrapped = this._wrapResponse(res);
+            this.onCancel?.(player, wrapped);
+            return wrapped;
+        }
+
+        const values = this._mapValues(res.formValues as FormValue[] | undefined);
+        const wrapped = this._wrapResponse(res, values);
+
+        this.onSubmit(player, wrapped);
+        return wrapped;
+    }
+}