脚本文档
版本：1.18.10.4

索引#

返回顶部

脚本API对象#

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

方块JS API对象#

名称	类型	方块JS API对象	描述
__identifier__	字符串		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__	字符串		READ ONLY. This defines the type of object. Will be: "block".
block_position	JavaScript对象		READ ONLY. This is the position of the block and it functions as part of its unique identifier. 参数# 名称 类型 描述 x 整数 The x position y 整数 The y position z 整数 The z position 返回顶部
ticking_area	JavaScript对象		READ ONLY. This is the ticking area object that was used to get this block.

返回顶部

组件JS API对象#

名称	类型	组件JS API对象	描述
__type__	字符串		READ ONLY. This defines the type of object. Will be: "component".
data	JavaScript对象		This is the content of the component.

返回顶部

实体JS API对象#

名称	类型	实体JS API对象	描述
__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
__type__	字符串		READ ONLY. This defines the type of object. Can be: "entity" or "item_entity".
id	正整数		READ ONLY. This is the unique identifier of the entity.

返回顶部

实体常加载区域JS API对象#

名称	类型	实体常加载区域JS API对象	描述
__type__	字符串		READ ONLY. This defines the type of object. Will be: "entity_ticking_area".
entity_ticking_area_id	正整数		READ ONLY. This is the unique identifier of the ticking area.

返回顶部

物品堆叠JS API对象#

名称	类型	物品堆叠JS API对象	描述
__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
__type__	字符串		READ ONLY. This defines the type of object. Will be: "item_stack".
count	字符串		READ ONLY. This is the number of items in the stack.
item	字符串		READ ONLY. This is the identifier of the item.

返回顶部

存档JS API对象#

名称	类型	存档JS API对象	描述
__type__	字符串		READ ONLY. This defines the type of object. Will be: "level".
level_id	正整数		READ ONLY. This is the unique identifier of the level.

返回顶部

存档常加载区域JS API对象#

名称	类型	存档常加载区域JS API对象	描述
__type__	字符串		READ ONLY. This defines the type of object. Will be: "level_ticking_area".
level_ticking_area_id	字符串		READ ONLY. This is the unique identifier of the ticking area.

返回顶部

查询JS API对象#

名称	类型	查询JS API对象	描述
__type__	字符串		READ ONLY. This defines the type of object. Will be: "query".
query_id	正整数		READ ONLY. This is the unique identifier of the query.

返回顶部

常加载区域JS API对象#

There are two types of ticking area objects. Entity and Level. When a function calls for a ticking area it can take either type as an argument.
返回顶部

脚本绑定#

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

方块绑定#

These functions define how you interact with blocks.

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.

参数#

名称	类型	描述
PositionObject	JavaScript对象	A JavaScript object with the x, y, and z position of the block you want 参数# 名称 类型 描述 x 整数 The x position y 整数 The y position z 整数 The z position 返回顶部
Ticking Area	常加载区域JS API对象	The ticking area the block is in

返回顶部

返回值#

类型	值
方块JS API对象	An object containing the block

返回顶部

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.

参数#

名称	类型	描述
Ticking Area	常加载区域JS API对象	The ticking area the block is in
x	整数	The x position of the block you want
y	整数	The y position of the block you want
z	整数	The z position of the block you want

返回顶部

返回值#

类型	值
JavaScript对象	Something went wrong when retrieving the block
方块JS API对象	An object containing the block

返回顶部

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.

参数#

名称	类型	描述
Maximum PositionObject	JavaScript对象	A JavaScript object with the maximum x, y, and z position of the blocks you want 参数# 名称 类型 描述 x 整数 The x position y 整数 The y position z 整数 The z position 返回顶部
Minimum PositionObject	JavaScript对象	A JavaScript object with the minimum x, y, and z position of the blocks you want 参数# 名称 类型 描述 x 整数 The x position y 整数 The y position z 整数 The z position 返回顶部
Ticking Area	常加载区域JS API对象	The ticking area the blocks are in

返回顶部

返回值#

类型	值
数组	A 3D array of block objects. Indexs are the blocks positions relative to the min position given
JavaScript对象	Something went wrong when retrieving the blocks

返回顶部

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.

参数#

名称	类型	描述
Ticking Area	常加载区域JS API对象	The ticking area the blocks are in
x max	整数	The maximum x position of the blocks you want
x min	整数	The minimum x position of the blocks you want
y max	整数	The maximum y position of the blocks you want
y min	整数	The minimum y position of the blocks you want
z max	整数	The maximum z position of the blocks you want
z min	整数	The minimum z position of the blocks you want

返回顶部

返回值#

类型	值
数组	A 3D array of block objects. Indexes are the blocks positions relative to the min position given
JavaScript对象	Something went wrong when retrieving the blocks

返回顶部

组件绑定#

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.

参数#

名称	类型	描述
ComponentObject	组件JS API对象	The component object retrieved from the entity that was returned by either createComponent() or getComponent()
EntityObject	实体JS API对象	The entity object that we are applying the component changes to

返回顶部

返回值#

类型	值
布尔值	The component was successfully updated

返回顶部

代码示例：

将更新应用至一个实体的组件

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);
  }
};

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.

参数#

名称	类型	描述
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()
EntityObject	实体JS API对象	The EntityObject that was retrieved from a call to createEntity() or retrieved from an event

返回顶部

返回值#

类型	值
组件JS API对象	An object with the following fields, and additionally, all the fields as defined in the 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");
    }
  }
};

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.

参数#

名称	类型	描述
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()
EntityObject	实体JS API对象	The EntityObject that was retrieved from a call to createEntity() or retrieved from an event

返回顶部

返回值#

类型	值
布尔值	The component was successfully removed from the entity

返回顶部

代码示例：

销毁一个实体的组件

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");
    }
  }
};

getComponent(EntityObject, ComponentIdentifier)#

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

参数#

名称	类型	描述
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()
EntityObject	实体JS API对象	The EntityObject that was retrieved from a call to createEntity() or retrieved from an event

返回顶部

返回值#

类型	值
组件JS API对象	An object with the following fields, and additionally, all the fields as defined in the component 组件JS API对象# 名称 类型 组件JS API对象 描述 __type__ 字符串 READ ONLY. This defines the type of object. Will be: "component". data JavaScript对象 This is the content of the 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");
    let positionComponent = this.getComponent(entity, "minecraft:position");
    if (positionComponent != null) {
      positionComponent.data.x = 0;
      positionComponent.data.y = 0;
      positionComponent.data.z = 0;
    }
  }
};

hasComponent(EntityObject, ComponentIdentifier)#

Checks if the given entity has the specified component.

参数#

名称	类型	描述
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()
EntityObject	实体JS API对象	The EntityObject that was retrieved from a call to createEntity() or retrieved from an event

返回顶部

返回值#

类型	值
布尔值	The EntityObject has the 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
    }
  }
};

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.

参数#

名称	类型	描述
ComponentData	JavaScript对象	A JavaScript Object that defines the name of the fields and the data each field holds inside the component.
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'

返回顶部

返回值#

类型	值
布尔值	The component was successfully registered

返回顶部

代码示例：

注册一个自定义组件

const mySystem = server.registerSystem(0, 0);

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

实体绑定#

createEntity()#

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

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

返回值#

类型	值
实体JS API对象	An object representing the newly created 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.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.

参数#

名称	类型	描述
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
类型	字符串	Specifies the type of the entity that is being created by the template. Valid inputs are `entity` and `item_entity`

返回顶部

返回值#

类型	值
实体JS API对象	An object representing the newly created 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.

参数#

名称	类型	描述
EntityObject	实体JS API对象	The object that was retrieved from a call to createEntity() or retrieved from an entity event

返回顶部

返回值#

类型	值
布尔值	The entity was successfully destroyed

返回顶部

isValidEntity(EntityObject)#

Checks if the given EntityObject corresponds to a valid entity.

参数#

名称	类型	描述
EntityObject	实体JS API对象	The object that was retrieved from a call to createEntity() or retrieved from an entity event

返回顶部

返回值#

类型	值
布尔值	The entity is in the Script Engine's database of entities

返回顶部

实体查询#

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.

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.

参数

名称	类型	描述
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
Query	查询JS API对象	The object containing the ID of the query that you want to apply the filter to

代码示例：

将一个过滤器添加至一个查询

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));
  }
};

返回顶部

getEntitiesFromQuery(Query)#

Allows you to fetch the entities captured by a query.

参数#

名称	类型	描述
Query	查询JS API对象	This is the query you registered earlier using registerQuery()

返回顶部

返回值#

类型	值
数组	An array of EntityObjects representing the entities found within the 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.

参数#

名称	类型	描述
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
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
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
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
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
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
Query	查询JS API对象	This is the query you created earlier using registerQuery(...)

返回顶部

返回值#

类型	值
数组	An array of EntityObjects representing the entities found within the 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));
  }
};

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.

返回值#

类型	值
查询JS API对象	An object containing the ID of the query

返回顶部

代码示例：

查询注册

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

参数#

名称	类型	默认值	描述
Component	字符串		This is the identifier of the component that will be used to filter entities when
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.
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.
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.

返回顶部

返回值#

类型	值
查询JS API对象	An object containing the ID of the query

返回顶部

代码示例：

查询注册

const mySystem = server.registerSystem(0, 0);

mySystem.initialize = function() {
  let spatialQuery = this.registerQuery("minecraft:position", "x", "y", "z");
};

事件绑定#

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.

参数#

名称	类型	描述
EventData	JavaScript对象	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	字符串	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

返回顶部

返回值#

类型	值
布尔值	Successfully broadcasted the 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);
};

createEventData(EventIdentifier)#

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

参数#

名称	类型	描述
EventIdentifier	字符串	This is the identifier of the custom event we are registering. The namespace is required and can't be set to minecraft.

返回顶部

返回值#

类型	值
JavaScript对象	The object containing the event data

返回顶部

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.

参数#

名称	类型	描述
CallbackObject	JavaScript对象	The JavaScript object that will get called whenever the event is broadcast
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

返回顶部

返回值#

类型	值
布尔值	Successfully registered to listen for the 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);
};

registerEventData(EventIdentifier, EventData)#

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

参数#

名称	类型	描述
EventData	JavaScript对象	The JavaScript object with the correct fields and default values for the event
EventIdentifier	字符串	This is the identifier of the custom event we are registering. The namespace is required and can't be set to minecraft.

返回顶部

返回值#

类型	值
布尔值	Successfully registered the event data

返回顶部

日志绑定#

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 '

参数#

名称	类型	描述
Message	字符串	The message that you want to send to the log file

返回顶部

代码示例：

日志

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

斜杠命令#

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

executeCommand(Command, Callback)#

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

名称	类型	描述
Callback	JSON对象	The JavaScript object that will be called after the command executes
Command	字符串	The slash command to run

示例

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, "    ") );
  }
};

返回顶部

脚本组件#

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.

方块组件#

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

minecraft:blockstate#

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

代码示例：

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

返回顶部

客户端组件#

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 variables review the add-on documentation. In scripts, you can get and set these variables that are defined in the entity's JSON files. Because of how the Molang variables are formatted (variable.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.

代码示例：

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

返回顶部

存档组件#

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

let levelComponent = this.getComponent(server.level, "minecraft:example_level_component");

minecraft:ticking_areas#

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

minecraft:weather#

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

名称	类型	描述
do_weather_cycle	布尔值	This is the world option that determines if the vanilla weather cycle will be used
lightning_level	小数	A value between 0 and 1 that determines how much lightning and thunder there is
lightning_time	整数	How long, in ticks, it will lightning and thunder for
rain_level	小数	A value between 0 and 1 that determains how heavy the rainfall is
rain_time	整数	How long, in ticks, it will rain for

返回顶部

服务端组件#

These are the components that run on the server and are synced with all the clients (players) in the world.
As much as possible, the API of each component matches its JSON counterpart (with some differences noted).

minecraft:armor_container#

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

// This example 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);
    }
});

返回顶部

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.

名称	类型	默认值	描述
damage	范围 [a, b]		Range of the random amount of damage the melee attack deals. A negative value can heal the entity instead of hurting it 名称 类型 默认值 描述 range_max 小数 0.0 The maximum amount of damage the entity will deal range_min 小数 0.0 The minimum amount of damage the entity will deal

返回顶部

minecraft:collision_box#

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

名称	类型	默认值	描述
height	小数	1.0	Height of the collision box in blocks. A negative value will be assumed to be 0.
width	小数	1.0	Width and Depth of the collision box in blocks. A negative value will be assumed to be 0.

返回顶部

minecraft:container#

This component represents the container of a block. The component contains an array of ItemStack JS API Objects representing each slot in the container. This specific component is used for blocks. Refer to inventory components for entities. NOTE: Currently items and containers are read-only. Slots are ordered left to right.

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

返回顶部

minecraft:damage_sensor#

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

名称	类型	默认值	描述
triggers	列表		List of triggers with the events to call when taking specific kinds of damage. 名称 类型 默认值 描述 cause 字符串 none Type of damage that triggers the events. damage_modifier 小数 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 小数 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 布尔值 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对象 Specifies filters for entity definitions and events. on_damage_sound_event 字符串 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);
});

返回顶部

minecraft:equipment#

Sets the Equipment table to use for this Entity.

名称	类型	默认值	描述
slot_drop_chance	列表		A list of slots with the chance to drop an equipped item from that slot.
table	字符串		The file path to the equipment table, relative to the behavior pack's root.

返回顶部

minecraft:equippable#

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

slots#

List of slots and the item that can be equipped.

名称	类型	默认值	描述
accepted_items	列表		The list of items that can go in this slot.
interact_text	字符串		Text to be displayed when the entity can be equipped with this item when playing with Touch-screen controls.
item	字符串		Identifier of the item that can be equipped for this slot.
on_equip	字符串		Event to trigger when this entity is equipped with this item.
on_unequip	字符串		Event to trigger when this item is removed from this entity.
slot	整数	0	The slot number of this slot.

返回顶部

minecraft:explode#

Defines how the entity explodes.

名称	类型	默认值	描述
breaks_blocks	布尔值	true	If true, the explosion will destroy blocks in the explosion radius.
causes_fire	布尔值	false	If true, blocks in the explosion radius will be set on fire.
destroy_affected_by_griefing	布尔值	false	If true, whether the explosion breaks blocks is affected by the mob griefing game rule.
fire_affected_by_griefing	布尔值	false	If true, whether the explosion causes fire is affected by the mob griefing game rule.
fuse_length	范围 [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	布尔值	false	If true, the fuse is already lit when this component is added to the entity.
max_resistance	小数	3.40282e+38	A blocks explosion resistance will be capped at this value when an explosion occurs.
power	小数	3	The radius of the explosion in blocks and the amount of damage the explosion deals.

返回顶部

minecraft:hand_container#

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

// This example 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);
    }
});

返回顶部

minecraft:healable#

Defines the interactions with this entity for healing it.

名称	类型	默认值	描述
filters	Minecraft过滤器		The filter group that defines the conditions for using this item to heal the entity.
force_use	布尔值	false	Determines if item can be used regardless of entity being at full health.
items	数组		The array of items that can be used to heal this entity. 名称 类型 默认值 描述 heal_amount 整数 1 The amount of health this entity gains when fed this item. item 字符串 Item identifier that can be used to heal this 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.

名称	类型	默认值	描述
max	整数	10	The maximum health the entity can heal
value	整数	1	Current health of the entity

返回顶部

minecraft:hotbar_container#

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

// 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);
    }
});

返回顶部

minecraft:interact#

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

名称	类型	默认值	描述
add_items	JSON对象		Loot table with items to add to the player's inventory upon successful interaction 名称 类型 默认值 描述 table 字符串 File path, relative to the behavior pack's path, to the loot table file
cooldown	小数	0.0	Time in seconds before this entity can be interacted with again
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
interact_text	字符串		Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
on_interact	字符串		An event identifier to fire when the interaction occurs
particle_on_start	JSON对象		Particle effect that will be triggered at the start of the interaction 名称 类型 默认值 描述 particle_offset_towards_interactor 布尔值 false Whether or not the particle will appear closer to who performed the interaction particle_type 字符串 The type of particle that will be spawned particle_y_offset 小数 0.0 Will offset the particle this amount in the y direction
play_sounds	数组		An array of sound identifiers to play when the interaction occurs
spawn_entities	数组		An array of entity identifiers to spawn when the interaction occurs
spawn_items	JSON对象		Loot table with items to drop on the ground upon successful interaction 名称 类型 默认值 描述 table 字符串 File path, relative to the behavior pack's path, to the loot table file
swing	布尔值	false	If true, the player will do the 'swing' animation when interacting with this entity
transform_to_item	字符串		The item used will transform to this item upon successful interaction. Format: itemName:auxValue
use_item	布尔值	false	If true, the interaction will use an item

返回顶部

minecraft:inventory#

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

名称	类型	默认值	描述
additional_slots_per_strength	整数	0	Number of slots that this entity can gain per extra strength
can_be_siphoned_from	布尔值	false	If true, the contents of this inventory can be removed by a hopper
container_type	字符串	none	Type of container this entity has. Can be horse, minecart_chest, minecart_hopper, inventory, container or hopper
inventory_size	整数	5	Number of slots the container has
private	布尔值	false	If true, only the entity can access the inventory
restrict_to_owner	布尔值	false	If true, the entity's inventory can only be accessed by its owner or itself

返回顶部

minecraft:inventory_container#

This component represents the inventory contents of an entity. The component contains an array of ItemStack JS API Objects representing each slot in the inventory. NOTE: Currently items and containers are read-only.Slot 0-8 is the hotbar, 9-16 is the top row of the player's inventory, 17-24 is the middle row, 25-32 is the bottom row

// 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);
    }
});

返回顶部

minecraft:lookat#

Defines the behavior when another entity looks at this entity.

名称	类型	默认值	描述
allow_invulnerable	布尔值	false	If true, invulnerable entities (e.g. Players in creative mode) are considered valid targets.
filters	Minecraft过滤器		Defines the entities that can trigger this component.
look_cooldown	范围 [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	字符串		The event identifier to run when the entities specified in filters look at this entity.
search_radius	小数	10	Maximum distance this entity will look for another entity looking at it.
set_target	布尔值	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'.

名称	类型	默认值	描述
allow_name_tag_renaming	布尔值	true	If true, this entity can be renamed with name tags
always_show	布尔值	false	If true, the name will always be shown
default_trigger	字符串		Trigger to run when the entity gets named
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
name_actions	JSON对象		Describes the special names for this entity and the events to call when the entity acquires those names 名称 类型 默认值 描述 name_filter 列表 List of special names that will cause the events defined in 'on_named' to fire on_named 字符串 Event to be called when this entity acquires the name specified in 'name_filter'

返回顶部

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.

名称	类型	默认值	描述
x	小数	0.0	Position along the X-Axis (east-west) of the entity
y	小数	0.0	Position along the Y-Axis (height) of the entity
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.

名称	类型	默认值	描述
x	小数	0.0	Controls the head rotation looking up and down
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.

名称	类型	默认值	描述
auxVal	整数	-1	ID of the Potion effect to be applied on hit
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

返回顶部

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

名称	类型	默认值	描述
filters	Minecraft过滤器		If present, the specified entity will only spawn if the filter evaluates to true.
max_wait_time	整数	600	Maximum amount of time to randomly wait in seconds before another entity is spawned.
min_wait_time	整数	300	Minimum amount of time to randomly wait in seconds before another entity is spawned.
num_to_spawn	整数	1	The number of entities of this type to spawn each time that this triggers.
should_leash	布尔值	false	If true, this the spawned entity will be leashed to the parent.
single_use	布尔值	false	If true, this component will only ever spawn the specified entity once.
spawn_entity	字符串		Identifier of the entity to spawn, leave empty to spawn the item defined by "spawn_item" instead.
spawn_event	字符串	minecraft:entity_born	Event to call when the entity is spawned.
spawn_item	字符串	egg	Item identifier of the item to spawn.
spawn_method	字符串	born	Method to use to spawn the entity.
spawn_sound	字符串	plop	Identifier of the sound effect to play when the entity is spawned.

返回顶部

minecraft:tag#

The tag component gives access to the array of entity tags that an entity may have. With this component you can add and remove any of the entity tags.
返回顶部

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.

名称	类型	默认值	描述
dark_teleport_chance	小数	0.01	Modifies the chance that the entity will teleport if the entity is in darkness
light_teleport_chance	小数	0.01	Modifies the chance that the entity will teleport if the entity is in daylight
max_random_teleport_time	小数	20	Maximum amount of time in seconds between random teleports
min_random_teleport_time	小数	0	Minimum amount of time in seconds between random teleports
random_teleport_cube	向量 [a, b, c]	[32, 16, 32]	Entity will teleport to a random position within the area defined by this cube
random_teleports	布尔值	true	If true, the entity will teleport randomly
target_distance	小数	16	Maximum distance the entity will teleport when chasing a target
target_teleport_chance	小数	1	The chance that the entity will teleport between 0.0 and 1.0. 1.0 means 100%

返回顶部

minecraft:tick_world#

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

名称	类型	描述
distance_to_players	小数	The distance a player needs to be within for the ticking area to be active. The distance is ignored if the ticking area is set to never despawn
never_despawn	布尔值	Whether or not this ticking area will despawn when a player is out of range
radius	整数	The radius in chunks of the ticking area
ticking_area	实体常加载区域JS API对象	The ticking area entity that is attached to this entity

返回顶部

minecraft:ticking_area_description#

Describes the ticking area's region.

名称	类型	默认值	描述
is_circle	布尔值		Is the area a circle. If false the area is a square.
max	向量 [a, b, c]		(if area is a square) The edge of the area.
name	字符串		The name of the area.
origin	向量 [a, b, c]		The origin position of the area.
radius	向量 [a, b, c]		(if area is a circle) The radius of the area.

返回顶部

脚本事件#

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

客户端事件#

Listening Events#

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

minecraft:client_entered_world#

This event is fired whenever a player joins the world. The event data contains the player entity object.
返回顶部

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.

名称	类型	描述
entity	实体JS API对象	The entity that was hit or null if it fired when moving off of an entity
position	向量 [a, b, c]	The position of the entity that was hit or null if it fired when moving off an entity

代码示例：

对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);
  }
};

返回顶部

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.

名称	类型	描述
entity	实体JS API对象	The entity that was hit or null if it not pointing at an entity
position	向量 [a, b, c]	The position of the entity that was hit or block that was hit

代码示例：

对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);
  }
};

返回顶部

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.

名称	类型	描述
entity	实体JS API对象	The entity that was hit or null if it fired when moving off of an entity
position	向量 [a, b, c]	The position of the entity that was hit or null if it fired when moving off an entity

代码示例：

对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);
  }
};

返回顶部

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.

名称	类型	描述
entity	实体JS API对象	The entity that was hit or null if it not pointing at an entity
position	向量 [a, b, c]	The position of the entity that was hit or block that was hit

代码示例：

对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);
  }
};

返回顶部

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.

名称	类型	默认值	描述
message	字符串		The chat message that will be displayed

代码示例：

触发聊天事件

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);
};

返回顶部

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 screen will be shown immediately after the event is triggered. Only screens defined in a HTML file can be shown using this event.

Event Data Parameters

名称	类型	默认值	描述
options	JSON对象		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 underneath 返回顶部 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 it 返回顶部 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 HUD 返回顶部 is_showing_menu# 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 screen 返回顶部 render_game_behind# If true, the game will continue to be rendered underneath this screen 返回顶部 render_only_when_topmost# If true, this screen will only be rendered if it is the screen at the top of the stack 返回顶部 should_steal_mouse# If true, the screen will capture the mouse pointer and limit its movement to the UI screen 返回顶部
path	字符串		The file path to the screen's HTML file

返回顶部

minecraft:script_logger_config#

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

名称	类型	默认值	描述
log_errors	布尔值	false	Set to true to log any scripting errors that occur on the client
log_information	布尔值	false	Set to true to log any general scripting information that occurs on the client. This includes any logging done with client.log()
log_warnings	布尔值	false	Set to true to log any scripting warnings that occur on the client

返回顶部

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.

名称	类型	描述
data	字符串	The data for the UI event being triggered
eventIdentifier	字符串	The identifier of the UI event

返回顶部

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.

名称	类型	默认值	描述
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
entity	实体JS API对象		The entity object you want to attach the effect to
offset	向量 [a, b, c]	[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.

名称	类型	默认值	描述
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
position	向量 [a, b, c]	[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.
返回顶部

服务端事件#

Listening Events#

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

minecraft:block_destruction_started#

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

名称	类型	描述
block_position	JavaScript对象	The position of the block that is being destroyed
player	实体JS API对象	The player that started destoying the block

返回顶部

minecraft:block_destruction_stopped#

This event is triggered whenever a player stops destroying a block.

名称	类型	描述
block_position	JavaScript对象	The position of the block that was being destroyed
destruction_progress	小数	How far along the destruction was before it was stopped (0 - 1 range)
player	实体JS API对象	The player that stopped destoying the block

返回顶部

minecraft:block_exploded#

This event is triggered whenever a block is destroyed by an explosion.

名称	类型	描述
block_identifier	字符串	The identifier of the block that was destroyed
block_position	JavaScript对象	The position of the block that was destroyed by the explosion
cause	字符串	The cause of the block's destruction
entity	实体JS API对象	The entity that exploded

返回顶部

minecraft:block_interacted_with#

This event is triggered whenever a player interacts with a block.

名称	类型	描述
block_position	JavaScript对象	The position of the block that is being interacted with
player	实体JS API对象	The player that interacted with the block

返回顶部

minecraft:entity_acquired_item#

This event is triggered whenever an entity acquires an item.

名称	类型	描述
acquired_amount	整数	The total number of items acquired by the entity during this event
acquisition_method	字符串	The way the entity acquired the item
entity	实体JS API对象	The entity who acquired the item
item_stack	物品堆叠JS API对象	The item that was acquired
secondary_entity	实体JS API对象	If it exists, the entity that affected the item before it was acquired. Example: A player completes a trade with a villager. The `entity` property would be the player and the `secondary_entity` would be the villager

返回顶部

minecraft:entity_attack#

This event is triggered whenever an entity is being attacked by another entity. This does not guarantee the entity was or will be hurt by the attack.

名称	类型	描述
entity	实体JS API对象	The entity that attacked
target	实体JS API对象	The entity that was targeted in the attack

返回顶部

minecraft:entity_carried_item_changed#

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

名称	类型	描述
carried_item	物品堆叠JS API对象	The item that is now in the entities hands
entity	实体JS API对象	The entity that changed what they were carrying
hand	字符串	Defines which hand the item was equipped to. Either main or offhand.
previous_carried_item	物品堆叠JS API对象	The item that was previously in the entities hands

返回顶部

minecraft:entity_created#

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

名称	类型	描述
entity	实体JS API对象	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). Not all of these values are present with every entity death.

名称	类型	描述
block_position	JavaScript对象	The position of the block that killed the entity
cause	字符串	The cause of the entity's death
entity	实体JS API对象	The entity that died
killer	实体JS API对象	The entity that killed the entity
projectile_type	字符串	The type of the projectile that killed the entity

返回顶部

minecraft:entity_definition_event#

This event is triggered whenever an entity definition event is triggered by either script or the entity's JSON.

名称	类型	描述
entity	实体JS API对象	The entity that was affected
event	字符串	The event that was triggered

返回顶部

minecraft:entity_dropped_item#

This event is triggered whenever an entity drops an item.

名称	类型	描述
entity	实体JS API对象	The entity who dropped the item
item_stack	物品堆叠JS API对象	The item that was dropped

返回顶部

minecraft:entity_equipped_armor#

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

名称	类型	描述
entity	实体JS API对象	The entity who is equipping the armor
item_stack	物品堆叠JS API对象	The armor that is being equipped
slot	字符串	Defines which slot the item was equipped to.

返回顶部

minecraft:entity_hurt#

This event is triggered whenever an entity is hurt.

名称	类型	描述
absorbed_damage	整数	The amount the damage was reduced by by the entity's absorption effect
attacker	实体JS API对象	Present only when damaged by an entity or projectile. The entity that attacked and caused the damage
block_position	向量 [a, b, c]	Present only when damaged by a block. This is the position of the block that hit the entity
cause	字符串	The way the entity took damage. Refer to the Damage Source documentation for a complete list of sources
damage	整数	The amount of damage the entity took after immunity and armor are taken into account
entity	实体JS API对象	The entity that took damage
projectile_type	字符串	Present only when damaged by a projectile. This is the identifier of the projectile that hit the entity

返回顶部

minecraft:entity_sneak#

This event is triggered whenever an entity flag's value changes.

名称	类型	描述
entity	实体JS API对象	The entity that changed their sneaking state
sneaking	布尔值	If true, the entity just started sneaking. If false, the entity just stopped sneaking

返回顶部

minecraft:entity_start_riding#

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

名称	类型	描述
entity	实体JS API对象	The rider
ride	实体JS API对象	The entity being ridden

返回顶部

minecraft:entity_stop_riding#

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

名称	类型	描述
entity	实体JS API对象	The entity that was riding another entity
entity_is_being_destroyed	布尔值	If true, the rider stopped riding because they are now dead
exit_from_rider	布尔值	If true, the rider stopped riding by their own decision
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.

名称	类型	描述
entity	实体JS API对象	The entity that was ticked

返回顶部

minecraft:entity_use_item#

This event is triggered whenever an entity uses an item.

名称	类型	描述
entity	实体JS API对象	The entity who is using the item
item_stack	物品堆叠JS API对象	The item that is being used
use_method	字符串	The way the entity used the item

返回顶部

minecraft:piston_moved_block#

This event is triggered whenever a piston moves a block.

名称	类型	描述
block_position	JavaScript对象	The position of the block that was moved
piston_action	字符串	The action the piston took, "extended" or "retracted"
piston_position	JavaScript对象	The position of the piston that moved the block

返回顶部

minecraft:play_sound#

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

名称	类型	默认值	描述
pitch	小数	1.0	The pitch of the sound effect. A value of 1.0 will play the sound effect with regular pitch
position	向量 [a, b, c]	[0, 0, 0]	The position in the world we want to play the sound at
sound	字符串		The identifier of the sound you want to play. Only sounds defined in the applied resource packs can be played
volume	小数	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

返回顶部

minecraft:player_attacked_entity#

This event is triggered whenever a player attacks an entity.

名称	类型	描述
attacked_entity	实体JS API对象	The entity that was attacked by the player
player	实体JS API对象	The player that attacked an entity

返回顶部

minecraft:player_destroyed_block#

This event is triggered whenever a player destroys a block.

名称	类型	描述
block_identifier	字符串	The identifier of the block that was destroyed
block_position	JavaScript对象	The position of the block that was destroyed
player	实体JS API对象	The player that destroyed the block

返回顶部

minecraft:player_placed_block#

This event is triggered whenever a player places a block.

名称	类型	描述
block_position	JavaScript对象	The position of the block that was placed
player	实体JS API对象	The player that placed the block

返回顶部

minecraft:projectile_hit#

This event is triggered whenever a projectile hits something.

名称	类型	描述
entity	实体JS API对象	The entity that was hit by the projectile, if any
owner	实体JS API对象	The entity that fired the projectile
position	向量 [a, b, c]	The position of the collision
projectile	实体JS API对象	The projectile in question

返回顶部

minecraft:weather_changed#

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

名称	类型	描述
dimension	字符串	The name of the dimension where the weather change happened
lightning	布尔值	Tells if the new weather has lightning
raining	布尔值	Tells if the new weather has rain

返回顶部

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.

名称	类型	默认值	描述
message	字符串		The chat message that will be displayed

返回顶部

minecraft:entity_definition_event#

This event is used to trigger events that Entity Definition JSON files are listening for. For example, you can trigger the minecraft:become_charged event on a creeper to turn it into a charged creeper.

名称	类型	默认值	描述
entity	实体JS API对象		The entity object you want to attach the effect to
event	字符串		The identifier of the event to trigger on that entity. Both built-in (minecraft:) and custom events are supported

返回顶部

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.

名称	类型	默认值	描述
command	字符串		The command that will be run

返回顶部

minecraft:play_sound#

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

名称	类型	默认值	描述
pitch	小数	1.0	The pitch of the sound effect. A value of 1.0 will play the sound effect with regular pitch
position	向量 [a, b, c]	[0, 0, 0]	The position in the world we want to play the sound at
sound	字符串		The identifier of the sound you want to play. Only sounds defined in the applied resource packs can be played
volume	小数	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

返回顶部

minecraft:script_logger_config#

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

名称	类型	默认值	描述
log_errors	布尔值	false	Set to true to log any scripting errors that occur on the server
log_information	布尔值	false	Set to true to log any general scripting information that occurs on the server. This includes any logging done with server.log()
log_warnings	布尔值	false	Set to true to log any scripting warnings that occur on the server

返回顶部

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.

名称	类型	默认值	描述
effect	字符串		The identifier of the particle effect you want to attach to the entity. This is the same identifier you gave the effect in its JSON file
entity	实体JS API对象		The entity object you want to attach the effect to
offset	向量 [a, b, c]	[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.

名称	类型	默认值	描述
dimension	字符串	overworld	The dimension in which you want to spawn the effect. Can be "overworld", "nether", or "the end"
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
position	向量 [a, b, c]	[0, 0, 0]	The position in the world where you want to spawn the effect

返回顶部

脚本系统#

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.

破坏性变更#

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

分类	变更
组件	Calls to getComponent now return the component's parameters inside of the 'data' parameter of the return object.
事件	Event data objects now hold the event's parameters inside of the 'data' parameter of the event data object.
UI	engine.on now takes a facet name. In order to check for the script engine starting and connect it to the UI you will need the following: engine.on("facet:updated:core.scripting", ...); Followed by the following line after you are done doing your initialization: engine.trigger("facet:request", ["core.scripting"]);

返回顶部

调试#

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.

游戏内#

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 ' %APPDATA%\..\Local\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
返回顶部

实时（高级）#

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.
返回顶部

演示#

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

演示	最后更新	下载链接
生物竞技场	2018年10月24日	https://aka.ms/minecraftscripting_mobarena
回合制RPG	2018年10月24日	https://aka.ms/minecraftscripting_turnbased

返回顶部

准备开始#

First you will need to download the latest Vanilla Behavior Pack. You can get this from the following link: https://aka.ms/behaviorpacktemplate
Once you have downloaded the Behavior Pack, unzip it to a folder. Inside the Behavior Pack 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

客户端脚本所需的清单模块的示例

        {
            "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

返回顶部

已知问题#

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

问题	解决方案
Calling removeEntity on a dying entity might cause the game to crash	Don't call removeEntity the same frame you reduced the entity's damage to 0. Removing the entity forces it to be removed right away. Instead, save any dying entities and clean the up on the next frame (See the Turn-Based Demo for an example of this)
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
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

返回顶部

开始之前#

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.

软件	最低	推荐
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

返回顶部

一个脚本的结构#

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. 系统注册#

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.

名称	类型	描述
majorVersion	整数	This is the major version of the Minecraft Script Engine your script was designed to work with
minorVersion	整数	This is the revision of the Minecraft Script Engine your script was designed to work with

代码示例：

客户端系统

let sampleClientSystem = client.registerSystem(0, 0);

服务端系统

let sampleServerSystem = server.registerSystem(0, 0);

返回顶部

2. 系统初始化#

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

代码示例：

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

返回顶部

2. 系统更新#

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.

代码示例：

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

返回顶部

2. 系统停机#

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.

代码示例：

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

返回顶部

用户自定义组件#

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.

代码示例：

组件注册

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

返回顶部