Add-On Scripting API 入門

2018年加入的Scripting API (腳本API) 是用於控制Minecraft Add-On組件的腳本程式,以JavaScript寫成,可以自訂UI和對Minecraft做更進階的操作,只能運作在Windows 10上,但伺服器也會生效。

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


這篇文章以介紹Scripting API為主。


在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
			]
		}
	]
}


檔案結構

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


簡單的例子

這個範本改寫自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 () {
}

啟用這個行為包進入世界後,client和server的script會交替執行(每1秒20次),並一直輪流顯示訊息在聊天欄中。


在這裡可以觀察到,總是server端先執行,才輪到client端。

按這裡閱讀官方的Scripting API文檔

MCPEDL上用Scripting API寫成的作品

留言

此網誌的熱門文章

Minecraft基岩版多人連線教學: 方法一覽

【詳細解說】什麼是Minecraft基岩版,跟Java版有什麼差?

Minecraft基岩版安裝模組(Add-On)&資源包&光影教學