Add-On Scripting API 入門

注意：這篇文章介紹的是舊版的Scripting API，Minecraft 1.18以後已經從遊戲中移除。

2018年加入的Scripting API (腳本API) 是用於控制Minecraft Add-On組件的腳本程式，以JavaScript寫成，可以自訂UI和對Minecraft做更進階的操作。

不過Script API只能運作在Windows 10或伺服器。

2021年，Mojang加入了Gametest Framework，舊的Scripting API稱做v1。官方在 Q&A已經表示若發展成熟，舊的Scripting API就會被取代掉，畢竟Scripting API已經N年沒更新了。可以確定的是，這些新項目將保證在手機上也能運作，而不是只限電腦。

2022年，Scripting API正式被新的Script API取代。請看： Minecraft基岩版Add-On Script API入門

1. 在manifest.json中註冊使用Scripting API
#

腳本是放在行為包中，除了註冊代表行為包的"data"外，還要使用"client_data"來註冊。

{
	"format_version": 2,
	"header": {
		"name": "Scripting API 範本包",
		"description": "Scripting API 範本包",
		"min_engine_version": [
			1,
			14,
			0
		],
		"uuid": "cd60231a-ebd3-450b-95af-2dea0034b1e0",
		"version": [
			0,
			0,
			1
		]
	},
	"modules": [
		{
			"type": "data",
			"description": "Scripting API module",
			"uuid": "3bde2b9a-051c-49ab-905e-e6eda498a34e",
			"version": [
				0,
				0,
				1
			]
		},
		//Scripting API
		{
			"type": "client_data",
			"description": "Scripting API module",
			"uuid": "fbf54196-a027-4d22-a976-c2b390c0fe94",
			"version": [
				0,
				0,
				1
			]
		}
	]
}

2. 檔案結構
#

腳本檔案放在行為包scripts/下，裡面有server和client二個資料夾，二個資料夾下又可以有個別的js，代表伺服器端和使用者端，有不同的函數可以使用。但沒有硬性規定要分client和server資料夾放。

3. 簡單的例子
#

這個範本改寫自 Bedrock Wiki

行為包scripts/server/serverScript.js，輸入:

//註冊server端的system
const systemServer = server.registerSystem(0, 0)

// 腳本完整載入後就會執行
systemServer.initialize = function () {
	// 開啟除錯訊息
	const scriptLoggerConfig = this.createEventData(
		'minecraft:script_logger_config'
	)
	scriptLoggerConfig.data.log_errors = true
	scriptLoggerConfig.data.log_information = true
	scriptLoggerConfig.data.log_warnings = true
	this.broadcastEvent('minecraft:script_logger_config', scriptLoggerConfig)

	//開始註冊事件，組件，監聽器...

	this.counter = 0
}

//  每1秒執行20次
systemServer.update = function () {
	this.counter++
	if (this.counter === 20) {
		this.log('Server!')
		this.counter = 0;
	}
}

//顯示訊息的方法
systemServer.log = function (input) {
	const chatEvent = this.createEventData('minecraft:display_chat_event')
	chatEvent.data.message = input;
	this.broadcastEvent('minecraft:display_chat_event', chatEvent)
}

// 離開世界時執行
systemServer.shutdown = function () {
}

行為包scripts/client/clientScript.js，輸入：

// 註冊client端的system
const systemClient = client.registerSystem(0, 0)

// 腳本完整載入後就會執行
systemClient.initialize = function () {
  // 開啟除錯訊息
  const scriptLoggerConfig = this.createEventData(
    'minecraft:script_logger_config'
  )
  scriptLoggerConfig.data.log_errors = true
  scriptLoggerConfig.data.log_information = true
  scriptLoggerConfig.data.log_warnings = true
  this.broadcastEvent('minecraft:script_logger_config', scriptLoggerConfig)

  // 開始註冊事件，組件，監聽器...

  this.counter = 0
}

// 每1秒執行20次
systemClient.update = function () {
  // print hello world to the world's chat once per second
  this.counter++
  if (this.counter === 20) {
    this.log('Client!')
    this.counter = 0;
  }
}

//顯示訊息的方法
systemClient.log = function(input){
  const chatEvent = this.createEventData('minecraft:display_chat_event')
	chatEvent.data.message = input;
	this.broadcastEvent('minecraft:display_chat_event', chatEvent)
}

// 離開世界時執行
systemClient.shutdown = function () {
}