程式模組
用一小段 JavaScript 讓模組對遊戲裡發生的事做出反應:聊天指令、擊殺計數、送物品、召喚生物。程式在隔離的沙盒裡跑,碰不到你的存檔。
程式模組適合做「發生了某件事,就做某件事」:打倒一隻怪物就記一筆、每天早上提醒你、輸入 /指令 就給你一個物品。它不能新增物品或生物(那是資料表的工作),但可以和資料表搭配使用。
能做什麼#
- 聽事件:進入世界、每秒、換日、打倒怪物、受傷、死亡、製作完成、聊天指令。
- 加聊天指令:例如
/kills,最多 16 個。 - 顯示提示:在左側通知串顯示一行字。
- 讀目前狀態:血量、等級、位置、天數、地形群系等(唯讀)。
- 給物品、召喚生物:有條件,見下面的「會改動世界的呼叫」。
安全承諾#
- 沒有網路(
fetch、XMLHttpRequest、WebSocket都不存在),也沒有任何儲存空間(indexedDB、caches都不存在)。 - 不能從文字產生程式:沒有
eval和Function,setTimeout只接受函式。 - 收到的資料是凍結的唯讀物件,改不動遊戲內部狀態。
fangjie.state()不含任何玩家名字或帳號。 - 一秒內送出超過 120 則訊息、10 秒內出錯 10 次,或超過 2 秒沒有回應(例如無窮迴圈),遊戲會停掉這個模組,畫面顯示「模組「名稱」的程式出錯,已停止」,模組清單記下原因。
在編輯器裡#
編輯器左欄「模組」底下有一頁「程式」,只在模組有程式時才出現。還沒有的話,按左欄最下面的「加入新的內容」選「程式」,編輯器會替你建好 scripts/main.js(裡面是一個擊倒計數的小範例),並登記到 mod.json。
遊戲裡不寫程式,這一頁是用來看說明和除錯的:
- 「程式檔」:顯示目前的程式檔路徑,按「在資料夾中顯示」或「開資料夾」,用外面的編輯器去改。存檔後按試玩,就會用新的。
- 「誰需要裝」:依你在模組資訊設的範圍,說明這個程式能做什麼。範圍是「只有我」時,程式只能做畫面提示與聊天指令,不能給物品或生怪。「到模組資訊改範圍」可以直接跳過去。
- 「能用什麼」:列出事件和呼叫的清單,並提醒次數限制。「開啟網站說明」會打開這個說明頁。
- 「上次試玩的紀錄」:試玩時程式印出的字和遇到的問題,回到編輯器後會留在這裡。按「清除紀錄」清掉。
試玩進世界後,畫面左下角有一個「程式紀錄」,點開可以即時看程式印出的字和問題,右邊的數字是目前有幾則。
怎麼加一個程式#
- 1寫程式檔
遊戲裡的編輯器沒有程式碼編輯區。在模組編輯器的「程式」頁按「開資料夾」,用外面的文字編輯器改
scripts/main.js(檔名可自訂,最大 512 KB)。程式裡只能用全域物件fangjie。 - 2在 mod.json 登記
在
content裡加上"script": "scripts/main.js",見下面的範例。 - 3選好範圍
只想改自己的畫面或提示,用
"scope": "client"(別人不用裝)。要給物品或召喚生物,需要host或everyone。 - 4試玩
改完存檔,回到編輯器按「試玩」,進世界後程式才會啟動,離開世界就停止。換模組組合會重新載入遊戲。
{
"format": 1,
"id": "my_script",
"name": "My script",
"version": "1.0.0",
"gameApi": { "min": 1 },
"scope": "client",
"content": {
"script": "scripts/main.js"
}
}事件:fangjie.on(事件, 函式)#
每個事件最多可以掛 32 個函式。收到的資料是唯讀的,座標都四捨五入到整格。
| 事件 | 收到的資料 | 什麼時候 |
|---|---|---|
worldEnter | { worldId, modded } | 進入世界,每次進世界一次 |
tick | { day, hour } | 每秒一次;hour 是 0 到 24,一位小數 |
dayStart | { day } | 遊戲裡換日的第一秒 |
enemyKilled | { speciesId, x, y, z, byLocalPlayer, isBoss } | 怪物死掉。單人與房主:每隻都有,byLocalPlayer 表示是不是自己(或自己的寵物)打倒的。加入者:只收到房主算在自己頭上的擊殺,byLocalPlayer 一律是 true |
playerDamaged | { amount, sourceSpeciesId? } | 自己真的掉血(被打、持續傷害、環境傷害都算;每次血量下降發一次) |
playerDeath | {} | 自己死亡(多人的「倒地」不算) |
itemCrafted | { itemId, count } | 自己製作或料理完成 |
chat | { text } | 自己在聊天輸入以 / 開頭、遊戲內建指令沒有處理的一行 |
呼叫#
| 呼叫 | 說明 |
|---|---|
fangjie.on(事件, 函式) | 訂閱事件。 |
fangjie.command(名稱, 函式) | 註冊聊天指令 /名稱。名稱只能用英文小寫、數字、底線,最長 24 字。跟遊戲內建指令或別的模組撞名時不會加上,模組清單會顯示原因。函式收到 (args, text):args 是用空白切開的參數陣列,text 是整行。每個模組最多 16 個指令。 |
fangjie.notify(文字) | 在左側通知串顯示一行「模組名稱:文字」。最多 120 字;連發 3 則之後每 2 秒 1 則,多的直接略過。 |
fangjie.log(...) | 寫一行到模組紀錄(開發用)。每秒最多 20 行。console.log 也會走這裡。 |
fangjie.state() | 目前狀態的唯讀快照,每秒更新一次:inWorld、day、hour、hp、maxHp、level、playerClass、x、y、z、biome、isHost。 |
fangjie.options | 這個世界替本模組選的選項(mod.json 的 options),唯讀。 |
fangjie.giveItem(物品id, 數量) | 給自己物品。有條件,見下方。 |
fangjie.spawn(生物id, 位置?) | 在自己附近召喚一隻生物;位置 是 { x, z },會被拉回玩家 24 格內。有條件,見下方。 |
會改動世界的呼叫#
giveItem 和 spawn 只有同時符合下面三點才有效。不符合時模組清單會出現一行說明,呼叫本身什麼都不做:
- 單人遊戲,或你是多人房間的房主。
- 模組的範圍(
scope)是host或everyone。client模組只能改自己的畫面。 - id 是遊戲原有的,或是本模組自己的物品與生物(
<模組id>__<本地id>)。別的模組的 id 不行;首領不能召喚。
上限:每個模組每分鐘最多給 64 個物品、召喚 20 隻。
限制與禁止的事#
| 項目 | 規則 |
|---|---|
| 訊息量 | 一秒內最多 120 則,超過就停掉模組 |
| 出錯 | 10 秒內出錯 10 次,就停掉模組 |
| 沒有回應 | 超過 2 秒沒有回應(例如無窮迴圈),就停掉模組 |
| 通知 | 最多 120 字;連發 3 則之後每 2 秒 1 則 |
| 紀錄 | 每秒最多 20 行 |
| 給物品、召喚 | 每分鐘最多 64 個物品、20 隻生物,召喚位置在玩家 24 格內 |
| 指令 | 每個模組最多 16 個,名稱最長 24 字 |
| 程式檔大小 | 最大 512 KB |
| 網路、儲存 | 沒有 fetch、XMLHttpRequest、WebSocket、importScripts、indexedDB、caches、Worker、通知、裝置 API |
| 產生程式 | 沒有 eval、Function;setTimeout 只接受函式 |
完整範例:擊倒計數#
這是創作模組頁「小程式」範本裡的真實程式。它會數你打倒幾隻怪物,達到選項設定的數量就提醒,輸入 /kills 可以查看目前的數字。你可以到下載頁拿到整個範本。
let kills = 0;
let bosses = 0;
fangjie.on('worldEnter', () => {
kills = 0;
bosses = 0;
});
fangjie.on('enemyKilled', (e) => {
if (!e.byLocalPlayer) return;
kills += 1;
if (e.isBoss) bosses += 1;
const every = Number(fangjie.options.announceEvery) || 0;
if (every > 0 && kills % every === 0) {
fangjie.notify(`已經打倒 ${kills} 隻了! / ${kills} defeated!`);
}
});
fangjie.command('kills', () => {
fangjie.notify(`這次打倒 ${kills} 隻,其中首領 ${bosses} 隻 / Defeated ${kills} (bosses: ${bosses})`);
});除錯小技巧#
- 想知道程式有沒有跑到某一行,先用
fangjie.notify("到這裡了"),畫面上馬上看得到。 - 要看更多細節用
fangjie.log(變數)或console.log,內容寫進模組紀錄,不會吵到畫面。 - 收到的物件可以用
fangjie.log(e)印出來,看有哪些欄位。 - 指令沒反應時,先到模組清單看有沒有撞名的說明。
- 程式出錯被停掉時,模組清單會記下原因,照著原因修改程式即可。
notify連發會被略過,如果要印很多東西,改用log。- 試玩時,畫面左下角的「程式紀錄」會即時列出
log的內容和程式遇到的問題。回到編輯器後,在「程式」頁的「上次試玩的紀錄」還看得到。