Bedrock Edition scripting documentation

This is the scripting documentation for Bedrock Edition 1.12.0.

Version: 1.12.0.28

Scripting system
The Minecraft Script Engine uses the JavaScript language.

The player can write JavaScript scripts and bundle them with Behavior Packs to listen and respond to game events, get and modify data in components that entities have, and affect different parts of the game.

Demos
Here are some demos from your friends at Minecraft to help you get started with scripting. Simply unzip them to check out the code, or import them as a  to play with them.


 * {| class="wikitable"

! Demo !! Last Updated !! Download Link
 * Turn-Based RPG
 * 4/17/2019
 * https://aka.ms/minecraftscripting_turnbased
 * Mob Arena
 * 4/17/2019
 * https://aka.ms/minecraftscripting_mobarena
 * }
 * https://aka.ms/minecraftscripting_mobarena
 * }

Known issues
This is the list of currently known issues with the Minecraft Script Engine.


 * {| class="wikitable"

! Issue !! Workaround
 * Scripts are not loaded properly from archived packs
 * Unzip script packs before applying them to a world. If you import a script pack with the  extension, it unzips it for you
 * Custom UI doesn't work in VR or MR mode
 * Currently you can use only custom UI when running the game in regular mode
 * Custom UI doesn't retain state upon suspend and resume
 * Currently there's no workaround for this issue
 * Exiting a world without scripts and entering one that has scripts might cause the wrong world to load
 * Restart Minecraft before loading a new world with scripts
 * Calling  on a dying entity might cause the game to crash
 * Don't call  the same frame you reduced the entity's damage to 0. Removing the entity forces it to be removed right away. Instead, save any dying entities and clean the up on the next frame (See the Turn-Based Demo for an example of this)
 * }
 * Restart Minecraft before loading a new world with scripts
 * Calling  on a dying entity might cause the game to crash
 * Don't call  the same frame you reduced the entity's damage to 0. Removing the entity forces it to be removed right away. Instead, save any dying entities and clean the up on the next frame (See the Turn-Based Demo for an example of this)
 * }
 * }

Breaking changes
While we continue to work and refine the experimental Scripting API we might need to make changes that break your current scripts. Please check this section if your scripts aren't working as expected.


 * {| class="wikitable"

! Category !! Change
 * UI
 * now takes a facet name. In order to check for the script engine starting and connect it to the UI you need the following:
 * now takes a facet name. In order to check for the script engine starting and connect it to the UI you need the following:

Followed by the following line after you are done doing your initialization:


 * Components
 * Calls to  now return the component's parameters inside of the   parameter of the return object.
 * Events
 * Event data objects now hold the event's parameters inside of the  parameter of the event data object.
 * Events
 * Custom events need to be registered before using. Check the documentation for  for more information.
 * Events
 * Custom events need to have a namespace and can't use the  namespace. This namespace is reserved for built-in events only.
 * Events
 * Event Data is now standardized. Call  to create an event data object prefilled with all the fields and default values for an event. You need this event data object to trigger any events.
 * }
 * Custom events need to have a namespace and can't use the  namespace. This namespace is reserved for built-in events only.
 * Events
 * Event Data is now standardized. Call  to create an event data object prefilled with all the fields and default values for an event. You need this event data object to trigger any events.
 * }
 * }

Prerequisites
So you want to make your own Scripts? That's awesome! This section lists the minimum and recommended software you need. Note: Scripts are supported only on Windows 10 PCs. If you try to open a world with scripts on a device that doesn't support scripts, an error message appears to let you know you can't enter the world.


 * {| class="wikitable"

! Software !! Minimum !! Recommended
 * Minecraft
 * Minecraft on your Windows 10 device
 * Minecraft on your Windows 10 device
 * Code Editor
 * Visual Studio Code or any plain-text editor
 * Visual Studio Community 2019 with the following components installed: 'JavaScript diagnostics', 'JavaScript and TypeScript language support', 'Just-In-Time debugger'
 * Debugger
 * N/A
 * Visual Studio Community 2019
 * Other
 * Vanilla Behavior Pack available from https://aka.ms/behaviorpacktemplate
 * Vanilla Behavior Pack available from https://aka.ms/behaviorpacktemplate
 * Storage
 * 1.0 GB of free space for text editor, game, and scripts
 * 3.0 GB of free space for Visual Studio, game, and scripts
 * }
 * Storage
 * 1.0 GB of free space for text editor, game, and scripts
 * 3.0 GB of free space for Visual Studio, game, and scripts
 * }
 * }

Getting started
First you must download the latest Vanilla Behavior Pack. You can get this from the following link: https://aka.ms/behaviorpacktemplate

Once you have downloaded the Behavior Pack, unzip it to a folder. Inside the Behavior Pack, the scripts folder contains all the scripting files you want to run.

The scripts folder contains two folders: one for client scripts and one for server scripts.
 * Server Scripts: These scripts run on the server side of the game. This includes spawning new entities, adding components, or modifying components of an entity.
 * Client Scripts: These scripts run on each individual player's side of the game. This is a good place to respond to events and manage anything specific to the player.

Once you have chosen whether you are making a client or server script, simply add a new blank text file with  extension to the appropriate folder, and open it in your preferred code editor. Then code away! You can have as many or as few JavaScript files as you want here (the name of the files doesn't matter) and they all run independently of each other!

Note: For scripts to be run by the game, you must enable Experimental Gameplay on the world on which you run scripts. This is necessary while scripting is still in beta.

When entering a world that has client scripts in it, you are prompted to accept that you wish to run scripts on your device (this appears both for local worlds as well as multiplayer worlds). Additionally, if your pack contains client scripts, you need to include a  module in the pack's manifest. This tells the game anything in the scripts/client folder needs to be sent over to the clients. Please refer to the Add-on Documentation page for more information on the pack's manifest contents.

Example of manifest module needed for client scripts
{           "description": "Example client scripts module", "type": "client_data", "uuid": "c05a992e-482a-455f-898c-58bbb4975e47", "version": [0, 0, 1] }

|-scripts
 * --client
 * ---myClientScript.js
 * --server
 * ---myServerScript.js
 * -manifest.json
 * -pack_icon.png

Structure of a script
In this section you can find a quick description of the basic structure of a JavaScript script file for the Minecraft Script Engine. If you would like to learn more about JavaScript or want to follow a fundamentals tutorial, you can check the official documentation on the Mozilla Developer Network here: https://developer.mozilla.org/docs/Web/JavaScript

These are, in a way, the required parts of a script but they are by no means the only parts you can have. You can create additional methods as needed - just make sure they are called from somewhere in one of the methods below!

1. System registration
First off we need to register the system for our file. This signs up our script to be set-up either on the client or server threads of the game. Generally speaking, you choose based on whether you put the script file in the client or server folders. To do that simply call  on either the client or server and give it the version of the API you require.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Integer
 * This is the major version of the Minecraft Script Engine your script was designed to work with
 * Integer
 * This is the revision of the Minecraft Script Engine your script was designed to work with
 * }
 * Code examples
 * This is the revision of the Minecraft Script Engine your script was designed to work with
 * }
 * Code examples
 * Code examples

//Client System let sampleClientSystem = client.registerSystem(0, 0); //Server System let sampleServerSystem = server.registerSystem(0, 0);

2. System initialization
This is the first method that gets called immediately after the system is registered. It runs as soon as the script loads at world start. You can use this to set up the environment for your script: register custom components and events, sign up event listeners, etc. This runs before the world is ready and the player has been added to it. This function should be used to initialize variables and setup event listeners. You shouldn't try to spawn or interact with any entities at this point! You should also avoid interaction with UI elements or sending messages to the chat window since this is called before the player is ready.


 * Code example:

sampleSystem.initialize = function { //register event data, register components, register queries, listen for events };

3. System update
This method gets called once every game tick. The server and client tick at 20 times per second. This is a good place to get, check, and react to component changes.


 * Code example:

sampleSystem.update = function { //Update all the things };

4. System shutdown
This method gets called when the Minecraft Script Engine is shutting down. For the client this is when they leave the world; for the server this is after the last player has exited the world.


 * Code example:

sampleSystem.shutdown = function { //Cleanup script only things };

Debugging
Your script isn't working or doing what you want it to do? Fret not! We have built some debugging capabilities into the Script Engine to help you figure out what's going on with your script. If you are new to programming or want to learn more about debugging we suggest checking out the documentation about debugging with Visual Studio available here: https://docs.microsoft.com/visualstudio/debugger

There are two ways to tell what happened when something goes wrong with a script: in-game and advanced, which we describe below. You only need the game and your script to debug in-game, but you need a Windows 10 PC and Visual Studio installed for the advanced debugging.

In-game
When you run a script in the game, the Script Engine prints out error messages whenever something goes wrong. For example, if you try to get a component that the script engine doesn't know about, you get an error. To look at these messages you can open the chat screen which has all the generated error messages there; or you can open the log file that the game generated. The location of the log file varies by platform. On Windows 10 you can find the log file in

We strongly encourage you to build further debug messages and tools into your scripts while working on them. This should help you discern when something isn't working quite right. Reach out on the official Discord channel if you need additional help: https://discord.gg/Minecraft

Real-time (advanced)
If you have a Windows 10 PC with Visual Studio installed, you can attach the Visual Studio debugger and debug your script in real-time. If you installed Visual Studio with the components mentioned in the "Recommended" section of this document you should have installed and enabled the Just-In-Time Debugger. This tool pops up a message from Visual Studio whenever an exception occurs in your script and allow you to open Visual Studio on the line of your script that broke.

Additionally, you can connect to the Script Engine manually and debug your code. You can use remote debugging to connect and debug Minecraft running on another device. Please refer to the Visual Studio Debugger documentation above for instructions on how to use remote debugging.

First you need to start up Visual Studio. If this is the first time you have launched Visual Studio after installation, we suggest setting up your environment for JavaScript development and logging in to your Microsoft account when prompted. This sets up the Visual Studio interface with the most important tools you need.

Once you have Visual Studio open you should launch Minecraft. Then create a new world with Experimental Gameplay enabled and apply the Behavior Pack containing your scripts.

After creating the world go back to Visual Studio and click on the Debug menu. Then click on "Attach to Process". In the window that opens there is a search box titled Filter Process. Click on it and type Minecraft.

Once the list is narrowed down to only the instance of Minecraft running, you can verify that the Script Engine is running by looking at the Type column. This say Script and either x86 or x64.

Select the process and click on Attach to attach the debugger to the game. Now you can press the Pause button to pause the Script Engine when the next line of script code runs. This allows you to inspect the values of variables in your script and break into Visual Studio if an error occurs in your code. Warning: When you hit a breakpoint to step through code with a debugger, it is possible for a client to time out and disconnect or for the server to disconnect all players.

Script API objects
Here you can find the definition of some objects returned by the script API.

Entity JS API object

 * {| class="wikitable"

! Type !! Name !! Entity JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Can be:  or.
 * String
 * READ ONLY. This is the identifier for the object in the format . For example, if the type is entity and the object is representing a vanilla cow, the identifier would be
 * Positive Integer
 * READ ONLY. This is the unique identifier of the entity.
 * }
 * READ ONLY. This is the identifier for the object in the format . For example, if the type is entity and the object is representing a vanilla cow, the identifier would be
 * Positive Integer
 * READ ONLY. This is the unique identifier of the entity.
 * }
 * Positive Integer
 * READ ONLY. This is the unique identifier of the entity.
 * }
 * READ ONLY. This is the unique identifier of the entity.
 * }

Level JS API object

 * {| class="wikitable"

! Type !! Name !! Level JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is:.
 * Positive Integer
 * READ ONLY. This is the unique identifier of the level.
 * }
 * Positive Integer
 * READ ONLY. This is the unique identifier of the level.
 * }
 * READ ONLY. This is the unique identifier of the level.
 * }
 * }

Component JS API object

 * {| class="wikitable"

! Type !! Name !! Component JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is:.
 * JavaScript Object
 * This is the content of the component.
 * }
 * JavaScript Object
 * This is the content of the component.
 * }
 * This is the content of the component.
 * }
 * }

Query JS API object

 * {| class="wikitable"

! Type !! Name !! Query JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is:.
 * Positive Integer
 * READ ONLY. This is the unique identifier of the query.
 * }
 * Positive Integer
 * READ ONLY. This is the unique identifier of the query.
 * }
 * READ ONLY. This is the unique identifier of the query.
 * }
 * }

ItemStack JS API object

 * {| class="wikitable"

! Type !! Name !! ItemStack JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is:.
 * String
 * READ ONLY. This is the identifier for the object in the format . For example, if the type is entity and the object is representing a vanilla cow, the identifier would be
 * String
 * READ ONLY. This is the identifier of the item.
 * String
 * READ ONLY. This is the number of items in the stack.
 * }
 * READ ONLY. This is the identifier for the object in the format . For example, if the type is entity and the object is representing a vanilla cow, the identifier would be
 * String
 * READ ONLY. This is the identifier of the item.
 * String
 * READ ONLY. This is the number of items in the stack.
 * }
 * String
 * READ ONLY. This is the number of items in the stack.
 * }
 * READ ONLY. This is the number of items in the stack.
 * }
 * }

Block JS API object

 * {| class="wikitable"

! Type !! Name !! Block JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is: " ".
 * String
 * READ ONLY. This is the identifier for the object in the format . For example, if the type is block and the object is representing a block of bedrock, the identifier would be
 * JavaScript Object
 * READ ONLY. This is the ticking area object that was used to get this block.
 * JavaScript Object
 * READ ONLY. This is the position of the block and it functions as part of its unique identifier.
 * READ ONLY. This is the identifier for the object in the format . For example, if the type is block and the object is representing a block of bedrock, the identifier would be
 * JavaScript Object
 * READ ONLY. This is the ticking area object that was used to get this block.
 * JavaScript Object
 * READ ONLY. This is the position of the block and it functions as part of its unique identifier.
 * READ ONLY. This is the ticking area object that was used to get this block.
 * JavaScript Object
 * READ ONLY. This is the position of the block and it functions as part of its unique identifier.
 * JavaScript Object
 * READ ONLY. This is the position of the block and it functions as part of its unique identifier.
 * READ ONLY. This is the position of the block and it functions as part of its unique identifier.
 * READ ONLY. This is the position of the block and it functions as part of its unique identifier.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Integer
 * The  position
 * Integer
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * }


 * }

Ticking area JS API object
There are two types of ticking area objects. Entity and Level. When a function calls for a ticking area it can take either type as an argument.

Entity ticking area JS API object

 * {| class="wikitable"

! Type !! Name !! Entity Ticking Area JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is: " ".
 * Positive Integer
 * READ ONLY. This is the unique identifier of the ticking area.
 * }
 * Positive Integer
 * READ ONLY. This is the unique identifier of the ticking area.
 * }
 * READ ONLY. This is the unique identifier of the ticking area.
 * }
 * }

Level ticking area JS API object

 * {| class="wikitable"

! Type !! Name !! Level Ticking Area JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is: " ".
 * String
 * READ ONLY. This is the unique identifier of the ticking area.
 * }
 * String
 * READ ONLY. This is the unique identifier of the ticking area.
 * }
 * READ ONLY. This is the unique identifier of the ticking area.
 * }
 * }

Script bindings
Bindings are the capabilities of the Minecraft Script Engine to change or modify things in the game.

log(Message)
The log function is accessed through the server or client objects and allows for logging a message to the  file. On Windows 10 devices it is located at

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * Message
 * The message that you want to send to the log file
 * }
 * }

Code example
//Log system.exampleFunction = function { client.log("example log message") };

Creates an empty entity with no components and does not place it in the world. The empty entity is of type " " and have a blank identifier. This is not a valid entity that exists in the world, just an empty one that only scripts know about.

NOTE: Entities are created first on the server, with the client notified of new entities afterward. Be aware that if you send the result object to the client right away, the created entity might not exist on the client yet.

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Entity JS API Object
 * An object representing the newly created entity
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * }

Creates an entity and applies the specified template as defined in JSON. This allows you to quickly create an entity from the applied Behavior Packs as the base for an entity created in scripting. The entity gets spawned into the world with all the components, component groups, and event triggers that are defined in the JSON file of the identifier specified. Only works on scripts registered on the server. NOTE: Entities are created first on the server, with the client notified of new entities afterward. Be aware that if you send the result object to the client right away, the created entity might not exist on the client yet.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * Specifies the type of the entity that is being created by the template. Valid inputs are  and
 * String
 * This can be any of the entity identifiers from the applied Behavior Packs. For example, specifying  here makes the provided entity a cow as defined in JSON. If the   is   this should be the item's identifier.
 * }
 * String
 * This can be any of the entity identifiers from the applied Behavior Packs. For example, specifying  here makes the provided entity a cow as defined in JSON. If the   is   this should be the item's identifier.
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Entity JS API Object
 * An object representing the newly created entity
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * }

Destroys an entity identified by the. If the entity exists in the world this removes it from the world and destroy it. This also makes the  no longer valid - you should only destroy an entity after you are done with it and no longer need to reference it again. This does not kill the entity. There is no event for its death; it is simply removed.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The object that was retrieved from a call to  or retrieved from an entity event
 * }
 * The object that was retrieved from a call to  or retrieved from an entity event
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * The entity was successfully destroyed
 * JavaScript Object
 * Something went wrong when destroying the entity
 * }
 * JavaScript Object
 * Something went wrong when destroying the entity
 * }
 * }

Checks if the given  corresponds to a valid entity.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The object that was retrieved from a call to  or retrieved from an entity event
 * }
 * The object that was retrieved from a call to  or retrieved from an entity event
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * The entity is in the Script Engine's database of entities
 * Boolean
 * The entity is not in the Script Engine's database of entities
 * JavaScript Object
 * Something went wrong when validating the entity
 * }
 * The entity is not in the Script Engine's database of entities
 * JavaScript Object
 * Something went wrong when validating the entity
 * }
 * Something went wrong when validating the entity
 * }

Creates a custom component that only exists in script. It can be then added, removed, and updated from entities. These custom components only exist while the Script Engine is running.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * The identifier of the custom component. It is required to use a namespace so you can uniquely refer to it later without overlapping a name with a built-in component: for example
 * JavaScript Object
 * A JavaScript Object that defines the name of the fields and the data each field holds inside the component.
 * }
 * JavaScript Object
 * A JavaScript Object that defines the name of the fields and the data each field holds inside the component.
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * The component was successfully registered
 * JavaScript Object
 * Something went wrong when registering the component
 * }
 * JavaScript Object
 * Something went wrong when registering the component
 * }
 * }

Creates the specified component and adds it to the entity. This should only be used with custom components which need to be registered first. If the entity already has the component, this retrieves the component already there instead.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The EntityObject that was retrieved from a call to  or retrieved from an event
 * String
 * The identifier of the component to add to the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * String
 * The identifier of the component to add to the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * }


 * Return value


 * {| class="wikitable"

! Type !! Value !! Description
 * Component JS API Object
 * An object with the following fields, and additionally, all the fields as defined in the component
 * JavaScript Object
 * Something went wrong when creating the component
 * }
 * JavaScript Object
 * Something went wrong when creating the component
 * }
 * }

Checks if the given entity has the specified component.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The  that was retrieved from a call to   or retrieved from an event
 * String
 * The identifier of the component to check on the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * String
 * The identifier of the component to check on the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * }


 * Return value


 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * The  has the component
 * Boolean
 * The  doesn't have the component
 * JavaScript Object
 * An unknown component was passed in or something else went wrong when checking if the  had the component
 * }
 * The  doesn't have the component
 * JavaScript Object
 * An unknown component was passed in or something else went wrong when checking if the  had the component
 * }
 * An unknown component was passed in or something else went wrong when checking if the  had the component
 * }

Looks for the specified component in the entity. If it exists, retrieves the data from the component and returns it.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The  that was retrieved from a call to   or retrieved from an event
 * String
 * The identifier of the component to retrieve from the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * String
 * The identifier of the component to retrieve from the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Component JS API Object
 * An object with the following fields, and additionally, all the fields as defined in the component
 * An object with the following fields, and additionally, all the fields as defined in the component
 * An object with the following fields, and additionally, all the fields as defined in the component

Component JS API Object

 * {| class="wikitable"

! Type !! Name !! Component JS API Object !! Description
 * String
 * READ ONLY. This defines the type of object. Value is:.
 * JavaScript Object
 * This is the content of the component.
 * }
 * JavaScript Object
 * This is the content of the component.
 * }
 * This is the content of the component.
 * }
 * }


 * JavaScript Object
 * The entity did not have the component or something went wrong when getting the component
 * }
 * The entity did not have the component or something went wrong when getting the component
 * }

Applies the component and any changes made to it in script back to the entity. What this means for each component can be slightly different: it makes the component reload on the entity with the new data as if it had just been added to the entity.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The  that we are applying the component changes to
 * Component JS API Object
 * The component object retrieved from the entity that was returned by either  or
 * }
 * Component JS API Object
 * The component object retrieved from the entity that was returned by either  or
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * The component was successfully updated
 * JavaScript Object
 * Something went wrong when updating the component
 * }
 * JavaScript Object
 * Something went wrong when updating the component
 * }
 * }

Removes the specified component from the given entity. If the entity has the component, it is removed. Currently this only works with custom components and can't be used to remove components defined for an entity in JSON.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * The  that was retrieved from a call to   or retrieved from an event
 * String
 * The identifier of the component to remove from the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * String
 * The identifier of the component to remove from the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * The component was successfully removed from the entity
 * JavaScript Object
 * The entity did not have the component or something went wrong when removing the component
 * }
 * JavaScript Object
 * The entity did not have the component or something went wrong when removing the component
 * }
 * }

Event bindings
These are the bindings used to handle events. For a list of events you can react to or trigger, check the Events section of this document.

Registers the Event to the script engine. This allows you to create Event Data by calling  and have it initialized with the correct default data and fields. Only custom events need to be registered.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * This is the identifier of the custom event we are registering. The namespace is required and can't be set to.
 * JavaScript Object
 * The JavaScript object with the correct fields and default values for the event
 * }
 * JavaScript Object
 * The JavaScript object with the correct fields and default values for the event
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * Successfully registered the event data
 * JavaScript Object
 * Something went wrong when registering the event for listening
 * }
 * JavaScript Object
 * Something went wrong when registering the event for listening
 * }
 * }

Creates an object with all the required fields and default data for the specified event. If the event is a custom event, it needs to have been previously registered.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * This is the identifier of the custom event we are registering. The namespace is required and can't be set to.
 * }
 * This is the identifier of the custom event we are registering. The namespace is required and can't be set to.
 * }

Return value

 * {| class="wikitable"

! Type !! Description
 * JavaScript Object
 * The object containing the event data
 * }
 * }

Allows you to register a JavaScript object that gets called whenever the specified event is broadcast. The event can either be a built-in event or an event specified in script.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * This is the identifier of the event to which we want to react. Can be the identifier of a built-in event or a custom one from script
 * JavaScript Object
 * The JavaScript object to be called whenever the event is broadcast
 * }
 * JavaScript Object
 * The JavaScript object to be called whenever the event is broadcast
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * Successfully registered to listen for the event
 * JavaScript Object
 * Something went wrong when registering the event for listening
 * }
 * JavaScript Object
 * Something went wrong when registering the event for listening
 * }
 * }

Allows you to trigger an event with the desired data from script. Anything that signed up to listen for the event is notified and the given data delivered to them.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * This is the identifier of the event we want to react to. Can be the identifier of a built-in event or a custom one from script
 * JavaScript Object
 * The data for the event. You can create a new JavaScript Object with the parameters you want to pass in to the listener and the engine takes care of delivering the data to them
 * }
 * JavaScript Object
 * The data for the event. You can create a new JavaScript Object with the parameters you want to pass in to the listener and the engine takes care of delivering the data to them
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Boolean
 * Successfully broadcasted the event
 * JavaScript Object
 * Something went wrong when broadcasting the event
 * }
 * JavaScript Object
 * Something went wrong when broadcasting the event
 * }
 * }

Entity queries
Entity Queries are a way for you to filter for entities based on their components. Once you have registered a query, you can request all the entities that are captured by it. Entity Queries only ever return entities that are currently active in the level. If your query extends into chunks that are not currently loaded, entities there are not included in the query.

Allows you to register a query. A query contains all entities that meet the filter requirement. No filters are added by default when you register a query so it captures all entities.

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Query JS API Object
 * An object containing the ID of the query
 * JavaScript Object
 * Something went wrong when creating the query
 * }
 * JavaScript Object
 * Something went wrong when creating the query
 * }
 * }

Code example
//Query Registration var simple_query = {}; system.initialize = function { simple_query = this.registerQuery; };

Allows you to register a query that show only entities that have the given component and define which fields of that component are used as a filter when getting the entities from the query. You can either provide just the component identifier, or the component identifier and the name of 3 properties on that component to be tested (If you do specify property names, you must specify 3).

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * This is the identifier of the component that is used to filter entities when
 * String
 * This is the name of the first field of the component that we want to filter entities by.
 * String
 * This is the name of the second field of the component that we want to filter entities by.
 * String
 * This is the name of the third field of the component that we want to filter entities by.
 * }
 * This is the name of the first field of the component that we want to filter entities by.
 * String
 * This is the name of the second field of the component that we want to filter entities by.
 * String
 * This is the name of the third field of the component that we want to filter entities by.
 * }
 * String
 * This is the name of the third field of the component that we want to filter entities by.
 * }
 * This is the name of the third field of the component that we want to filter entities by.
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Query JS API Object
 * An object containing the ID of the query
 * JavaScript Object
 * Something went wrong when creating the query
 * }
 * JavaScript Object
 * Something went wrong when creating the query
 * }
 * }

Code example
//Query Registration var spacial_query = {}; system.initialize = function { spacial_query = this.registerQuery("minecraft:position", "x", "y", "z"); };

By default no filters are added. This allows queries to capture all entities.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Query JS API Object
 * The object containing the ID of the query that you want to apply the filter to
 * String
 * This is the identifier of the component that is added to the filter list. Only entities that have that component are listed in the query
 * }
 * String
 * This is the identifier of the component that is added to the filter list. Only entities that have that component are listed in the query
 * }
 * }

Code example
//Query Filtering var filtered_query = {}; system.initialize = function { filtered_query = this.registerQuery; this.addFilterToQuery(filtered_query, "minecraft:explode"); };

Allows you to fetch the entities captured by a query.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Query JS API Object
 * This is the query you registered earlier using
 * }
 * This is the query you registered earlier using
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Array
 * An array of EntityObjects representing the entities found within the query
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * }

Code example
//Entity Fletching system.update = function { let all_entities = this.getEntitiesFromQuery(simple_query); let exploding_creepers = this.getEntitiesFromQuery(filtered_query); };

Allows you to fetch the entities captured by a query that was created with a component filter built-in. The only entities returned are those entities that have the component that was defined when the query was registered and that have a value in the three fields on that component that were defined in the query within the values specified in the call to.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Query JS API Object
 * This is the query you created earlier using
 * Decimal
 * The minimum value that the first component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The minimum value that the second component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The minimum value that the third component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the first component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the second component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the third component field needs to be on an entity for that entity to be included in the query
 * }
 * The minimum value that the third component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the first component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the second component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the third component field needs to be on an entity for that entity to be included in the query
 * }
 * The maximum value that the second component field needs to be on an entity for that entity to be included in the query
 * Decimal
 * The maximum value that the third component field needs to be on an entity for that entity to be included in the query
 * }
 * The maximum value that the third component field needs to be on an entity for that entity to be included in the query
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Array
 * An array of  representing the entities found within the query
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * JavaScript Object
 * Something went wrong when creating the entity
 * }
 * }

Code example
//Entity Fletching system.update = function { let player_pos_component = this.getComponent(player, "minecraft:position"); let pos = player_pos_component.data; let spacial_query = this.registerQuery("minecraft:position", "x", "y", "z"); let entities_near_player = this.getEntitiesFromQuery(spacial_query, pos.x - 10, pos.y - 10, pos.z - 10, pos.x + 10, pos.y + 10, pos.z + 10); };

Slash commands
You can use the traditional Slash Command system from scripts. Currently you can either trigger an event or use the executeCommand binding. Commands in scripts are restricted to server scripts, they can't be run from the client's side at the moment.

Allows you to execute a Slash Command on the server. The command is queried and executed at the end of the current frame. All data output from the command is compiled on a JavaScript Object and sent to the Callback object specified in the second parameter.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * The slash command to run
 * JSON Object
 * The JavaScript object called after the command executes
 * }
 * JSON Object
 * The JavaScript object called after the command executes
 * }
 * }

Code example
system.executeCommand("/fill ~ ~ ~ ~100 ~5 ~50 stone", (commandResultData) => this.commandCallback(commandResultData));

system.commandCallback = function (commandResultData) { let eventData = this.createEventData("minecraft:display_chat_event"); if (eventData) { eventData.data.message = message; this.broadcastEvent("minecraft:display_chat_event", "Callback called! Command: " + commandResultData.command + " Data: " + JSON.stringify(commandResultData.data, null, "   ") ); } };

Block bindings
These functions define how you interact with blocks.

Allows you to get a block from the world when provided an,  , and   position. The block must be within a ticking area.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Ticking Area JS API Object
 * The ticking area the block is in
 * Integer
 * The  position of the block you want
 * Integer
 * The  position of the block you want
 * Integer
 * The  position of the block you want
 * }
 * Integer
 * The  position of the block you want
 * Integer
 * The  position of the block you want
 * }
 * The  position of the block you want
 * }
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Block JS API Object
 * An object containing the block
 * JavaScript Object
 * Something went wrong when retrieving the block
 * }
 * JavaScript Object
 * Something went wrong when retrieving the block
 * }
 * }

Allows you to get a block from the world when provided a JavaScript object containing a position. The block must be within a ticking area.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Ticking Area JS API Object
 * The ticking area the block is in
 * JavaScript Object
 * A JavaScript object with the,  , and   position of the block you want
 * JavaScript Object
 * A JavaScript object with the,  , and   position of the block you want
 * A JavaScript object with the,  , and   position of the block you want
 * A JavaScript object with the,  , and   position of the block you want


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Integer
 * The  position
 * Integer
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * }


 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Block JS API Object
 * An object containing the block
 * JavaScript Object
 * Something went wrong when retrieving the block
 * }
 * JavaScript Object
 * Something went wrong when retrieving the block
 * }
 * }

Allows you to get an array of blocks from the world when provided a minimum and maximum x, y, and z position. The blocks must be within a ticking area.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Ticking Area JS API Object
 * The ticking area the blocks are in
 * Integer
 * The minimum  position of the blocks you want
 * Integer
 * The minimum  position of the blocks you want
 * Integer
 * The minimum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * }
 * The minimum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * }
 * The maximum  position of the blocks you want
 * Integer
 * The maximum  position of the blocks you want
 * }
 * The maximum  position of the blocks you want
 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Array
 * A 3D array of block objects. Indexs are the blocks positions relative to the min position given
 * JavaScript Object
 * Something went wrong when retrieving the blocks
 * }
 * JavaScript Object
 * Something went wrong when retrieving the blocks
 * }
 * }

Allows you to get an array of blocks from the world when provided a minimum and maximum position. The blocks must be within a ticking area.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Ticking Area JS API Object
 * The ticking area the blocks are in
 * JavaScript Object
 * A JavaScript object with the minimum,  , and   position of the blocks you want
 * JavaScript Object
 * A JavaScript object with the minimum,  , and   position of the blocks you want
 * A JavaScript object with the minimum,  , and   position of the blocks you want
 * A JavaScript object with the minimum,  , and   position of the blocks you want

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Integer
 * The  position
 * Integer
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * }


 * JavaScript Object
 * A JavaScript object with the maximum,  , and   position of the blocks you want
 * A JavaScript object with the maximum,  , and   position of the blocks you want
 * A JavaScript object with the maximum,  , and   position of the blocks you want


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Integer
 * The  position
 * Integer
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * Integer
 * The  position
 * }
 * The  position
 * }


 * }

Return value

 * {| class="wikitable"

! Type !! Value !! Description
 * Array
 * A 3D array of block objects. Indexs are the blocks positions relative to the min position given
 * JavaScript Object
 * Something went wrong when retrieving the blocks
 * }
 * JavaScript Object
 * Something went wrong when retrieving the blocks
 * }
 * }

Script components
This is the documentation for the attributes, properties, and components available from the Minecraft Script Engine.

There are two kinds of components: server components and client components. We go into more detail on what they are in their respective sections below.

Components can be added, retrieved, updated, and removed from entities. They do not exist on their own. Currently only user-defined components can be added and removed from entities. A component must be in an entity in order to retrieve or update it.

Check the Script Engine Bindings section to see how to add, remove, retrieve, and update components. This section deals with the specific API of each component.

Level components
These are the components that belong to the level. They can only belong on the level object and cannot be removed from it. You can get the components and change their data through the global server object.

minecraft:ticking_areas
This component gives access to the static ticking areas in the level. The component contains an array of ticking areas. The ticking areas can be accessed by name or by UUID if they were not given a name.

minecraft:weather
The weather component allows users to change the level's weather. Rain and lightning levels can be changed independently and the default weather cycle can be turned off completely.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Boolean
 * This is the world option that determines if the vanilla weather cycle is used
 * Decimal
 * A value between 0 and 1 that determains how heavy the rainfall is
 * Integer
 * How long it rains, in ticks
 * Decimal
 * A value between 0 and 1 that determines how much lightning and thunder there is
 * Integer
 * How long lightning and thunder lasts, in ticks
 * }
 * How long it rains, in ticks
 * Decimal
 * A value between 0 and 1 that determines how much lightning and thunder there is
 * Integer
 * How long lightning and thunder lasts, in ticks
 * }
 * Integer
 * How long lightning and thunder lasts, in ticks
 * }
 * }

Server components
These are the components that run on the server and are synced with all the clients (players) in the world.

As much as possible, the API of each component matches its JSON counterpart (with some differences noted).

minecraft:armor_container
This component represents the armor contents of an entity. The component contains an array of  Objects representing each slot in the armor container. Note: Currently items and containers are read-only. Slots are ordered from head to feet.

// This example checks the players helmet armor slot for a specific item after the player attacks an entity. system.listenForEvent("minecraft:player_attacked_entity", function(eventData) {   // Get the players armor container    let playerArmor = system.getComponent(eventData.data.player, "minecraft:armor_container");    // Get the players helmet    let playerHelmet = playerArmor.data[0];    // Destroy the attacked entity if the player has a gold helmet equipped    if (playerHelmet.item == "minecraft:golden_helmet") {        system.destroyEntity(eventData.data.attacked_entity);    } });

This component controls the Attack Damage attribute from the entity. It allows you to change the current minimum and maximum values. Once the changes are applied, the current attack of the entity is reset to the minimum specified. With the minimum and maximum changed to the values specified. Any buffs or debuffs are left intact.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Range [a, b]
 * Range of the random amount of damage the melee attack deals. A negative value can heal the entity instead of hurting it
 * Range of the random amount of damage the melee attack deals. A negative value can heal the entity instead of hurting it
 * Range of the random amount of damage the melee attack deals. A negative value can heal the entity instead of hurting it
 * Range of the random amount of damage the melee attack deals. A negative value can heal the entity instead of hurting it

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Decimal
 * 0.0
 * The minimum amount of damage the entity can deal
 * Decimal
 * 0.0
 * The maximum amount of damage the entity can deal
 * }
 * }
 * 0.0
 * The maximum amount of damage the entity can deal
 * }
 * }

Controls the collision box of the entity. When changes to the component are applied the entity's collision box is immediately updated to reflect the new dimensions. WARNING: If the change of the collision box dimensions would cause the entity to be inside a block, the entity might become stuck there and start suffocating.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Decimal
 * 1.0
 * Width and Depth of the collision box in blocks. A negative value is assumed to be 0
 * Decimal
 * 1.0
 * Height of the collision box in blocks. A negative value is assumed to be 0
 * }
 * 1.0
 * Height of the collision box in blocks. A negative value is assumed to be 0
 * }
 * }

Defines an array of damages and how the entity reacts to them - including whether the entity ignores that damage or not. Currently Minecraft triggers can't be properly serialized so any existing triggers are completely replaced when


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * List
 * List of triggers with the events to call when taking this specific kind of damage, allows specifying filters for entity definitions and events
 * Boolean
 * true
 * If true, the damage dealt to the entity reduces its health; set to false to make the entity ignore that damage
 * String
 * Type of damage that triggers this set of events
 * }
 * true
 * If true, the damage dealt to the entity reduces its health; set to false to make the entity ignore that damage
 * String
 * Type of damage that triggers this set of events
 * }
 * Type of damage that triggers this set of events
 * }
 * }

// This example causes an entity (in this case, a creeper) to start exploding when the player attacks it. // Note: the entity must have the damage_sensor component and the associated events defined in their JSON description. this.listenForEvent("minecraft:player_attacked_entity", function(eventData) {	let damageSensorComponent = serverSystem.getComponent(eventData.attacked_entity, "minecraft:damage_sensor");	damageSensorComponent.data[0].on_damage = { event:"minecraft:start_exploding", filters:[{test:"has_component", operator:"==", value:"minecraft:breathable"}] };	serverSystem.applyComponentChanges(eventData.attacked_entity, damageSensorComponent); });

Defines the loot table the entity uses to defines its equipment. Once the changes are applied, the equipment is re-rolled and a new set of equipment is chosen for the entity.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * The file path to the equipment table, relative to the behavior pack's root
 * List
 * A list of slots with the chance to drop an equipped item from that slot
 * }
 * List
 * A list of slots with the chance to drop an equipped item from that slot
 * }
 * A list of slots with the chance to drop an equipped item from that slot
 * }
 * }

Defines how many and what items the entity can be equipped with.

List of slots and the item that can be equipped

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Integer
 * 0
 * The slot number of this slot
 * List
 * The list of items that can go in this slot
 * String
 * Identifier of the item that can be equipped for this slot
 * String
 * Text to be displayed when the entity can be equipped with this item when playing with Touch-screen controls
 * String
 * Event to trigger when this entity is equipped with this item
 * String
 * Event to trigger when this item is removed from this entity
 * }
 * Identifier of the item that can be equipped for this slot
 * String
 * Text to be displayed when the entity can be equipped with this item when playing with Touch-screen controls
 * String
 * Event to trigger when this entity is equipped with this item
 * String
 * Event to trigger when this item is removed from this entity
 * }
 * Event to trigger when this entity is equipped with this item
 * String
 * Event to trigger when this item is removed from this entity
 * }
 * String
 * Event to trigger when this item is removed from this entity
 * }
 * Event to trigger when this item is removed from this entity
 * }

Controls the entity's explosion, timer until the explosion, and whether the timer is counting down or not.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Range [a, b]
 * [0.0, 0.0]
 * The range for the random amount of time the fuse burns before exploding, a negative value means the explosion is immediate
 * Decimal
 * 3.0
 * The radius of the explosion in blocks and the amount of damage the explosion deals
 * Decimal
 * Infinite
 * A block's explosion resistance is capped at this value when an explosion occurs
 * Boolean
 * false
 * If true, the fuse is already lit when this component is added to the entity
 * Boolean
 * false
 * If true, blocks in the explosion radius are set on fire
 * Boolean
 * true
 * If true, the explosion destroys blocks in the explosion radius
 * Boolean
 * false
 * If true, whether the explosion causes fire is affected by the mob griefing game rule
 * Boolean
 * false
 * If true, whether the explosion breaks blocks is affected by the mob griefing game rule
 * }
 * Boolean
 * true
 * If true, the explosion destroys blocks in the explosion radius
 * Boolean
 * false
 * If true, whether the explosion causes fire is affected by the mob griefing game rule
 * Boolean
 * false
 * If true, whether the explosion breaks blocks is affected by the mob griefing game rule
 * }
 * Boolean
 * false
 * If true, whether the explosion breaks blocks is affected by the mob griefing game rule
 * }
 * If true, whether the explosion breaks blocks is affected by the mob griefing game rule
 * }

This component represents the contents of an entity's hands. The component contains an array of  Objects representing each slot in the hand container. Note: Currently items and containers are read-only. Slot 0 is main-hand Slot 1 is off-hand.

// This example checks the players offhand slot for a specific item after the player attacks an entity. system.listenForEvent("minecraft:player_attacked_entity", function(eventData) {   // Get the players hand container    let handContainer = system.getComponent(eventData.data.player, "minecraft:hand_container");    // Get the players offhand item    let offhandItem = handContainer.data[1];    // Destroy the attacked entity if the player has a totem in their offhand    if (offhandItem.item == "minecraft:totem") {        system.destroyEntity(eventData.data.attacked_entity);    } });

Defines how the entity can be healed by the player. This doesn't control how much health the entity can have; you must use the Health component for that instead.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Array
 * The array of items that can be used to heal this entity
 * The array of items that can be used to heal this entity
 * The array of items that can be used to heal this entity
 * The array of items that can be used to heal this entity

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * Item identifier that can be used to heal this entity
 * Integer
 * 1
 * The amount of health this entity gains when fed this item
 * Minecraft Filter
 * The filter group that defines the conditions for using this item to heal the entity
 * }
 * Boolean
 * Determines if item can be used regardless of entity being at full health
 * Minecraft Filter
 * The filter group that defines the conditions for this trigger
 * }
 * The filter group that defines the conditions for using this item to heal the entity
 * }
 * Boolean
 * Determines if item can be used regardless of entity being at full health
 * Minecraft Filter
 * The filter group that defines the conditions for this trigger
 * }
 * Determines if item can be used regardless of entity being at full health
 * Minecraft Filter
 * The filter group that defines the conditions for this trigger
 * }
 * The filter group that defines the conditions for this trigger
 * }
 * }

Defines the current and maximum possible health of the entity. Upon applying the component back to the entity, the health changes if it reaches 0 or below the entity dies.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Integer
 * 1
 * Current health of the entity
 * Integer
 * 10
 * The maximum health the entity can heal
 * }
 * 10
 * The maximum health the entity can heal
 * }
 * }

This component represents the hotbar contents of a player. The component contains an array of  Objects representing each slot in the hotbar. Note: Currently items and containers are read-only. Slots are ordered left to right.

// This example check sthe players first hotbar item slot for a specific item after the player attacks an entity. system.listenForEvent("minecraft:player_attacked_entity", function(eventData) {   // Get the players hotbar    let playerHotbar = system.getComponent(eventData.data.player, "minecraft:hotbar_container");    // Get the item at the first slot in the hotbar    let firstHotbarSlot = playerHotbar.data[0];    // Destroy the attacked entity if the player has an apple in their first hotbar slot    if (firstHotbarSlot.item == "minecraft:apple") {        system.destroyEntity(eventData.data.attacked_entity);    } });

Defines the ways the player can interact with the entity to which this component is applied.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Array
 * An array of entity identifiers to spawn when the interaction occurs
 * String
 * An event identifier to fire when the interaction occurs
 * JSON Object
 * Particle effect to be triggered at the start of the interaction
 * String
 * An event identifier to fire when the interaction occurs
 * JSON Object
 * Particle effect to be triggered at the start of the interaction
 * JSON Object
 * Particle effect to be triggered at the start of the interaction
 * Particle effect to be triggered at the start of the interaction
 * Particle effect to be triggered at the start of the interaction
 * Particle effect to be triggered at the start of the interaction

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * The type of particle to be spawned
 * Decimal
 * 0.0
 * Offsets the particle this amount in the y direction
 * Boolean
 * false
 * Whether or not the particle appears closer to who performed the interaction
 * }
 * Decimal
 * 0.0
 * Time in seconds before this entity can be interacted with again
 * Boolean
 * false
 * If true, the player does the 'swing' animation when interacting with this entity
 * Boolean
 * false
 * If true, the interaction uses an item
 * Integer
 * 0
 * The amount of damage the item takes when used to interact with this entity. A value of 0 means the item does not lose durability
 * String
 * Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
 * JSON Object
 * Loot table with items to add to the player's inventory upon successful interaction
 * If true, the player does the 'swing' animation when interacting with this entity
 * Boolean
 * false
 * If true, the interaction uses an item
 * Integer
 * 0
 * The amount of damage the item takes when used to interact with this entity. A value of 0 means the item does not lose durability
 * String
 * Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
 * JSON Object
 * Loot table with items to add to the player's inventory upon successful interaction
 * String
 * Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
 * JSON Object
 * Loot table with items to add to the player's inventory upon successful interaction
 * Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
 * JSON Object
 * Loot table with items to add to the player's inventory upon successful interaction
 * Loot table with items to add to the player's inventory upon successful interaction
 * Loot table with items to add to the player's inventory upon successful interaction
 * Loot table with items to add to the player's inventory upon successful interaction

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * File path, relative to the behavior pack's path, to the loot table file
 * }
 * JSON Object
 * Loot table with items to drop on the ground upon successful interaction
 * }
 * JSON Object
 * Loot table with items to drop on the ground upon successful interaction
 * Loot table with items to drop on the ground upon successful interaction
 * Loot table with items to drop on the ground upon successful interaction
 * Loot table with items to drop on the ground upon successful interaction

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * File path, relative to the behavior pack's path, to the loot table file
 * }
 * String
 * The item used transforms to this item upon successful interaction. Format:
 * Array
 * An array of sound identifiers to play when the interaction occurs
 * }
 * The item used transforms to this item upon successful interaction. Format:
 * Array
 * An array of sound identifiers to play when the interaction occurs
 * }
 * Array
 * An array of sound identifiers to play when the interaction occurs
 * }
 * An array of sound identifiers to play when the interaction occurs
 * }

Defines the entity's inventory (size, restrictions, etc.). Currently this does not allow changing the entity's inventory contents.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * none
 * Type of container this entity has. Can be,  ,  ,  ,   or
 * Integer
 * 5
 * Number of slots the container has
 * Boolean
 * false
 * If true, the contents of this inventory can be removed by a hopper
 * Boolean
 * false
 * If true, only the entity can access the inventory
 * Boolean
 * false
 * If true, the entity's inventory can only be accessed by its owner or itself
 * Integer
 * 0
 * Number of slots that this entity can gain per extra strength
 * }
 * If true, only the entity can access the inventory
 * Boolean
 * false
 * If true, the entity's inventory can only be accessed by its owner or itself
 * Integer
 * 0
 * Number of slots that this entity can gain per extra strength
 * }
 * 0
 * Number of slots that this entity can gain per extra strength
 * }
 * }

This component represents the inventory contents of an entity. The component contains an array of  Objects representing each slot in the inventory. Note: Currently items and containers are read-only.Slot 0-8 is the hotbar, 9-17 is the top row of the player's inventory, 18-26 is the middle row, 27-35 is the bottom row.

// This example checks the players third inventory item slot for a specific item after the player attacks an entity. system.listenForEvent("minecraft:player_attacked_entity", function(eventData) {   // Get the players inventory    let playerInventory = system.getComponent(eventData.data.player, "minecraft:inventory_container");    // Get the item at the third slot in the inventory    let thirdItemSlot = playerInventory.data[2];    // Destroy the attacked entity if the player has an apple in their third item slot    if (thirdItemSlot.item == "minecraft:apple") {        system.destroyEntity(eventData.data.attacked_entity);    } });

Makes the entity look at another entity. Once applied, if an entity of the specified type is nearby and can be targeted the entity turns toward it.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Boolean
 * true
 * If true, this entity sets the attack target as the entity that looked at it
 * Decimal
 * 10.0
 * Maximum distance this entity can look for another entity looking at it
 * Boolean
 * false
 * If true, invulnerable entities (e.g. Players in creative mode) are considered valid targets
 * Range [a, b]
 * [0.0, 0.0]
 * The range for the random amount of time during which the entity is 'cooling down' and won't get angered or look for a target
 * Minecraft Filter
 * player
 * Defines the entities that can trigger this component
 * String
 * The event identifier to run when the entities specified in filters look at this entity
 * }
 * [0.0, 0.0]
 * The range for the random amount of time during which the entity is 'cooling down' and won't get angered or look for a target
 * Minecraft Filter
 * player
 * Defines the entities that can trigger this component
 * String
 * The event identifier to run when the entities specified in filters look at this entity
 * }
 * String
 * The event identifier to run when the entities specified in filters look at this entity
 * }
 * The event identifier to run when the entities specified in filters look at this entity
 * }

Nameable component describes an entity's ability to be named using a nametag and whether the name shows up or not once applied. Additionally, scripting allows setting the name of the entity directly with the property 'name'.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * JSON Object
 * Describes the special names for this entity and the events to call when the entity acquires those names
 * Describes the special names for this entity and the events to call when the entity acquires those names
 * Describes the special names for this entity and the events to call when the entity acquires those names
 * Describes the special names for this entity and the events to call when the entity acquires those names

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * Event to be called when this entity acquires the name specified in
 * List
 * List of special names that cause the events defined in  to fire
 * }
 * String
 * Trigger to run when the entity gets named
 * Boolean
 * false
 * If true, the name is always shown
 * Boolean
 * true
 * If true, this entity can be renamed with name tags
 * String
 * The current name of the entity, empty if the entity hasn't been named yet, making this non-empty applies the name to the entity
 * }
 * Boolean
 * false
 * If true, the name is always shown
 * Boolean
 * true
 * If true, this entity can be renamed with name tags
 * String
 * The current name of the entity, empty if the entity hasn't been named yet, making this non-empty applies the name to the entity
 * }
 * If true, this entity can be renamed with name tags
 * String
 * The current name of the entity, empty if the entity hasn't been named yet, making this non-empty applies the name to the entity
 * }
 * The current name of the entity, empty if the entity hasn't been named yet, making this non-empty applies the name to the entity
 * }
 * }

This component allows you to control an entity's current position in the world. Once applied, the entity is teleported to the new position specified.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Decimal
 * 0.0
 * Position along the X-Axis (east-west) of the entity
 * Decimal
 * 0.0
 * Position along the Y-Axis (height) of the entity
 * Decimal
 * 0.0
 * Position along the Z-Axis (north-south) of the entity
 * }
 * Decimal
 * 0.0
 * Position along the Z-Axis (north-south) of the entity
 * }
 * Position along the Z-Axis (north-south) of the entity
 * }

This component allows you to control an entity's current rotation in the world as well as the entity's head rotation. Once applied, the entity is rotated as specified.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Decimal
 * 0.0
 * Controls the head rotation looking up and down
 * Decimal
 * 0.0
 * Controls the body rotation parallel to the floor
 * }
 * 0.0
 * Controls the body rotation parallel to the floor
 * }
 * }

Defines the entity's ranged attacks. This doesn't allow the entity to use a ranged attack: it only defines what kind of projectile it shoots.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * Entity identifier to use as projectile for the ranged attack. The entity must have the projectile component to be able to be shot as a projectile
 * Integer
 * -1
 * ID of the Potion effect to be applied on hit
 * }
 * Integer
 * -1
 * ID of the Potion effect to be applied on hit
 * }
 * }

Controls the entity's ability to spawn an entity or an item. This is similar to the chicken's ability to lay eggs after a set amount of time.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Boolean
 * If true, this the spawned entity is leashed to the parent
 * Integer
 * The number of entities of this type to spawn each time that this triggers
 * Integer
 * Minimum amount of time to randomly wait in seconds before another entity is spawned
 * Integer
 * Maximum amount of time to randomly wait in seconds before another entity is spawned
 * String
 * Identifier of the sound effect to play when the entity is spawned
 * String
 * Item identifier of the item to spawn
 * String
 * Identifier of the entity to spawn, leave empty to spawn the item defined above instead
 * String
 * Method to use to spawn the entity
 * String
 * Event to call when the entity is spawned
 * Minecraft Filter
 * If present, the specified entity spawns only if the filter evaluates to true
 * Boolean
 * If true, this component spawns the specified entity only once
 * }
 * Identifier of the sound effect to play when the entity is spawned
 * String
 * Item identifier of the item to spawn
 * String
 * Identifier of the entity to spawn, leave empty to spawn the item defined above instead
 * String
 * Method to use to spawn the entity
 * String
 * Event to call when the entity is spawned
 * Minecraft Filter
 * If present, the specified entity spawns only if the filter evaluates to true
 * Boolean
 * If true, this component spawns the specified entity only once
 * }
 * Method to use to spawn the entity
 * String
 * Event to call when the entity is spawned
 * Minecraft Filter
 * If present, the specified entity spawns only if the filter evaluates to true
 * Boolean
 * If true, this component spawns the specified entity only once
 * }
 * Minecraft Filter
 * If present, the specified entity spawns only if the filter evaluates to true
 * Boolean
 * If true, this component spawns the specified entity only once
 * }
 * Boolean
 * If true, this component spawns the specified entity only once
 * }
 * If true, this component spawns the specified entity only once
 * }
 * }

This controls the entity's ability to teleport itself (similar to the Enderman). If you wish to teleport the entity once use the Position component instead.

Parameters

 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Boolean
 * If true, the entity teleports randomly
 * Decimal
 * Minimum amount of time in seconds between random teleports
 * Decimal
 * Maximum amount of time in seconds between random teleports
 * Vector [a, b, c]
 * Entity teleports to a random position within the area defined by this cube
 * Decimal
 * Maximum distance the entity can teleport when chasing a target
 * Decimal
 * The chance (0.0 to 1.0, where 1.0=100%) that the entity can teleport
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in daylight
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in darkness
 * }
 * Entity teleports to a random position within the area defined by this cube
 * Decimal
 * Maximum distance the entity can teleport when chasing a target
 * Decimal
 * The chance (0.0 to 1.0, where 1.0=100%) that the entity can teleport
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in daylight
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in darkness
 * }
 * The chance (0.0 to 1.0, where 1.0=100%) that the entity can teleport
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in daylight
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in darkness
 * }
 * Modifies the chance that the entity can teleport if the entity is in daylight
 * Decimal
 * Modifies the chance that the entity can teleport if the entity is in darkness
 * }
 * Modifies the chance that the entity can teleport if the entity is in darkness
 * }
 * Modifies the chance that the entity can teleport if the entity is in darkness
 * }

The tick world component is a read-only component that allows users to access the ticking areas on entities as well as the ticking area's data.

Parameters

 * {| class="wikitable"

! Type !! Name !! Description
 * Integer
 * The radius in chunks of the ticking area
 * Decimal
 * distance_to_players
 * Boolean
 * Whether or not this ticking area despawns when a player is out of range
 * Entity Ticking Area JS API Object
 * The ticking area entity that is attached to this entity
 * }
 * Boolean
 * Whether or not this ticking area despawns when a player is out of range
 * Entity Ticking Area JS API Object
 * The ticking area entity that is attached to this entity
 * }
 * The ticking area entity that is attached to this entity
 * }
 * }

Client components
These components only run on the client where the script ran and can only be used from client scripts.

The MoLang component gives access to the MoLang variables in an entity. To learn more about MoLang varibles review the add-on documentation. In scripts, you can get and set these varibles that are defined in the entity's JSON files. Because of how the MoLang variables are formatted ( for example) you must use the [] operator on the object to access the variable. The example below shows how to use the [] operator to access the variable.

Code example


let molangComponent = this.createComponent(entity, "minecraft:molang"); molangComponent["variable.molangexample"] = 1.0; this.applyComponentChanges(molangComponent);

Block components
These components are only found on block objects and can only be on block objects

This component contains all the blockstates on a block object. Blockstates control all different aspects of blocks from their orientation to the type of wood they are. Blockstates are represented by numbers, bools, or strings. Please see the Blockstates Documentation to see the valid values for each state. This component allows for the getting and setting of these states.

Code example


let blockstateComponent = this.getComponent(block, "minecraft:blockstate"); blockstateComponent.data.coral_color = "blue"; this.applyComponentChanges(block, blockstateComponent);

User-Defined Components
User-Defined components are a special kind of component that can be defined in script and no built-in game system acts on it. The component needs to be registered with the Script Engine by giving it a name and a set of fields in the format name:value. Once applied, the component behaves like any of the built-in components: you can get it from an entity, modify its values, and apply the changes. Currently, user-Defined components are the only components that can be dynamically added and removed from an entity using scripts. They don't need to be previously defined in an entity's JSON file. In the current version, these components are not saved out or loaded back in: they exist only while the entity is there and need to be added back when reloading the level.

Code example
//Component Registration this.registerComponent("myNamespace:myComponent", { myString: "TamerJeison", myInt: 42, myFloat: 1.0, myArray: [1, 2, 3] });

Script events
Here you can find the list of events that you can listen for and respond to in your scripts.

Listening events
The following Minecraft events are events the Script Engine is listening for and to which you can react in scripts.

minecraft:client_entered_world
This event is fired whenever a player joins the world. The event data contains the player entity object.


 * Parameters

minecraft:hit_result_changed
This event is triggered whenever the reticle changes from pointing at a block or air to pointing at an entity and the other way around. Up to 1000 blocks away.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was hit or null if it fired when moving off of an entity
 * Vector [a, b, c]
 * position
 * The position of the entity that was hit or null if it fired when moving off an entity
 * }
 * The position of the entity that was hit or null if it fired when moving off an entity
 * }


 * Code example:

system.initialize = function { this.listenForEvent("minecraft:hit_result_changed", (eventData) => this.onPick(eventData)); };

system.onPick = function(eventData) { if (eventData.position !== null) { this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); } };

minecraft:hit_result_continuous
This event is triggered every update and tells you what entity the reticle is pointing to in the world up to 1000 blocks away.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was hit or null if it not pointing at an entity
 * Vector [a, b, c]
 * position
 * The position of the entity that was hit or block that was hit
 * }
 * The position of the entity that was hit or block that was hit
 * }


 * Code example:

system.initialize = function { this.listenForEvent("minecraft:hit_result_continuous", (eventData) => this.onPick(eventData)); };

system.onPick = function(eventData) { if (eventData.position !== null) { this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); } };

minecraft:pick_hit_result_changed
This event is triggered whenever the mouse pointer changes from pointing at a block or air to pointing at an entity and the other way around. Up to 1000 blocks away.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was hit or null if it fired when moving off of an entity
 * Vector [a, b, c]
 * position
 * The position of the entity that was hit or null if it fired when moving off an entity
 * }
 * The position of the entity that was hit or null if it fired when moving off an entity
 * }


 * Code example:

system.initialize = function { this.listenForEvent("minecraft:pick_hit_result_changed", (eventData) => this.onPick(eventData)); };

system.onPick = function(eventData) { if (eventData.position !== null) { this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); } };

minecraft:pick_hit_result_continuous
This event is triggered every update and tells you what entity the mouse pointer is pointing to in the world up to 1000 blocks away.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was hit or null if it not pointing at an entity
 * Vector [a, b, c]
 * position
 * The position of the entity that was hit or block that was hit
 * }
 * The position of the entity that was hit or block that was hit
 * }


 * Code example:

system.initialize = function { this.listenForEvent("minecraft:pick_hit_result_continuous", (eventData) => this.onPick(eventData)); };

system.onPick = function(eventData) { if (eventData.position !== null) { this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); } };

Triggerable events
The following Minecraft Events can be triggered from scripting and cause the game to respond accordingly.

minecraft:display_chat_event
This event is used to display a chat message to the specific player that is running the client script. The event data is the message to be displayed in plain text. Special formatting is supported the same way it would be if a player was sending the message.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * message
 * The chat message to be displayed
 * }
 * The chat message to be displayed
 * }

minecraft:load_ui


This event is used to show a UI screen to the specific player running the client script. This event adds the UI screen to the top of the UI screen stack. The screen is shown immediately after the event is triggered. Only screens defined in a HTML file can be shown using this event.


 * Event Data Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description always_accepts_input
 * String
 * path
 * The file path to the screen's HTML file
 * JSON Object
 * options
 * You can define the following options for the screen by setting their value to true or false:
 * JSON Object
 * options
 * You can define the following options for the screen by setting their value to true or false:
 * You can define the following options for the screen by setting their value to true or false:

If true, the screen always accepts and processes input for as long as it is in the stack, even if other custom UI screens appear on top of it

render_game_behind

If true, the game continues to be rendered underneath this screen

absorbs_input

If true, input does pass down to any other screens underneath

is_showing_menu

If true, the screen is treated as the pause menu and the pause menu won't be allowed to show on top of this screen

should_steal_mouse

If true, the screen captures the mouse pointer and limits its movement to the UI screen

force_render_below

If true, this screen is rendered even if another screen is on top of it and renders over them, including the HUD

render_only_when_topmost

If true, this screen is rendered only if it is the screen at the top of the stack
 * }

minecraft:send_ui_event
This event is used to send UI events to the UI Engine for the specific player running the script. After the event is triggered, the UI event is sent immediately. Custom UI is based on HTML 5. Review the scripting demo for an example of a custom UI file.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * eventIdentifier
 * The identifier of the UI event
 * String
 * data
 * The data for the UI event being triggered
 * }
 * The data for the UI event being triggered
 * }

minecraft:spawn_particle_attached_entity
This event is used to create a particle effect that follows an entity around. This particle effect is only visible to the specific player that is running the client script where you fired the event. Any effect defined in a JSON file (both in your resource pack and in Minecraft) can be used here. MoLang variables defined in the JSON of the effect can then be used to control that effect by changing them in the entity to which it is attached.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * effect
 * The identifier of the particle effect you want to attach to the entity. This is the same name you gave the effect in its JSON file
 * Vector [a, b, c]
 * offset
 * [0, 0, 0]
 * The offset from the entity's "center" where you want to spawn the effect
 * Entity JS API Object
 * entity
 * The entity object you want to attach the effect to
 * }
 * Entity JS API Object
 * entity
 * The entity object you want to attach the effect to
 * }
 * }

minecraft:spawn_particle_in_world
This event is used to create a static particle effect in the world. This particle effect is only visible to the specific player that is running the client script where you fired the event. Any effect defined in a JSON file (both in your resource pack and in Minecraft) can be used here. Once the effect is spawned you won't be able to control it further. Unlike the server version of the event, the client version spawns the particle in the dimension the player is currently in.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * effect
 * The identifier of the particle effect you want to attach to spawn. This is the same name you gave the effect in its JSON file
 * Vector [a, b, c]
 * position
 * [0, 0, 0]
 * The position in the world where you want to spawn the effect
 * }
 * [0, 0, 0]
 * The position in the world where you want to spawn the effect
 * }

minecraft:unload_ui
This event is used to remove a UI screen from the stack of the specific player running the client script. The event data contains the name of the screen to remove as a string. After the event is triggered, the screen is scheduled to be removed from the stack the next time the UI Engine can do so. Only screens defined in a HTML file can be removed using this event.

minecraft:script_logger_config
This event is used to turn various levels of logging on and off for client scripts. Note that turning logging on/off is not limited to the script that broadcasted the event. It affects all client scripts including those in other Behavior Packs that are applied to the world. See the Debugging section for more information on logging.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Boolean
 * log_errors
 * false
 * Set to true to log any scripting errors that occur on the client
 * Boolean
 * log_warnings
 * false
 * Set to true to log any scripting warnings that occur on the client
 * Boolean
 * log_information
 * false
 * Set to true to log any general scripting information that occurs on the client. This includes any logging done with client.log
 * }
 * false
 * Set to true to log any general scripting information that occurs on the client. This includes any logging done with client.log
 * }

Listening events
The following Minecraft events are events the Script Engine is listening for and to which you can react in scripts.

minecraft:player_attacked_entity
This event is triggered whenever a player attacks an entity.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * player
 * The player that attacked an entity
 * Entity JS API Object
 * attacked_entity
 * The entity that was attacked by the player
 * }
 * The entity that was attacked by the player
 * }

minecraft:entity_acquired_item
This event is triggered whenever an entity acquires an item.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity who acquired the item
 * ItemStack JS API Object
 * item_stack
 * The item that was acquired
 * String
 * acquisition_method
 * The way the entity acquired the item
 * Integer
 * acquired_amount
 * The total number of items acquired by the entity during this event
 * Entity JS API Object
 * secondary_entity
 * If it exists, the entity that affected the item before it was acquired. Example: A player completes a trade with a villager. The `entity` property would be the player and the `secondary_entity` would be the villager
 * }
 * Entity JS API Object
 * secondary_entity
 * If it exists, the entity that affected the item before it was acquired. Example: A player completes a trade with a villager. The `entity` property would be the player and the `secondary_entity` would be the villager
 * }
 * }

minecraft:entity_carried_item_changed
This event is triggered whenever an entity changes the item carried in their hand.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that changed what they were carrying
 * ItemStack JS API Object
 * previous_carried_item
 * The item that was previously in the entities hands
 * ItemStack JS API Object
 * carried_item
 * The item that is now in the entities hands
 * }
 * carried_item
 * The item that is now in the entities hands
 * }

minecraft:entity_created
This event is triggered whenever an entity is added to the world.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was just created
 * }
 * }

minecraft:entity_death
This event is triggered whenever an entity dies. This won't be triggered when an entity is removed (such as when using destroyEntity).


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that died
 * }
 * }

minecraft:entity_dropped_item
This event is triggered whenever an entity drops an item.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity who dropped the item
 * ItemStack JS API Object
 * item_stack
 * The item that was dropped
 * }
 * The item that was dropped
 * }

minecraft:entity_equipped_armor
This event is triggered whenever an entity equips an item in their armor slots.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity who is equipping the armor
 * ItemStack JS API Object
 * item_stack
 * The armor that is being equipped
 * }
 * The armor that is being equipped
 * }

minecraft:entity_start_riding
This event is triggered whenever an entity becomes a rider on another entity.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The rider
 * Entity JS API Object
 * ride
 * The entity being ridden
 * }
 * The entity being ridden
 * }

minecraft:entity_stop_riding
This event is triggered whenever an entity stops riding another entity.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was riding another entity
 * Boolean
 * exit_from_rider
 * If true, the rider stopped riding by their own decision
 * Boolean
 * entity_is_being_destroyed
 * If true, the rider stopped riding because they are now dead
 * Boolean
 * switching_rides
 * If true, the rider stopped riding because they are now riding a different entity
 * }
 * Boolean
 * switching_rides
 * If true, the rider stopped riding because they are now riding a different entity
 * }

minecraft:entity_tick
This event is triggered whenever an entity is ticked. This event does not fire when a player is ticked.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity that was ticked
 * }
 * }

minecraft:entity_use_item
This event is triggered whenever an entity uses an item.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * entity
 * The entity who is using the item
 * ItemStack JS API Object
 * item_stack
 * The item that is being used
 * String
 * use_method
 * The way the entity used the item
 * }
 * use_method
 * The way the entity used the item
 * }

minecraft:block_destruction_started
This event is triggered whenever a player starts to destroy a block.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * player
 * The player that started destoying the block
 * JavaScript Object
 * block_position
 * The position of the block that is being destroyed
 * }
 * The position of the block that is being destroyed
 * }

minecraft:block_destruction_stopped
This event is triggered whenever a player stops destroying a block.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * player
 * The player that stopped destoying the block
 * JavaScript Object
 * block_position
 * The position of the block that was being destroyed
 * Decimal
 * destruction_progress
 * How far along the destruction was before it was stopped (0 - 1 range)
 * }
 * destruction_progress
 * How far along the destruction was before it was stopped (0 - 1 range)
 * }

minecraft:block_interacted_with
This event is triggered whenever a player interacts with a block.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * player
 * The player that interacted with the block
 * JavaScript Object
 * block_position
 * The position of the block that is being interacted with
 * }
 * The position of the block that is being interacted with
 * }

minecraft:piston_moved_block
This event is triggered whenever a piston moves a block.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * JavaScript Object
 * piston_position
 * The position of the piston that moved the block
 * JavaScript Object
 * block_position
 * The position of the block that was moved
 * String
 * piston_action
 * The action the piston took, "extended" or "retracted"
 * }
 * piston_action
 * The action the piston took, "extended" or "retracted"
 * }

minecraft:player_destroyed_block
This event is triggered whenever a player destroys a block.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * player
 * The player that destroyed the block
 * JavaScript Object
 * block_position
 * The position of the block that was destroyed
 * String
 * block_identifier
 * The identifier of the block that was destroyed
 * }
 * block_identifier
 * The identifier of the block that was destroyed
 * }

minecraft:player_placed_block
This event is triggered whenever a player places a block.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * Entity JS API Object
 * player
 * The player that placed the block
 * JavaScript Object
 * block_position
 * The position of the block that was placed
 * }
 * The position of the block that was placed
 * }

minecraft:play_sound
This event is used to play a sound effect. Currently, sounds can only be played at a fixed position in the world. Global sounds and sounds played by an entity may be supported in a later update.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * sound
 * The identifier of the sound you want to play. Only sounds defined in the applied resource packs can be played
 * Decimal
 * volume
 * 1.0
 * The volume of the sound effect. A value of 1.0 plays the sound effect at the volume it was recorded at
 * Decimal
 * pitch
 * 1.0
 * The pitch of the sound effect. A value of 1.0 plays the sound effect with regular pitch
 * Vector [a, b, c]
 * position
 * [0, 0, 0]
 * The position in the world we want to play the sound at
 * }
 * Vector [a, b, c]
 * position
 * [0, 0, 0]
 * The position in the world we want to play the sound at
 * }

minecraft:weather_changed
This event is triggered whenever the weather changes. It contains information about the weather it is changing to.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Description
 * String
 * dimension
 * The name of the dimension where the weather change happened
 * Boolean
 * raining
 * Tells if the new weather has rain
 * Boolean
 * lightning
 * Tells if the new weather has lightning
 * }
 * lightning
 * Tells if the new weather has lightning
 * }

Triggerable events
The following Minecraft events can be triggered from scripting and the game responds accordingly.

minecraft:display_chat_event
This event is used to send a chat message from the server to the players. The event data is the message being sent as a string. Special formatting is supported the same way it would be if a player was sending the message.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * message
 * The chat message to be displayed
 * }
 * The chat message to be displayed
 * }

minecraft:execute_command
This event is used to execute a slash command on the server with the World Owner permission level. The event data contains the slash command as a string. The slash command is processed and runs after the event is sent.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * command
 * The command to be run
 * }
 * The command to be run
 * }

minecraft:play_sound
This event is used to play a sound effect. Currently, sounds can only be played at a fixed position in the world. Global sounds and sounds played by an entity may be supported in a later update.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * sound
 * The identifier of the sound you want to play. Only sounds defined in the applied resource packs can be played
 * Decimal
 * volume
 * 1.0
 * The volume of the sound effect. A value of 1.0 plays the sound effect at the volume it was recorded at
 * Decimal
 * pitch
 * 1.0
 * The pitch of the sound effect. A value of 1.0 plays the sound effect with regular pitch
 * Vector [a, b, c]
 * position
 * [0, 0, 0]
 * The position in the world we want to play the sound at
 * }
 * Vector [a, b, c]
 * position
 * [0, 0, 0]
 * The position in the world we want to play the sound at
 * }

minecraft:spawn_particle_attached_entity
This event is used to create a particle effect that follows an entity around. This particle effect is visible to all players. Any effect defined in a JSON file (both in your resource pack and in Minecraft) can be used here. MoLang variables defined in the JSON of the effect can then be used to control that effect by changing them in the entity to which it is attached.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * effect
 * The identifier of the particle effect you want to attach to the entity. This is the same identifier you gave the effect in its JSON file
 * Vector [a, b, c]
 * offset
 * [0, 0, 0]
 * The offset from the entity's "center" where you want to spawn the effect
 * Entity JS API Object
 * entity
 * The entity object you want to attach the effect to
 * }
 * Entity JS API Object
 * entity
 * The entity object you want to attach the effect to
 * }
 * }

minecraft:spawn_particle_in_world
This event is used to create a static particle effect in the world. This particle effect is visible to all players. Any effect defined in a JSON file (both in your resource pack and in Minecraft) can be used here. Once the effect is spawned you won't be able to control it further.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * String
 * effect
 * The identifier of the particle effect you want to attach to spawn. This is the same name you gave the effect in its JSON file
 * Vector [a, b, c]
 * position
 * [0, 0, 0]
 * The position in the world where you want to spawn the effect
 * String
 * dimension
 * overworld
 * The dimension in which you want to spawn the effect. Can be "overworld", "nether", or "the end"
 * }
 * dimension
 * overworld
 * The dimension in which you want to spawn the effect. Can be "overworld", "nether", or "the end"
 * }

minecraft:script_logger_config
This event is used to turn various levels of logging on and off for server scripts. Note that turning logging on/off is not limited to the script that broadcasted the event. It affects all server scripts including those in other Behavior Packs that are applied to the world. See the Debugging section for more information on logging.


 * Parameters


 * {| class="wikitable"

! Type !! Name !! Default Value !! Description
 * Boolean
 * log_errors
 * false
 * Set to true to log any scripting errors that occur on the server
 * Boolean
 * log_warnings
 * false
 * Set to true to log any scripting warnings that occur on the server
 * Boolean
 * log_information
 * false
 * Set to true to log any general scripting information that occurs on the server. This includes any logging done with server.log
 * }
 * false
 * Set to true to log any general scripting information that occurs on the server. This includes any logging done with server.log
 * }