Introduction
Due to the recent removal of the “Holiday Creator Features,” it is no longer possible to control the behavior of original items using json files. Therefore, if you want to create usable items, you will need to use the Script API.
ScriptAPI is a feature that allows you to customize the game system using a programming language called JavaScript. For more information about this update, please see this article.
However, using ScriptAPI requires some prior preparation and basic knowledge. If you are not familiar with ScriptAPI, we recommend that you read this article before reading this one.
Below, we will assume you are familiar with APIScript and explain how to make any item available.
overview
If you are using the SciptAPI template, open main.js in the script folder. First, write the import statement as usual (this step is not necessary if this statement already exists).
import * as server from '@minecraft/server';
This completes the declaration of the variable server that defines the Minecraft module. We will use this server below.
Write a script
Now it’s time to write the script. To make any item available, follow the steps below to implement it.
- Detect when an item is used
- If a specific item is used, it will execute commands under the user.
For example, “Use a wooden stick to obtain diamonds,” would look like this:
server.world.beforeEvents.itemUse.subscribe(ev => {
if (ev.itemStack.typeId == "minecraft:stick"){
ev.source.runCommandAsync("give @a diamond 1");
}
})
Copy and paste this text directly below the import statement above.
This script itself has appeared in a previous article, but in this article we will provide a detailed explanation of the script.
Commentary
The Minecraft module has a beforeEvents (or afterEvents) class in the world class. This triggers various events in the world and invokes functions when an event occurs. This is very commonly used in the Script API, so it’s important to remember it. In this example, we’re using the itemUse class within it to detect when an item has been used and fire a function. The subscribe() function promises to execute a certain function. The content of the function is written within these parentheses.
As shown above, the name of the function is ev (the initial letter of “event”).
The ev.itemStack.typeId in the if statement is the id of the used item (String type). In this case, if this is equal to minecraft:stick, it will return true and proceed to the next step.
ev.source is the entity that caused the event. In this case, it’s the player who used the stick. Under this entity, execute the command with the runCommandAsync() function. In this case, we used the give command. This will give diamonds when the stick is used.
You can customize it to your liking by changing the “minecraft:stick” and “give @a diamond 1” parts above. This allows you to make any item available for use.
Implemented cooldown
This article doesn’t end here, because after reading the comments on the YouTube video, I felt there was a demand for cooldowns, so in this article I’ll explain how to implement cooldowns on more usable items.
To begin with, a “cooldown” is a mechanism that means “once you’ve used an item, you can’t use it again for a certain period of time.” To implement this, you can take the following approaches:
- When using an item, use the scoreboard command to give the user a score of (cooldown time [seconds]) x 20.
- Use runInterval or tick.json to decrease the score by 1 every tick (1/20th of a second).
- When using an item, read the player’s score, and if the score is 0, execute the command, otherwise do not execute it.
This time, let’s consider a method using the runInterval() function. We will explain tick.json in a separate video and article. The script should look something like this:
let cooldown_time = 3
let item_name = "minecraft:stick"
let command = "say hello!"
server.world.beforeEvents.itemUse.subscribe(ev => {
if (ev.itemStack.typeId == item_name){
ev.source.runCommandAsync("execute as @s[scores={test_score=0}] run " + command);
ev.source.runCommandAsync("execute as @s[scores={test_score=0}] run scoreboard players set @s test_score " + cooldown_time*20);
}
});
server.system.runInterval(ev => {
for (const player of server.world.getAllPlayers()){
player.runCommandAsync("scoreboard objectives add test_score dummy");
player.runCommandAsync("scoreboard players remove @s[scores={test_score=0..}] test_score 1");
player.runCommandAsync("scoreboard players set @s[scores={test_score=..-1}] test_score 0");
}
}
);
This is an example of executing the command “say hello!” when using a wooden stick. The cooldown time is 3 seconds, so the command will not be executed until 3 seconds have passed since the last time it was used.
Feel free to change the cooldown_time, item_name, and command above to create your own arrangement.
Commentary
This script is divided into two main parts. The first half defines the function that fires when an item is used, and is not much different from the previous script. The only difference is that when an item is used, the scoreboard command is used to add to the score.
The second half defines a function that is always executed. Here, it mainly uses the scoreboard command to decrease the score by 1 every tick.
Restrict Use
Finally, I’ll explain how to restrict the use of items. Up until now, right-clicking on an item always invoked a command. However, in some cases, you may want to execute a command only under special conditions. Or, you may want a single item to have two functions (in fact, I often find myself doing this). Assuming such a situation, here is an example of activating a command when the player is in a certain condition.
server.world.beforeEvents.itemUse.subscribe(ev => {
if (ev.itemStack.typeId == "minecraft:stick"){
if (ev.source.isSneaking == true){
ev.source.runCommandAsync("say Hello!");
}
}
});
In this example, if you sneak while using a stick, the command “say Hello!” will be activated. In this way, you can also set conditions for using items.
You can customize it to your liking by changing the IDs and commands of the above items.
Similarly, by setting the process for when you are not sneaking, you can equip one item with two functions. Below is an example.
server.world.beforeEvents.itemUse.subscribe(ev => {
if (ev.itemStack.typeId == "minecraft:stick"){
if (ev.source.isSneaking == true){
ev.source.runCommandAsync("say Hello!");
}else{
ev.source.runCommandAsync("say I'm standing!");
}
}
});
This is an example where the item says “Hello!” when sneaking, and “I’m standing!” when not. In this way, by using conditional branching with if~else~ statements, you can give an item multiple functions.
Condition Examples
Here, we checked whether the object is sneaking or not. This is because the isSneaking property returns true if the object is sneaking, and false if it is not. The main properties that have this property are as follows:
- isInWater
- isOnGround
- isSleeping
- isSneaking
- isSwimming
- isFlying
- isJumping
You can combine these to create unique items.
Apply the script
As mentioned above, the Script API is based on Javascript, so understanding Javascript will make writing scripts easier. Naturally, knowledge of Javascript will also be essential when arranging the script mentioned above. Here we will introduce a good book 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
This article explains how to use ScriptAPI to make items usable. Please also refer to the following article for more information on ScriptAPI.
Also, this article provides more detailed information on the “Reverse ScriptAPI”:
