# SCRIPTING DOCUMENTATION Version: 1.17.0.2

##

Index

Script API Objects
Entity JS API Object
Level JS API Object
Component JS API Object
Query JS API Object
ItemStack JS API Object
Block JS API Object
Ticking Area JS API Object
Entity Ticking Area JS API Object
Level Ticking Area JS API Object
Script Bindings
Logging Bindings
Entity Bindings
Component Bindings
Event Bindings
Entity Queries
Block Bindings
Slash Commands
Script Components
Level Components
Server Components
Client Components
Block Components
Script Events
Client Events
Server Events
Scripting System
Demos
Known Issues
Breaking Changes
Pre-Requisites
Getting Started
Structure of a Script
Debugging
User-Defined Components

Back to top

#

Script API Objects

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

#

Entity JS API Object

##

Name | Type | Entity JS API Object | Description
--- | --- | --- | ---
__identifier__ | String |  | 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
__type__ | String |  | READ ONLY. This defines the type of object. Can be: "entity" or "item_entity".
id | Positive Integer |  | READ ONLY. This is the unique identifier of the entity.

Back to top

#

Level JS API Object

##

Name | Type | Level JS API Object | Description
--- | --- | --- | ---
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "level".
level_id | Positive Integer |  | READ ONLY. This is the unique identifier of the level.

Back to top

#

Component JS API Object

##

Name | Type | Component JS API Object | Description
--- | --- | --- | ---
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "component".
data | JavaScript Object |  | This is the content of the component.

Back to top

#

Query JS API Object

##

Name | Type | Query JS API Object | Description
--- | --- | --- | ---
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "query".
query_id | Positive Integer |  | READ ONLY. This is the unique identifier of the query.

Back to top

#

ItemStack JS API Object

##

Name | Type | ItemStack JS API Object | Description
--- | --- | --- | ---
__identifier__ | String |  | 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
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "item_stack".
count | String |  | READ ONLY. This is the number of items in the stack.
item | String |  | READ ONLY. This is the identifier of the item.

Back to top

#

Block JS API Object

##

Name | Type | Block JS API Object | Description
--- | --- | --- | ---
__identifier__ | String |  | READ ONLY. This is the identifier for the object in the format namespace:name. For example, if the type is block and the object is representing a block of bedrock, the identifier would be minecraft:bedrock
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "block".
block_position | JavaScript Object |  | READ ONLY. This is the position of the block and it functions as part of its unique identifier. ### Parameters ####
Name | Type | Description
--- | --- | ---
x | Integer | The x position
y | Integer | The y position
z | Integer | The z position
Back to top
ticking_area | JavaScript Object |  | READ ONLY. This is the ticking area object that was used to get this block.

Back to top

#

Ticking Area JS API Object

Back to top

#

Entity Ticking Area JS API Object

##

Name | Type | Entity Ticking Area JS API Object | Description
--- | --- | --- | ---
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "entity_ticking_area".
entity_ticking_area_id | Positive Integer |  | READ ONLY. This is the unique identifier of the ticking area.

Back to top

#

Level Ticking Area JS API Object

##

Name | Type | Level Ticking Area JS API Object | Description
--- | --- | --- | ---
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "level_ticking_area".
level_ticking_area_id | String |  | READ ONLY. This is the unique identifier of the ticking area.

Back to top

#

Script Bindings

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

#

Logging Bindings

##

##

log(Message)

The log function is accessed through the server or client objects and allows for logging a message to the ContentLog file. On Windows 10 devices it is located at ' %APPDATA%\..\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\logs '

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
Message | String | The message that you want to send to the log file

Back to top

### Code Example:

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

#

Entity Bindings

##

##

createEntity()

NOTE: Entities are created first on the server, with the client notified of new entities afterwards. 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

####

Type | Value
--- | ---
Entity JS API Object | An object representing the newly created entity

Back to top

##

createEntity(Type, TemplateIdentifier)

NOTE: Entities are created first on the server, with the client notified of new entities afterwards. 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

####

Name | Type | Description
--- | --- | ---
TemplateIdentifier | String | 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
Type | String | Specifies the type of the entity that is being created by the template. Valid inputs are `entity` and `item_entity`

Back to top

###

Return Value

####

Type | Value
--- | ---
Entity JS API Object | An object representing the newly created entity

Back to top

##

destroyEntity(EntityObject)

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
EntityObject | Entity JS API Object | The object that was retrieved from a call to createEntity() or retrieved from an entity event

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | The entity was successfully destroyed

Back to top

##

isValidEntity(EntityObject)

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
EntityObject | Entity JS API Object | The object that was retrieved from a call to createEntity() or retrieved from an entity event

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | The entity is in the Script Engine's database of entities

Back to top

#

Component Bindings

##

##

registerComponent(ComponentIdentifier, ComponentData)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | The component was successfully registered

Back to top

### Code Example:

Registering a custom component
const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { this.registerComponent("myPack:myCustomComponent", { myString: "string", myNumber: 0, myBool: true, myArray: [1, 2, 3] }); };

##

createComponent(EntityObject, ComponentIdentifier)

###

###

Parameters

####

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

Back to top

###

Return Value

####

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

Back to top

### Code Example:

Creating a custom component
let globals = { ready: false }; const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { this.registerComponent("myPack:myCustomComponent", { myString: "string", myNumber: 0, myBool: true, myArray: [1, 2, 3] }); } mySystem.update = function() { if(globals.ready == false) { globals.ready = true; let myEntity = this.createEntity(); if(myEntity != null) { let myComponent = this.createComponent(myEntity, "myPack:myCustomComponent"); } } };

##

hasComponent(EntityObject, ComponentIdentifier)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | The EntityObject has the component

Back to top

### Code Example:

Check whether an entity has specified component
let globals = { ready: false }; const mySystem = server.registerSystem(0, 0); mySystem.update = function() { if(globals.ready == false) { globals.ready = true; let entity = this.createEntity("entity", "minecraft:pig"); if(this.hasComponent(entity, "minecraft:nameable")) { // Do some work } } };

##

getComponent(EntityObject, ComponentIdentifier)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Component JS API Object | An object with the following fields, and additionally, all the fields as defined in the component ##### Component JS API Object ######
Name | Type | Component JS API Object | Description
--- | --- | --- | ---
__type__ | String |  | READ ONLY. This defines the type of object. Will be: "component".
data | JavaScript Object |  | This is the content of the component.
Back to top

Back to top

### Code Example:

Get a specified component from an entity
let globals = { ready: false }; const mySystem = server.registerSystem(0, 0); mySystem.update = function() { if(globals.ready == false) { globals.ready = true; let entity = this.createEntity("entity", "minecraft:pig"); let positionComponent = this.getComponent(entity, "minecraft:position"); if (positionComponent != null) { positionComponent.data.x = 0; positionComponent.data.y = 0; positionComponent.data.z = 0; } } };

##

applyComponentChanges(EntityObject, ComponentObject)

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
ComponentObject | Component JS API Object | The component object retrieved from the entity that was returned by either createComponent() or getComponent()
EntityObject | Entity JS API Object | The entity object that we are applying the component changes to

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | The component was successfully updated

Back to top

### Code Example:

Apply updates to an entity's component
let globals = { pig: null }; const mySystem = server.registerSystem(0, 0); mySystem.update = function() { if(globals.pig == null) { globals.pig = this.createEntity("entity", "minecraft:pig"); } else { let positionComponent = this.getComponent(globals.pig, "minecraft:position"); positionComponent.data.y += 0.1; this.applyComponentChanges(globals.pig, positionComponent); } };

##

destroyComponent(EntityObject, ComponentIdentifier)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | The component was successfully removed from the entity

Back to top

### Code Example:

Destroy an entity's component
let globals = { myEntity: null }; const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { this.registerComponent("myPack:myCustomComponent", { myString: "string", myNumber: 0, myBool: true, myArray: [1, 2, 3] }); }; mySystem.update = function() { if(globals.myEntity == null) { globals.myEntity = this.createEntity(); } else { if(this.hasComponent(globals.myEntity, "myPack:myCustomComponent")) { this.destroyComponent(globals.myEntity, "myPack:myCustomComponent"); } else { this.createComponent(globals.myEntity, "myPack:myCustomComponent"); } } };

#

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.

##

##

registerEventData(EventIdentifier, EventData)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | Successfully registered the event data

Back to top

##

createEventData(EventIdentifier)

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
EventIdentifier | String | This is the identifier of the custom event we are registering. The namespace is required and can't be set to minecraft.

Back to top

###

Return Value

####

Type | Value
--- | ---
JavaScript Object | The object containing the event data

Back to top

##

listenForEvent(EventIdentifier, CallbackObject)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | Successfully registered to listen for the event

Back to top

### Code Example:

Register a callback for a specified event
const mySystem = client.registerSystem(0, 0); mySystem.initialize = function() { this.listenForEvent("minecraft:client_entered_world", (eventData) => this.onClientEnteredWorld(eventData)); }; mySystem.onClientEnteredWorld = function(eventData) { let messageData = this.createEventData("minecraft:display_chat_event"); messageData.data.message = "Player has entered the world"; this.broadcastEvent("minecraft:display_chat_event", messageData); };

##

broadcastEvent(EventIdentifier, EventData)

###

###

Parameters

####

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

Back to top

###

Return Value

####

Type | Value
--- | ---
Boolean | Successfully broadcasted the event

Back to top

### Code Example:

Broadcasting an event
const mySystem = client.registerSystem(0, 0); mySystem.initialize = function() { let eventData = this.createEventData("minecraft:display_chat_event"); eventData.data.message = "Hello, World!"; this.broadcastEvent("minecraft:display_chat_event", eventData); };

#

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 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
--- | ---
Query JS API Object | An object containing the ID of the query

Back to top

### Code Example:

Query Registration
const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { let myQuery = this.registerQuery(); };

##

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

####

Name | Type | Default Value | Description
--- | --- | --- | ---
Component | String |  | This is the identifier of the component that will be used to filter entities when
ComponentField1 | String | "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.
ComponentField2 | String | "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.
ComponentField3 | String | "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.

Back to top

###

Return Value

####

Type | Value
--- | ---
Query JS API Object | An object containing the ID of the query

Back to top

### Code Example:

Query Registration
const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { let spatialQuery = this.registerQuery("minecraft:position", "x", "y", "z"); };

##

addFilterToQuery(Query, ComponentIdentifier)

Allows you to add filters to your query. The query will only contain entities that have all the components specified.By default no filters are added. This will allow queries to capture all entities.

### Parameters

Name | Type | Description
--- | --- | ---
ComponentIdentifier | String | 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
Query | Query JS API Object | The object containing the ID of the query that you want to apply the filter to

### Code Example:

Adding a filter to a query
let globals = { simpleQuery: null }; const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { globals.simpleQuery = this.registerQuery(); }; mySystem.update = function() { globals.simpleQuery = this.registerQuery(); this.addFilterToQuery(globals.simpleQuery, "minecraft:explode"); let explodingEntities = this.getEntitiesFromQuery(globals.simpleQuery); for(var entity in explodingEntities) { server.log(JSON.stringify(entity)); } }; Back to top

##

getEntitiesFromQuery(Query)

Allows you to fetch the entities captured by a query.

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
Query | Query JS API Object | This is the query you registered earlier using registerQuery()

Back to top

###

Return Value

####

Type | Value
--- | ---
Array | An array of EntityObjects representing the entities found within the query

Back to top

### Code Example:

Get a list of entities from a query
const mySystem = server.registerSystem(0, 0); mySystem.update = function() { let simpleQuery = this.registerQuery(); let allEntities = this.getEntitiesFromQuery(simpleQuery); for(var entity in allEntities) { server.log(JSON.stringify(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

####

Name | Type | Description
--- | --- | ---
ComponentField1_Max | Decimal | The maximum value that the first component field needs to be on an entity for that entity to be included in the query
ComponentField1_Min | Decimal | The minimum value that the first component field needs to be on an entity for that entity to be included in the query
ComponentField2_Max | Decimal | The maximum value that the second component field needs to be on an entity for that entity to be included in the query
ComponentField2_Min | Decimal | The minimum value that the second component field needs to be on an entity for that entity to be included in the query
ComponentField3_Max | Decimal | The maximum value that the third component field needs to be on an entity for that entity to be included in the query
ComponentField3_Min | Decimal | The minimum value that the third component field needs to be on an entity for that entity to be included in the query
Query | Query JS API Object | This is the query you created earlier using registerQuery(...)

Back to top

###

Return Value

####

Type | Value
--- | ---
Array | An array of EntityObjects representing the entities found within the query

Back to top

### Code Example:

Get a list of entities from a query
let globals = { spatialQuery: null }; const mySystem = server.registerSystem(0, 0); mySystem.initialize = function() { globals.spatialQuery = this.registerQuery("minecraft:position", "x", "y", "z"); }; mySystem.update = function() { let closeEntities = this.getEntitiesFromQuery(globals.spatialQuery, 0, 10, 0, 5, 0, 10); for(var entity in closeEntities) { server.log(JSON.stringify(entity)); } };

#

Block Bindings

These functions define how you interact with blocks.

##

##

getBlock(Ticking Area, x, y, z)

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

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
Ticking Area | Ticking Area JS API Object | The ticking area the block is in
x | Integer | The x position of the block you want
y | Integer | The y position of the block you want
z | Integer | The z position of the block you want

Back to top

###

Return Value

####

Type | Value
--- | ---
| object
| null

Back to top

##

getBlock(Ticking Area, PositionObject)

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

####

Name | Type | Description
--- | --- | ---
PositionObject | JavaScript Object | A JavaScript object with the x, y, and z position of the block you want ##### Parameters ######
Name | Type | Description
--- | --- | ---
x | Integer | The x position
y | Integer | The y position
z | Integer | The z position
Back to top
Ticking Area | Ticking Area JS API Object | The ticking area the block is in

Back to top

###

Return Value

####

Type | Value
--- | ---
Block JS API Object | An object containing the block

Back to top

##

getBlocks(Ticking Area, x min, y min, z min, x max, y max, z max)

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. This call can be slow if given a lot of blocks, and should be used infrequently.

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
Ticking Area | Ticking Area JS API Object | The ticking area the blocks are in
x max | Integer | The maximum x position of the blocks you want
x min | Integer | The minimum x position of the blocks you want
y max | Integer | The maximum y position of the blocks you want
y min | Integer | The minimum y position of the blocks you want
z max | Integer | The maximum z position of the blocks you want
z min | Integer | The minimum z position of the blocks you want

Back to top

###

Return Value

####

Type | Value
--- | ---
| array
| null

Back to top

##

getBlocks(Ticking Area, Minimum PositionObject, Maximum PositionObject)

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. This call can be slow if given a lot of blocks, and should be used infrequently.

###

###

Parameters

####

Name | Type | Description
--- | --- | ---
Maximum PositionObject | JavaScript Object | A JavaScript object with the maximum x, y, and z position of the blocks you want ##### Parameters ######
Name | Type | Description
--- | --- | ---
x | Integer | The x position
y | Integer | The y position
z | Integer | The z position
Back to top
Minimum PositionObject | JavaScript Object | A JavaScript object with the minimum x, y, and z position of the blocks you want ##### Parameters ######
Name | Type | Description
--- | --- | ---
x | Integer | The x position
y | Integer | The y position
z | Integer | The z position
Back to top
Ticking Area | Ticking Area JS API Object | The ticking area the blocks are in

Back to top

###

Return Value

####

Type | Value
--- | ---
Array | A 3D array of block objects. Indexs are the blocks positions relative to the min position given
| null

Back to top

#

Slash Commands

##

##

executeCommand(Command, Callback)

###

Name | Type | Description
--- | --- | ---
Callback | JSON Object | The JavaScript object that will be called after the command executes
Command | String | The slash command to run

### 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, " ") ); } }; Back to top

#

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

#

Level Components

##

##

minecraft:ticking_areas

Back to top

##

minecraft:weather

###

Name | Type | Description
--- | --- | ---
do_weather_cycle | Boolean | This is the world option that determines if the vanilla weather cycle will be used
lightning_level | Decimal | A value between 0 and 1 that determines how much lightning and thunder there is
lightning_time | Integer | How long, in ticks, it will lightning and thunder for
rain_level | Decimal | A value between 0 and 1 that determains how heavy the rainfall is
rain_time | Integer | How long, in ticks, it will rain for

Back to top

#

Server Components

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

##

##

minecraft:armor_container

###

// This example will check 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); } }); Back to top

##

minecraft:attack

###

Name | Type | Default Value | Description
--- | --- | --- | ---
damage | 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
Name | Type | Default Value | Description
--- | --- | --- | ---
range_max | Decimal | 0.0 | The maximum amount of damage the entity will deal
range_min | Decimal | 0.0 | The minimum amount of damage the entity will deal

Back to top

##

minecraft:container

###

// This example will check if a block has a container. let block; // check getBlock API on how to access a block let has_container = system.hasComponent(block, "minecraft:container"); if (has_container === true) { let container = system.getComponent(block, "minecraft:container"); // you can now use the container to read items. Back to top

##

minecraft:collision_box

Sets the width and height of the Entity's collision box.

###

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

Back to top

##

minecraft:damage_sensor

Defines what events to call when this entity is damaged by specific entities or items.

###

Name | Type | Default Value | Description
--- | --- | --- | ---
triggers | List |  | List of triggers with the events to call when taking specific kinds of damage.
Name | Type | Default Value | Description
--- | --- | --- | ---
cause | String | none | Type of damage that triggers the events.
damage_modifier | Decimal | 0.0 | A modifier that adds to/removes from the base damage from the damage cause. It does not reduce damage to less than 0.
damage_multiplier | Decimal | 1.0 | A multiplier that modifies the base damage from the damage cause. If deals_damage is true the multiplier can only reduce the damage the entity will take to a minimum of 1.
deals_damage | Boolean | 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.
on_damage | JSON Object |  | Specifies filters for entity definitions and events.
on_damage_sound_event | String |  | Defines what sound to play, if any, when the on_damage filters are met.

###

// This example will cause 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); }); Back to top

##

minecraft:equipment

Sets the Equipment table to use for this Entity.

###

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

Back to top

##

minecraft:equippable

Defines an entity's behavior for having items equipped to it.

###

###

slots

List of slots and the item that can be equipped.

####

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

Back to top

##

minecraft:explode

Defines how the entity explodes.

###

Name | Type | Default Value | Description
--- | --- | --- | ---
breaks_blocks | Boolean | true | If true, the explosion will destroy blocks in the explosion radius.
causes_fire | Boolean | false | If true, blocks in the explosion radius will be set on fire.
destroy_affected_by_griefing | Boolean | false | If true, whether the explosion breaks blocks is affected by the mob griefing game rule.
fire_affected_by_griefing | Boolean | false | If true, whether the explosion causes fire is affected by the mob griefing game rule.
fuse_length | Range [a, b] | [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.
fuse_lit | Boolean | false | If true, the fuse is already lit when this component is added to the entity.
max_resistance | Decimal | 3.40282e+38 | A blocks explosion resistance will be capped at this value when an explosion occurs.
power | Decimal | 3 | The radius of the explosion in blocks and the amount of damage the explosion deals.

Back to top

##

minecraft:hand_container

###

// This example will check 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); } }); Back to top

##

minecraft:healable

Defines the interactions with this entity for healing it.

###

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

Back to top

##

minecraft:health

###

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

Back to top

##

minecraft:hotbar_container

###

// This example will check the 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); } }); Back to top

##

minecraft:interact

###

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

Back to top

##

minecraft:inventory

###

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

Back to top

##

minecraft:inventory_container

###

// This example will check 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); } }); Back to top

##

minecraft:lookat

Defines the behavior when another entity looks at this entity.

###

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

Back to top

##

minecraft:nameable

###

Name | Type | Default Value | Description
--- | --- | --- | ---
allow_name_tag_renaming | Boolean | true | If true, this entity can be renamed with name tags
always_show | Boolean | false | If true, the name will always be shown
default_trigger | String |  | Trigger to run when the entity gets named
name | String |  | 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
name_actions | JSON Object |  | Describes the special names for this entity and the events to call when the entity acquires those names
Name | Type | Default Value | Description
--- | --- | --- | ---
name_filter | List |  | List of special names that will cause the events defined in 'on_named' to fire
on_named | String |  | Event to be called when this entity acquires the name specified in 'name_filter'

Back to top

##

minecraft:position

###

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

Back to top

##

minecraft:rotation

###

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

Back to top

##

minecraft:shooter

###

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

Back to top

##

minecraft:spawn_entity

Adds a timer after which this entity will spawn another entity or item (similar to vanilla's chicken's egg-laying behavior).

###

Name | Type | Default Value | Description
--- | --- | --- | ---
filters | Minecraft Filter |  | If present, the specified entity will only spawn if the filter evaluates to true.
max_wait_time | Integer | 600 | Maximum amount of time to randomly wait in seconds before another entity is spawned.
min_wait_time | Integer | 300 | Minimum amount of time to randomly wait in seconds before another entity is spawned.
num_to_spawn | Integer | 1 | The number of entities of this type to spawn each time that this triggers.
should_leash | Boolean | false | If true, this the spawned entity will be leashed to the parent.
single_use | Boolean | false | If true, this component will only ever spawn the specified entity once.
spawn_entity | String |  | Identifier of the entity to spawn, leave empty to spawn the item defined above instead.
spawn_event | String | minecraft:entity_born | Event to call when the entity is spawned.
spawn_item | String | egg | Item identifier of the item to spawn.
spawn_method | String | born | Method to use to spawn the entity.
spawn_sound | String | plop | Identifier of the sound effect to play when the entity is spawned.

Back to top

##

minecraft:tag

Back to top

##

minecraft:teleport

###

Name | Type | Default Value | Description
--- | --- | --- | ---
dark_teleport_chance | Decimal | 0.01 | Modifies the chance that the entity will teleport if the entity is in darkness
light_teleport_chance | Decimal | 0.01 | Modifies the chance that the entity will teleport if the entity is in daylight
max_random_teleport_time | Decimal | 20 | Maximum amount of time in seconds between random teleports
min_random_teleport_time | Decimal | 0 | Minimum amount of time in seconds between random teleports
random_teleport_cube | Vector [a, b, c] | [32, 16, 32] | Entity will teleport to a random position within the area defined by this cube
random_teleports | Boolean | true | If true, the entity will teleport randomly
target_distance | Decimal | 16 | Maximum distance the entity will teleport when chasing a target
target_teleport_chance | Decimal | 1 | The chance that the entity will teleport between 0.0 and 1.0. 1.0 means 100%

Back to top

##

minecraft:ticking_area_description

###

Name | Type | Default Value | Description
--- | --- | --- | ---
is_circle | Boolean |  | Is the area a circle. If false the area is a square.
max | Vector [a, b, c] |  | (if area is a square) The edge of the area.
name | String |  | The name of the area.
origin | Vector [a, b, c] |  | The origin position of the area.
radius | Vector [a, b, c] |  | (if area is a circle) The radius of the area.

Back to top

##

minecraft:tick_world

###

Name | Type | Description
--- | --- | ---
distance_to_players | Decimal | distance_to_players
never_despawn | Boolean | Whether or not this ticking area will despawn when a player is out of range
radius | Integer | The radius in chunks of the ticking area
ticking_area | Entity Ticking Area JS API Object | The ticking area entity that is attached to this entity

Back to top

##

minecraft:transformation

###

Name | Type | Default Value | Description
--- | --- | --- | ---
add | JSON Object |  | List of components to add to the entity after the transformation
Name | Type | Default Value | Description
--- | --- | --- | ---
component_groups | List |  | Names of component groups to add
begin_transform_sound | String |  | Sound to play when the transformation starts
delay | JSON Object |  | Defines the properties of the delay for the transformation
Name | Type | Default Value | Description
--- | --- | --- | ---
block_assist_chance | Decimal | 0.0 | Chance that the entity will look for nearby blocks that can speed up the transformation. Value must be between 0.0 and 1.0
block_chance | Decimal | 0.0 | Chance that, once a block is found, will help speed up the transformation
block_max | Integer | 0 | Maximum number of blocks the entity will look for to aid in the transformation. If not defined or set to 0, it will be set to the block radius
block_radius | Integer | 0 | Distance in Blocks that the entity will search for blocks that can help the transformation
block_types | List |  | List of blocks that can help the transformation of this entity
keep_owner | Boolean |  | If this entity is owned by another entity, it should remain owned after transformation
value | Decimal | 0.0 | Time in seconds before the entity transforms
drop_equipment | Boolean |  | Cause the entity to drop all equipment upon transformation
into | String |  | Entity Definition that this entity will transform into
transformation_sound | String |  | Sound to play when the entity is done transforming

Back to top

#

Client Components

##

##

minecraft:molang

### Code Example:

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

#

Block Components

##

##

minecraft:blockstate

### Code Example:

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

#

Script Events

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

#

Client Events

##

##

Listening Events

###

###

minecraft:client_entered_world

Back to top

###

minecraft:hit_result_changed

####

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

#### Code Example:

Responding to hit_result_changed
const mySystem = client.registerSystem(0, 0); mySystem.initialize = function() { this.listenForEvent("minecraft:hit_result_changed", (eventData) => this.onHitChanged(eventData)); }; mySystem.onHitChanged = function(eventData) { if(eventData.position != null) { let chatEvent = this.createEventData("minecraft:display_chat_event"); chatEvent.data.message = "Hit at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z; this.broadcastEvent("minecraft:display_chat_event", chatEvent); } }; Back to top

###

minecraft:hit_result_continuous

####

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

#### Code Example:

Responding to hit_result_continuous
const mySystem = client.registerSystem(0, 0); mySystem.initialize = function() { this.listenForEvent("minecraft:hit_result_continuous", (eventData) => this.onHit(eventData)); }; mySystem.onHit = function(eventData) { if(eventData.position != null) { let chatEvent = this.createEventData("minecraft:display_chat_event"); chatEvent.data.message = "Position at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z; this.broadcastEvent("minecraft:display_chat_event", chatEvent); } }; Back to top

###

minecraft:pick_hit_result_changed

####

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

#### Code Example:

Responding to pick_hit_result_changed
const mySystem = client.registerSystem(0, 0); mySystem.initialize = function() { this.listenForEvent("minecraft:pick_hit_result_changed", (eventData) => this.onPickChanged(eventData)); }; mySystem.onPickChanged = function(eventData) { if(eventData.position != null) { let chatEvent = this.createEventData("minecraft:display_chat_event"); chatEvent.data.message = "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z; this.broadcastEvent("minecraft:display_chat_event", chatEvent); } }; Back to top

###

minecraft:pick_hit_result_continuous

####

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

#### Code Example:

Responding to pick_hit_result_continuous
const mySystem = client.registerSystem(0, 0); mySystem.initialize = function() { this.listenForEvent("minecraft:pick_hit_result_continuous", (eventData) => this.onPick(eventData)); }; mySystem.onPick = function(eventData) { if(eventData.position != null) { let chatEvent = this.createEventData("minecraft:display_chat_event"); chatEvent.data.message = "Pick at:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.y + " z:" + eventData.position.z; this.broadcastEvent("minecraft:display_chat_event", chatEvent); } }; Back to top

##

Trigger-able Events

###

###

minecraft:display_chat_event

####

Name | Type | Default Value | Description
--- | --- | --- | ---
message | String |  | The chat message that will be displayed

#### Code Example:

Trigger chat event
const mySystem = server.registerSystem(0, 0); mySystem.update = function() { let chatEvent = this.createEventData("minecraft:display_chat_event"); chatEvent.data.message = "Hello, World!"; this.broadcastEvent("minecraft:display_chat_event", chatEvent); }; Back to top

###

minecraft:load_ui

#### Event Data Parameters

Name | Type | Default Value | Description
--- | --- | --- | ---
options | JSON Object |  | You can define the following options for the screen by setting their value to true or false: ##### absorbs_input If true, input will not be passed down to any other screens underneathBack to top ##### always_accepts_input If true, the screen will always accept and process input for as long as it is in the stack, even if other custom UI screens appear on top of itBack to top ##### force_render_below If true, this screen will be rendered even if another screen is on top of it and will render over them, including the HUDBack to top ##### If true, the screen will be treated as the pause menu and the pause menu won't be allowed to show on top of this screenBack to top ##### render_game_behind If true, the game will continue to be rendered underneath this screenBack to top ##### render_only_when_topmost If true, this screen will only be rendered if it is the screen at the top of the stackBack to top ##### should_steal_mouse If true, the screen will capture the mouse pointer and limit its movement to the UI screenBack to top
path | String |  | The file path to the screen's HTML file

Back to top

###

minecraft:send_ui_event

Custom UI is based on HTML 5. Review the scripting demo for an example of a custom UI file.

####

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

Back to top

###

minecraft:spawn_particle_attached_entity

####

Name | Type | Default Value | Description
--- | --- | --- | ---
effect | String |  | 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
entity | Entity JS API Object |  | The entity object you want to attach the effect to
offset | Vector [a, b, c] | [0, 0, 0] | The offset from the entity's "center" where you want to spawn the effect

Back to top

###

minecraft:spawn_particle_in_world

####

Name | Type | Default Value | Description
--- | --- | --- | ---
effect | String |  | 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
position | Vector [a, b, c] | [0, 0, 0] | The position in the world where you want to spawn the effect

Back to top

###

minecraft:unload_ui

Back to top

###

minecraft:script_logger_config

####

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

Back to top

#

Server Events

##

##

Listening Events

###

###

minecraft:entity_attack

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that attacked
target | Entity JS API Object | The entity that was targeted in the attack

Back to top

###

minecraft:player_attacked_entity

####

Name | Type | Description
--- | --- | ---
attacked_entity | Entity JS API Object | The entity that was attacked by the player
player | Entity JS API Object | The player that attacked an entity

Back to top

###

minecraft:entity_acquired_item

####

Name | Type | Description
--- | --- | ---
acquired_amount | Integer | The total number of items acquired by the entity during this event
acquisition_method | String | The way the entity acquired the item
entity | Entity JS API Object | The entity who acquired the item
item_stack | ItemStack JS API Object | The item that was acquired
secondary_entity | Entity JS API Object | 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

Back to top

###

minecraft:entity_carried_item_changed

####

Name | Type | Description
--- | --- | ---
carried_item | ItemStack JS API Object | The item that is now in the entities hands
entity | Entity JS API Object | The entity that changed what they were carrying
hand | String | Defines which hand the item was equipped to. Either main or offhand.
previous_carried_item | ItemStack JS API Object | The item that was previously in the entities hands

Back to top

###

minecraft:entity_created

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that was just created

Back to top

###

minecraft:entity_definition_event

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that was affected
event | String | The event that was triggered

Back to top

###

minecraft:entity_death

####

Name | Type | Description
--- | --- | ---
block_position | JavaScript Object | The position of the block that killed the entity
cause | String | The cause of the entity's death
entity | Entity JS API Object | The entity that died
killer | Entity JS API Object | The entity that killed the entity
projectile_type | String | The type of the projectile that killed the entity

Back to top

###

minecraft:entity_dropped_item

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity who dropped the item
item_stack | ItemStack JS API Object | The item that was dropped

Back to top

###

minecraft:entity_equipped_armor

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity who is equipping the armor
item_stack | ItemStack JS API Object | The armor that is being equipped
slot | String | Defines which slot the item was equipped to.

Back to top

###

minecraft:entity_hurt

####

Name | Type | Description
--- | --- | ---
absorbed_damage | Integer | The amount the damage was reduced by by the entity's absorption effect
attacker | Entity JS API Object | Present only when damaged by an entity or projectile. The entity that attacked and caused the damage
block_position | Vector [a, b, c] | Present only when damaged by a block. This is the position of the block that hit the entity
cause | String | The way the entity took damage. Refer to the Damage Source documentation for a complete list of sources
damage | Integer | The amount of damage the entity took after immunity and armor are taken into account
entity | Entity JS API Object | The entity that took damage
projectile_type | String | Present only when damaged by a projectile. This is the identifier of the projectile that hit the entity

Back to top

###

minecraft:entity_move

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that moved

Back to top

###

minecraft:entity_sneak

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that changed their sneaking state
sneaking | Boolean | If true, the entity just started sneaking. If false, the entity just stopped sneaking

Back to top

###

minecraft:entity_start_riding

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The rider
ride | Entity JS API Object | The entity being ridden

Back to top

###

minecraft:entity_stop_riding

####

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

Back to top

###

minecraft:entity_tick

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that was ticked

Back to top

###

minecraft:entity_use_item

####

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

Back to top

###

minecraft:block_destruction_started

####

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

Back to top

###

minecraft:block_destruction_stopped

####

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

Back to top

###

minecraft:block_exploded

####

Name | Type | Description
--- | --- | ---
block_identifier | String | The identifier of the block that was destroyed
block_position | JavaScript Object | The position of the block that was destroyed by the explosion
cause | String | The cause of the block's destruction
entity | Entity JS API Object | The entity that exploded

Back to top

###

minecraft:block_interacted_with

####

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

Back to top

###

minecraft:piston_moved_block

####

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

Back to top

###

minecraft:player_destroyed_block

####

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

Back to top

###

minecraft:player_placed_block

####

Name | Type | Description
--- | --- | ---
block_position | JavaScript Object | The position of the block that was placed
player | Entity JS API Object | The player that placed the block

Back to top

###

minecraft:play_sound

####

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

Back to top

###

minecraft:projectile_hit

####

Name | Type | Description
--- | --- | ---
entity | Entity JS API Object | The entity that was hit by the projectile, if any
owner | Entity JS API Object | The entity that fired the projectile
position | Vector [a, b, c] | The position of the collision
projectile | Entity JS API Object | The projectile in question

Back to top

###

minecraft:weather_changed

####

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

Back to top

##

Trigger-able Events

###

###

minecraft:entity_definition_event

####

Name | Type | Default Value | Description
--- | --- | --- | ---
entity | Entity JS API Object |  | The entity object you want to attach the effect to
event | String |  | The identifier of the event to trigger on that entity. Both built-in (minecraft:) and custom events are supported

Back to top

###

minecraft:display_chat_event

####

Name | Type | Default Value | Description
--- | --- | --- | ---
message | String |  | The chat message that will be displayed

Back to top

###

minecraft:execute_command

####

Name | Type | Default Value | Description
--- | --- | --- | ---
command | String |  | The command that will be run

Back to top

###

minecraft:play_sound

####

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

Back to top

###

minecraft:spawn_particle_attached_entity

####

Name | Type | Default Value | Description
--- | --- | --- | ---
effect | String |  | 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
entity | Entity JS API Object |  | The entity object you want to attach the effect to
offset | Vector [a, b, c] | [0, 0, 0] | The offset from the entity's "center" where you want to spawn the effect

Back to top

###

minecraft:spawn_particle_in_world

####

Name | Type | Default Value | Description
--- | --- | --- | ---
dimension | String | overworld | The dimension in which you want to spawn the effect. Can be "overworld", "nether", or "the end"
effect | String |  | 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
position | Vector [a, b, c] | [0, 0, 0] | The position in the world where you want to spawn the effect

Back to top

###

minecraft:script_logger_config

####

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

Back to top

#

Scripting System

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

##

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

Back to top

#

Known Issues

##

Issue | Workaround
--- | ---
Scripts are not loaded properly from archived packs |
Custom UI doesn't work in VR or MR mode |
Custom UI doesn't retain state upon suspend and resume |
Exiting a world without scripts and entering one that has scripts might cause the wrong world to load |
Calling removeEntity on a dying entity might cause the game to crash |

Back to top

#

Breaking Changes

##

Category | Change
--- | ---
UI |
Components |
Events |
Events |
Events |
Events |

Back to top

#

Pre-Requisites

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/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

Back to top

#

Getting Started

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).Additionally, if your pack contains client scripts, you need to include a client_data 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.

## Folder Structure

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] } vanilla_behavior_pack
|-scripts |--client |---myClientScript.js |--server |---myServerScript.js |-manifest.json |-pack_icon.png Back to top

#

Structure of a Script

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

###

Name | Type | Description
--- | --- | ---
majorVersion | Integer | This is the major version of the Minecraft Script Engine your script was designed to work with
minorVersion | Integer | 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); Back to top

##

2. System Initialization

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. 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 }; Back to top

##

3. System Update

### Code Example:

sampleSystem.update = function() { //Update all the things }; Back to top

##

4. System Shutdown

### Code Example:

sampleSystem.shutdown = function() { //Cleanup script only things }; Back to top

#

Debugging

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

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/MinecraftBack to top

##

Real-Time (Advanced)

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.Back to top

#

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 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] }); Back to top