脚本API¶
这一组教程只讲国际版附加包中的脚本API。它使用@minecraft/server等@minecraft/*模块，以JavaScript或TypeScript编写行为包脚本；它不讲中国版模组SDK，也不使用mod.server.extraServerApi或mod.client.extraClientApi。
如果你已经会制作普通行为包，这里就是从“写JSON配置”迈向“写程序逻辑”的入口。本组目前先让世界自动发出消息，再把项目升级为TypeScript工程；事件、多人游戏、安全调试和服务端部署适合在脚本入口跑通后继续补充。
- 构建第一个脚本 从
manifest.json中的脚本模块开始，创建scripts/main.js，用system.runInterval让世界每隔一段时间执行一次代码。 - 使用TypeScript构建包 使用Node.js、NPM和官方TypeScript启动项目，把
main.ts编译并部署为Minecraft可加载的JavaScript。 - 脚本执行权限 了解受限执行模式与早期执行模式，学习如何用
system.run()和worldLoad事件安全地绕过权限限制。 - 脚本核心功能 事件订阅与取消、任务调度（
runInterval、runTimeout、runJob）、动态属性持久化存储，以及runCommand的用法与限制。 - 服务端表单 使用
@minecraft/server-ui向玩家弹出动作表单、消息表单和模态表单，处理玩家的选择和输入。 - 自定义命令 通过
system.beforeEvents.startup注册自定义命令，配置参数类型和权限级别。 - 服务端HTTP请求 在BDS上使用
@minecraft/server-net模块发出GET/POST HTTP请求，与外部服务集成。 - 方块放置拦截 使用
world.beforeEvents.playerPlaceBlock拦截并取消玩家的方块放置操作，实现区域保护。 - GameTest框架 用
@minecraft/server-gametest模块编写自动化测试用例，通过/gametest命令运行。 - 脚本错误排查 常见JavaScript错误类型解析、脚本API特有错误（权限不足、实体失效等），以及读取内容日志调用栈的技巧。
开始前要知道什么¶
脚本API脚本属于行为包的一部分。行为包通过manifest.json声明一个type为script的模块，并通过dependencies声明它需要的@minecraft/server等脚本模块；脚本模块的entry字段指向入口文件，例如scripts/main.js。游戏加载世界和行为包后，会执行这个入口文件。
官方入门资料使用JavaScript解释脚本基础，并建议在更复杂的项目中使用TypeScript。TypeScript本身不会被Minecraft直接执行，它必须先编译为JavaScript；这样做的好处是可以获得类型检查、自动补全、内联参考文档和更早暴露的编译错误。
推荐学习顺序¶
- 先完成构建第一个脚本，确认脚本模块能被世界加载。
- 学会使用
/reload重新加载脚本，并打开内容日志查看错误。 - 再进入使用TypeScript构建包，把项目迁移到可编译、可部署、可调试的工程结构。
- 继续查阅脚本API参考时，优先确认模块名、模块版本和稳定性标记。预览版、测试版或实验性API可能在后续版本改变。
不要混用两个生态
国际版脚本API和中国版模组SDK都能写逻辑，但它们的运行环境、语言、包结构和接口名称完全不同。本系列中的world.afterEvents、system.runInterval、@minecraft/server只适用于国际版脚本API；中国版Python脚本请阅读模组SDK系列。