模組資料夾與 mod.json
模組資料夾在哪、裡面放什麼,以及模組的名片 mod.json 每個欄位怎麼填。
這一頁是「進階:手寫檔案」的第一頁。模組編輯器會幫你寫好下面所有的東西,大多數人不需要讀這頁。如果你想用外面的文字編輯器直接改檔案,或想看懂編輯器替你寫了什麼,再往下讀。
一個模組就是一個資料夾。裡面一定要有一份叫 mod.json 的檔案,那是模組的名片:寫著它叫什麼、第幾版、誰要裝、有哪些選項,以及內容放在哪些檔案。欄位指檔案裡的一項設定,例如 name 或 version。
模組功能只在電腦版(Steam)可用。用範本開始的話,遊戲會幫你把整個資料夾和 mod.json 建好,這一頁是讓你看懂、改得動它。
模組資料夾在哪裡#
最簡單的找法:進標題畫面的「工作坊」,切到「創作模組」分頁,按「開啟模組資料夾」(或在編輯器裡按「開資料夾」,會直接打開這個模組自己的資料夾),會用檔案總管(Finder)直接打開。資料夾第一次用到時才會建立,裡面還會放一份 README.txt。每個模組是這個資料夾裡的一個子資料夾。實際位置如下:
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 個問題」,並用白話告訴你哪個檔案、第幾筆、哪個欄位有問題。不用重開遊戲。
- 想實際玩到改動,在「創作模組」頁或編輯器上列按「試玩」,遊戲只載入這個模組(和它需要的模組)並重新載入。改了檔案之後再按一次。
資料夾裡面長什麼樣子#
我的模組/
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。它宣告了三個選項(後面會說明),並且指向兩個內容檔,這兩個檔案的內容就是本頁後面的範例。
{
"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 工作坊的編號,寫成文字,讓缺少的模組可以自動訂閱):
"dependsOn": [
{ "id": "icepack", "minVersion": "1.0.0", "workshopId": "3123456789" }
]- 最多 16 個;不能依賴自己,同一個模組不能列兩次。
- 需要的模組沒裝、版本太舊或載入失敗時,你的模組會被略過,並用白話告訴你缺了哪一個。
- 兩個模組互相需要對方會無法決定先後,兩個都不會載入。
- 寫了
dependsOn,才能用@icepack/frost_shard這種寫法引用對方的東西。
範圍:誰要裝#
scope 決定一起玩的人要不要裝這個模組:
| `scope` | 遊戲裡的名稱 | 意思 |
|---|---|---|
client | 只影響自己 | 只改你自己看到的東西(例如翻譯、介面小程式),隊友不用裝 |
host | 房主裝就好 | 只要房主有裝,加入的人不用裝 |
everyone | 全員都要裝 | 一起玩的每個人都要裝同一版、同樣的選項,加入時會自動下載 |
選項:讓房主調整#
選項讓同一個模組有不同玩法,例如「霜刃攻擊力」或「多一個小哨子」。房主在建立世界時挑選,一起玩的人都會用同一組值。在 mod.json 的 options 宣告,有三種類型:
| `type` | 玩家看到 | 要寫的欄位 | 值 |
|---|---|---|---|
toggle | 開關 | default | true 或 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 使用:
[
{
"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:
[
{
"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 對應語言到一個檔案:
"i18n": { "zh-TW": "i18n/zh-TW.json", "en": "i18n/en.json" }檔案內容是單層的「鍵: 文字」,鍵建議都以 <模組代號>__ 開頭,避免和遊戲或別的模組撞名。不能覆蓋遊戲原有的文字(會被略過並提醒):
{
"frost_pack__hello": "你好,霜原"
}常見錯誤#
id有大寫、空白或中文,或只有 1 到 2 個字,或含有__。version寫成v1.0或1.0-beta:只能是數字和點。content的路徑指到不存在的檔案,或內容表不是.json、程式不是.js,或路徑跳出資料夾(../)。content裡寫了不認得的表名:畫面會說它不是已知的內容表。- 選項的
default不在範圍或選單裡。 - 資料夾裡放了不允許的檔案(例如
.zip、.exe、捷徑)。 - 自己在條目
id前面加模組代號與__。