跳到正文
龙介Longjie·

MCBE SAPI

新手上路

假期玩 MC 服务器，换整合包期间无聊外加开发组有需要，我本身是有了解过 JavaScript，于是就上手琢磨了下《我的世界》基岩版附加包（Add-on）的 Script API 开发。

开发环境部署

步骤 1：安装代码编辑器和调试器拓展

  • 自行下载和安装 Visual Studio Code；

  • 安装 Minecraft Bedrock Edition Debugger 拓展，这是用于开发过程中对部分代码进行调试的工具。通过该拓展，可以直观的看到代码运行时的情况。

    • （该拓展可根据自己需求选择性安装，不影响开发）

步骤 2：安装 Node.js 环境

步骤 3：新建行为包文件夹

  • 在资源管理器地址栏中输入下面的路径地址，打开 Win10 MCBE 的行为包开发文件夹。该文件夹可方便开发者进行开发行为包的活动，当你修改源码后不必编译打包，只需在游戏内输入/reload命令即可重新加载行为包，以便测试；

    • %localappdata%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs

  • 创建文件夹，名字随便你，这个创建的文件夹就是用来存放你开发的 Add-on 包的文件。

步骤 4：安装 NPM 包

  • 使用 Visual Studio Code 打开新建的文件夹，按下快捷键Ctrl + ~ 打开终端，输入以下命令即可安装开发所需的包。

    • npm i @minecraft/server@1.4.0-beta.1.20.10-stable

      • @minecraft/server：这部分是指定开发时所需要使用到的模块包

      • @1.4.0-beta.1.20.10-stable：这部分是该包的版本，需要与游戏版本对应！

        • 该版本号中的 1.20.10 就是对应游戏版本号
        • 请记住 1.4.0-beta 这个信息，后面要用

      • 在 @minecraft/server - versions 该页面可查看到历史版本，我们只需找到与游戏版本对应的包安装即可

    • 通过该包，开发者可在编写代码的过程中看到相关函数的注解提示内容

    • （该包可根据自己需求选择性安装，不影响开发，但是需要你有熟练的开发能力）

步骤 5：配置和使用调试器

  • （若你没有安装调试器拓展可忽略本步骤）
  • 在当前文件夹下继续新建一个名为.vscode的文件夹；
  • 进入文件夹，并新建名为launch.json文件，复制下面代码即可，无须任何改动；
{
   	"version": "0.2.0",
    "configurations": [
        {
            "type": "minecraft-js",
            "request": "attach",
            "name": "Wait for Minecraft Debug Connections",
            "mode": "listen",
            "localRoot": "${workspaceFolder}/scripts/",
            "port": 19144
        }
    ]
}
  • 当你需要用到调试器时，按下快捷键F5即可启动调试；
  • 进入游戏激活本行为包后，输入/script debugger connect localhost 19144连接成功后，即可愉快的进行调试工作了。

开始上手开发

Manifest JSON 配置文件

在行为包的主文件夹里新建行为包的清单文件manifest.json文件，该文件包含有关 Minecraft 识别它所需的包的所有基本信息。

在开始编写脚本前，需要在manifest.json文件里，写上依赖模块导入的配置信息，如下所示：

"dependencies": [
    {
        "module_name": "@minecraft/server",
        "version": "1.4.0-beta"
    }
]

里面的module_name是你写脚本时需要用到的模块；version是该模块的版本号，需要与游戏版本对应，上面步骤 4 让你记住的 1.4.0-beta 内容此时就有用了。

如果你需要用到其他模块可按照上面的环境部署步骤 4 安装好开发包，确定好版本号，分别修改module_name和version即可。

接着，我们需要继续在这个文件里写上导入脚本的配置信息，如下所示：

"modules": [
    {
        "type": "script",
        "language": "javascript",
        "uuid": "4df749f2-8fb3-2560-97a2-0c906ea84b98",
        "entry": "scripts/main.js",
        "version": [ 1, 0, 0 ]
    }
]

里面uuid是脚本模块的唯一标识符，可在线生成UUID；entry是脚本存放的路径，一般行为包脚本文件是存放在主文件夹的script目录里；version是该脚本的版本号；type和language是用来标识该模块类型为脚本模块。

完成以上部分配置即可进行脚本开发，更多相关配置项请自行查阅 Addons Documentation - manifest.json - Microsoft Learn 文档。

编写第一个脚本

在scripts/main.js中写下如下代码，当有玩家进入游戏生成后就会触发事件，在触发的事件里，如果玩家是进入游戏并非重生，则向该玩家发送一条内容为“欢迎 玩家名 进入游戏！”的消息并且执行了一条内容为say hello的指令。

import { world } from "@minecraft/server";

world.afterEvents.playerSpawn.subscribe(ev => {
    const plName = ev.player.name

    if (ev.initialSpawn) {
        ev.player.sendMessage(`欢迎 ${plName} 进入游戏！`)
        ev.player.runCommandAsync('say hello')
    }
})

测试脚本运行

完成代码编写后，我们打开游戏，创建新世界，在左侧的“实验性游戏内容”里开启“测试版 API”功能；同时在左侧的“行为包”里激活你的行为包，创造并进入游戏，你就能看见脚本运行的结果了！

**非常棒吧？**赶紧去试一下。

至此，以上是我新手上路时经历的一些过程，希望对您有参考帮助，有不足之处望您谅解，或可与我联系共同进步，祝您编码愉快！

折腾过程记录

按我习惯的学习思路，先是去 脚本API - Minecraft基岩版开发Wiki 和 Script API Reference Documentation - Microsoft Learn了解了相关知识，发现是为行为包提供的一个脚本系统。

继续深入了解，我分别从搜索引擎和 B 站大学进行了海量的相关检索，了解到大致的代码编写形式，但是我依然找不到适合我开始上手编写的非常小白的教程，大多都是功能展示和代码编写过程，根本没有给出代码编写的前置环境情况。

后面的时间里，我仍然在海量的进行检索。从原来的搜索引擎和 B 站大学拓展到了 YouTube、ChatGPT 和 Github，甚至到 MCPEDL 下载了别人写好行为包，进行解包查阅代码，结果嘛，要么是没效果要么是代码加密的。一直没得到进展，检索到的东西也是反反复复的。

当然，在这过程里，我从 YouTube 了解到一个专门开发基岩版 Add-on 的网站 bridge IDE，为我后面的 Script API 开发奠定了基础。经过我反反复复的查阅 Use Visual Studio Code tools to write script - Microsoft Learn，不断地踩坑，终于是部署好了我的开发环境！

踩完了基础的坑，接着就是踩写代码的坑了。不断海量检索还是反反复复的内容，如出一辙；不断地试错求最合适的解。

到了晚饭的点，心累到极致的我暂停了折腾，在群里吐槽我搞不动了。群聊过程中得到的信息我也基本上都看过了，但我还是忍不住又打开看了看，什么嘛又是一样的内容，心累的我只能无聊的仔细看了个遍；反复的看别人 Github 仓库的文件，脑海出现了一个新思路，会不会是版本问题？npm 安装的默认是 latest 的版本，于是我查阅了 @minecraft/server 包的版本历史发现最近的更新竟然是 3 天前！

接着又发现每个版本的命名格式有部分跟 MC 版本号是一致的，再接着的发现证实了我的猜想，在 minecraft-scripting-samples/ts-starter 这个库的自述文件里有这么一句被引用的话，是这样说的：

IMPORTANT: You may also need to update the version of Beta APIs in your dependencies section to match your version of Minecraft. Versions 1.19.40 feature 1.0.0-beta APIs Versions 1.19.50, 1.19.60, and 1.19.70 feature 1.1.0-beta APIs Versions 1.19.80 features 1.2.0-beta APIs Versions 1.20.0 features 1.3.0-beta APIs Versions 1.20.10 features 1.4.0-beta APIs Versions 1.20.20 features 1.5.0-beta APIs Future versions will likely require updated versions of Beta APIs.

根据这个猜想，我修改了相关的文件，重新下载了 npm 包，激活了写好的 Add-on 包进入游戏，Oh My God！ 成功啦！！！

折腾总结

  • 一直以来没有养成过看专业性的文档，导致我看这类文档的时候很浮躁，不够仔细；
  • 自己的能力基础不扎实，以至于看不懂文档，或者说要看几十遍才能勉强了解；
  • 最重要的一点，英文不好导致有小部分时间在理解机翻的内容。
  • 我还是太嫩了
记录于此。