@minecraft/server-ui 1.0.0-beta.00001b37

package/.eslintrc.json

@@ -0,0 +1,23 @@
+{
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended"
+    ],
+    "overrides": [
+    ],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": "latest",
+        "sourceType": "module"
+    },
+    "plugins": [
+        "@typescript-eslint"
+    ],
+    "rules": {
+        "@typescript-eslint/no-explicit-any": "off"
+    }
+}

package/README.md

@@ -0,0 +1,17 @@
+# `@minecraft/server-ui`
+
+The `@minecraft/server-ui` module contains types for expressing simple dialog-based user experiences.
+
+
+
+  * [*@minecraft/server-ui.ActionFormData*](../@minecraft-server-ui/ActionFormData.md) contain a list of buttons with captions and images that can be used for presenting a set of options to a player.
+
+  * [*@minecraft/server-ui.MessageFormData*](../@minecraft-server-ui/MessageFormData.md) are simple two-button message experiences that are functional for Yes/No or OK/Cancel questions.
+
+  * [*@minecraft/server-ui.ModalFormData*](../@minecraft-server-ui/ModalFormData.md) allow for a more flexible "questionnaire-style" list of controls that can be used to take input.
+
+## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
+
+See full documentation for this module here:
+
+https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/@minecraft/server-ui/@minecraft/server-ui

package/index.d.ts

@@ -0,0 +1,268 @@
+// Type definitions for Minecraft Bedrock Edition script APIs
+// Project: https://docs.microsoft.com/minecraft/creator/
+// Definitions by: Jake Shirley <https://github.com/JakeShirley>
+//                 Mike Ammerlaan <https://github.com/mammerla>
+
+/* *****************************************************************************
+   Copyright (c) Microsoft Corporation.
+   ***************************************************************************** */
+/**
+ * @packageDocumentation
+ * The `@minecraft/server-ui` module contains types for
+ * expressing simple dialog-based user experiences.
+ *
+ *   * {@link ActionFormData} contain a list of buttons with
+ * captions and images that can be used for presenting a set of
+ * options to a player.
+ *   * {@link MessageFormData} are simple two-button message
+ * experiences that are functional for Yes/No or OK/Cancel
+ * questions.
+ *   * {@link ModalFormData} allow for a more flexible
+ * "questionnaire-style" list of controls that can be used to
+ * take input.
+ * @example createActionForm.js
+ * ```typescript
+ * const form = new ActionFormData()
+ *   .title("Months")
+ *   .body("Choose your favorite month!")
+ *   .button("January")
+ *   .button("February")
+ *   .button("March")
+ *   .button("April")
+ *   .button("May");
+ *
+ * form.show(players[0]).then((response) => {
+ *   if (response.selection === 3) {
+ *     dimension.runCommand("say I like April too!");
+ *   }
+ * });
+ *
+ * ```
+ *
+ * Manifest Details
+ * ```json
+ * {
+ *   "module_name": "@minecraft/server-ui",
+ *   "version": "0.1.0"
+ * }
+ * ```
+ *
+ */
+import * as minecraftserver from '@minecraft/server';
+export enum FormCancelationReason {
+    userBusy = 'userBusy',
+    userClosed = 'userClosed',
+}
+/**
+ * Builds a simple player form with buttons that let the player
+ * take action.
+ */
+export class ActionFormData {
+    /**
+     * @remarks
+     * Method that sets the body text for the modal form.
+     * @param bodyText
+     */
+    body(bodyText: string): ActionFormData;
+    /**
+     * @remarks
+     * Adds a button to this form with an icon from a resource
+     * pack.
+     * @param text
+     * @param iconPath
+     */
+    button(text: string, iconPath?: string): ActionFormData;
+    /**
+     * @remarks
+     * Creates and shows this modal popup form. Returns
+     * asynchronously when the player confirms or cancels the
+     * dialog.
+     * @param player
+     * Player to show this dialog to.
+     * @throws This function can throw errors.
+     */
+    show(player: minecraftserver.Player): Promise<ActionFormResponse>;
+    /**
+     * @remarks
+     * This builder method sets the title for the modal dialog.
+     * @param titleText
+     */
+    title(titleText: string): ActionFormData;
+}
+/**
+ * Returns data about the player results from a modal action
+ * form.
+ */
+export class ActionFormResponse extends FormResponse {
+    /**
+     * Contains additional details as to why a form was canceled.
+     */
+    readonly cancelationReason?: FormCancelationReason;
+    /**
+     * If true, the form was canceled by the player (e.g., they
+     * selected the pop-up X close button).
+     */
+    readonly canceled: boolean;
+    /**
+     * Returns the index of the button that was pushed.
+     */
+    readonly selection?: number;
+    protected constructor();
+}
+/**
+ * Base type for a form response.
+ */
+export class FormResponse {
+    /**
+     * Contains additional details as to why a form was canceled.
+     */
+    readonly cancelationReason?: FormCancelationReason;
+    /**
+     * If true, the form was canceled by the player (e.g., they
+     * selected the pop-up X close button).
+     */
+    readonly canceled: boolean;
+    protected constructor();
+}
+/**
+ * Builds a simple two-button modal dialog.
+ */
+export class MessageFormData {
+    /**
+     * @remarks
+     * Method that sets the body text for the modal form.
+     * @param bodyText
+     */
+    body(bodyText: string): MessageFormData;
+    /**
+     * @remarks
+     * Method that sets the text for the first button of the
+     * dialog.
+     * @param text
+     */
+    button1(text: string): MessageFormData;
+    /**
+     * @remarks
+     * This method sets the text for the second button on the
+     * dialog.
+     * @param text
+     */
+    button2(text: string): MessageFormData;
+    /**
+     * @remarks
+     * Creates and shows this modal popup form. Returns
+     * asynchronously when the player confirms or cancels the
+     * dialog.
+     * @param player
+     * Player to show this dialog to.
+     * @throws This function can throw errors.
+     */
+    show(player: minecraftserver.Player): Promise<MessageFormResponse>;
+    /**
+     * @remarks
+     * This builder method sets the title for the modal dialog.
+     * @param titleText
+     */
+    title(titleText: string): MessageFormData;
+}
+/**
+ * Returns data about the player results from a modal message
+ * form.
+ */
+export class MessageFormResponse extends FormResponse {
+    /**
+     * Contains additional details as to why a form was canceled.
+     */
+    readonly cancelationReason?: FormCancelationReason;
+    /**
+     * If true, the form was canceled by the player (e.g., they
+     * selected the pop-up X close button).
+     */
+    readonly canceled: boolean;
+    /**
+     * Returns the index of the button that was pushed.
+     */
+    readonly selection?: number;
+    protected constructor();
+}
+/**
+ * Used to create a fully customizable pop-up form for a
+ * player.
+ */
+export class ModalFormData {
+    /**
+     * @remarks
+     * Adds a dropdown with choices to the form.
+     * @param label
+     * @param options
+     * @param defaultValueIndex
+     */
+    dropdown(label: string, options: string[], defaultValueIndex?: number): ModalFormData;
+    /**
+     * @remarks
+     * Creates and shows this modal popup form. Returns
+     * asynchronously when the player confirms or cancels the
+     * dialog.
+     * @param player
+     * Player to show this dialog to.
+     * @throws This function can throw errors.
+     */
+    show(player: minecraftserver.Player): Promise<ModalFormResponse>;
+    /**
+     * @remarks
+     * Adds a numeric slider to the form.
+     * @param label
+     * @param minimumValue
+     * @param maximumValue
+     * @param valueStep
+     * @param defaultValue
+     */
+    slider(
+        label: string,
+        minimumValue: number,
+        maximumValue: number,
+        valueStep: number,
+        defaultValue?: number,
+    ): ModalFormData;
+    /**
+     * @remarks
+     * Adds a textbox to the form.
+     * @param label
+     * @param placeholderText
+     * @param defaultValue
+     */
+    textField(label: string, placeholderText: string, defaultValue?: string): ModalFormData;
+    /**
+     * @remarks
+     * This builder method sets the title for the modal dialog.
+     * @param titleText
+     */
+    title(titleText: string): ModalFormData;
+    /**
+     * @remarks
+     * Adds a toggle checkbox button to the form.
+     * @param label
+     * @param defaultValue
+     */
+    toggle(label: string, defaultValue?: boolean): ModalFormData;
+}
+/**
+ * Returns data about player responses to a modal form.
+ */
+export class ModalFormResponse extends FormResponse {
+    /**
+     * Contains additional details as to why a form was canceled.
+     */
+    readonly cancelationReason?: FormCancelationReason;
+    /**
+     * If true, the form was canceled by the player (e.g., they
+     * selected the pop-up X close button).
+     */
+    readonly canceled: boolean;
+    /**
+     * An ordered set of values based on the order of controls
+     * specified by ModalFormData.
+     */
+    readonly formValues?: any[];
+    protected constructor();
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@minecraft/server-ui",
+  "version": "1.0.0-beta.00001b37",
+  "description": "",
+  "contributors": [
+    {
+      "name": "Jake Shirley",
+      "email": "jake@xbox.com"
+    },
+    {
+      "name": "Mike Ammerlaan",
+      "email": "mikeam@microsoft.com"
+    }
+  ],
+  "dependencies": {
+    "@minecraft/server": "1.0.0-beta.00001b37"
+  },
+  "license": "MIT"
+}

package/tests.ts

@@ -0,0 +1,171 @@
+import * as mc from '@minecraft/server';
+
+export async function showActionForm(log: (message: string, status?: number) => void) {
+    const players = mc.world.getPlayers();
+
+    const playerList = Array.from(players);
+
+    if (playerList.length >= 1) {
+        const form = new mcui.ActionFormData()
+            .title('Test Title')
+            .body('Body text here!')
+            .button('btn 1')
+            .button('btn 2')
+            .button('btn 3')
+            .button('btn 4')
+            .button('btn 5');
+
+        const result = await form.show(playerList[0]);
+
+        if (result.canceled) {
+            log('Player exited out of the dialog.');
+        } else {
+            log('Your result was: ' + result.selection);
+        }
+    }
+}
+
+export function showFavoriteMonth(log: (message: string, status?: number) => void) {
+    const players = mc.world.getPlayers();
+
+    const playerList = Array.from(players);
+
+    if (playerList.length >= 1) {
+        const form = new mcui.ActionFormData()
+            .title('Months')
+            .body('Choose your favorite month!')
+            .button('January')
+            .button('February')
+            .button('March')
+            .button('April')
+            .button('May');
+
+        form.show(playerList[0]).then((response: mcui.ActionFormResponse) => {
+            if (response.selection === 3) {
+                log('I like April too!');
+            }
+        });
+    }
+}
+
+export default class SampleManager {
+    tickCount = 0;
+
+    _availableFuncs: {
+        [name: string]: Array<(log: (message: string, status?: number) => void, location: mc.Location) => void>;
+    };
+
+    pendingFuncs: Array<{
+        name: string;
+        func: (log: (message: string, status?: number) => void, location: mc.Location) => void;
+        location: mc.Location;
+    }> = [];
+
+    gameplayLogger(message: string, status?: number) {
+        if (status !== undefined && status > 0) {
+            message = 'SUCCESS: ' + message;
+        } else if (status !== undefined && status < 0) {
+            message = 'FAIL: ' + message;
+        }
+
+        this.say(message);
+    }
+    say(message: string) {
+        mc.world.getDimension('overworld').runCommand('say ' + message);
+    }
+
+    newChatMessage(chatEvent: mc.ChatEvent) {
+        const message = chatEvent.message.toLowerCase();
+
+        if (message.startsWith('howto') && chatEvent.sender) {
+            const nearbyBlock = chatEvent.sender.getBlockFromViewVector();
+            if (!nearbyBlock) {
+                this.gameplayLogger('Please look at the block where you want me to run this.');
+                return;
+            }
+
+            const nearbyBlockLoc = nearbyBlock.location;
+            const nearbyLoc = new mc.Location(nearbyBlockLoc.x, nearbyBlockLoc.y + 1, nearbyBlockLoc.z);
+
+            const sampleId = message.substring(5).trim();
+
+            if (sampleId.length < 2) {
+                let availableFuncStr = 'Here is my list of available samples:';
+
+                for (const sampleFuncKey in this._availableFuncs) {
+                    availableFuncStr += ' ' + sampleFuncKey;
+                }
+
+                this.say(availableFuncStr);
+            } else {
+                for (const sampleFuncKey in this._availableFuncs) {
+                    if (sampleFuncKey.toLowerCase() === sampleId) {
+                        const sampleFunc = this._availableFuncs[sampleFuncKey];
+
+                        this.runSample(sampleFuncKey + this.tickCount, sampleFunc, nearbyLoc);
+
+                        return;
+                    }
+                }
+
+                this.say(`I couldn't find the sample '${sampleId}"'`);
+            }
+        }
+    }
+
+    runSample(
+        sampleId: string,
+        snippetFunctions: Array<(log: (message: string, status?: number) => void, location: mc.Location) => void>,
+        targetLocation: mc.Location,
+    ) {
+        for (let i = snippetFunctions.length - 1; i >= 0; i--) {
+            this.pendingFuncs.push({ name: sampleId, func: snippetFunctions[i], location: targetLocation });
+        }
+    }
+
+    worldTick() {
+        if (this.tickCount % 10 === 0) {
+            if (this.pendingFuncs.length > 0) {
+                const funcSet = this.pendingFuncs.pop();
+
+                if (funcSet) {
+                    funcSet.func(this.gameplayLogger, funcSet.location);
+                }
+            }
+        }
+
+        this.tickCount++;
+    }
+
+    constructor() {
+        this._availableFuncs = {};
+
+        this.gameplayLogger = this.gameplayLogger.bind(this);
+
+        mc.world.events.tick.subscribe(this.worldTick.bind(this));
+        mc.world.events.chat.subscribe(this.newChatMessage.bind(this));
+    }
+
+    registerSamples(sampleSet: {
+        [name: string]: Array<(log: (message: string, status?: number) => void, location: mc.Location) => void>;
+    }) {
+        for (const sampleKey in sampleSet) {
+            if (sampleKey.length > 1 && sampleSet[sampleKey]) {
+                this._availableFuncs[sampleKey] = sampleSet[sampleKey];
+            }
+        }
+    }
+}
+
+import * as mcui from '@minecraft/server-ui';
+
+const mojangMinecraftUIFuncs: {
+    [name: string]: Array<(log: (message: string, status?: number) => void, location: mc.Location) => void>;
+} = {
+    showActionForm: [showActionForm],
+    showFavoriteMonth: [showFavoriteMonth],
+};
+
+export function register(sampleManager: SampleManager) {
+    sampleManager.registerSamples(mojangMinecraftUIFuncs);
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+      "module": "commonjs",
+      "lib": ["es6"],
+      "target": "es6",
+      "forceConsistentCasingInFileNames": true,
+      "noEmit": true,
+      "noImplicitAny": true,
+      "noImplicitThis": true,
+      "strictFunctionTypes": true,
+      "strictNullChecks": true,
+      "baseUrl": "../",
+      "typeRoots": ["../"],
+      "types": []
+  },
+  "files": [
+      "index.d.ts",
+      "tests.ts"
+  ]
+}