我的世界基岩版 Script API 入门:用 @minecraft/server 给服务器写逻辑

基岩版服务端没有 Java 那样的插件,但行为包里的 Script API 可以实现事件监听、命令扩展和自定义玩法。

先给结论

Script API 是基岩版官方提供的脚本能力,脚本放在行为包内,通过 manifest 声明依赖 @minecraft/server 等模块后由服务端加载执行。它适合做事件响应、计分逻辑、传送与提示等轻量玩法。上手的关键是理解模块版本、实验开关与 BDS 的模块白名单,再用小功能逐步验证,而不是一次写完整套系统。

一、Script API 能做什么、不能做什么

Script API 运行在世界内部,能监听玩家加入、方块破坏、实体受伤、聊天等事件,并调用接口执行传送、给予物品、修改计分板、发送消息等操作。

它适合实现「规则型」玩法:新手礼包、签到奖励、区域提示、简单商店、小游戏计时与结算。这些功能过去要靠命令方块堆叠,现在可以用脚本集中维护。

它不等于 Java 版插件生态。脚本无法直接访问服务器文件系统,也不能随意建立外部网络连接,网络能力需要单独模块并受服务端配置约束。

把 Script API 当作「世界内的逻辑层」来理解最准确:它擅长处理游戏内事件,不擅长做数据库、跨服同步这类基础设施工作。

明确边界之后再设计功能,能避免写到一半才发现某个需求在脚本层根本无法实现。

二、行为包结构与 manifest 依赖

脚本必须放在行为包中,manifest 里需要一个 script 类型的模块,并指定入口文件,例如 scripts/main.js。

dependencies 中要声明依赖的脚本模块与版本,最常用的是 @minecraft/server,界面类需求可再加 @minecraft/server-ui。

模块版本必须与服务端支持的版本匹配。版本写高了,脚本会加载失败;写低了,部分新接口不可用。

标注为 beta 的模块版本通常需要在世界中开启对应实验选项,正式稳定版本则不需要。生产服务器优先使用稳定版本,减少升级时接口变动的风险。

每个包的 header uuid 与模块 uuid 都应唯一,复制模板包时最容易忘记更换,导致后加载的包被忽略。

三、BDS 的模块白名单

专用服务器对脚本模块有额外控制,配置目录下的 permissions.json 用于声明允许加载的模块列表。

如果脚本依赖的模块不在允许列表中,脚本会在服务端加载失败,而单机测试时却可能正常,这是「本地能跑、服务器不行」的常见原因。

涉及网络请求、服务器管理类的模块风险更高,只在明确需要时加入白名单,并评估脚本来源是否可信。

每次升级 BDS 后都要检查该配置文件是否被新版本覆盖或格式变化,避免升级后脚本静默失效。

把允许的模块清单写进运维文档,后续接手的人能快速判断某个脚本为什么不能运行。

四、从一个最小功能开始

第一个脚本建议只做一件事:玩家加入时发送欢迎消息。它能验证包加载、模块依赖、事件订阅三件事是否都正确。

验证通过后再加第二个功能,例如首次加入发放新手物品。此时需要考虑「首次」如何判断,可以借助计分板或动态属性记录状态。

每加一个功能就重启测试一次,确认日志中没有脚本报错。脚本错误通常会在内容日志中给出文件与行号,比猜测高效得多。

不要把所有逻辑写在一个文件里。按功能拆分文件并在入口统一导入,后续定位问题和多人协作都会轻松很多。

在测试世界里完成验证,再部署到正式世界,避免一个异常循环拖慢在线玩家。

五、性能与稳定性

脚本运行在服务端主循环中,频繁执行的逻辑会直接消耗服务器性能。每刻执行的定时任务要格外谨慎。

能用事件驱动的逻辑就不要用轮询。例如检测玩家进入区域,可以降低检测频率,而不是每刻遍历所有玩家坐标。

避免在循环中做大量实体查询或方块修改,必要时分批处理,把开销摊到多个刻里。

对异常要做捕获处理,单个功能报错不应让整套脚本停止工作。

上线后观察 TPS 与玩家反馈,若出现卡顿,先停用最近加入的脚本功能再排查。

六、版本升级与维护

Script API 随游戏版本持续演进,接口可能新增、调整或从 beta 转为稳定。每次升级前都要查看对应版本的接口变化。

建议为脚本包维护版本号,并记录它依赖的模块版本,这样升级时能快速判断哪些包需要同步修改。

升级流程应当是:测试服升级 BDS、更新脚本依赖、完整回归测试、再切换正式服。

保留上一版脚本包副本,新版本出问题时能立刻回退。

如果脚本由外部作者提供,要关注其是否持续维护,停更的脚本会成为升级阻塞点。

七、常见问题

有人问脚本放进去没反应。先确认行为包已应用到世界,再检查 manifest 的模块依赖与 BDS 允许列表,最后看内容日志报错。

还有人问能不能用脚本做经济系统。可以做基础版本,数据可以存在计分板或动态属性中,但复杂经济仍要谨慎设计回收与防刷。

也有人担心 beta 接口不稳定。生产环境尽量只用稳定版本,beta 功能先在测试服验证。

最后一个常见问题是单机正常、服务器异常。几乎都是模块白名单或版本不一致导致,按这两项排查即可。

执行步骤

  1. 明确需求是否属于世界内的事件与规则逻辑。
  2. 创建行为包,在 manifest 中添加 script 模块与入口文件。
  3. 声明 @minecraft/server 等依赖,并选择服务端支持的稳定版本。
  4. 检查 BDS 配置中的模块允许列表,加入必要模块。
  5. 先实现玩家加入欢迎消息,验证加载与事件订阅。
  6. 逐个增加功能,每次重启测试并查看内容日志。
  7. 控制高频逻辑,优先事件驱动,并做异常捕获。
  8. 记录脚本版本与依赖,升级前在测试服完整回归。

验收标准

  • 脚本在专用服务器上成功加载,日志无报错。
  • manifest 中包与模块 uuid 唯一,依赖版本正确。
  • 所需模块已在 BDS 允许列表中。
  • 每个功能都有可观察的游戏内验证结果。
  • 脚本上线后 TPS 无明显下降。
  • 脚本包有版本记录与可回退副本。

常见误区

  • 复制模板包未更换 uuid,包被忽略。
  • 依赖模块版本高于服务端支持版本。
  • 单机测试通过就上线,忽略 BDS 模块白名单。
  • 每刻轮询大量实体,造成服务器卡顿。
  • 所有逻辑写在一个文件里,难以维护与排错。
  • 升级 BDS 后不检查脚本兼容性。

Script API 让基岩版服务器第一次拥有了可维护的服务端逻辑层。从最小功能开始、控制性能开销、记录版本依赖,脚本就能成为稳定的玩法基础,而不是新的故障来源。