Minecraft基岩版Script API入门：编写首个JS脚本

一、Script API 运行机制与前置准备

在 Minecraft 基岩版早期版本中，开发者通常依赖函数（.mcfunction）或实体组件事件（Animation Controller）来实现自定义机制。这类传统方式缺乏严密的逻辑控制与复杂数据结构支持。Script API 的引入，将标准的 JavaScript/TypeScript 执行沙盒（基于 V8 或 QuickJS）嵌入到基岩版服务端引擎中。脚本代码运行在独立的沙盒内，通过官方提供的原生接口模块（@minecraft/server）与 C++ 编写的游戏核心进行双向安全交互。

在动手编写脚本前，需要准备以下开发环境与测试条件：

• 游戏客户端：Minecraft 基岩版（Windows 10/11 平台最佳，移动端与主机端亦通用）。建议使用 1.20.0 及以上正式版，文中以通用稳定的基准版本进行配置。
• 文本与代码编辑器：Visual Studio Code 或任意支持 UTF-8 编码的纯文本编辑器。
• UUID 生成工具：每个行为包与脚本模块都需要独一无二的 UUID-v4 字符串，可使用系统命令或在线工具生成。

二、构建行为包目录与清单配置

基岩版中的脚本不能单独存在，必须封装在行为包（Behavior Pack）中。游戏引擎通过包根目录下的 manifest.json 识别包的属性，并定位脚本的入口文件。

1. 物理目录结构

首先在本地任意位置（或直接在游戏的开发行为包目录下）建立一个纯英文命名的文件夹，例如 my_first_script_bp。在该文件夹中建立以下目录树：

my_first_script_bp/
├── manifest.json
├── pack_icon.png
└── scripts/
    └── main.js

其中 pack_icon.png 为可选的材质包图标（推荐 128×128 像素的 PNG 图片），scripts/ 目录专门存放全部 JavaScript 源文件，main.js 即为首个脚本的执行入口。

2. 配置 manifest.json

在 manifest.json 中，除了常规的行为包头部信息，最关键的是声明一个类型为 script 的模块，并在 dependencies 中引入官方提供的服务端核心模块 @minecraft/server。完整的配置文件如下：

{
  "format_version": 2,
  "header": {
    "name": "首个Script API脚本包",
    "description": "Minecraft基岩版JavaScript脚本入门示例",
    "uuid": "4a7c1b24-9f81-4b77-a841-8e9f0d11c001",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 0]
  },
  "modules": [
    {
      "description": "Script Module",
      "type": "script",
      "language": "javascript",
      "uuid": "7b8d2c35-0a92-4c88-b952-9f0e1e22d002",
      "version": [1, 0, 0],
      "entry": "scripts/main.js"
    }
  ],
  "dependencies": [
    {
      "module_name": "@minecraft/server",
      "version": "1.8.0"
    }
  ]
}

三、编写首个 JavaScript 脚本

完成配置声明后，在 scripts/main.js 中编写业务代码。首个脚本的目标非常明确：当任意玩家初次进入游戏世界（生成）时，捕获该事件并向全服发送一条格式化的彩色欢迎提示。

1. 脚本完整源码

打开 scripts/main.js，输入以下代码并以 UTF-8 编码保存：

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

// 监听玩家在世界中生成的后置事件
world.afterEvents.playerSpawn.subscribe((eventData) => {
  const player = eventData.player;
  const isInitialSpawn = eventData.initialSpawn;

  // 仅在玩家初次进入世界（或首次连接）时触发，死亡重生时不重复广播
  if (isInitialSpawn) {
    // 获取玩家显示名称
    const playerName = player.name;

    // 向游戏世界公屏广播欢迎信息（支持 § 颜色代码）
    world.sendMessage(`§a[系统提示] §e欢迎玩家 §b${playerName}§e 加入世界！§r`);
    world.sendMessage("§7首个 Script API JavaScript 脚本运行成功！§r");

    // 在服务端后台日志记录确认
    console.warn(`[Script Log] 玩家 ${playerName} 已成功加载进世界。`);
  }
});

2. 代码逐行解析

• import { world, system } from "@minecraft/server";：从基岩版内置引擎注入全局对象。world 负责世界、实体、事件与维度管理；system 负责 Tick 调度与延时任务。
• world.afterEvents.playerSpawn.subscribe(...)：订阅玩家生成事件。基岩版将事件划分为 beforeEvents（前置事件）与 afterEvents（后置事件）。玩家进入世界属于已经发生的事实，因此使用 afterEvents 进行响应。
• eventData.initialSpawn：该布尔值用于区分“首次加入世界”与“死亡后在床/重生点复活”。通过条件判断，避免每次玩家死亡复活都重复刷屏。
• world.sendMessage(...)：世界级消息广播方法，字符串中支持 Minecraft 原生格式代码（如 §a 表示绿色，§b 表示水蓝，§e 表示黄色，§r 重置样式）。
• console.warn(...)：在基岩版中，console.log 在部分端可能不会直接弹窗显示，而 console.warn 会直接显示在内容日志（Content Log）的浮层中，极利于快速调试。

四、部署至游戏与测试运行

编写完毕后，需要将开发好的行为包部署至 Minecraft 的专用开发目录中，以便随时修改并热刷新测试。

1. 寻找部署目录

在 Windows 10/11 系统中，打开文件资源管理器，按下 Win + R 并在运行框中输入：

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

打开后，找到 development_behavior_packs 文件夹（若不存在可手动新建）。将先前创建的 my_first_script_bp 整个文件夹完整复制到该目录下。放置在开发目录中的包无需打包成 .mcpack，支持文件原地修改。

2. 新建测试世界并开启实验选项

这是脚本能否正常加载的核心开关。具体步骤如下：

1. 启动 Minecraft 基岩版，点击“创建新世界”；
2. 在左侧菜单切换到“实验（Experiments）”选项卡；
3. 找到“Beta APIs（测试版 API）”开关，将其切换为开启状态，并在弹出的风险确认对话框中点击确定；
4. 在左侧切换到“行为包（Behavior Packs）”面板，在“我的包”列表中找到“首个Script API脚本包”，点击“激活”；
5. 确认该包已出现在“使用中”列表后，点击“创建世界”。

五、常见问题排查与关键避坑指南

初次接触 Script API 时，容易出现进入世界后没有任何提示、脚本静默失效的现象。此时可按照以下检查清单逐一排除：

完成上述步骤后，你的基岩版客户端已经具备了完整的 JavaScript 脚本开发与实时调试环境。通过 world.afterEvents，你不仅可以监听玩家生成，还能继续探索 entityHitEntity（实体受击）、itemUse（物品使用）以及 chatSend（聊天发送）等丰富事件，逐步构建更加复杂好玩的自定义机制。