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

模組資料夾與 mod.json

模組資料夾在哪、裡面放什麼,以及模組的名片 mod.json 每個欄位怎麼填。

這一頁是「進階:手寫檔案」的第一頁。模組編輯器會幫你寫好下面所有的東西,大多數人不需要讀這頁。如果你想用外面的文字編輯器直接改檔案,或想看懂編輯器替你寫了什麼,再往下讀。

一個模組就是一個資料夾。裡面一定要有一份叫 mod.json 的檔案,那是模組的名片:寫著它叫什麼、第幾版、誰要裝、有哪些選項,以及內容放在哪些檔案。欄位指檔案裡的一項設定,例如 name 或 version。

模組功能只在電腦版(Steam)可用。用範本開始的話,遊戲會幫你把整個資料夾和 mod.json 建好,這一頁是讓你看懂、改得動它。

模組資料夾在哪裡#

最簡單的找法:進標題畫面的「工作坊」,切到「創作模組」分頁,按「開啟模組資料夾」(或在編輯器裡按「開資料夾」,會直接打開這個模組自己的資料夾),會用檔案總管(Finder)直接打開。資料夾第一次用到時才會建立,裡面還會放一份 README.txt。每個模組是這個資料夾裡的一個子資料夾。實際位置如下:

text
Windows  %APPDATA%\FangjieShatteredAltars\mods-dev
         (通常是 C:\Users\你的名字\AppData\Roaming\FangjieShatteredAltars\mods-dev)
macOS    ~/Library/Application Support/FangjieShatteredAltars/mods-dev
Linux    ~/.config/FangjieShatteredAltars/mods-dev
  • 子資料夾的名字只能用英文字母、數字、底線和減號,以英文或數字開頭,最長 64 字。它不一定要跟模組代號 id 一樣。
  • 你在這裡建立的模組,在模組清單裡會標成「本機開發中」。
  • 改了檔案、存檔之後,遊戲會自動重新檢查,在模組旁顯示「可以用」或「N 個問題」,並用白話告訴你哪個檔案、第幾筆、哪個欄位有問題。不用重開遊戲。
  • 想實際玩到改動,在「創作模組」頁或編輯器上列按「試玩」,遊戲只載入這個模組(和它需要的模組)並重新載入。改了檔案之後再按一次。

資料夾裡面長什麼樣子#

text
我的模組/
  mod.json              模組名片(唯一必要的檔案)
  data/
    items.json          內容表,檔名自訂,路徑寫在 mod.json 的 content
    recipes.json
    buffs.json
  models/
    frost_whistle.json  體素造型(物品的外觀)
  i18n/
    zh-TW.json          翻譯,簡單的「鍵: 文字」
    en.json
  scripts/
    main.js             小程式(content.script 指到它)
  preview.png           工作坊預覽圖(可有可無)

只有 mod.json 是必要的,其他看你要加什麼。資料夾名稱和檔案路徑可以自己取,只要 mod.json 裡的路徑對得上。規定如下:

項目規定
可以放的檔案.json、.js、.png、.md、.txt。捷徑、連結或其他種類的檔案會讓模組讀不進來
以 . 開頭的檔案(.DS_Store、.git 之類)會被忽略,不會報錯也不會被上傳
檔案數量一個模組最多 200 個檔案
總大小整個模組最多 32 MB
單一 JSON 檔最多 2 MB,而且巢狀不能太深
程式檔最多 512 KB
mod.json最多 64 KB
內容路徑要用相對路徑,指到模組資料夾裡的檔案,不能跳出資料夾,內容表要是 .json、程式要是 .js

mod.json 的欄位#

下面是一份用到大部分欄位的完整 mod.json。它宣告了三個選項(後面會說明),並且指向兩個內容檔,這兩個檔案的內容就是本頁後面的範例。

mod.json
{
  "format": 1,
  "id": "frost_pack",
  "name": "霜原補給",
  "names": { "en": "Frost Supplies", "zh-CN": "霜原补给" },
  "version": "1.0.0",
  "author": "你的名字",
  "description": "一把霜刃、一個強化藥增益,和一個可以開關的小哨子。",
  "descriptions": { "en": "A frost blade, a tonic buff and a small whistle you can switch on." },
  "gameApi": { "min": 1 },
  "scope": "everyone",
  "options": [
    { "key": "bladePower", "label": "霜刃攻擊力", "labels": { "en": "Frost Blade power" },
      "hint": "原本是 34", "type": "number", "min": 10, "max": 60, "step": 2, "default": 34 },
    { "key": "tonicBonus", "label": "霜護加成", "labels": { "en": "Frost ward bonus" }, "type": "choice", "default": 8,
      "choices": [
        { "value": 4, "label": "弱", "labels": { "en": "Weak" } },
        { "value": 8, "label": "普通", "labels": { "en": "Normal" } },
        { "value": 12, "label": "強", "labels": { "en": "Strong" } }
      ] },
    { "key": "extraWhistle", "label": "多一個小哨子", "labels": { "en": "Add a whistle" }, "type": "toggle", "default": false }
  ],
  "content": {
    "items": "data/items.json",
    "buffs": "data/buffs.json"
  }
}
欄位必填?意思可以填什麼
format必填檔案格式版本固定寫 1
id必填模組代號,整個遊戲裡不重複的名字見下面「取名規則」
name必填模組顯示名稱1 到 128 字
names選填其他語言的名稱例如 { "en": "...", "zh-CN": "..." },語言代號像 en、zh-TW
version必填版本號數字用點隔開,例如 1.0.0,最多四段。見下面「版本」
author選填作者名稱最長 64 字
description、descriptions選填一段簡介,以及其他語言版本最長 1000 字
gameApi必填需要的遊戲模組介面版本現在寫 { "min": 1 }
scope必填誰要裝這個模組client、host、everyone。見下面「範圍」
dependsOn選填需要先裝的其他模組最多 16 個。見下面「相依」
options選填讓房主在建立世界時挑的選項最多 32 個。見下面「選項」
content必填各內容表的檔案路徑,全部可選items recipes dishes fish crops buffs loot rules patches species spawns directorEvents dialogue quests blueprints,值是 .json 路徑。另有 i18n(語言對應檔案)和 script(.js 路徑)

取名規則#

  • 模組代號 id:3 到 32 個字,小寫英文開頭,只能用小寫英文、數字、底線,不能含連續兩個底線 __。發布後不要再改,改了就是另一個模組。
  • 條目代號(物品、配方、增益等各條目的 id):叫「本地代號」,小寫英文或數字開頭,只能用小寫英文、數字、底線,最長 48 字,例如 frost_blade。
  • 遊戲會自動幫你加上模組代號。frost_blade 載入後實際叫 frost_pack__frost_blade,所以不會跟別人的模組撞名。你永遠只寫本地代號,不要自己寫 frost_pack__,也不要在本地代號裡放 __。
  • 同一種東西在同一個檔案裡不能重複;物品、配方、料理等不同種類各有各的名字空間。

在資料檔裡引用東西時(配方的材料、掉落的物品、任務的目標等)有三種寫法:

寫法意思
frost_blade先找自己模組有沒有這個本地代號,沒有就當成遊戲原版的代號(例如 iron_ore、wood)
iron_ore遊戲原版的代號。生物的原版代號是全大寫(ZOMBIE、FROST_WOLF),物品是小寫
@icepack/frost_shard別的模組 icepack 的 frost_shard。對方一定要列在你的 dependsOn

版本#

版本號是用點隔開的數字,最多四段,例如 1、1.2、1.2.3、1.2.3.4。比較時是一段一段比數字,所以 1.10 比 1.9 新,1.2 和 1.2.0 一樣。每次更新模組都要把 version 往上加(例如 1.0.0 改成 1.0.1),訂閱的玩家才會收到新版。

相依:需要別的模組#

如果你的模組要用到別的模組的東西,就在 dependsOn 列出它。每一項有 id,可以再加 minVersion(至少要幾版)和 workshopId(Steam 工作坊的編號,寫成文字,讓缺少的模組可以自動訂閱):

json
"dependsOn": [
  { "id": "icepack", "minVersion": "1.0.0", "workshopId": "3123456789" }
]
  • 最多 16 個;不能依賴自己,同一個模組不能列兩次。
  • 需要的模組沒裝、版本太舊或載入失敗時,你的模組會被略過,並用白話告訴你缺了哪一個。
  • 兩個模組互相需要對方會無法決定先後,兩個都不會載入。
  • 寫了 dependsOn,才能用 @icepack/frost_shard 這種寫法引用對方的東西。

範圍:誰要裝#

scope 決定一起玩的人要不要裝這個模組:

`scope`遊戲裡的名稱意思
client只影響自己只改你自己看到的東西(例如翻譯、介面小程式),隊友不用裝
host房主裝就好只要房主有裝,加入的人不用裝
everyone全員都要裝一起玩的每個人都要裝同一版、同樣的選項,加入時會自動下載

選項:讓房主調整#

選項讓同一個模組有不同玩法,例如「霜刃攻擊力」或「多一個小哨子」。房主在建立世界時挑選,一起玩的人都會用同一組值。在 mod.json 的 options 宣告,有三種類型:

`type`玩家看到要寫的欄位值
toggle開關defaulttrue 或 false
number數字滑桿min、max、step(選填)、default數字。min 要小於 max,default 要在兩者之間,step 不能超過 max - min
choice選單choices(1 到 32 個,每個有 value 和 label)、default其中一個 value,可以是文字(最長 64 字)或數字
選項欄位必填?意思可以填什麼
key必填在資料檔裡用來指到這個選項的英文代號英文字母開頭,只能用英文字母、數字、底線,最長 32 字,不能重複
label、labels必填玩家看到的名稱,以及其他語言1 到 64 字
hint選填小字說明最長 200 字
type必填類型toggle number choice
default必填預設值依類型,見上表

選項值如果不在允許範圍內(超出 min 到 max,或不在 choices 裡),遊戲會改用預設值。

在資料檔裡用選項:$option 與 $if#

資料檔裡任何「單一值」都可以換成 { "$option": "key" },載入時會換成這個世界所選的值。陣列裡的條目可以加 "$if",條件不成立就整筆略過:

寫法意思
{ "$option": "bladePower" }換成選項 bladePower 的值
"$if": { "option": "extraWhistle" }選項為真(開關打開)才保留這一筆
"$if": { "option": "tonicBonus", "equals": 12 }選項等於 12 才保留
"$if": { "option": "tonicBonus", "notEquals": 4 }選項不等於 4 才保留

下面的物品表,霜刃的攻擊力吃 bladePower,哨子只在 extraWhistle 打開時才存在。放在 data/items.json,配合上面的 mod.json 使用:

data/items.json
[
  {
    "id": "frost_blade",
    "name": "霜刃",
    "names": { "en": "Frost Blade" },
    "type": "WEAPON",
    "rarity": "RARE",
    "color": "#9fd8ff",
    "stats": { "power": { "$option": "bladePower" }, "tempo": 8 },
    "voxels": [
      { "x": 0, "y": 0, "z": 0, "color": "#3a4a5c" },
      { "x": 0, "y": 1, "z": 0, "color": "#9fd8ff" },
      { "x": 0, "y": 2, "z": 0, "color": "#9fd8ff" }
    ]
  },
  {
    "$if": { "option": "extraWhistle" },
    "id": "frost_whistle",
    "name": "霜哨",
    "names": { "en": "Frost Whistle" },
    "type": "MATERIAL",
    "color": "#cfe8ff",
    "voxels": [
      { "x": 0, "y": 0, "z": 0, "color": "#cfe8ff" },
      { "x": 1, "y": 0, "z": 0, "color": "#9fd8ff" }
    ]
  }
]

選單選項也一樣。下面的增益表,霜護的最大生命加成吃 tonicBonus(4、8 或 12),選到「強」的時候才多一個更強的增益。放在 data/buffs.json:

data/buffs.json
[
  {
    "id": "frost_ward",
    "slot": "tonic",
    "name": "霜護",
    "names": { "en": "Frost ward" },
    "effects": { "maxHpPct": { "$option": "tonicBonus" }, "frostResistPct": 15 }
  },
  {
    "$if": { "option": "tonicBonus", "equals": 12 },
    "id": "frost_surge",
    "slot": "tonic",
    "name": "霜湧",
    "names": { "en": "Frost surge" },
    "effects": { "moveSpeedPct": 5 }
  }
]

翻譯檔(i18n)#

多數內容表可以直接把各語言的名字寫在條目裡(name 與 names),不用另外寫翻譯檔。想放更多文字的話,在 content.i18n 對應語言到一個檔案:

json
"i18n": { "zh-TW": "i18n/zh-TW.json", "en": "i18n/en.json" }

檔案內容是單層的「鍵: 文字」,鍵建議都以 <模組代號>__ 開頭,避免和遊戲或別的模組撞名。不能覆蓋遊戲原有的文字(會被略過並提醒):

i18n/zh-TW.json
{
  "frost_pack__hello": "你好,霜原"
}

常見錯誤#

  • id 有大寫、空白或中文,或只有 1 到 2 個字,或含有 __。
  • version 寫成 v1.0 或 1.0-beta:只能是數字和點。
  • content 的路徑指到不存在的檔案,或內容表不是 .json、程式不是 .js,或路徑跳出資料夾(../)。
  • content 裡寫了不認得的表名:畫面會說它不是已知的內容表。
  • 選項的 default 不在範圍或選單裡。
  • 資料夾裡放了不允許的檔案(例如 .zip、.exe、捷徑)。
  • 自己在條目 id 前面加模組代號與 __。