脚本API核心内容

在脚本API中，大多数核心功能都在 @minecraft/server 模块，具有许多方法来交互Minecraft世界，包括实体、块、维度等。此页面用于介绍脚本api的核心内容。有关更多内容请访问 官方文档。

设置

在进行接下来的操作前，您应该先完成以下设置。

您需要将Script模块作为依赖项添加到 manifest.json。详细流程可见 脚本API 。

关于事件

在脚本API中 @minecraft/server 模块使用自己的事件驱动体系结构，通过订阅特定事件侦听器，可以在特定事件发生时执行代码。

世界事件

World Events API提供了许多事件侦听器，当在Minecraft世界中/向特定类型的事件发生时将触发这些事件，例如 chatSend, entityHurt, playerSpawn, worldInitialize 还有更多。

要订阅事件，请获取 events 来自世界对象的属性。在下面例子中，我们将订阅blockBreak事件。

import { world } from "@minecraft/server";  //导入
//订阅blockBreak事件
//-当玩家打破一个方块时触发
world.afterEvents.playerBreakBlock.subscribe((event) => {
	const player = event.player; //打破方块的玩家
	const block = event.block; //被打破的方块
	player.sendMessage(`你打破了${block.typeId}`); //发送信息给玩家
});

系统事件

当Minecraft附加组件系统的范围内发生特定类型的事件时，系统事件将触发。

就像世界事件一样，获取 events 来自系统对象的属性。在这个例子中，我们订阅了beforeWatchdogTermnate事件，API可以取消由于超出性能边界而终止脚本执行的性能看门狗，这取决于运行时环境的配置。

import { system } from "@minecraft/server"; //导入

//订阅beforeWatchdogTernate事件

system.beforeEvents.watchdogTerminate.subscribe((event) => {
	event.cancel = true;
	console.warn('已取消严重异常' + event.terminateReason);
});

脚本事件

脚本事件(Script Events)。允许我们通过/scriptevent命令来响应入站事件scriptEventReceive事件并处理程序。

命令/scriptevent 可以用ID和消息触发脚本事件。

示例:

scriptevent wiki:test Hello World

脚本事件监听器返回:

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

system.afterEvents.scriptEventReceive.subscribe((event) => {
  const {
  	id,           //返回名 即指令中的第2个参数(wiki:test)
  	initiator,    //返回命令执行者
    message,      //返回字符串 在指令中的第3个参数(Hello World)
    sourceBlock,  //返回方块
    sourceEntity, //返回实体
    sourceType,   //返回 MessageSourceType
  } = event;
});

调度

介绍

我们可以决定不是现在执行一个函数，而是在以后的某个时间执行。这就是所谓的“调度”。

在脚本 API中，基本方法 setTimeout 和 setInterval 脚本API中不存在，而是Minecraft实现了自己的调度方法。

这些方法可以从 system 对象获得：

import { system } from "@minecraft/server";
//导入@minecraft/server

我们介绍一种方法。

调度计时器

调度计时器( system.run(callback) )本质上是一个 在指定刻度之后运行规定内容的函数 。

这通常用于实现延迟行为和游戏循环。

//示例代码
import { system, world } from "@minecraft/server";
//导入
system.run(() => {
	world.sendMessage("这条消息在下一个刻度发送");//其实就是每一个游戏刻都发送一次，直到调回停止
});

这里还有另一个函数 system.runInterval(callback, tickInterval)。它可以在每 tickInterval 个游戏刻运行一次。

import { system, world } from "@minecraft/server";
//示例代码
system.runInterval(() => {
	world.sendMessage("这条信息每20个游戏刻发送一次");
}, 20);

除此以外还有 system.runTimeout(callback, tickDelay) 函数。它可以在每 tickDelay 秒后运行一次。

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

system.runTimeout(() => {
	world.sendMessage("这条消息每20秒发送一次");
}, 20);

停止计时器

system.clearRun(runId): void 其功能是清除以前通过 run, runTimeout 或 runInterval 功能创建的计时器。

完成这个任务，需要先把前面的函数定义为常量。

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

const callbackId = system.runInterval(() => {//将函数定义为常量 callbackId
	world.sendMessage("滴答滴答滴答");
});

然后就可以使用函数 system.clearRun(runId) 。

system.runTimeout(() => {
	system.clearRun(callbackId); //停止system.runInterval回调在20个滴答后运行
	world.sendMessage("已停止");
}, 20);

完整代码

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

const callbackId = system.runInterval(() => {
	world.sendMessage("信息");
});

system.runTimeout(() => {
	system.clearRun(callbackId);
	world.sendMessage("已停止");
}, 20);

保存和加载

见 脚本API 动态属性。

运行命令

Entity.runCommandAsync() 或 Dimension.runCommandAsync() 允许脚在API从更广泛的维度的上下文异步运行特定命令。

通常，它会在下一个游戏刻度时中执行命令。要与脚本并行运行命令，必须将代码包围在异步函数中。

下面是示例:

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

(async () => {
	await world.getDimension("overworld").runCommandAsync("say Using say command on dimension.");

	world.sendMessage("这在执行RunCommandAsync之后运行。");
})();

如果排列已满则抛出错误。

避免在脚本中运行命令

通常，我们建议避免使用命令，因为从Script API运行命令会很慢，并且随着时间的推移执行更多的命令，服务器性能开始变慢。但是，以下命令功能并没有在脚本API中实现，这让我们别无选择。

关于玩家物品栏

脚本API不提供任何获取/设置玩家物品栏信息的方法。

常加载区域

脚本api不能访问滴答区。

gamerule

脚本API不能定义任何游戏规则。

设置游戏难度。

读取和设置玩家的能力。

不能向玩家播放 雾效 ，镜头晃动效果 。

NPC

脚本api不能读取/设置npc的对话，不能查看谁正在跟npc聊天，也不能向玩家发送npc对话。

Before Events 特权系统

原本我们可以在计时器的回调中运行我们需要的代码。但是，微软认为这种方式可能会引起一些问题。 所以新的替代品，Before Events 特权系统 应遇而生。它可以订阅一个事件，在事件发生后去执行程序。