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.
| term | meaning |
| function | A program that produces a unique output depending on the input |
| GUI | An abbreviation for Graphical User Interface, which allows for intuitive and sensory operation. |
| Module | Elements and parts for running a program |
| JavaScript. | A type of programming language that is primarily used on web pages |
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.
In this article, we will first explain how to set up the APIScript environment. If you already know how, please skip this section.
Environment Construction
First, we will show you what you need to build the environment. You can download each item from the links below.
| Name of the software you need | Download location | remarks |
| Minecraft | amazon | It goes without saying that this is a well-known game software. The Win10 version is preferable. |
| vscode | https://code.visualstudio.com/ | A text editor specialized for writing code (free). Not necessary if you already have another text editor. |
| node.js | https://nodejs.org/ | A free tool for running javascript on your computer. After downloading, run the msi file. |
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/servernpm 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.
Note that we are using the afterEvents property here to trigger the use of the item, but using the beforeEvents property here will result in an error, as mentioned in this article.
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.
The official documentation is a textbook on the scripting API. It is very helpful, so it's definitely worth taking a look at (note that it's only available in English).
https://learn.microsoft.com/ja-jp/minecraft/creator/scriptapi/minecraft/server/minecraft-server?view=minecraft-bedrock-experimental
The end
In this article, we explained how to display a UI in Minecraft using APIScript. Being able to display a UI greatly increases the extensibility and flexibility of add-ons, so please give it a try.
For more information on the basics of add-ons, see this article.
You can also find more information about commonly used APIScript phrases here.
Next article:
