Bedrock Beta Script Documentation

From Minecraft Wiki
Jump to: navigation, search
Mclogo.svg

Version: 1.9.0.3[edit]

This is documentation for a beta release of Minecraft. New features, components, and capabilities in this release are not final and might change without notice before the final release. Be sure to check the documentation once the release is out of beta if your add-on isn't working properly. Resource and Behavior Packs created for the beta are not guaranteed to work on the final release.

Scripting System[edit]

The Minecraft Script Engine uses the JavaScript language.
You 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[edit]

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 .mcpack to play with them

Demo Last Updated Download Link
Mob Arena 12/5/2018 https://aka.ms/minecraftscripting_mobarena
Turn-Based RPG 12/5/2018 https://aka.ms/minecraftscripting_turnbased


Known Issues[edit]

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

Issue Workaround
Custom UI doesn't retain state upon suspend and resume Currently there's no workaround for this issue
Custom UI doesn't work in VR or MR mode Currently you will only be able to use custom UI when running the game in regular mode
Custom UI draws on top of the chat screen and chat pop-ups If you are using custom UI we recommend using Visual Studio to debug your scripts. Script errors are printed out to the chat but they won't be visible if you have a custom UI due to this bug
Custom UI prevents menus (such as the pause menu) from displaying You need to close and re-open Minecraft to exit out of a world that uses custom UI
Custom UI resets after the application is suspended 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
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 .mcpack extension, it will unzip it for you
Pressing the Leave button at the end of the demo will display some errors The errors are from running the /fill command to replace a block with a block that's already there and can be safely ignored
There might be an extra Ocelot at the beginning of the game This is due to the built-in behavior of Ocelot to spawn with a litter but is otherwise a harmless issue


Pre-Requisites[edit]

So you want to make your own Scripts? That's awesome! In this section you will find the list of minimum and recommended software you will need.

NOTE: Scripts are only supported on Windows 10 PCs at the moment. If you try to open a world with scripts on a device that doesn't support scripts, you will see an error message letting you know you can't enter the world.

Software Minimum Recommended
Code Editor Visual Studio Code or any plain-text editor Visual Studio Community 2017 with the following components installed: 'JavaScript diagnostics', 'JavaScript and TypeScript language support', 'Just-In-Time debugger'
Debugger N/A Visual Studio Community 2017
Minecraft Minecraft on your Windows 10 device Minecraft on your Windows 10 device
Other Vanilla Behavior Pack available from https://aka.ms/MinecraftBetaBehaviors Vanilla Behavior Pack available from https://aka.ms/MinecraftBetaBehaviors
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[edit]

First you will need to download the latest Vanilla Behavior Pack. You can get this from the following link: https://aka.ms/MinecraftBetaBehaviors
Once you have downloaded the Behavior Pack, unzip it to a folder. Inside the Behavior Pack you will find the scripts folder which contains all the scripting files you want to run.
In the scripts folder you will find 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 on 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 .js 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 will all be run independently of each other!

NOTE: For scripts to be run by the game, you need to enable Experimental Gameplay on the world where you will run scripts on. This will be necessary while scripting is still in beta.
When entering a world that has client scripts in it, you will be prompted to accept that you wish to run scripts on your device (this will show up both for local worlds as well as multiplayer worlds).

Folder Structure
vanilla_behavior_pack
|-scripts
|--client
|---myClientScript.js
|--server
|---myServerScript.js
|-manifest.json
|-pack_icon.png


Structure of a Script[edit]

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 will choose based on whether you put the script file in the client or server folders. To do that simply call registerSystem on either the client or server and give it the version of the API you require.

Parameters
Type Name Description
Integer majorVersion This is the major version of the Minecraft Script Engine your script was designed to work with
Integer minorVersion This is the revision of the Minecraft Script Engine your script was designed to work with
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 will run 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 will run BEFORE the world is ready and the player has been added to it, so you shouldn't try to spawn any entities here!

Code Example
sampleSystem.initialize = function() {
	//Initialize all the things
};


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 all the things
};



Debugging[edit]

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 will describe below. You only need the game and your script to debug in-game, but you will 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 will print 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 will get an error.
To look at these messages you can open the chat screen which will have 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:

%LOCALAPPDATA%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\logs

We strongly encourage you to build further debug messages and tools into your scripts while working on them. This will 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 will have installed and enabled the Just-In-Time Debugger. This tool will pop-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 will set up the Visual Studio interface with the most important tools you will 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 will be 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 will say Script and either x86 or x64.

Select the process and click on Attach to attach the debugger to the game. Now you will be able to 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 Bindings[edit]

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

Entity Bindings[edit]

createEntity()

Creates an empty entity with no components and does not place it in the world.

Return Value
Type Value Description
JavaScript Object object An EntityObject representing the newly created entity
Parameters
Type Name Description
String __identifier__ READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is entity and the object is representing a vanilla cow, the identifier would be minecraft:cow
String __type__ READ ONLY. This defines the type of object we are using. Can be: entity, item_entity, level, component, query
Integer id READ ONLY. This is the unique identifier of the entity in the world
JavaScript Object null Something went wrong when creating the entity



createEntity(Type, TemplateIdentifier)

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 will be 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.

Parameters
Type Name Description
String Type Specifies the type of the entity that is being created by the template. Valid inputs are `entity` and `item_entity`
String TemplateIdentifier This can be any of the entity identifiers from the applied Behavior Packs. For example specifying minecraft:cow here will make the provided entity a cow as defined in JSON


Return Value
Type Value Description
JavaScript Object object An EntityObject representing the newly created entity
Parameters
Type Name Description
String __identifier__ READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is entity and the object is representing a vanilla cow, the identifier would be minecraft:cow
String __type__ READ ONLY. This defines the type of object we are using. Can be: entity, item_entity, level, component, query
Integer id READ ONLY. This is the unique identifier of the entity in the world
JavaScript Object null Something went wrong when creating the entity



destroyEntity(EntityObject)

Destroys an entity identified by the EntityObject. If the entity exists in the world this will remove it from the world and destroy it. This also makes the EntityObject 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 won't be an event for its death: it will be removed.

Parameters
Type Name Description
JavaScript Object EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event


Return Value
Type Value Description
Boolean true The entity was successfully destroyed
JavaScript Object null Something went wrong when destroying the entity



isValidEntity(EntityObject)

Checks if the given EntityObject corresponds to a valid entity.

Parameters
Type Name Description
JavaScript Object EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event


Return Value
Type Value Description
Boolean true The entity is in the Script Engine's database of entities
Boolean false The entity is not in the Script Engine's database of entities
JavaScript Object null Something went wrong when validating the entity




Component Bindings[edit]

registerComponent(ComponentIdentifier, ComponentData)

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
Type Name Description
String ComponentIdentifier 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 'myPack:myCustomComponent'
JavaScript Object ComponentData A JavaScript Object that defines the name of the fields and the data each field holds inside the component.


Return Value
Type Value Description
Boolean true The component was successfully registered
JavaScript Object null Something went wrong when registering the component



createComponent(EntityObject, ComponentIdentifier)

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 will retrieve the component already there instead.

Parameters
Type Name Description
JavaScript Object EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
String ComponentIdentifier 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 registerComponent()


Return Value
Type Value Description
JavaScript Object object An object with the following fields, and additionally, all the fields as defined in the component
Parameters
Type Name Description
String __identifier__ READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is entity and the object is representing a vanilla cow, the identifier would be minecraft:cow
String __type__ READ ONLY. This defines the type of object we are using. Can be: entity, item_entity, level, component, query
JavaScript Object null Something went wrong when creating the component



hasComponent(EntityObject, ComponentIdentifier)

Checks if the given entity has the specified component.

Parameters
Type Name Description
JavaScript Object EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
String ComponentIdentifier 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 registerComponent()


Return Value
Type Value Description
Boolean true The EntityObject has the component
Boolean false The EntityObject doesn't have the component
JavaScript Object null An unknown component was passed in or something else went wrong when checking if the EntityObject had the component



getComponent(EntityObject, ComponentIdentifier)

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

Parameters
Type Name Description
JavaScript Object EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
String ComponentIdentifier 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 registerComponent()


Return Value
Type Value Description
JavaScript Object object An object with the following fields, and additionally, all the fields as defined in the component
Parameters
Type Name Description
String __identifier__ READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is entity and the object is representing a vanilla cow, the identifier would be minecraft:cow
String __type__ READ ONLY. This defines the type of object we are using. Can be: entity, item_entity, level, component, query
JavaScript Object null The entity did not have the component or something went wrong when getting the component



applyComponentChanges(entityObject, componentObject)

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
Type Name Description
JavaScript Object entityObject The entity object that we are applying the component changes to
JavaScript Object componentObject The component object retrieved from the entity that was returned by either createComponent() or getComponent()


Return Value
Type Value Description
Boolean true The component was successfully updated
JavaScript Object null Something went wrong when updating the component



destroyComponent(EntityObject, ComponentIdentifier)

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

Parameters
Type Name Description
JavaScript Object EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
String ComponentIdentifier 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 registerComponent()


Return Value
Type Value Description
Boolean true The component was successfully removed from the entity
JavaScript Object null The entity did not have the component or something went wrong when removing the component




Event Bindings[edit]

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.

broadcastEvent(EventIdentifier, EventData)

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

Parameters
Type Name Description
String EventIdentifier 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 EventData 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 will take care of delivering the data to them


Return Value
Type Value Description
Boolean true Successfully broadcasted the event
JavaScript Object null Something went wrong when broadcasting the event



listenForEvent(EventIdentifier, CallbackObject)

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
Type Name Description
String EventIdentifier 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 CallbackObject The JavaScript object that will get called whenever the event is broadcast


Return Value
Type Value Description
Boolean true Successfully registered to listen for the event
JavaScript Object null Something went wrong when registering the event for listening




Entity Queries[edit]

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 will only ever return entities that are currently active in the level. If your query extends into chunks that are not currently loaded, entities there will not be included in the query.

registerQuery()

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

Return Value
Type Value Description
JavaScript Object object An object containing the ID of the query
Parameters
Type Name Description
String __identifier__ READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is entity and the object is representing a vanilla cow, the identifier would be minecraft:cow
String __type__ READ ONLY. This defines the type of object we are using. Can be: entity, item_entity, level, component, query
Integer id READ ONLY. This is the unique identifier of the query
JavaScript Object null Something went wrong when creating the query



registerQuery(Component, ComponentField1, ComponentField2, ComponentField3)

Allows you to register a query that will only show entities that have the given component and define which fields of that component will be used as a filter when getting the entities from the query.

Parameters
Type Name Default Value Description
String Component This is the identifier of the component that will be used to filter entities when
String ComponentField1 "x" This is the name of the first field of the component that we want to filter entities by. By default this is set to x. If the component you used doesn't have the field you defined here, the field will be ignored
String ComponentField2 "y" This is the name of the second field of the component that we want to filter entities by. By default this is set to y. If the component you used doesn't have the field you defined here, the field will be ignored
String ComponentField3 "z" This is the name of the third field of the component that we want to filter entities by. By default this is set to z. If the component you used doesn't have the field you defined here, the field will be ignored


Return Value
Type Value Description
JavaScript Object object An object containing the ID of the query
Parameters
Type Name Description
String __identifier__ READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is entity and the object is representing a vanilla cow, the identifier would be minecraft:cow
String __type__ READ ONLY. This defines the type of object we are using. Can be: entity, item_entity, level, component, query
Integer id READ ONLY. This is the unique identifier of the query
JavaScript Object null Something went wrong when creating the query



addFilterToQuery(Query, ComponentIdentifier)

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

Parameters
Type Name Description
JavaScript Object Query The object containing the ID of the query that you want to apply the filter to
String ComponentIdentifier This is the identifier of the component that will be added to the filter list. Only entities that have that component will be listed in the query


getEntitiesFromQuery(Query)

Allows you to fetch the entities captured by a query.

Parameters
Type Name Description
JavaScript Object Query This is the query you registered earlier using registerQuery()


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



getEntitiesFromQuery(Query, ComponentField1_Min, ComponentField2_Min, ComponentField3_Min, ComponentField1_Max, ComponentField2_Max, ComponentField3_Max)

Allows you to fetch the entities captured by a query that was created with a component filter built-in. The only entities that will be 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 getEntitiesFromQuery.

Parameters
Type Name Description
JavaScript Object Query This is the query you created earlier using registerQuery(...)
Decimal ComponentField1_Min The minimum value that the first component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField2_Min The minimum value that the second component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField3_Min The minimum value that the third component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField1_Max The maximum value that the first component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField2_Max The maximum value that the second component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField3_Max 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
Type Value Description
Array array An array of EntityObjects representing the entities found within the query
JavaScript Object null Something went wrong when creating the entity





Script Components[edit]

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 will go into a bit 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.

Client Components[edit]

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

minecraft:molang

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 (entity.isgrazing 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["entity.molangexample"] = 1.0; 
this.applyComponentChanges(molangComponent);



Server Components[edit]

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:attack

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 will be reset to the minimum specified. With the minimum and maximum changed to the values specified. Any buffs or debuffs will be left intact.

Parameters
Type Name Default Value Description
Range [a, b] damage Range of the random amount of damage the melee attack deals. A negative value can heal the entity instead of hurting it
String effect_name Identifier of the status ailment to apply to an entity attacked by this entity's melee attack
Decimal effect_duration 0.0 Duration in seconds of the status ailment applied to the damaged entity


minecraft:collision_box

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
Type Name Default Value Description
Decimal width 1.0 Width and Depth of the collision box in blocks. A negative value will be assumed to be 0
Decimal height 1.0 Height of the collision box in blocks. A negative value will be assumed to be 0


minecraft:damage_sensor

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 will be completely replaced when applyComponentChanges().

Parameters
Type Name Default Value Description
List on_damage List of triggers with the events to call when taking this specific kind of damage, allows specifying filters for entity definitions and events
Boolean deals_damage true If true, the damage dealt to the entity will take away health from it, set to false to make the entity ignore that damage
String cause Type of damage that triggers this set of events


minecraft:equipment

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
Type Name Default Value Description
String table The file path to the equipment table, relative to the behavior pack's root
List slot_drop_chance A list of slots with the chance to drop an equipped item from that slot


minecraft:equippable

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

slots 

List of slots and the item that can be equipped

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



minecraft:explode

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

Parameters
Type Name Default Value Description
Range [a, b] fuseLength [0.0, 0.0] The range for the random amount of time the fuse will be lit before exploding, a negative value means the explosion will be immediate
Decimal power 3.0 The radius of the explosion in blocks and the amount of damage the explosion deals
Decimal maxResistance Infinite A blocks explosion resistance will be capped at this value when an explosion occurs
Boolean fuseLit false If true, the fuse is already lit when this component is added to the entity
Boolean causesFire false If true, blocks in the explosion radius will be set on fire
Boolean breaks_blocks true If true, the explosion will destroy blocks in the explosion radius
Boolean fireAffectedByGriefing false If true, whether the explosion causes fire is affected by the mob griefing game rule
Boolean destroyAffectedByGriefing false If true, whether the explosion breaks blocks is affected by the mob griefing game rule


minecraft:healable

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
Type Name Default Value Description
Boolean force_use false Determines if item can be used regardless of entity being at full health
Minecraft Filter filters The filter group that defines the conditions for this trigger
Array items The array of items that can be used to heal this entity
Parameters
Type Name Default Value Description
String item Item identifier that can be used to heal this entity
Integer heal_amount 1 The amount of health this entity gains when fed this item
Minecraft Filter filters The filter group that defines the conditions for using this item to heal the entity


minecraft:health

Defines the current and maximum possible health of the entity. Upon applying the component back to the entity the health will change. If it reaches 0 or below the entity will die.

Parameters
Type Name Default Value Description
Integer value 1 Current health of the entity
Integer max 10 The maximum health the entity can heal


minecraft:interact

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

Parameters
Type Name Default Value Description
Array spawn_entities An array of entity identifiers to spawn when the interaction occurs
String on_interact An event identifier to fire when the interaction occurs
JSON Object particle_on_start Particle effect that will be triggered at the start of the interaction
Parameters
Type Name Default Value Description
String particle_type The type of particle that will be spawned
Decimal particle_y_offset 0.0 Will offset the particle this amount in the y direction
Boolean particle_offset_towards_interactor false Whether or not the particle will appear closer to who performed the interaction
Decimal cooldown 0.0 Time in seconds before this entity can be interacted with again
Boolean swing false If true, the player will do the 'swing' animation when interacting with this entity
Boolean use_item false If true, the interaction will use an item
Integer hurt_item 0 The amount of damage the item will take when used to interact with this entity. A value of 0 means the item won't lose durability
String interact_text Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
JSON Object add_items Loot table with items to add to the player's inventory upon successful interaction
Parameters
Type Name Default Value Description
String table File path, relative to the behavior pack's path, to the loot table file
JSON Object spawn_items Loot table with items to drop on the ground upon successful interaction
Parameters
Type Name Default Value Description
String table File path, relative to the behavior pack's path, to the loot table file
String transform_to_item The item used will transform to this item upon successful interaction. Format: itemName:auxValue
Array play_sounds An array of sound identifiers to play when the interaction occurs


minecraft:inventory

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

Parameters
Type Name Default Value Description
String container_type none Type of container this entity has. Can be horse, minecart_chest, minecart_hopper, inventory, container or hopper
Integer inventory_size 5 Number of slots the container has
Boolean can_be_siphoned_from false If true, the contents of this inventory can be removed by a hopper
Boolean private false If true, only the entity can access the inventory
Boolean restrict_to_owner false If true, the entity's inventory can only be accessed by its owner or itself
Integer additional_slots_per_strength 0 Number of slots that this entity can gain per extra strength


minecraft:lookat

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

Parameters
Type Name Default Value Description
Minecraft Filter filters player Defines the entities that can trigger this component
Range [a, b] look_cooldown [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
String look_event The event identifier to run when the entities specified in filters look at this entity
Boolean mAllowInvulnerable false If true, invulnerable entities (e.g. Players in creative mode) are considered valid targets
Decimal searchRadius 10.0 Maximum distance this entity will look for another entity looking at it
Boolean setTarget true If true, this entity will set the attack target as the entity that looked at it


minecraft:nameable

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
Type Name Default Value Description
JSON Object name_actions Describes the special names for this entity and the events to call when the entity acquires those names
Parameters
Type Name Default Value Description
String on_named Event to be called when this entity acquires the name specified in 'name_filter'
List name_filter List of special names that will cause the events defined in 'on_named' to fire
String default_trigger Trigger to run when the entity gets named
Boolean alwaysShow false If true, the name will always be shown
Boolean allowNameTagRenaming true If true, this entity can be renamed with name tags
String name The current name of the entity, empty if the entity hasn't been named yet, making this non-empty will apply the name to the entity


minecraft:position

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

Parameters
Type Name Default Value Description
Decimal x 0.0 Position along the X-Axis (east-west) of the entity
Decimal y 0.0 Position along the Y-Axis (height) of the entity
Decimal z 0.0 Position along the Z-Axis (north-south) of the entity


minecraft:rotation

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 will be rotated as specified.

Parameters
Type Name Default Value Description
Decimal x 0.0 Controls the head rotation looking up and down
Decimal y 0.0 Controls the body rotation parallel to the floor


minecraft:shooter

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
Type Name Default Value Description
String def 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 auxVal -1 ID of the Potion effect to be applied on hit


minecraft:spawn_entity

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
Type Name Default Value Description
Integer min_wait_time 300 Minimum amount of time to randomly wait in seconds before another entity is spawned
Integer max_wait_time 600 Maximum amount of time to randomly wait in seconds before another entity is spawned
String spawn_sound plop Identifier of the sound effect to play when the entity is spawned
String spawn_item egg Item identifier of the item to spawn
String spawn_entity Identifier of the entity to spawn, leave empty to spawn the item defined above instead
String spawn_method born Method to use to spawn the entity
String spawn_event minecraft:entity_born Event to call when the entity is spawned


minecraft:teleport

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
Type Name Default Value Description
Decimal darkTeleportChance 0.01 Modifies the chance that the entity will teleport if the entity is in darkness
Decimal lightTeleportChance 0.01 Modifies the chance that the entity will teleport if the entity is in daylight
Decimal maxRandomTeleportTime 20.0 Maximum amount of time in seconds between random teleports
Decimal minRandomTeleportTime 0.0 Minimum amount of time in seconds between random teleports
Vector [a, b, c] randomTeleportCube [32.0, 16.0, 32.0] Entity will teleport to a random position within the area defined by this cube
Boolean randomTeleports true If true, the entity will teleport randomly
Decimal targetDistance 16.0 Maximum distance the entity will teleport when chasing a target
Decimal target_teleport_chance 1.0 The chance that the entity will teleport between 0.0 and 1.0. 1.0 means 100%




User-Defined Components[edit]

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 will NOT be saved out or loaded back in: they only exist 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[edit]

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

Client Events[edit]

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 ID of the player in the world. The ID uniquely identifies the player in the world. This does NOT uniquely identify the player if they disconnect and reconnect.


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
Type Name Description
JavaScript Object entity The enity that was hit or null if it fired when moving off of an entity
Vector [a, b, c] position The position of the enity that was hit or null if it fired when moving off an entity
Code Example
[1]
system.initialize = function() {
	this.listenForEvent("minecraft:hit_result_changed", (eventData) = > this.onPick(eventData)); 
};
[2]
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
Type Name Description
JavaScript Object entity The enity that was hit or null if it not pointing at an entity
Vector [a, b, c] position The position of the enity that was hit or block that was hit
Code Example
[1]
system.initialize = function() {
	this.listenForEvent("minecraft:hit_result_continuous", (eventData) = > this.onPick(eventData)); 
};
[2]
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
Type Name Description
JavaScript Object entity The enity that was hit or null if it fired when moving off of an entity
Vector [a, b, c] position The position of the enity that was hit or null if it fired when moving off an entity
Code Example
[1]
system.initialize = function() {
	this.listenForEvent("minecraft:pick_hit_result_changed", (eventData) = > this.onPick(eventData)); 
};
[2]
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
Type Name Description
JavaScript Object entity The enity that was hit or null if it not pointing at an entity
Vector [a, b, c] position The position of the enity that was hit or block that was hit
Code Example
[1]
system.initialize = function() {
	this.listenForEvent("minecraft:pick_hit_result_continuous", (eventData) = > this.onPick(eventData)); 
};
[2]
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); 
	} 
};



Trigger-able 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.


minecraft:execute_command 

This event is used to run a slash command from the specific player running the client script. The script runs it as that player. The event data contains the slash command in plain text. The slash command will be run immediately after the event is triggered.


minecraft:load_ui 

This event is used to show a UI screen to the specific player running the client script. This event will add the UI screen to the top of the UI screen stack. The event data contains the file path to the screen's HTML file as a string. The screen will be shown immediately after the event is triggered. Only screens defined in a HTML file can be shown using this event.


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 will be sent immediately.
Custom UI is based on HTML 5. Review the scripting demo for an example of a custom UI file.

Parameters
Type Name Description
String eventIdentifier The identifier of the UI event
String data The data for the UI event being triggered


minecraft:spawn_particle_attached_entity 

This event is used to create a particle effect that will follow 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
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
JavaScript Object entity The entity object you want to attach the effect to
Vector [a, b, c] offset [0, 0, 0] The offset from the entity's "center" where you want to spawn the effect


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 will spawn the particle in the dimension the player is currently in.

Parameters
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


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 will be 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.




Server Events[edit]

Listening Events

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

minecraft:entity_created 

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

Parameters
Type Name Description
JavaScript 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
Type Name Description
JavaScript Object entity The entity that died


minecraft:entity_start_riding 

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

Parameters
Type Name Description
JavaScript Object entity The rider
JavaScript Object ride The entity being ridden


minecraft:entity_stop_riding 

This event is triggered whenever an entity stops riding another entity.

Parameters
Type Name Description
JavaScript 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


minecraft:entity_tick 

This event is triggered whenever an entity is ticked. This event will not fire when a player is ticked.

Parameters
Type Name Description
JavaScript Object entity The entity that was ticked


minecraft:player_attacked_actor 

This event is triggered whenever a player attacks an entity.

Parameters
Type Name Description
JavaScript Object player The player that attacked an entity
JavaScript Object attacked_entity The entity that was attacked by the player



Trigger-able Events

The following Minecraft events can be triggered from scripting and the game will respond, 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.


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 will be processed and will run after the event is sent.


minecraft:spawn_particle_attached_entity 

This event is used to create a particle effect that will follow 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
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
JavaScript Object entity The entity object you want to attach the effect to
Vector [a, b, c] offset [0, 0, 0] The offset from the entity's "center" where you want to spawn the effect


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
Type Name Default Value Description
String dimension overworld The dimension in which you want to spawn the effect. Can be "overworld", "nether", or "the end"
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