<本站文本内容除另有声明外,转载时均必须注明出处。(详情…中文Minecraft Wiki是完全公开的。请勇于扩充与修正内容!Minecraft中文Wiki微博正在更新!或许有兴趣去看看想与其他用户进行编辑上的沟通?社区专页正是为此创建的。翻译或创建页面之前,不妨看看译名标准化Wiki条例页面。需要管理员的协助?在管理员告示板留言也许可以帮到您。>

Minecraft Wiki:沙盒/基岩版脚本文档

来自Minecraft Wiki
跳转至: 导航搜索
Information icon.svg
此特性为基岩版独有。
Ic translate.svg
此条目的(部分)内容需要翻译。

你可以帮助我们来翻译此条目,但请勿使用机器翻译

本条目是基岩版1.12.0的脚本文档。

版本:1.12.0.28

目录

脚本执行系统[编辑源代码]

Minecraft脚本引擎(Minecraft Script Engine)(下面简称脚本引擎)使用的语言是JavaScript。

玩家可以编写Javascript脚本,与行为包捆绑在一起来监测游戏中的事件(event)、对游戏中的事件做出回应,获取、修改实体的组件(components that an entity have)的数据,以及影响Minecraft的其他方面。

Demo[编辑源代码]

这些脚本(script)是来自Mojang的脚本,有助于入门编写脚本。解压它们来查看代码,或把它们作为.mcpack格式的文件,导入游戏并游玩。

Demo 最近的更新时间 下载链接
Turn-Based RPG 2019/4/17 https://aka.ms/minecraftscripting_turnbased
Mob Arena 2019/4/17 https://aka.ms/minecraftscripting_mobarena

已知问题[编辑源代码]

下面是Minecraft脚本引擎到目前为止的已知问题的清单。

已知问题 权益方法(workaround)
Scripts are not loaded properly from archived packs 在把含脚本的行为包应用于世界之前解压它。如果导入的是拓展名为.mcpack的含脚本的行为包,它会自动被解压。
自定义UI在VR或MR模式不工作 目前自定义UI只在一般的模式下被启用
自定义UI在暂停游戏和继续游戏之间不保持状态 该问题目前没有权益方法
Exiting a world without scripts and entering one that has scripts might cause the wrong world to load 在打开另一个世界之前重启Minecraft
在濒死的实体(entity)上调用removeEntity可能会导致游戏崩溃 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)

重大变化[编辑源代码]

随着我们不断改进实验中的脚本API,我们可能会对Minecraft做出使你的脚本出问题的修改。

如果你的脚本的表现不合预期,请查阅该表格。

分类 变化
UI engine.on now takes a facet name. In order to check for the script engine starting and connect it to the UI you 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"]);

组件 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.
事件 Custom events need to be registered before using. Check the documentation for registerEventData for more information.
事件 Custom events need to have a namespace and can't use the 'minecraft' namespace. This namespace is reserved for built-in events only.
事件 Event Data is now standardized. Call createEventData to create an event data object prefilled with all the fields and default values for an event. You need this event data object to trigger any events.

准备[编辑源代码]

你希望制作自己的脚本?太好了!这一节列出了最低配置要求和建议配置要求。

注意: 脚本只在Windows 10上的基岩版上受支持。如果在不支持脚本的版本上打开含脚本的世界,就会显示不能进入该世界的错误信息。

软件 最低配置要求 建议配置要求
Minecraft Windows 10上的基岩版 Windows 10上的基岩版
代码编辑器 Visual Studio Code或其他文本编辑器 安装了“JavaScript 诊断”“JavaScript 和 TypeScript 语言支持”“实时调试器”组件的Visual Studio Community 2019
调试器 Visual Studio Community 2019
其他 Vanilla Behavior Pack(可从 https://aka.ms/behaviorpacktemplate 下载) Vanilla Behavior Pack(可从 https://aka.ms/behaviorpacktemplate 下载)
存储容量 1.0 GB 的剩余空间,以供文本编辑器、游戏和脚本占用 1.0 GB 的剩余空间,以供Visual Studio、游戏和脚本占用

开始[编辑源代码]

首先要下载最新的原版行为包(可以从 https://aka.ms/behaviorpacktemplate 下载),然后解压。

要运行的脚本应该放在行为包的scripts文件夹(的子文件夹)里,这个文件夹包含两个子文件夹:server和client。

  • server:这里的脚本在服务器端运行。生成新的实体,添加组件(component)和修改实体的组件的代码适合放在这里。
  • client:这里的脚本在客户端运行。回应事件(event)和处理因玩家而异的事务的代码适合放在这里。

无论是制作客户端脚本还是服务器脚本,只需要在对应的文件夹中创建一个拓展名为.js的空文件,之后在代码编辑器中打开。然后尽情编写代码吧!文件夹中的脚本文件的多少不限,名称也不限。各脚本文件的运行相互独立。

注意: 要在某个世界运行脚本,你必须那个世界启用“使用实验玩法”,因为该功能仍在Beta测试阶段。

当进入含客户端脚本的世界时,会有是否同意在你的设备上运行脚本的提示(this appears 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.

文件夹结构

客户端脚本所需的文件夹结构的示例

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

脚本的结构[编辑源代码]

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

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

1. System registration[编辑源代码]

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

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

客户端

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 runs as soon as the script loads at world start. You can use this to set up the environment for your script: register custom components and events, sign up event listeners, etc. This runs before the world is ready and the player has been added to it. This function should be used to initialize variables and setup event listeners. You shouldn't try to spawn or interact with any entities at this point! You should also avoid interaction with UI elements or sending messages to the chat window since this is called before the player is ready.

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

3. 系统更新[编辑源代码]

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

4. System shutdown[编辑源代码]

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

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

调试[编辑源代码]

你的脚本不能运行或不按照期望工作?别担心!我们在Minecraft脚本引擎中开发了一些调试工具,来帮助你弄明白你的脚本哪里有问题。如果你是编程新手或进一步了解调试,我们建议你阅读下面的有关用Visual Studio调试的文件: https://docs.microsoft.com/visualstudio/debugger

下面介绍了两种弄明白当脚本出问题时发生了什么的方法:游戏内(in-game)调试和实时(Real-time)调试。要进行游戏内(in-game)调试,只需要游戏和脚本;而要进行实时调试,需要一台Windows 10 PC和配置成可以进行实时调试的Visual Studio。

游戏内调试[编辑源代码]

当脚本在游戏中运行时,脚本引擎在出问题时会输出报错消息(error message)。例如,如果你尝试获取脚本引擎不知道的组件,会收到一个报错信息。要查看所有报错信息,可以打开有所有生成的报错信息的聊天框,还可以打开游戏产生的日志文件(log file)。日志文件的位置因平台而异,Windows 10上的基岩版的日志文件位于 %APPDATA%\..\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\logs

我们强烈建议你,当你开发脚本时,在你的脚本中开发进一步的的调试消息(debug message)和工具。这对你弄清楚哪里出问题有帮助。如果你需要更多帮助,可以联系官方Discord频道: https://discord.gg/Minecraft。

实时调试[编辑源代码]

如果你有一台装有Visual Studio的Windows 10 PC,你可以把Visual Studio debugger附加到Minecraft的进程,对脚本进行实时调试。Visual Studio如果安装有本文"建议配置要求"所要求的组件,那么实时调试已被安装并启用了。This tool pops up a message from Visual Studio whenever an exception occurs in your script and allow you to open Visual Studio on the line of your script that broke.

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

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

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

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

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

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

脚本API对象(Script API object)[编辑源代码]

下面介绍了脚本API返回的一些对象(object)的定义。

实体JS API对象(Entity JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"entity""item_entity"
字符串(string) __identifier__ 只读。这是该对象的命名空间ID,写作命名空间:名称的形式。例如,如果__type__值为"entity",且该对象代表的实体是牛,那么__identifier__值为minecraft:cow
正整数(positive interger) id 只读。这是所代表的实体的唯一ID(unique identifier)。

Level JS API对象(Level JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"level"
正整数(positive interger) level_id 只读。这是所代表的level的唯一ID。

组件JS API对象(Component JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"component"
JavaScript 对象(JavaScript object) data This is the content of the component.

查询JS API对象(Query JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"query"
正整数(positive interger) query_id 只读。这是所代表的查询的唯一ID。

堆叠物品JS API对象(ItemStack JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"item_stack"
字符串(string) __identifier__ 只读。这是该对象的命名空间ID,写作命名空间:名称的形式。例如,如果__type__值为"entity",且该对象代表的是牛,那么__identifier__值为minecraft:cow
字符串(string) item 只读。这是所代表的堆叠物品的物品的唯一ID。
字符串(string) count 只读。这是所代表的堆叠物品的物品数量。

方块JS API对象(Block JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"block"
字符串(string) __identifier__ 只读。这是该对象的命名空间ID,写作命名空间:名称的形式。例如,如果__type__值为"block",且该对象代表的是基岩,那么__identifier__值为minecraft:bedrock
JavaScript 对象(JavaScript object) ticking_area 只读。这是被用于获取方块信息的常加载区域JS API对象。
JavaScript 对象(JavaScript object) block_position 只读。这是方块的方向,它起唯一ID的部分作用。

参数

类型 名称 描述
整数(integer) x x坐标
整数(integer) y y坐标
整数(integer) z z坐标

常加载区域JS API对象(Ticking area JS API object)[编辑源代码]

常加载区域JS API对象共有两种:实体常加载区域JS API对象(Entity Ticking area JS API object)和level常加载区域JS API对象(Level Ticking area JS API object)。当函数要输入一个常加载区域,这两种都可以。

实体常加载区域JS API对象(Entity Ticking area JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"entity_ticking_area"
正整数(positive interger) entity_ticking_area_id 只读。这是所代表的常加载区域的唯一ID。

level常加载区域JS API对象(Level Ticking area JS API object)[编辑源代码]

类型 名称 描述
字符串(string) __type__ 只读。它明确了对象的类型。值为"level_ticking_area"
字符串(string) level_ticking_area_id 只读。这是所代表的常加载区域的唯一ID。

脚本Binding(Script bindings)[编辑源代码]

Binding是脚本引擎修改游戏中的事物的工具。

日志Binding[编辑源代码]

log[编辑源代码]

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

参数

类型 名称 描述
字符串(string) Message 希望发送到日志文件的内容(Message)
示例
Log
system.exampleFunction = function() {
	client.log("example log message") 
};

实体Binding[编辑源代码]

createEntity()[编辑源代码]

Creates an empty entity with no components and does not place it in the world. The empty entity is 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 对象(Entity JS API Object) object An object representing the newly created entity
JavaScript 对象(JavaScript object) null Something went wrong when creating the entity

createEntity(Type, TemplateIdentifier)[编辑源代码]

Creates an entity and applies the specified template as defined in JSON. This allows you to quickly create an entity from the applied Behavior Packs as the base for an entity created in scripting. The entity gets spawned into the world with all the components, component groups, and event triggers that are defined in the JSON file of the identifier specified. Only works on scripts registered on the server. NOTE: Entities are created first on the server, with the client notified of new entities 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.

参数
类型 名称 描述
字符串(string) Type Specifies the type of the entity that is being created by the template. Valid inputs are `entity` and `item_entity`
字符串(string) TemplateIdentifier This can be any of the entity identifiers from the applied Behavior Packs. For example specifying minecraft:cow here makes the provided entity a cow as defined in JSON
返回值
类型 名称 描述
实体 JS API 对象(Entity JS API Object) object An object representing the newly created entity
JavaScript 对象(JavaScript object) null Something went wrong when creating the entity

destroyEntity(EntityObject)[编辑源代码]

Destroys an entity identified by the EntityObject. If the entity exists in the world this removes 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 is no event for its death; it is simply removed.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The object that was retrieved from a call to createEntity() or retrieved from an entity event
返回值
类型 名称 描述
布尔值(boolean) true The entity was successfully destroyed
JavaScript 对象(JavaScript object) null Something went wrong when destroying the entity

isValidEntity(EntityObject)[编辑源代码]

Checks if the given EntityObject corresponds to a valid entity.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The object that was retrieved from a call to createEntity() or retrieved from an entity event
返回值
类型 名称 描述
布尔值(boolean) true The entity is in the Script Engine's database of entities
布尔值(boolean) false The entity is not in the Script Engine's database of entities
JavaScript 对象(JavaScript object) null Something went wrong when validating the entity

组件Binding[编辑源代码]

registerComponent(ComponentIdentifier, ComponentData)[编辑源代码]

创建一个只有在脚本中存在的组件。It can be then added, removed, and updated from entities.创建的自定义组件只在脚本引擎运行期间存在。

参数
类型 名称 描述
字符串(string) ComponentIdentifier 自定义组件的identifier。It is required to use a namespace so you can uniquely refer to it later without overlapping a name with a built-in component: 例如'myPack:myCustomComponent'
JavaScript 对象(JavaScript object) ComponentData A JavaScript Object that defines the name of the fields and the data each field holds inside the component.
返回值
类型 名称 描述
布尔值(boolean) true 这个组件注册成功了
JavaScript 对象(JavaScript object) null 注册这个组件时出问题了

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
字符串(string) ComponentIdentifier The identifier of the component to add to the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to registerComponent()
返回值
类型 描述
组件 JS API 对象(Component JS API Object) object An object with the following fields, and additionally, all the fields as defined in the component
JavaScript 对象(JavaScript object) null Something went wrong when creating the component

hasComponent(EntityObject, ComponentIdentifier)[编辑源代码]

Checks if the given entity has the specified component.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
字符串(string) ComponentIdentifier The identifier of the component to check on the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to registerComponent()
返回值
类型 名称 描述
布尔值(boolean) true The EntityObject has the component
布尔值(boolean) false The EntityObject doesn't have the component
JavaScript 对象(JavaScript object) null An unknown component was passed in or something else went wrong when checking if the EntityObject had the component

getComponent(EntityObject, ComponentIdentifier)[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
字符串(string) ComponentIdentifier The identifier of the component to retrieve from the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to registerComponent()
返回值
类型 名称 描述
组件 JS API 对象(Component JS API Object) object An object with the following fields, and additionally, all the fields as defined in the component

Component JS API Object

类型 名称 描述
字符串(string) __type__ 只读。 This defines the type of object. Value is: "component".
JavaScript 对象(JavaScript object) data This is the content of the component.
JavaScript 对象(JavaScript object) null The entity did not have the component or something went wrong when getting the component

applyComponentChanges(EntityObject, ComponentObject)[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The entity object that we are applying the component changes to
组件 JS API 对象(Component JS API Object) ComponentObject The component object retrieved from the entity that was returned by either createComponent() or getComponent()
返回值
类型 名称 描述
布尔值(boolean) true The component was successfully updated
JavaScript 对象(JavaScript object) null Something went wrong when updating the component

destroyComponent(EntityObject, ComponentIdentifier)[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) EntityObject The EntityObject that was retrieved from a call to createEntity() or retrieved from an event
字符串(string) ComponentIdentifier The identifier of the component to remove from the entity. This is either the identifier of a built-in component (check the Script Components section) or a custom component created with a call to registerComponent()
返回值
类型 名称 描述
布尔值(boolean) true The component was successfully removed from the entity
JavaScript 对象(JavaScript object) null The entity did not have the component or something went wrong when removing the component

事件Binding[编辑源代码]

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)[编辑源代码]

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.

参数
类型 名称 描述
字符串(string) EventIdentifier This is the identifier of the custom event we are registering. The namespace is required and can't be set to minecraft.
JavaScript 对象(JavaScript object) EventData The JavaScript object with the correct fields and default values for the event
返回值
类型 名称 描述
布尔值(boolean) true Successfully registered the event data
JavaScript 对象(JavaScript object) null Something went wrong when registering the event for listening

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.

参数
类型 名称 描述
字符串(string) EventIdentifier This is the identifier of the custom event we are registering. The namespace is required and can't be set to minecraft.
返回值
类型 名称 描述
JavaScript 对象(JavaScript object) The object containing the event data
JavaScript 对象(JavaScript object) null Something went wrong when registering the event for listening

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.

参数
类型 名称 描述
字符串(string) EventIdentifier This is the identifier of the event to which we want to react. Can be the identifier of a built-in event or a custom one from script
JavaScript 对象(JavaScript object) CallbackObject The JavaScript object to be called whenever the event is broadcast
返回值
类型 名称 描述
布尔值(boolean) true Successfully registered to listen for the event
JavaScript 对象(JavaScript object) null Something went wrong when registering the event for listening

broadcastEvent(EventIdentifier, EventData)[编辑源代码]

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

参数
类型 名称 描述
字符串(string) EventIdentifier This is the identifier of the event we want to react to. Can be the identifier of a built-in event or a custom one from script
JavaScript 对象(JavaScript object) EventData The data for the event. You can create a new JavaScript Object with the parameters you want to pass in to the listener and the engine takes care of delivering the data to them
返回值
类型 名称 描述
布尔值(boolean) true Successfully broadcasted the event
JavaScript 对象(JavaScript object) null Something went wrong when broadcasting the event

实体查询(Entity queries)Binding[编辑源代码]

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

registerQuery()[编辑源代码]

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

返回值
类型 名称 描述
查询JS API对象(Query JS API object) object An object containing the ID of the query
JavaScript 对象(JavaScript object) null Something went wrong when creating the query
示例
Query Registration
var simple_query = {};
system.initialize = function() {
	simple_query = this.registerQuery(); 
};

registerQuery(Component, ComponentField1, ComponentField2, ComponentField3)[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) Component This is the identifier of the component that is used to filter entities when
字符串(string) ComponentField1 "x" This is the name of the first field of the component that we want to filter entities by. By default this is set to x.
字符串(string) ComponentField2 "y" This is the name of the second field of the component that we want to filter entities by. By default this is set to y.
字符串(string) ComponentField3 "z" This is the name of the third field of the component that we want to filter entities by. By default this is set to z.
返回值
类型 名称 描述
查询JS API对象(Query JS API object) object An object containing the ID of the query
JavaScript 对象(JavaScript object) null Something went wrong when creating the query
示例
Query Registration
var spacial_query = {};
system.initialize = function() {
	spacial_query = this.registerQuery("minecraft:position", "x", "y", "z"); 
};

addFilterToQuery(Query, ComponentIdentifier)[编辑源代码]

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

参数
类型 名称 描述
查询JS API对象(Query JS API object) Query The object containing the ID of the query that you want to apply the filter to
字符串(string) ComponentIdentifier This is the identifier of the component that is added to the filter list. Only entities that have that component are listed in the query
示例
Query Filtering
var filtered_query = {};
system.initialize = function() {
	filtered_query = this.registerQuery(); 
	this.addFilterToQuery(filtered_query, "minecraft:explode"); 
};

getEntitiesFromQuery(Query)[编辑源代码]

Allows you to fetch the entities captured by a query.<

参数
类型 名称 描述
查询JS API对象(Query JS API object) Query This is the query you registered earlier using registerQuery()
返回值
类型 名称 描述
序列(array) 序列(array) An 序列(array) of EntityObjects representing the entities found within the query
JavaScript 对象(JavaScript object) null Something went wrong when creating the entity
示例
Entity Fetching
system.update = function() {
	let all_entities = this.getEntitiesFromQuery(simple_query);
	let exploding_creepers = this.getEntitiesFromQuery(filtered_query);
};

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

参数
类型 名称 描述
查询JS API对象(Query JS API object) Query This is the query you created earlier using registerQuery(...)
Decimal ComponentField1_Min The minimum value that the first component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField2_Min The minimum value that the second component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField3_Min The minimum value that the third component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField1_Max The maximum value that the first component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField2_Max The maximum value that the second component field needs to be on an entity for that entity to be included in the query
Decimal ComponentField3_Max The maximum value that the third component field needs to be on an entity for that entity to be included in the query
返回值
类型 名称 描述
序列(array) 序列(array) An 序列(array) of EntityObjects representing the entities found within the query
JavaScript 对象(JavaScript object) null Something went wrong when creating the entity
示例
Entity Fetching
system.update = function() {
	let player_pos_component = this.getComponent(player, "minecraft:position");
	let pos = player_pos_component.data;
	let spacial_query = this.registerQuery("minecraft:position", "x", "y", "z");
	let entities_near_player = this.getEntitiesFromQuery(spacial_query, pos.x - 10, pos.y - 10, pos.z - 10, pos.x + 10, pos.y + 10, pos.z + 10);
};

命令(Slash commands)Binding[编辑源代码]

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 is queried and executed at the end of the current frame. All data output from the command is compiled on a JavaScript Object and sent to the Callback object specified in the second parameter.

参数
类型 名称 描述
字符串(string) Command The slash command to run
JSON Object Callback The JavaScript object called after the command executes
示例
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, "    ") );
	}
};

方块Binding[编辑源代码]

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.

参数
类型 名称 描述
常加载区域JS API对象(Ticking area JS API object) Ticking Area The ticking area the block is in
整数(integer) x The x position of the block you want
整数(integer) y The y position of the block you want
整数(integer) z The z position of the block you want
返回值
类型 名称 描述
方块JS API对象(Block JS API object) object An object containing the block
JavaScript 对象(JavaScript object) null Something went wrong when retrieving the block

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.

参数
类型 名称 描述
常加载区域JS API对象(Ticking area JS API object) Ticking Area The ticking area the block is in
JavaScript 对象(JavaScript object) PositionObject A JavaScript object with the x, y, and z position of the block you want
参数
类型 名称 描述
整数(integer) x The x position
整数(integer) y The y position
整数(integer) z The z position
返回值
类型 名称 描述
方块JS API对象(Block JS API object) object An object containing the block
JavaScript 对象(JavaScript object) null Something went wrong when retrieving the block

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.

参数

类型 名称 描述
常加载区域JS API对象(Ticking area JS API object) Ticking Area The ticking area the blocks are in
整数(integer) x min The minimum x position of the blocks you want
整数(integer) y min The minimum y position of the blocks you want
整数(integer) z min The minimum z position of the blocks you want
整数(integer) x max The maximum x position of the blocks you want
整数(integer) y max The maximum y position of the blocks you want
整数(integer) z max The maximum z position of the blocks you want
返回值
类型 名称 描述
序列(array) 序列(array) A 3D 序列(array) of block objects. Indexs are the blocks positions relative to the min position given
JavaScript 对象(JavaScript object) null Something went wrong when retrieving the blocks

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.

参数
类型 名称 描述
常加载区域JS API对象(Ticking area JS API object) Ticking Area The ticking area the blocks are in
JavaScript 对象(JavaScript object) Minimum PositionObject A JavaScript object with the minimum x, y, and z position of the blocks you want
参数
类型 名称 描述
整数(integer) x The x position
整数(integer) y The y position
整数(integer) z The z position
JavaScript 对象(JavaScript object) Maximum PositionObject A JavaScript object with the maximum x, y, and z position of the blocks you want
参数
类型 名称 描述
整数(integer) x The x position
整数(integer) y The y position
整数(integer) z The z position
返回值
类型 名称 描述
序列(array) 序列(array) A 3D 序列(array) of block objects. Indexs are the blocks positions relative to the min position given
JavaScript 对象(JavaScript object) null Something went wrong when retrieving the blocks

脚本组件(script component)[编辑源代码]

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

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

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

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

Level components[编辑源代码]

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

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.

参数
类型 名称 描述
布尔值(boolean) do_weather_cycle This is the world option that determines if the vanilla weather cycle is used
Decimal rain_level A value between 0 and 1 that determains how heavy the rainfall is
整数(integer) rain_time How long it rains, in ticks
Decimal lightning_level A value between 0 and 1 that determines how much lightning and thunder there is
整数(integer) lightning_time How long lightning and thunder lasts, in ticks

服务器组件(server component)[编辑源代码]

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

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

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

minecraft:collision_box[编辑源代码]

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

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

minecraft:damage_sensor[编辑源代码]

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

参数
类型 名称 默认值 描述
List on_damage List of triggers with the events to call when taking this specific kind of damage, allows specifying filters for entity definitions and events
布尔值(boolean) deals_damage true If true, the damage dealt to the entity reduces its health; set to false to make the entity ignore that damage
字符串(string) cause Type of damage that triggers this set of events
// This example causes an entity (in this case, a creeper) to start exploding when the player attacks it.
// Note: the entity must have the damage_sensor component and the associated events defined in their JSON description.
this.listenForEvent("minecraft:player_attacked_entity", function(eventData) {
	let damageSensorComponent = serverSystem.getComponent(eventData.attacked_entity, "minecraft:damage_sensor");
	damageSensorComponent.data[0].on_damage = { event:"minecraft:start_exploding", filters:[{test:"has_component", operator:"==", value:"minecraft:breathable"}] };
	serverSystem.applyComponentChanges(eventData.attacked_entity, damageSensorComponent);
});

minecraft:equipment[编辑源代码]

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

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

minecraft:equippable[编辑源代码]

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

slots

List of slots and the item that can be equipped

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

minecraft:explode[编辑源代码]

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

参数
类型 名称 默认值 描述
Range [a, b] fuseLength [0.0, 0.0] The range for the random amount of time the fuse burns before exploding, a negative value means the explosion is immediate
Decimal power 3.0 The radius of the explosion in blocks and the amount of damage the explosion deals
Decimal maxResistance Infinite A block's explosion resistance is capped at this value when an explosion occurs
布尔值(boolean) fuseLit false If true, the fuse is already lit when this component is added to the entity
布尔值(boolean) causesFire false If true, blocks in the explosion radius are set on fire
布尔值(boolean) breaks_blocks true If true, the explosion destroys blocks in the explosion radius
布尔值(boolean) fireAffectedByGriefing false If true, whether the explosion causes fire is affected by the mob griefing game rule
布尔值(boolean) destroyAffectedByGriefing false If true, whether the explosion breaks blocks is affected by the mob griefing game rule

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

minecraft:healable[编辑源代码]

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

参数
类型 名称 默认值 描述
Array items The array of items that can be used to heal this entity
参数
类型 名称 默认值 描述
字符串(string) item Item identifier that can be used to heal this entity
整数(integer) heal_amount 1 The amount of health this entity gains when fed this item
Minecraft Filter filters The filter group that defines the conditions for using this item to heal the entity
布尔值(boolean) force_use false Determines if item can be used regardless of entity being at full health
Minecraft Filter filters The filter group that defines the conditions for this trigger

minecraft:health[编辑源代码]

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

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

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

minecraft:interact[编辑源代码]

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

参数
类型 名称 默认值 描述
Array spawn_entities An array of entity identifiers to spawn when the interaction occurs
字符串(string) on_interact An event identifier to fire when the interaction occurs
JSON Object particle_on_start Particle effect to be triggered at the start of the interaction
参数
类型 名称 默认值 描述
字符串(string) particle_type The type of particle to be spawned
Decimal particle_y_offset 0.0 Offsets the particle this amount in the y direction
布尔值(boolean) particle_offset_towards_interactor false Whether or not the particle appears closer to who performed the interaction
Decimal cooldown 0.0 Time in seconds before this entity can be interacted with again
布尔值(boolean) swing false If true, the player does the 'swing' animation when interacting with this entity
布尔值(boolean) use_item false If true, the interaction uses an item
整数(integer) hurt_item 0 The amount of damage the item takes when used to interact with this entity. A value of 0 means the item does not lose durability
字符串(string) interact_text Text to show when the player is able to interact in this way with this entity when playing with Touch-screen controls
JSON Object add_items Loot table with items to add to the player's inventory upon successful interaction
参数
类型 名称 默认值 描述
字符串(string) table File path, relative to the behavior pack's path, to the loot table file
JSON Object spawn_items Loot table with items to drop on the ground upon successful interaction
参数
类型 名称 默认值 描述
字符串(string) table File path, relative to the behavior pack's path, to the loot table file
字符串(string) transform_to_item The item used transforms to this item upon successful interaction. Format: itemName:auxValue
Array play_sounds An array of sound identifiers to play when the interaction occurs

minecraft:inventory[编辑源代码]

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

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

minecraft: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-17 is the top row of the player's inventory, 18-26 is the middle row, 27-35 is the bottom row.

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

minecraft:lookat[编辑源代码]

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

参数
类型 名称 默认值 描述
布尔值(boolean) setTarget true If true, this entity sets the attack target as the entity that looked at it
Decimal searchRadius 10.0 Maximum distance this entity can look for another entity looking at it
布尔值(boolean) mAllowInvulnerable false If true, invulnerable entities (e.g. Players in creative mode) are considered valid targets
Range [a, b] look_cooldown [0.0, 0.0] The range for the random amount of time during which the entity is 'cooling down' and won't get angered or look for a target
Minecraft Filter filters player Defines the entities that can trigger this component
字符串(string) look_event The event identifier to run when the entities specified in filters look at this entity

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

参数
类型 名称 默认值 描述
JSON Object name_actions Describes the special names for this entity and the events to call when the entity acquires those names
参数
类型 名称 默认值 描述
字符串(string) on_named Event to be called when this entity acquires the name specified in 'name_filter'
List name_filter List of special names that cause the events defined in 'on_named' to fire
字符串(string) default_trigger Trigger to run when the entity gets named
布尔值(boolean) alwaysShow false If true, the name is always be shown
布尔值(boolean) allowNameTagRenaming true If true, this entity can be renamed with name tags
字符串(string) name The current name of the entity, empty if the entity hasn't been named yet, making this non-empty applies the name to the entity

minecraft:position[编辑源代码]

該組件使您可以控制實體在世界上的位置。 使用後,實體將被傳送到指定的新位置。

参数
类型 名称 默认值 描述
Decimal x 0.0 Position along the X-Axis (east-west) of the entity
Decimal y 0.0 Position along the Y-Axis (height) of the entity
Decimal z 0.0 Position along the Z-Axis (north-south) of the entity

minecraft:rotation[编辑源代码]

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

参数
类型 名称 默认值 描述
Decimal x 0.0 Controls the head rotation looking up and down
Decimal y 0.0 Controls the body rotation parallel to the floor

minecraft:shooter[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) def Entity identifier to use as projectile for the ranged attack. The entity must have the projectile component to be able to be shot as a projectile
整数(integer) auxVal -1 ID of the Potion effect to be applied on hit

minecraft:spawn_entity[编辑源代码]

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

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

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.

参数
类型 名称 默认值 描述
布尔值(boolean) randomTeleports true If true, the entity teleports randomly
Decimal minRandomTeleportTime 0.0 Minimum amount of time in seconds between random teleports
Decimal maxRandomTeleportTime 20.0 Maximum amount of time in seconds between random teleports
数组 [a, b, c] randomTeleportCube [32.0, 16.0, 32.0] Entity teleports to a random position within the area defined by this cube
Decimal targetDistance 16.0 Maximum distance the entity can teleport when chasing a target
Decimal target_teleport_chance 1.0 The chance (0.0 to 1.0, where 1.0=100%) that the entity can teleport
Decimal lightTeleportChance 0.01 Modifies the chance that the entity can teleport if the entity is in daylight
Decimal darkTeleportChance 0.01 Modifies the chance that the entity can teleport if the entity is in darkness

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.

参数
类型 名称 描述
整数(integer) radius The radius in chunks of the ticking area
Decimal distance_to_players distance_to_players
布尔值(boolean) never_despawn Whether or not this ticking area despawns when a player is out of range
Entity Ticking Area JS API Object ticking_area The ticking area entity that is attached to this entity

客户端组件(client component)[编辑源代码]

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

minecraft:molang[编辑源代码]

The MoLang component gives access to the MoLang variables in an entity. To learn more about MoLang varibles review the add-on documentation. In scripts, you can get and set these varibles that are defined in the entity's JSON files. Because of how the MoLang variables are formatted (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);

方块组件(block 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);

用户定义的组件(User-Defined Components)[编辑源代码]

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

示例

组件注册(Component Registration)

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

脚本事件(Script events)[编辑源代码]

下面介绍了可以在脚本中监听和回应的事件。

客户端事件(Client events)[编辑源代码]

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.

参数
Type Name Description
Entity JS API Object player The player entity that joined the world
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.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was hit or null if it fired when moving off of an entity
数组 [a, b, c] position The position of the entity that was hit or null if it fired when moving off an entity
示例
system.initialize = function() {
	this.listenForEvent("minecraft:hit_result_changed", (eventData) => this.onPick(eventData)); 
};
system.onPick = function(eventData) { 
	if (eventData.position !== null) { 
		this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); 
	} 
};
minecraft:hit_result_continuous[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was hit or null if it not pointing at an entity
数组 [a, b, c] position The position of the entity that was hit or block that was hit
示例
system.initialize = function() {
	this.listenForEvent("minecraft:hit_result_continuous", (eventData) => this.onPick(eventData)); 
};
system.onPick = function(eventData) { 
	if (eventData.position !== null) { 
		this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); 
	} 
};
minecraft:pick_hit_result_changed[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was hit or null if it fired when moving off of an entity
数组 [a, b, c] position The position of the entity that was hit or null if it fired when moving off an entity
示例
system.initialize = function() {
	this.listenForEvent("minecraft:pick_hit_result_changed", (eventData) => this.onPick(eventData)); 
};
system.onPick = function(eventData) { 
	if (eventData.position !== null) { 
		this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); 
	} 
};
minecraft:pick_hit_result_continuous[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was hit or null if it not pointing at an entity
数组 [a, b, c] position The position of the entity that was hit or block that was hit
示例
system.initialize = function() {
	this.listenForEvent("minecraft:pick_hit_result_continuous", (eventData) => this.onPick(eventData)); 
};
system.onPick = function(eventData) { 
	if (eventData.position !== null) { 
		this.broadcastEvent("minecraft:display_chat_event", "Pick at x:" + eventData.position.x + " y:" + eventData.position.y + " z:" + eventData.position.z); 
	} 
};

Triggerable events[编辑源代码]

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

minecraft:display_chat_event[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) message The chat message to be displayed


minecraft:load_ui[编辑源代码]

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

Event Data 参数
类型 名称 默认值 描述
字符串(string) path The file path to the screen's HTML file
JSON Object options You can define the following options for the screen by setting their value to true or false:

always_accepts_input

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

render_game_behind

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

absorbs_input

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

is_showing_menu

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

should_steal_mouse

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

force_render_below

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

render_only_when_topmost

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

minecraft:send_ui_event[编辑源代码]

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

参数
类型 名称 描述
字符串(string) eventIdentifier The identifier of the UI event
字符串(string) data The data for the UI event being triggered
minecraft:spawn_particle_attached_entity[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) effect The identifier of the particle effect you want to attach to the entity. This is the same name you gave the effect in its JSON file
数组 [a, b, c] offset [0, 0, 0] The offset from the entity's "center" where you want to spawn the effect
实体 JS API 对象(Entity JS API Object) entity The entity object you want to attach the effect to
minecraft:spawn_particle_in_world[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) effect The identifier of the particle effect you want to attach to spawn. This is the same name you gave the effect in its JSON file
数组 [a, b, c] position [0, 0, 0] The position in the world where you want to spawn the effect
minecraft:unload_ui[编辑源代码]

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

minecraft:script_logger_config[编辑源代码]

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

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

服务器事件(Server events)[编辑源代码]

Listening events[编辑源代码]

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

minecraft:player_attacked_entity[编辑源代码]

This event is triggered whenever a player attacks an entity.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) player The player that attacked an entity
实体 JS API 对象(Entity JS API Object) attacked_entity The entity that was attacked by the player
minecraft:entity_acquired_item[编辑源代码]

This event is triggered whenever an entity acquires an item.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity who acquired the item
堆叠物品JS API对象(ItemStack JS API object) item_stack The item that was acquired
字符串(string) acquisition_method The way the entity acquired the item
整数(integer) acquired_amount The total number of items acquired by the entity during this event
实体 JS API 对象(Entity JS API Object) secondary_entity If it exists, the entity that affected the item before it was acquired. Example: A player completes a trade with a villager. The `entity` property would be the player and the `secondary_entity` would be the villager
minecraft:entity_carried_item_changed[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that changed what they were carrying
堆叠物品JS API对象(ItemStack JS API object) previous_carried_item The item that was previously in the entities hands
堆叠物品JS API对象(ItemStack JS API object) carried_item The item that is now in the entities hands
minecraft:entity_created[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was just created
minecraft:entity_death[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that died
minecraft:entity_dropped_item[编辑源代码]

This event is triggered whenever an entity drops an item.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity who dropped the item
堆叠物品JS API对象(ItemStack JS API object) item_stack The item that was dropped
minecraft:entity_equipped_armor[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity who is equipping the armor
堆叠物品JS API对象(ItemStack JS API object) item_stack The armor that is being equipped
minecraft:entity_start_riding[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The rider
实体 JS API 对象(Entity JS API Object) ride The entity being ridden
minecraft:entity_stop_riding[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was riding another entity
布尔值(boolean) exit_from_rider If true, the rider stopped riding by their own decision
布尔值(boolean) entity_is_being_destroyed If true, the rider stopped riding because they are now dead
布尔值(boolean) switching_rides If true, the rider stopped riding because they are now riding a different entity
minecraft:entity_tick[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity that was ticked
minecraft:entity_use_item[编辑源代码]

This event is triggered whenever an entity uses an item.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) entity The entity who is using the item
堆叠物品JS API对象(ItemStack JS API object) item_stack The item that is being used
字符串(string) use_method The way the entity used the item
minecraft:block_destruction_started[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) player The player that started destoying the block
JavaScript 对象(JavaScript object) block_position The position of the block that is being destroyed
minecraft:block_destruction_stopped[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) player The player that stopped destoying the block
JavaScript 对象(JavaScript object) block_position The position of the block that was being destroyed
Decimal destruction_progress How far along the destruction was before it was stopped (0 - 1 range)
minecraft:block_interacted_with[编辑源代码]

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

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) player The player that interacted with the block
JavaScript 对象(JavaScript object) block_position The position of the block that is being interacted with
minecraft:piston_moved_block[编辑源代码]

This event is triggered whenever a piston moves a block.

参数
类型 名称 描述
JavaScript 对象(JavaScript object) piston_position The position of the piston that moved the block
JavaScript 对象(JavaScript object) block_position The position of the block that was moved
字符串(string) piston_action The action the piston took, "extended" or "retracted"
minecraft:player_destroyed_block[编辑源代码]

This event is triggered whenever a player destroys a block.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) player The player that destroyed the block
JavaScript 对象(JavaScript object) block_position The position of the block that was destroyed
字符串(string) block_identifier The identifier of the block that was destroyed
minecraft:player_placed_block[编辑源代码]

This event is triggered whenever a player places a block.

参数
类型 名称 描述
实体 JS API 对象(Entity JS API Object) player The player that placed the block
JavaScript 对象(JavaScript object) block_position The position of the block that was placed
minecraft:play_sound[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) sound The identifier of the sound you want to play. Only sounds defined in the applied resource packs can be played
Decimal volume 1.0 The volume of the sound effect. A value of 1.0 plays the sound effect at the volume it was recorded at
Decimal pitch 1.0 The pitch of the sound effect. A value of 1.0 plays the sound effect with regular pitch
数组 [a, b, c] position [0, 0, 0] The position in the world we want to play the sound at
minecraft:weather_changed[编辑源代码]

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

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

Triggerable events[编辑源代码]

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

minecraft:display_chat_event[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) message The chat message to be displayed
minecraft:execute_command[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) command The command to be run
minecraft:play_sound[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) sound The identifier of the sound you want to play. Only sounds defined in the applied resource packs can be played
Decimal volume 1.0 The volume of the sound effect. A value of 1.0 plays the sound effect at the volume it was recorded at
Decimal pitch 1.0 The pitch of the sound effect. A value of 1.0 plays the sound effect with regular pitch
数组 [a, b, c] position [0, 0, 0] The position in the world we want to play the sound at
minecraft:spawn_particle_attached_entity[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) effect The identifier of the particle effect you want to attach to the entity. This is the same identifier you gave the effect in its JSON file
数组 [a, b, c] offset [0, 0, 0] The offset from the entity's "center" where you want to spawn the effect
实体 JS API 对象(Entity JS API Object) entity The entity object you want to attach the effect to
minecraft:spawn_particle_in_world[编辑源代码]

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

参数
类型 名称 默认值 描述
字符串(string) effect The identifier of the particle effect you want to attach to spawn. This is the same name you gave the effect in its JSON file
数组 [a, b, c] position [0, 0, 0] The position in the world where you want to spawn the effect
字符串(string) dimension overworld The dimension in which you want to spawn the effect. Can be "overworld", "nether", or "the end"
minecraft:script_logger_config[编辑源代码]

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

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

参见[编辑源代码]