@block_factory/lib 0.0.1

package/util/Command.ts

@@ -0,0 +1,124 @@
+import {
+    CustomCommand,
+    CommandPermissionLevel,
+    CustomCommandParameter,
+    CustomCommandOrigin,
+    CustomCommandResult,
+    system,
+    StartupEvent
+} from "@minecraft/server";
+
+/**
+ * Command utilities and base classes for defining and registering
+ * Minecraft Bedrock custom commands.
+ *
+ * Provides:
+ * - `ICustomCommand` base class
+ * - `RegisterCustomCommand` decorator/function
+ * - Internal command registry used during startup
+ */
+export namespace Command {
+    /**
+     * Base class for all custom commands.
+     *
+     * @example
+     * ```ts
+     * import { Command } from "@block_factory/lib";
+     * import {
+     *   world,
+     *   system,
+     *   CommandPermissionLevel,
+     *   CustomCommandParameter,
+     *   CustomCommandParamType,
+     *   CustomCommandOrigin,
+     *   CustomCommandResult,
+     *   CustomCommandStatus
+     * } from "@minecraft/server";
+     *
+     * @Command.RegisterCustomCommand
+     * export default class TestCommand extends Command.ICustomCommand {
+     *   public name = "bf_sd:test_cmd";
+     *   public description = "Test command for debugging purposes.";
+     *   public permissionLevel = CommandPermissionLevel.Admin;
+     *
+     *   public optionalParameters: CustomCommandParameter[] = [
+     *     { type: CustomCommandParamType.Integer, name: "size" }
+     *   ];
+     *
+     *   public execute(
+     *     origin: CustomCommandOrigin,
+     *     value: number
+     *   ): CustomCommandResult | undefined {
+     *     const entity = origin.sourceEntity;
+     *     if (!entity)
+     *       return {
+     *         status: CustomCommandStatus.Failure,
+     *         message: "Command fail"
+     *       };
+     *
+     *     system.run(() => {
+     *       world.sendMessage(`Running Test: ${value}`);
+     *     });
+     *
+     *     return {
+     *       status: CustomCommandStatus.Success,
+     *       message: "Completed Test"
+     *     };
+     *   }
+     * }
+     * ```
+     */
+    export abstract class ICustomCommand implements CustomCommand {
+
+        /** Command identifier (e.g. `bf_sd:test_cmd`) */
+        public abstract name: string;
+
+        /** Short description shown in help */
+        public abstract description: string;
+
+        /** Required permission level to execute */
+        public abstract permissionLevel: CommandPermissionLevel;
+
+        /** Whether cheats must be enabled */
+        public cheatsRequired?: boolean;
+
+        /** Required command parameters */
+        public mandatoryParameters?: CustomCommandParameter[];
+
+        /** Optional command parameters */
+        public optionalParameters?: CustomCommandParameter[];
+
+        /**
+         * Executes the command.
+         * @param origin Command execution context
+         * @param args Parsed command arguments
+         */
+        public abstract execute(
+            origin: CustomCommandOrigin,
+            ...args: any[]
+        ): CustomCommandResult | undefined;
+    };
+
+    /** Internal list of registered command instances */
+    export const customCommands: ICustomCommand[] = [];
+
+    /**
+     * Registers a command class.
+     * Can be used as a decorator: `@RegisterCustomCommand`.
+     */
+    export function RegisterCustomCommand<
+        T extends { new(): ICustomCommand }
+    >(customCommand: T): void {
+        const instance = new customCommand();
+        customCommands.push(instance);
+    };
+}
+
+system.beforeEvents.startup.subscribe(
+    (event: StartupEvent) => {
+        const { customCommandRegistry } = event;
+        for (const command of Command.customCommands) {
+            customCommandRegistry.registerCommand(command, command.execute);
+        };
+    },
+);

package/util/Form.d.ts

@@ -0,0 +1,75 @@
+import { Player, RawMessage } from "@minecraft/server";
+import { ActionFormResponse, ModalFormResponse } from "@minecraft/server-ui";
+declare class Form {
+    readonly isOccupied: (player: Player) => boolean;
+}
+export interface Button {
+    indexId: string | number;
+    text: string | RawMessage;
+    iconPath?: string;
+}
+export interface FormActionData {
+    response: ActionFormResponse;
+    indexId?: string | number;
+}
+export declare class ActionForm extends Form {
+    private readonly actionForm;
+    private buttonMap;
+    private buttons;
+    private titleText;
+    private bodyText;
+    title(title: string | RawMessage): void;
+    body(body: string | RawMessage): void;
+    button(indexId: string, text: string | RawMessage, iconPath?: string): void;
+    showForm(player: Player): Promise<FormActionData>;
+    private generateButtons;
+}
+export interface TextField {
+    indexId: string;
+    label: string | RawMessage;
+    placeholder: string | RawMessage;
+    defaultValue?: string;
+}
+export interface Dropdown {
+    indexId: string;
+    label: string | RawMessage;
+    options: string[];
+    defaultValueIndex?: number;
+}
+export interface Slider {
+    indexId: string;
+    label: string | RawMessage;
+    min: number;
+    max: number;
+    step: number;
+    defaultValue?: number;
+}
+export interface Toggle {
+    indexId: string;
+    label: string | RawMessage;
+    defaultValue?: boolean;
+}
+export type FormValue = string | boolean | number | undefined;
+export interface FormModalData {
+    response: ModalFormResponse;
+    indexMap?: Map<string, FormValue>;
+}
+export declare class ModalForm extends Form {
+    private readonly modalForm;
+    private widgitMap;
+    private indexMap;
+    private widgets;
+    title(title: string | RawMessage): void;
+    label(label: string | RawMessage): void;
+    header(header: string | RawMessage): void;
+    divider(): void;
+    textField(indexId: string, label: string | RawMessage, placeholder: string | RawMessage, defaultValue?: string): void;
+    dropdown(indexId: string, label: string | RawMessage, options: string[], defaultValueIndex?: number): void;
+    slider(indexId: string, label: string | RawMessage, min: number, max: number, step: number, defaultValue?: number): void;
+    toggle(indexId: string, label: string | RawMessage, defaultValue?: boolean): void;
+    showForm(player: Player): Promise<FormModalData>;
+    private processWidgets;
+    private processValues;
+}
+export {};
+//# sourceMappingURL=Form.d.ts.map

package/util/Form.ts

@@ -0,0 +1,246 @@
+/*  
+**************************************************
+ Copyright (c) Block Factory - All rights reserved.
+**************************************************
+ Author: Donthedev <https://github.com/voxeldon> 
+**************************************************
+*/
+import { Player, RawMessage } from "@minecraft/server";
+import { ActionFormData, ActionFormResponse, ModalFormData, ModalFormDataDropdownOptions, ModalFormDataSliderOptions, ModalFormDataTextFieldOptions, ModalFormDataToggleOptions, ModalFormResponse } from "@minecraft/server-ui";
+
+const occupiedPlayers: Set<string> = new Set();
+
+class Form {
+    public readonly isOccupied = ((player: Player): boolean => {
+        return occupiedPlayers.has(player.id);
+    })
+}
+
+export interface Button {
+    indexId: string | number;
+    text: string | RawMessage;
+    iconPath?: string;
+}
+
+export interface FormActionData {
+    response: ActionFormResponse;
+    indexId?: string | number;
+}
+
+export class ActionForm extends Form {
+    private readonly actionForm: ActionFormData = new ActionFormData();
+    private buttonMap: Map<number, string | number> = new Map<number, string | number>();
+    private buttons: Button[] = [];
+    private titleText: string | RawMessage | undefined;
+    private bodyText: string | RawMessage | undefined;
+
+    public title(title: string | RawMessage): void {
+        this.titleText = title;
+    }
+
+    public body(body: string | RawMessage): void {
+        this.bodyText = body;
+    }
+
+    public button(indexId: string, text: string | RawMessage, iconPath?: string): void {
+        this.buttons.push({ indexId, text, iconPath });
+    }
+
+    public async showForm(player: Player): Promise<FormActionData> {
+        if (this.titleText === undefined || this.bodyText === undefined) {
+            throw Error('Title and body must be set before showing the form');
+        }
+        this.actionForm.title(this.titleText);
+        this.actionForm.body(this.bodyText);
+        this.generateButtons();
+
+        occupiedPlayers.add(player.id);
+
+        const response: ActionFormResponse = await this.actionForm.show(player).finally(() => {
+            occupiedPlayers.delete(player.id);
+        });
+
+        const return_data: FormActionData = {
+            response: response,
+            indexId: undefined
+        };
+        if (response.selection !== undefined && response.selection !== null) {
+            const selection: string | number | undefined = this.buttonMap.get(response.selection);
+            return_data.indexId = selection;
+        }
+
+        return return_data;
+    }
+
+    private generateButtons() {
+        let buttonIndex: number = 0;
+        this.buttons.forEach(button => {
+            if (button.iconPath) {
+                this.actionForm.button(button.text, button.iconPath);
+            } else {
+                this.actionForm.button(button.text);
+            }
+            this.buttonMap.set(buttonIndex, button.indexId);
+            buttonIndex++;
+        });
+    }
+}
+
+enum WidgetType {
+    TextField = 'textField',
+    Dropdown = 'dropdown',
+    Slider = 'slider',
+    Toggle = 'toggle'
+}
+
+interface Widget {
+    typeId: string,
+    widget: any
+};
+
+export interface TextField {
+    indexId: string,
+    label: string | RawMessage,
+    placeholder: string | RawMessage,
+    defaultValue?: string
+}
+
+export interface Dropdown {
+    indexId: string,
+    label: string | RawMessage,
+    options: string[],
+    defaultValueIndex?: number
+}
+
+export interface Slider {
+    indexId: string,
+    label: string | RawMessage,
+    min: number,
+    max: number,
+    step: number,
+    defaultValue?: number
+}
+
+export interface Toggle {
+    indexId: string,
+    label: string | RawMessage,
+    defaultValue?: boolean
+}
+
+export type FormValue = string | boolean | number | undefined;
+
+export interface FormModalData {
+    response: ModalFormResponse;
+    indexMap?: Map<string, FormValue>;
+}
+
+export class ModalForm extends Form {
+    private readonly modalForm: ModalFormData = new ModalFormData();
+    private widgitMap: Map<number, string> = new Map<number, string>();
+    private indexMap: Map<string, FormValue> = new Map<string, FormValue>();
+    private widgets: Widget[] = [];
+
+    public title(title: string | RawMessage): void {
+        this.modalForm.title(title);
+    }
+
+    public label(label: string | RawMessage): void {
+        this.modalForm.label(label);
+    }
+
+    public header(header: string | RawMessage): void {
+        this.modalForm.header(header);
+    }
+
+    public divider(): void {
+        this.modalForm.divider();
+    }
+
+    public textField(indexId: string, label: string | RawMessage, placeholder: string | RawMessage, defaultValue?: string): void {
+        this.widgets.push({ typeId: WidgetType.TextField, widget: { indexId, label, placeholder, defaultValue } });
+    }
+    public dropdown(indexId: string, label: string | RawMessage, options: string[], defaultValueIndex?: number): void {
+        this.widgets.push({ typeId: WidgetType.Dropdown, widget: { indexId, label, options, defaultValueIndex } });
+    }
+
+    public slider(indexId: string, label: string | RawMessage, min: number, max: number, step: number, defaultValue?: number): void {
+        this.widgets.push({ typeId: WidgetType.Slider, widget: { indexId, label, min, max, step, defaultValue } });
+    }
+
+    public toggle(indexId: string, label: string | RawMessage, defaultValue?: boolean): void {
+        this.widgets.push({ typeId: WidgetType.Toggle, widget: { indexId, label, defaultValue } });
+    }
+
+    public async showForm(player: Player): Promise<FormModalData> {
+        this.processWidgets();
+        occupiedPlayers.add(player.id);
+
+        const response: ModalFormResponse = await this.modalForm.show(player).finally(() => {
+            occupiedPlayers.delete(player.id);
+        });
+
+        const return_data: FormModalData = {
+            response: response,
+            indexMap: undefined
+        }
+
+        if (response.formValues !== null && response.formValues !== undefined) {
+            this.processValues(response.formValues);
+            return_data.indexMap = this.indexMap;
+        }
+
+        return return_data;
+    }
+
+    private processWidgets(): void {
+        let widgitIndex: number = 0;
+
+        for (const widget of this.widgets) {
+            if (widget.typeId === WidgetType.TextField) {
+                const textField: TextField = widget.widget;
+                const options: ModalFormDataTextFieldOptions = {
+                    defaultValue: textField?.defaultValue
+                };
+                this.modalForm.textField(textField.label, textField.placeholder, options);
+                this.widgitMap.set(widgitIndex, textField.indexId);
+            }
+            else if (widget.typeId === WidgetType.Dropdown) {
+                const dropdown: Dropdown = widget.widget;
+                const options: ModalFormDataDropdownOptions = {
+                    defaultValueIndex: dropdown?.defaultValueIndex
+                };
+                this.modalForm.dropdown(dropdown.label, dropdown.options, options);
+                this.widgitMap.set(widgitIndex, dropdown.indexId);
+
+            }
+            else if (widget.typeId === WidgetType.Slider) {
+                const slider: Slider = widget.widget;
+                const options: ModalFormDataSliderOptions = {
+                    defaultValue: slider?.defaultValue,
+                    valueStep: slider.step
+                };
+                this.modalForm.slider(slider.label, slider.min, slider.max, options);
+                this.widgitMap.set(widgitIndex, slider.indexId);
+            }
+            else if (widget.typeId === WidgetType.Toggle) {
+                const toggle: Toggle = widget.widget;
+                const options: ModalFormDataToggleOptions = {
+                    defaultValue: toggle?.defaultValue
+                }
+                this.modalForm.toggle(toggle.label, options);
+                this.widgitMap.set(widgitIndex, toggle.indexId);
+            }
+            widgitIndex += 1;
+        }
+    }
+
+    private processValues(formValues: FormValue[]): void {
+        let widgitIndex: number = 0;
+        for (const i of formValues) {
+            const value: FormValue = i?.valueOf();
+            const indexId: string | undefined = this.widgitMap.get(widgitIndex);
+            if (indexId) this.indexMap.set(indexId, value);
+            widgitIndex++;
+        }
+    }
+}

package/util/Math.d.ts

@@ -0,0 +1,14 @@
+import type { Vector2, Vector3 } from "@minecraft/server";
+
+export declare namespace MathUtils {
+    function clamp(value: number, min: number, max: number): number;
+    function lerp(start: number, end: number, factor: number): number;
+    function toRadians(degrees: number): number;
+    function toDegrees(radians: number): number;
+    function fromRotation(rotation: Vector2): Vector3;
+    function rotateOffset(offset: Vector3, yawDegrees: number): Vector3;
+    function distance3D(pointA: Vector3, pointB: Vector3): number;
+    function randomInt(min: number, max: number): number;
+    function randomFloat(min: number, max: number): number;
+}
+//# sourceMappingURL=Math.d.ts.map

package/util/Math.ts

@@ -0,0 +1,68 @@
+import { Vector2, Vector3 } from "@minecraft/server";
+
+export namespace MathUtils {
+   /** Clamps a number between a minimum and maximum value */
+    export function clamp(value: number, min: number, max: number): number {
+        return Math.min(Math.max(value, min), max);
+    };
+    
+    /** Linearly interpolates between two values based on a given factor (0 to 1) */
+    export function lerp(start: number, end: number, factor: number): number {
+        return start + (end - start) * clamp(factor, 0, 1);
+    };
+    
+    /** Converts degrees to radians */
+    export function toRadians(degrees: number): number {
+        return degrees * (Math.PI / 180);
+    };
+    
+    /** Converts radians to degrees */
+    export function toDegrees(radians: number): number {
+        return radians * (180 / Math.PI);
+    };
+
+    export function fromRotation(rotation: Vector2): Vector3 {
+        const rotationH = toRadians(rotation.y * -1);
+        const z0 = Math.cos(rotationH);
+        const x0 = Math.sin(rotationH);
+
+        const rotationV = toRadians(rotation.x * -1);
+        const h = Math.cos(rotationV);
+        const v = Math.sin(rotationV);
+
+        return {
+            x: h * x0,
+            y: v,
+            z: h * z0
+        };
+    };
+
+    export function rotateOffset(offset: Vector3, yawDegrees: number): Vector3 {
+        const yaw = -yawDegrees * Math.PI / 180;
+        const cos = Math.cos(yaw);
+        const sin = Math.sin(yaw);
+        return {
+            x: offset.x * cos - offset.z * sin,
+            y: offset.y,
+            z: offset.x * sin + offset.z * cos
+        };
+    };
+    
+    /** Calculates the distance between two points in 3D space */
+    export function distance3D(pointA: Vector3, pointB: Vector3): number {
+        const dx = pointB.x - pointA.x;
+        const dy = pointB.y - pointA.y;
+        const dz = pointB.z - pointA.z;
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    };
+    
+    /** Generates a random integer between min and max (inclusive) */
+    export function randomInt(min: number, max: number): number {
+        return Math.floor(Math.random() * (max - min + 1)) + min;
+    };
+    
+    /** Generates a random float between min and max */
+    export function randomFloat(min: number, max: number): number {
+        return Math.random() * (max - min) + min;
+    };
+}

package/util/RawText.d.ts

@@ -0,0 +1,33 @@
+import type { RawMessage } from "@minecraft/server";
+
+export declare namespace RawText {
+    export const TEXT: (value: string) => RawMessage;
+    export const TRANSLATE: (key: string, ...params: string[]) => RawMessage;
+    export const SCORE: (name: string, objective: string) => RawMessage;
+    export const MESSAGE: (...rawText: RawMessage[]) => RawMessage;
+    export const FORMAT: {
+        DarkRed: RawMessage;
+        Red: RawMessage;
+        Gold: RawMessage;
+        Yellow: RawMessage;
+        Green: RawMessage;
+        Lime: RawMessage;
+        Aqua: RawMessage;
+        Cyan: RawMessage;
+        DarkBlue: RawMessage;
+        Blue: RawMessage;
+        Magenta: RawMessage;
+        Purple: RawMessage;
+        White: RawMessage;
+        Gray: RawMessage;
+        DarkGray: RawMessage;
+        Black: RawMessage;
+        Obfuscated: RawMessage;
+        Bold: RawMessage;
+        StrikeThrough: RawMessage;
+        Italic: RawMessage;
+        Reset: RawMessage;
+        NewLine: RawMessage;
+    };
+}
+//# sourceMappingURL=RawText.d.ts.map

package/util/RawText.ts

@@ -0,0 +1,76 @@
+import { RawMessage } from '@minecraft/server';
+
+/**
+ * Utility helpers for building rawtext messages.
+ */
+export namespace RawText {
+    /**
+     * Creates a simple text component.
+     * @param value - The text value.
+     * @returns Text component object.
+     */
+    export const TEXT = (value: string): RawMessage => ({
+        text: value
+    });
+
+    /**
+     * Creates a translation component with optional 'with' parameters.
+     * @param key - The translation key.
+     * @param params - The optional parameters for translation.
+     * @returns Translation component object.
+     */
+    export const TRANSLATE = (key: string, ...params: string[]): RawMessage => ({
+        translate: key,
+        with: params.length ? params : undefined
+    });
+
+    /**
+     * Creates a score component.
+     * @param name - The entity's name whose score is being displayed.
+     * @param objective - The name of the score objective.
+     * @returns Score component object.
+     */
+    export const SCORE = (name: string, objective: string): RawMessage => ({
+        score: {
+            name: name,
+            objective: objective
+        }
+    });
+
+    /**
+     * Wraps various text components into a rawtext structure.
+     * @param rawText - The raw text components.
+     * @returns Raw text object.
+     */
+    export const MESSAGE = (...rawText: RawMessage[]): RawMessage => ({
+        rawtext: rawText
+    });
+
+    /**
+     * Common formatting and color codes.
+     */
+    export const FORMAT = {
+        DarkRed: TEXT('§4'),
+        Red: TEXT('§c'),
+        Gold: TEXT('§6'),
+        Yellow: TEXT('§e'),
+        Green: TEXT('§2'),
+        Lime: TEXT('§a'),
+        Aqua: TEXT('§b'),
+        Cyan: TEXT('§3'),
+        DarkBlue: TEXT('§1'),
+        Blue: TEXT('§9'),
+        Magenta: TEXT('§d'),
+        Purple: TEXT('§5'),
+        White: TEXT('§f'),
+        Gray: TEXT('§7'),
+        DarkGray: TEXT('§8'),
+        Black: TEXT('§0'),
+        Obfuscated: TEXT('§k'),
+        Bold: TEXT('§l'),
+        StrikeThrough: TEXT('§m'),
+        Italic: TEXT('§o'),
+        Reset: TEXT('§r'),
+        NewLine: TEXT('\n')
+    }
+}

package/util/Signal.d.ts

@@ -0,0 +1,9 @@
+export type Callback<T = void> = (data: T) => void;
+export declare class Signal<T = void> {
+    private listeners;
+    connect(callback: Callback<T>): void;
+    disconnect(callback?: Callback<T>): boolean;
+    once(callback: Callback<T>): void;
+    emit(data: T): void;
+}
+//# sourceMappingURL=Signal.d.ts.map