模組是正式版功能,試玩版沒有。正式版推出後開放,內容可能在推出前調整。

程式模組

用一小段 JavaScript 讓模組對遊戲裡發生的事做出反應:聊天指令、擊殺計數、送物品、召喚生物。程式在隔離的沙盒裡跑,碰不到你的存檔。

程式模組適合做「發生了某件事,就做某件事」:打倒一隻怪物就記一筆、每天早上提醒你、輸入 /指令 就給你一個物品。它不能新增物品或生物(那是資料表的工作),但可以和資料表搭配使用。

能做什麼#

  • 聽事件:進入世界、每秒、換日、打倒怪物、受傷、死亡、製作完成、聊天指令。
  • 加聊天指令:例如 /kills,最多 16 個。
  • 顯示提示:在左側通知串顯示一行字。
  • 讀目前狀態:血量、等級、位置、天數、地形群系等(唯讀)。
  • 給物品、召喚生物:有條件,見下面的「會改動世界的呼叫」。

安全承諾#

  • 沒有網路(fetch、XMLHttpRequest、WebSocket 都不存在),也沒有任何儲存空間(indexedDB、caches 都不存在)。
  • 不能從文字產生程式:沒有 eval 和 Function,setTimeout 只接受函式。
  • 收到的資料是凍結的唯讀物件,改不動遊戲內部狀態。fangjie.state() 不含任何玩家名字或帳號。
  • 一秒內送出超過 120 則訊息、10 秒內出錯 10 次,或超過 2 秒沒有回應(例如無窮迴圈),遊戲會停掉這個模組,畫面顯示「模組「名稱」的程式出錯,已停止」,模組清單記下原因。

在編輯器裡#

編輯器左欄「模組」底下有一頁「程式」,只在模組有程式時才出現。還沒有的話,按左欄最下面的「加入新的內容」選「程式」,編輯器會替你建好 scripts/main.js(裡面是一個擊倒計數的小範例),並登記到 mod.json。

遊戲裡不寫程式,這一頁是用來看說明和除錯的:

  • 「程式檔」:顯示目前的程式檔路徑,按「在資料夾中顯示」或「開資料夾」,用外面的編輯器去改。存檔後按試玩,就會用新的。
  • 「誰需要裝」:依你在模組資訊設的範圍,說明這個程式能做什麼。範圍是「只有我」時,程式只能做畫面提示與聊天指令,不能給物品或生怪。「到模組資訊改範圍」可以直接跳過去。
  • 「能用什麼」:列出事件和呼叫的清單,並提醒次數限制。「開啟網站說明」會打開這個說明頁。
  • 「上次試玩的紀錄」:試玩時程式印出的字和遇到的問題,回到編輯器後會留在這裡。按「清除紀錄」清掉。

試玩進世界後,畫面左下角有一個「程式紀錄」,點開可以即時看程式印出的字和問題,右邊的數字是目前有幾則。

怎麼加一個程式#

  1. 1
    寫程式檔

    遊戲裡的編輯器沒有程式碼編輯區。在模組編輯器的「程式」頁按「開資料夾」,用外面的文字編輯器改 scripts/main.js(檔名可自訂,最大 512 KB)。程式裡只能用全域物件 fangjie。

  2. 2
    在 mod.json 登記

    在 content 裡加上 "script": "scripts/main.js",見下面的範例。

  3. 3
    選好範圍

    只想改自己的畫面或提示,用 "scope": "client"(別人不用裝)。要給物品或召喚生物,需要 host 或 everyone。

  4. 4
    試玩

    改完存檔,回到編輯器按「試玩」,進世界後程式才會啟動,離開世界就停止。換模組組合會重新載入遊戲。

mod.json
{
  "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 只有同時符合下面三點才有效。不符合時模組清單會出現一行說明,呼叫本身什麼都不做:

  1. 單人遊戲,或你是多人房間的房主。
  2. 模組的範圍(scope)是 host 或 everyone。client 模組只能改自己的畫面。
  3. 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 可以查看目前的數字。你可以到下載頁拿到整個範本。

scripts/main.js
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 的內容和程式遇到的問題。回到編輯器後,在「程式」頁的「上次試玩的紀錄」還看得到。