教學:編寫腳本API/開始之前

開始之前

系列教學

所屬系列

編寫腳本API

難易度

初級

前置知識

• 附加包

適用版本

≥ 1.20.30

所需軟件

包的執行、除錯 ►

引言

腳本API（Script API）是Minecraft國際版中的一個腳本系統，可在附加包中實現腳本運算。

腳本API支援使用JavaScript語言（以下簡稱JS）編寫，因此其靈活性要遠大於資料驅動，可為附加包的創作提供更多可能，但腳本API無法取代資料驅動的底層註冊與定義功能，例如加入方塊、實體、物品等內容。在附加包的實際開發過程中，腳本API可以彌補資料驅動在邏輯運算方面靈活性的不足，從而實現更複雜的效果，而且可以在一定程度上減小附加包編寫過程中的繁瑣程度。同時，腳本API與Molang的對接也可以使資料驅動的靈活性更進一層。

本教學將初步幫助您了解腳本API，並完成初步的打包除錯。

開始

腳本API 本質上說不應該屬於行為或資源包，但我們將它歸類到行為包中。在清單檔案中，我們可以管理腳本api的一些基本內容，以下提供一個範例:

{
  "format_version": 2,
  "header": {
    "name": "示例",
    "description": "wiki",
    "uuid": "0e6bc13f-4fab-463f-bf10-a8be2ef591f6",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 50]
  },
  "modules": [
    {
      "type": "script",
      "language": "javascript",
      "uuid": "7807f855-db55-4878-b4ad-e5701f1cd98d",
      "entry": "scripts/Main.js",
      "version": [1, 0, 0]
    },
    {
      "description": "使游戏能识别此包为行为包",
      "type": "data",
      "uuid": "b24cd5fc-c2cc-403e-92ac-a63ffa27be77",
      "version": [1, 0, 0]
    }
  ],
  "capabilities": ["script_eval"],
  "dependencies": [
    {
      "module_name": "@minecraft/server",
      "version": "1.13.0"    // 这里写的是"1.13.0"但实际介绍中会有更高版的
    },
    {
      "module_name": "@minecraft/server-ui",
      "version": "1.2.0"    // 这里写的是"1.2.0"但实际介绍中会有更高版的
    }
  ]
}

我們來簡單觀察一下這個 清單檔案 。

首先，在 modules 中，我們看到了下面的內容:

{
  "type": "script",
  "language": "javascript",
  "uuid": "7807f855-db55-4878-b4ad-e5701f1cd98d",
  "entry": "scripts/JSMAIN.js",
  "version": [1, 0, 0]
}

• type ，這是模組的型別，script 表明這這個行為包可以使用腳本API，這是一切的基礎，沒有它，我們將無法正常地使用腳本API。
• language 表明腳本api使用的語言，指的是程式設計語言(如Python)，目前腳本api只能使用Js，這個關鍵字對應的值是 "javascript"。
• entry 指的是腳本api的入口檔案，當腳本api開始執行時，會去執行入口檔案

要注意的是:

• 入口檔案只能有一個，它的位置參考是基於清單檔案的，為了方便，我們將所有的腳本api檔案存放於 scripts 資料夾中。
• 並不是說腳本api只能執行一個檔案，透過在入口檔案中利用 export 關鍵字等進行引用，可以執行其他檔案的內容。

腳本api只需script模組便可以執行，不必再加入更多的模組，但加入data有很多的好處:

• 將腳本api打包成 .mcpack 並匯入時，如果有行為包模組，它便能成功的被當做行為包正常匯入，沒有的話只會傳回一條匯入失敗的錯誤提示
• 使用行為包模組的話就可以使自訂物品一類能與腳本更方便的互動，而不是打包成兩個包。
• 在只擁有腳本api模組的情況下‌^{[需要驗證]}，不能加入資源包依賴，而擁有了行為包模組便可以。

這便是 modules 中有關 腳本api 的內容。

繼續往下您會看見capabilities關鍵字。腳本api預設不使用eval()和Function()，當像上方範例一樣，便可使用。如果您沒有使用它們的需要，便可以刪除它。

dependencies 是可以使用的腳本api的模組，請注意，您不應該把它放在模組中。腳本api可以使用很多模組 @minecraft/server 等，它們擁有各種各樣的能力，我們在接下來的教學中會講到。

接下來我們就可以在 行為包/scripts/ 路徑下建立 Main.js 檔案便可進行腳本編寫了。

基本概念

下面介紹有關腳本api的基本概念，包括一些專有名詞，了解它們可以更好的幫助接下來的學習:

看門狗

Watchdog是腳本api的效能系統，預設情況下在啟用，它擁有強大的能力，用於保護腳本api和世界存檔。

看門狗會有以下操作:

操作	注意
監聽執行緩慢的腳本	看本狗會監聽執行緩慢的腳本，當開啟了 開發人員UI (記錄ui)後，您就會看到它傳送的警告，同時警報中還會附帶執行的延遲(毫秒級)，預設為2毫秒。
監聽腳本執行峰值	當腳本執行達到峰值時，它會發出警告
監聽腳本執行掛載	當腳本無響應時，發出警告提醒。一般情況下，它會傳回無響應時間(毫秒級)
腳本記憶體不足錯誤	當記憶體不足時，產生錯誤，看門狗會為您終止並儲存世界，以防止存檔受損，並留下記錄
監聽腳本的堆疊溢出	當發現無出口的呼叫時，終止呼叫(例如呼叫自己的函式)
監聽腳本記憶體使用	當記憶體使用達到峰值或過高時，傳回記錄和警告
強終止錯誤	當發現未處理的嚴重異常時，傳回記錄和錯誤，並終止此腳本。這一般是由於腳本長時間無響應或發現了潛在的無限呼叫

在接下來的過程中，我們會詳細介紹有關看門狗的內容，此僅作基本的錯誤參考

API

API是兩個或多個應用程式之間的一種相互或單方面的互動。腳本API是一組功能，允許我們與Minecraft進行互動。我們可以接收事件，讀取塊，修改實體，建立粒子等等。

TypeScript

TypeScript是由Microsoft開發和維護的程式設計語言。它是JavaScript的嚴格語法超集，並為語言加入了可選的靜態型別。TypeScript是為大型應用程式的開發而設計的，並可轉換為JavaScript。由於TypeScript是JavaScript的超集，因此現有的JavaScript程式也是有效的TypeScript程式。

Typescript在為Minecraft外掛開發腳本時非常有用。有一些庫可以幫助開發Minecraft外掛，為廣播和收聽事件提供智慧感知和型別安全。

我們可能在其他教學中講到這些。

引用

1. 官方文件:manifest.json
2. 官方文件:腳本api