Bedrock Wiki
Beginner's Guide
Animation Controllers
Blocks
Commands
Concepts
Documentation
Entities
Items
JSON UI
Loot, Recipes & Trading
Meta
NBT
Particles
Scripting
Servers
Visuals
World Generation

Intro to Scripting

Intro to Scripting

TIP

This script API page assumes basic knowledge of pack setup for add-ons. For information on how to set up behaviour packs, please see the Introduction to Add-Ons page.

WARNING

The Script API is currently in active development, and breaking changes are frequent. This page assumes the format of Minecraft 1.21.70x.

Overview ​

The Script API (formerly GameTest Framework) is a feature that allows for a new variety of creations, these are built with JavaScript files in the behavior pack folder. Most parts of the Script API are not experimental.

This page will give you an introduction to the 80% of Minecraft's Creator API concepts that you will use on a daily basis.

Create Your First Project ​

Currently, scripts can only be used in behavior packs.

In the behavior pack manifest, you need to add a script module and set an entry point for your script project. Currently, only "javascript" is supported as a valid language.

BP/manifest.json#modules[0]
json
{
    "uuid": "239c134f-67bf-4738-9bcc-8c69d31b1f72",
    "version": [1, 0, 0],
    "type": "script",
    "language": "javascript",
    "entry": "scripts/main.js"
}

Additionally, dependencies will need to be set based on modules used. To import and use script API modules, you must specify dependencies using the module_name and version. In this example, the @minecraft/server module is used.

BP/manifest.json
json
{
    "format_version": 2,
    "header": {
        "name": "Bedrock Add-ons",
        "description": "Script API Template",
        "uuid": "<UUID>",
        "version": [0, 1, 0],
        "min_engine_version": [1, 20, 70]
    },
    "modules": [
        {
            "type": "script",
            "language": "javascript",
            "uuid": "<UUID>",
            // Your entry file; where Minecraft will read your code from.
            "entry": "scripts/main.js",
            "version": [0, 1, 0]
        }
    ],
    // to use eval() and Function() inside your code, remove it if not neccessary
    "capabilities": ["script_eval"],
    "dependencies": [
        {
            // Enables the use of @minecraft/server module, with a version of 1.17.0.
            // It must be the latest version or it might not work!
            "module_name": "@minecraft/server",
            "version": "1.18.0"
        },
        {
            // Enables the use of @minecraft/server-ui module, with a version of 1.3.0.
            // It must be the latest version or it might not work!
            "module_name": "@minecraft/server-ui",
            "version": "1.3.0"
        }
    ]
}

If your project needs other module to run your code, add the other dependencies that follow the format above.

Stable API modules, these do not require the Beta APIs experiment to be turned on. Most features are included in stable APIs, and will not break or be changed when Minecraft is updated.

Beta API modules, requirs the Beta APIs experiment to be turned on in world settings, and add many of experimental features in the API. These APIs can be changed, removed, or added to with very little warning, and are prone to breaking. Be warned!

In order to use the eval() function or Function() constructors within your code, you can add the following in the manifest capabilities:

BP/manifest.json
json
{
    "capabilities": ["script_eval"]
}

The entry point file can contain scripts and/or imports to other script files. Only one entry point file can be specified.

Writing Scripts with JS ​

Minecraft's scripting engine only runs JavaScript, like any other JavaScript projects. Check out Scripting with TypeScript for compiling TS directly to JavaScript.

BP/scripts/main.js
js
// This file demonstrates that the code is working by
// Spamming the chat with "Hello World"

// Import world & system component from "@minecraft/server", for world & game logic.
import { world, system } from "@minecraft/server";

// Create & run an interval that is called every Minecraft tick
system.runInterval(() => {
    // Spams the chat with "Hello World" with world.sendMessage function from the API
    world.sendMessage("Hello World");
}, 1);

Script API 2.0.0 ​

With Script API Version 2, scripts now by default execute before the world has loaded. This means that we now have to wait until the world is loaded to run most functions.

BP/scripts/main.js
js
import { world } from "@minecraft/server";

// wait until the world is loaded
world.afterEvents.worldLoad.subscribe(() => {
    // Send a message in chat
    world.sendMessage("World has loaded");

    // import other js files
    import("./path/to/file.js");
});

Reference Documentation ​

Official documentation are hosted on Microsoft Learn and can be found here:

Official typescript declarations for the latest Beta API modules in Minecraft Preview can be found here:

These allow for enhanced auto-completions and validation when used inside of your editor.

  • bridge. v2: Ships with GameTest support built-in.
  • Visual Studio Code: Install Node.js and npm, then run the following in command line:

Latest beta API modules:

bash
npm i @minecraft/server@2.0.0-beta.1.21.70-stable
npm i @minecraft/server-ui@2.0.0-beta.1.21.70-stable
npm i @minecraft/server-gametest@1.0.0-beta.1.21.70-stable
npm i @minecraft/server-admin@1.0.0-beta.1.21.70-stable
npm i @minecraft/server-net@1.0.0-beta.1.21.70-stable
npm i @minecraft/debug-utilities@1.0.0-beta.1.21.70-stable

Latest stable API modules:

bash
npm i @minecraft/server
npm i @minecraft/server-ui

Contributors

Edit Intro to Scripting on GitHub