模組API

From Minecraft基岩版开发Wiki

模組APIModAPI)是網易為了使開發人員能夠結合自訂遊戲內容對遊戲進行更深入的監測與修改而開發的一套API,是模組SDK的一部分。與其同時被開發的姊妹API還有專門針對網路伺服器遊戲管理的網路遊戲開服工具

基本內容介紹[edit]

模組API使用Python語言編寫,其基本執行方式與原版的腳本引擎(Script Engine)類似,都採用Client-Server(即用戶端-伺服器端)結構。伺服器端負責資料的管理與邏輯的計算,而用戶端負責完成與使用者的互動任務。舉個通俗的例子,玩家在遊戲裡遇到一隻殭屍,這隻殭屍的外觀、被攻擊時的粒子效果由用戶端繪製,而這隻殭屍的內部屬性(如位置,血量,速度等)和它的行為(如攻擊玩家,在太陽下燃燒等)則由伺服器端控制,兩者的分工負責非常明確,可用的事件和元件也有很大不同。而每個端的執行流程又大致為[監聽事件-#響應事件-回呼函式-執行邏輯(呼叫元件)#-銷毀事件](其中##部分為循環部分),其中內建事件和元件皆為網易封裝好的方法。

系統[edit]

系統是整個模組API的核心基礎,所有操作都必須基於系統之上進行。

系統System是我們的核心類,用於監聽事件,使用元件,更新等。 取得自訂的System需要繼承引擎的系統基類 ClientSystem/ServerSystem.

——網易開發人員文件

模組API中並不是所有的介面都經過API庫執行,有部分底層操作方法如取得執行平台、所有事件相關操作、建立物品實體、建立粒子效果等等都使用System類自帶的方法執行。

事件[edit]

事件,指在遊戲內觸發了某個操作或達到某一種條件時遊戲向引擎傳送的包含傳回值的資訊,如監測玩家升級的AddLevelEvent附帶[玩家ID][增加的等級值][新等級]三個傳回值。所有傳回值皆可透過預先在回呼函式中設定的參數讀取。在模組API中,所有事件皆使用ListenForEvent方法監聽UnListenForEvent方法反監聽

在網易的腳本系統中,用戶端和伺服器端實際上擁有很多觸發時機相同的事件,但其中部分型別相同的事件物件又不同,開發人員可根據自身需要選擇相應的部分進行監聽。

事件依賴於系統,事件需要系統才能監聽觸發,因此在使用事件之前需要先擁有自己的系統system。事件分為定義事件、監聽事件、反監聽、發布事件和響應事件。
定義事件
定義事件分為引擎定義的事件和自訂事件。引擎定義的事件不需要定義可以直接使用。自訂函式DefineEvent(新版中此函式已廢棄).
監聽事件
監聽事件的含義是將回呼函式註冊到事件上,當事件發生時主動呼叫該回呼函式。監聽函式ListenForEvent.
反監聽事件
監聽完畢後需要自行反監聽該事件(即銷毀事件)在System的Destroy函式中。反監聽函式UnListenForEvent.
發布事件
發布事件是指,在事件發生時發布這個事件通知所有監聽了這個事件的回呼函式。引擎定義的事件會在引擎事件發生時自動發布,自訂事件的發布需要先DefineEvent後才能發布(已廢棄,新版可以直接發布),需要先CreateEventData建立事件資料,發布函式有BroadcastEvent / NotifyToClient / BroadcastToAllClient / NotifyToServer.
響應事件
上述的發布事件很多都是廣播,但是不是每條訊息都需要每個system都處理,因此響應函式只會響應那些監聽了這些事件訊息源有發布這些事件的時候才會響應。
響應函式會響應在監聽事件時ListenForEvent的參數中的回呼函式。回呼函式會傳入參數dict,不同事件的參數在下面具體事件(見網易開發人員文件)中進行了說明,其中部分參數是可設定參數,可以透過修改值來改變事件的結果。

——網易開發人員文件

介面[edit]

介面(原稱元件),是一些已經封裝好的方法,開發人員可以更好對其進行呼叫以達到直接或間接修改遊戲(核心玩法)邏輯的目的。

元件是為了完成某個或某些特定邏輯功能的資料集合,元件只會儲存資料並不會執行相應的邏輯,只有元件在System中更新的時候,System從判斷元件是否需要更新,從元件中拿到需要更新的資料來執行相應的邏輯功能。 元件分為引擎元件和自訂元件。引擎元件的參數型別和功能都是確定好的,玩家可以建立Create或取得Get元件來完成邏輯功能。自訂元件需要自訂元件的資料結構,自訂元件的更新邏輯。

——網易開發人員文件

元件和事件一樣,都依賴System類執行。同時元件在很大程度上也必須依賴事件所傳入的傳回值進行註冊和繫結。