腳本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 特權系統 應遇而生。它可以訂閱一個事件，在事件發生後去執行程式。