How to Create a Custom UI with ScriptAPI in Minecraft Bedrock (Advanced Tutorial)

Introduction

Minecraft is a game with a huge degree of freedom. You can simply survive and defeat the Ender Dragon, master architecture and create highly artistic works, or even create maps for distribution using commands. The possibilities are truly endless.
Now, creating add-ons further increases this freedom. Not only can you create your own original items and weapons, but you can also customize the system and create distribution maps. Below is an example, which recreates the “One-Hit Sword” that appears in a certain game in Minecraft.

This add-on creation is not limited to simply creating items and modifying systems. Although it is not widely known, you can also create your own GUI. This article aims to explain how to create your own GUI from scratch and to assist you in creating add-ons.

This is a scene from a video I made, showing a GUI asking whether you prefer “Mac” or “McDo.” By reading this article, you will be able to create a GUI like this and build your own original worldview. Please read to the end.
YouTube videos
I have created a YouTube video that explains the contents of this article. You can watch it here.

Vocabulary Definitions

First, I will briefly explain the definitions of the main terms that will be frequently used in this article. These are my own interpretations, so please let me know if I am wrong. If you already know the terms, please skip ahead.

Main topic

When creating a GUI, it is necessary to use APIScript. APIScript is a feature that allows you to customize the Minecraft system using the programming language Javascript. For more information about APIScript, please see this article.

Environment Construction

First, we will show you what you need to build the environment. You can download each item from the links below.

Of the required software, only Minecraft is paid; the rest are free. A text editor (vscode) is not required, but it is highly recommended. Also, since the ScriptAPI relies on JavaScript, node.js is required to run this JavaScript on your PC.
Regarding node.js, I found this article by another person to be very helpful, so I’d like to introduce it to you.
https://qiita.com/non_cal/items/a8fee0b7ad96e67713eb
The following procedure assumes that these are installed.
First, go to development_behavior_packs in the com.mojang folder and create a new folder (you can name it anything you like). This will be the working folder for your add-on. The location of the com.mojang folder is explained below. If you already know it, you can skip this part.

com.mojang location

The folder com.mojang is
C:\Users\(username)\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang
It is located in the following location: The “AppData” file is hidden in File Explorer, so to select it, you must enable hidden files in File Explorer’s View settings. Alternatively, you can open it by launching the “Run” app and entering “%LocalAppData%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang“.
Inside this com.mojang folder there is a development_behavior_packs folder, so open it and create a new folder.

Creating manifest.json

Next, go to the newly created add-on folder and create a new json file called “manifest.json”. Right-click and select “New” -> “Text Document”, then change the name of the created file to “manifest.json”.
“manifest.json” is a file that describes the add-on’s details (such as its name and ID), allowing Minecraft to recognize the add-on.
The contents of manifest.json are as follows. Open the created manifest.json using vscode or similar that you downloaded earlier, and copy and paste the following.

{
"format_version": 2,
"header": {
"name": "Addon that displays a GUI",
"description": "This is a template",
"uuid": "b1ef9620-a18e-4fa3-bdca-f5f1d3c71c31",
"version": [0, 1, 0],
"min_engine_version": [1, 20, 0]
},
"modules": [
{
"type": "script",
"language": "javascript",
"uuid": "b1ef9620-a18e-4fa3-bdca-f5f1d3c71c32",
"entry": "scripts/main.js",
"version": [0, 1, 0]
}
],
"capabilities": ["script_eval"],
"dependencies": [
{
"module_name": "@minecraft/server",
"version": "1.10.0"
},
{
"module_name": "@minecraft/server-ui",
"version": "1.1.0"
}
]
}

The name and description above are the name and description of this add-on. Please adjust these parts as you like. Also, the two uuids are strings unique to the add-on, and overlapping them can be troublesome, so we recommend using the generator below to generate and change them.
https://www.uuidgenerator.net
The version of minecraft/server is (1.10.0 in this case), but you may want to change it by referring to the following page. At the time of writing, the latest version is 1.14.0-beta, but the beta version is unstable, so if you want stability, you may want to use 1.13.0. Note that when using the beta version, you will need to enable the experimental feature “Beta API” when launching the world (this is not necessary if you are not using the beta version).
https://learn.microsoft.com/ja-jp/minecraft/creator/scriptapi/minecraft/server/minecraft-server?view=minecraft-bedrock-experimental
Also, since this add-on displays the UI, it is necessary to specify the server-ui module. Please note that this add-on is different from the other add-ons introduced on this site so far.

Installing “@minecraft/server”

Next, install the “@minecraft/server” module that will be used in this add-on and “@minecraft/server-ui”, which is required to display the UI. Enter “cmd” in the search field on the taskbar to launch the command prompt, or launch the vscode terminal. Then,

cd (path of working folder)

Enter the command. The cd command allows you to move to a directory by specifying the directory. For example, if the add-on folder (the folder containing manifest.json) is
C:\Users\User\AppData\Local\packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\test_pack
If it was,

cd C:\Users\User\AppData\Local\packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\test_pack

The folder location (especially the user name) will be different for each user, so please check the path yourself. You can check it in the top column of File Explorer.

Once you have completed the above command, enter the following two commands.

npm install @minecraft/server

npm install @minecraft/server-ui

If an error occurs regarding the command “npm”, the installation of node.js may not have been completed. If an error occurs, we recommend checking this point.

Write a script

Once you’ve completed the above steps, you’re ready to start creating the UI.
Create a folder called “scripts” in the add-on folder. Then create a JavaScript file called “main.js” inside it. This is where you will write your script. This js file can be opened with a text editor such as vscode.

Calling a Module

First, we will call the two modules we installed earlier in this script. This will allow us to interact with the Minecraft world and prepare the UI for display.
Copy and paste the following into main.js:

import * as server from "@minecraft/server";
import * as ui from "@minecraft/server-ui";

The “*” symbol in this script indicates that all of the modules will be installed. You can install what you need for each class (player, world, etc.), but I thought that would be a bit cumbersome and time-consuming, so I installed everything. This is up to you. For reference, the following is an example of installing only the world class and system class modules from @minecraft/server. (This does not need to be written in the script.)

import {world,system} from "@minecraft/server";

Defining the UI

Next, define the UI to be displayed. Below is an example of defining show_form(), a function that displays the UI with the player as an argument.

function show_form(player){
const form = new ui.ActionFormData();
form.title("Selection Menu: Which do you prefer?");
form.button("Mac");
form.button("McDo");
form.show(player).then((response) => {
switch(response.selection){
case 0:
player.sendMessage("You selected Mac.");
player.runCommandAsync("give @s emerald 1");
break;
case 1:
player.sendMessage("You selected McDonald's.");
break;
default:
player.sendMessage("Nothing selected.");
break;
}
}).catch(error =>
player.sendMessage("An error occurred: " + error.message)
);
}

Let me explain a bit. form.title() is a function that defines the title of this UI. You can arrange it by entering a title here. Also, a button is placed using the button() function of the form class. This takes a string as an argument and places the argument string on the button. As you can see, it is possible to place multiple buttons.
The final show() function makes it possible to display this UI. You can also define the behavior when buttons are pressed under show(), and here we define the behavior when each button is pressed. At the same time, we use the “sendMessage()” function, which displays a message, and the “runCommandAsync()” function, which executes a command. These are commonly used, so it’s worth remembering.

reference

You will see the notations “case 0” and “case 1”, which are called switch statements and are often used in JavaScript to distinguish between cases. Here, the behavior is distinguished depending on the value of the variable response. The value of response becomes 0 when the top button is pressed, becomes 1 when the next button is pressed, and so on. If nothing is pressed, “default” is assigned.
You can also set the behavior when an error occurs. This is called catch(), and is often used in JavaScript. This setting is not required.
Now, you might think that this is the end, but it’s not. This just defines the function that displays the UI, but does not actually issue a command to display the UI. Separately, you need to issue a command to execute the defined function and display the UI.

Displaying the UI

The UI will be displayed when you call the “show_form()” function defined above, but simply displaying it is not enough. It would be very distracting if the UI was always displayed in the game. In other words, we need to implement a system that displays the UI under certain conditions.
Below is an example of calling show_form() to display the UI when using a wooden stick.

server.world.afterEvents.itemUse.subscribe(ev => {
    if (ev.itemStack.typeId == "minecraft:stick"){
        let player = ev.source;
        show_form(player);
    }
});

One thing to note: This function show_form requires the specification of a “player” as an argument, so the item’s user is declared in advance as the “player” variable. Please note that you must prepare the “player” argument somehow. The function will be executed starting from this “player”.
For more information on how to cause certain actions to occur when using items, please see this article.

【ScriptAPI】UIの表示でエラーが出たときの対処法【マイクラ統合版】

Introduction Minecraft is a game with a huge degree of freedom. You can simply survive and defeat the Ender Dragon, master architecture and create highly artistic works, or even create maps for distribution using commands. The possibilities are truly endless.Now, creating add-ons further increases this freedom. Not only can you…

execution

This completes the definition of the UI in the script. All that’s left is to actually start Minecraft and check its behavior. Enable this add-on and start a world. The UI should then be displayed when you use the stick.

Also, in this example, choosing “Mac” will give you an emerald, so you can see that there are consequences depending on your choices.

ModalFormData

Now, there is a useful function for displaying UI. This is called ModalFormData, and it allows you to place not only buttons, but also text boxes and check boxes. This allows you to create add-ons that are extremely flexible and extensible.

The image above is a frame from a video I created, and you can see that there are various input fields, such as sliders and dropdowns.

YouTube videos

For details on how to create such a form, please see this video.

This is just a simple introduction to the script.

script

Here are some examples of how you can use ModalFormData to implement various functions:

function show_form(player){
const form = new ui.ModalFormData();
form.slider("Slider",0,100,1,50);
form.textField("Enter text here","Text");
form.dropdown("dropdown",["a","b","c"]);
form.toggle("checkbox");
form.show(player).then(response => {
if (response.canceled){
player.sendMessage("Cancelled");
return;
}
player.sendMessage("Slider value: " + String(response.formValues[0]));
player.sendMessage("Enter text: " + String(response.formValues[1]));
player.sendMessage("Dropdown selection: " + String(response.formValues[2]));
player.sendMessage("Checkbox state: " + String(response.formValues[3]));
})
.catch(error => {
player.sendMessage("Error: " + error.message);
});
}

The script is slightly different from the one in the video, but the general framework is the same. Here, we’ve only defined a simple system that uses the sendMessage function to convert input data into a String type and then output it, but in reality, you’ll probably want to perform more flexible processing by combining it with functions like runCommand, as shown below.

Example 1

Here’s an example that will award diamonds to the player depending on the slider value:

player.runCommand("give @s diamond " + String(response.formValues[0]));

You can also set a player’s score to a fixed value in the same way:

player.runCommand("scoreboard players set @s test_score " + String(response.formValues[0]));

Example 2

A common question in the comments section of the video above was, “How do I display the player’s name in a dropdown?” Here’s an example function that implements that:

form.dropdown("Dropdown",generate_player_list());

After defining this function, you can use it in a dropdown function to define a dropdown with player names, like this:

let players = server.world.getAllPlayers();
for (let i = 0; i<= players.length; i++){
    if (response.formValues[2] == i){
         player.sendMessage("Selected Player： " + players[i].name);
    }
}

Learning

As mentioned above, the creation of UI and ScriptAPI is based on Javascript. Therefore, understanding Javascript syntax and functions will make writing scripts easier. Here are some good books to help you master Javascript.

独習JavaScript 新版 [ CodeMafia 外村 将大 ]

created by Rinker

¥3,278 (2025/09/01 19:18:15時点 楽天市場調べ-詳細)

• Amazon
• 楽天市場

【初心者向け】オリジナルアドオンとアイテムの作り方【マイクラ統合版】

Introduction Minecraft is a game with a huge degree of freedom. You can simply survive and defeat the Ender Dragon, master architecture and create highly artistic works, or even create maps for distribution using commands. The possibilities are truly endless.Now, creating add-ons further increases this freedom. Not only can you…

【Minecraft統合版】よく使うAPI Scriptのフレーズ 5選

Introduction Minecraft is a game with a huge degree of freedom. You can simply survive and defeat the Ender Dragon, master architecture and create highly artistic works, or even create maps for distribution using commands. The possibilities are truly endless.Now, creating add-ons further increases this freedom. Not only can you…

【革命】オリジナルのコマンドを作る方法を徹底解説 – ScriptAPIでアドオン制作【マイクラ統合版】

Introduction Minecraft is a game with a huge degree of freedom. You can simply survive and defeat the Ender Dragon, master architecture and create highly artistic works, or even create maps for distribution using commands. The possibilities are truly endless.Now, creating add-ons further increases this freedom. Not only can you…