脚本API¶
脚本API（Script API）是Minecraft基岩版提供的基于JavaScript的编程接口，允许附加包开发者通过编写脚本代码来与游戏世界进行交互。脚本API是附加包生态中功能最强大的扩展方式，能够实现数据驱动系统无法独立完成的复杂逻辑。
概述¶
脚本API由一系列模块（Module）组成，每个模块提供一组特定领域的功能接口。脚本代码以JavaScript文件的形式存放在行为包的scripts/目录中，游戏引擎在加载行为包时会启动一个JavaScript运行时环境来执行这些脚本。
脚本API的模块需要在行为包的清单文件中作为依赖声明，同时清单文件中需要包含一个类型为script的模块定义，并将language字段设置为javascript。
核心模块¶
脚本API的核心模块包括：
| 模块名称 | 描述 |
|---|---|
@minecraft/server | 服务端核心API，提供对实体、方块、维度、世界等游戏对象的访问和操控能力 |
@minecraft/server-ui | 服务端UI模块，提供向玩家显示表单对话框的能力 |
@minecraft/server-gametest | 游戏测试模块，提供自动化测试框架 |
@minecraft/server-admin | 服务端管理模块，提供服务器配置的访问能力 |
@minecraft/server-net | 网络模块，提供HTTP请求能力（仅BDS） |
每个模块都有独立的版本号，遵循语义版本规范。部分模块的最新版本可能以-beta后缀标识实验性版本。
事件系统¶
脚本API采用事件驱动（Event-Driven）的编程模型。开发者通过订阅特定事件来响应游戏中发生的各种情况。事件分为两类：
前置事件¶
前置事件（Before Event）在行为发生之前触发，允许脚本取消该行为。例如，world.beforeEvents.chatSend在聊天消息发送之前触发，脚本可以通过设置cancel属性来阻止消息发送。
后置事件¶
后置事件（After Event）在行为发生之后触发，不可取消，主要用于对已发生的事件进行响应。例如，world.afterEvents.entityHurt在实体受到伤害之后触发。
脚本事件¶
脚本事件（Script Event）是一种从命令系统向脚本API传递消息的机制。通过/scriptevent命令发送的事件可以被脚本通过system.afterEvents.scriptEventReceive监听和处理，从而实现命令系统与脚本逻辑之间的通信。
系统调度¶
脚本API提供了基于刻的调度机制，允许脚本按照时间计划执行逻辑：
system.runTimeout(callback, delay)：在指定的刻数后执行回调。system.runInterval(callback, interval)：每隔指定的刻数重复执行回调。system.run(callback)：在下一刻执行回调。
TypeScript支持¶
虽然游戏引擎直接执行的是JavaScript代码，但开发者可以使用TypeScript编写脚本，然后在构建阶段将TypeScript编译为JavaScript。脚本API为所有模块提供了TypeScript类型声明文件，可以通过npm安装获取，以获得完整的类型检查和代码补全支持。
脚本引擎¶
脚本引擎（Script Engine）是脚本API的前身，是一套已被弃用的早期脚本系统。旧版脚本引擎提供了client和server两个脚本上下文，使用了不同于当前脚本API的接口设计。旧版脚本引擎已在较新的游戏版本中移除，所有新开发应使用当前的脚本API。