跳到正文
本頁目錄

lip.toml

本頁說明 lip.toml 的每一個欄位,讀完後你能看懂任何套件的套件檔,也能寫出自己的。分步講解參見用 lip 發佈你的模組。

lip 套件是根部帶有套件檔 lip.toml 的歸檔。lip.toml 給出套件的名稱和版本,並針對每個變體、執行端和平臺 描述 lip 要安裝的內容:相依、要放置的檔案、要安裝的模組以及要執行的命令。 規範性定義見協議的 lip.toml(5) 頁。

lip.toml 是格式 4 的 TOML 1.0 檔案,由以 TOML 編寫的 JSON Schema lip.schema.toml 描述。lip 也可讀取 lip v0.x 套件的 tooth.json(格式 1 到 3),參見早期格式。

歸檔

套件位於一個歸檔中,歸檔是一棵根部帶有 lip.toml 的檔案和目錄樹:

  • git 歸檔:git 儲存庫的一個提交,通常是某個版本標籤所指的提交。只有其中的普通檔案和目錄屬於 該歸檔(不含符號連結和子模塊);
  • ZIP 歸檔:一個 ZIP 檔案,可通過 HTTPS 下載,也可位於你的磁碟上。一個檔案是否為 ZIP 歸檔只看 內容,與檔案名稱無關。其條目必須是普通檔案或目錄,路徑以 / 分隔,不得以 / 開頭,也不得包含 .. 段或 \;
  • 目錄歸檔:你磁碟上的一個目錄,以其內容作為歸檔。其中檔案和目錄的名字不得包含 \。

有一個套件既沒有歸檔也沒有 lip.toml:遊戲 github.com/LiteLDev/bds。lip 根據伺服器組建的清單自己定義 它的套件檔;參見 lip setup和 伺服器檔案。

示例

一個模組,以附加到每個 GitHub Release 的 ZIP 檔案發佈,支援 Windows x64 上的服務端和客戶端:

toml
format = 4
id = "github.com/example/MyMod"
version = "1.0.0"

[info]
name = "My Mod"
description = "A short description"
tags = ["utility"]

[[variants.""]]
side = "server"
platform = "win-x64"
preserve = ["mods/MyMod/config/"]

[variants."".deps]
"github.com/LiteLDev/LeviLamina" = ">=1.0.0 <2.0.0"
"github.com/example/MyLib" = "^0.3.0"

[[variants."".assets]]
type = "mcmod"
urls = ["https://github.com/example/MyMod/releases/download/v{{version}}/MyMod-server-win-x64.zip"]

[[variants.""]]
side = "client"
platform = "win-x64"
preserve = ["mods/MyMod/config/"]

[variants."".deps]
"github.com/LiteLDev/LeviLamina" = ">=1.0.0 <2.0.0"
"github.com/example/MyLib" = "^0.3.0"

[[variants."".assets]]
type = "mcmod"
urls = ["https://github.com/example/MyMod/releases/download/v{{version}}/MyMod-client-win-x64.zip"]

版本和版本範圍都是字串,因此總要加引號。含有 ASCII 字母、數字、_ 和 - 以外字元的鍵也要加引號,例如 deps 中的套件 id 或預設變體 "":[[variants.""]] 為預設變體新增一個條目。

欄位

lip.toml 不得包含日期時間、日期、時間,或浮點數 inf、nan。此處未描述的鍵會被忽略。

頂層

欄位 類型 必填 說明
format int 是 必須為 4。
id string 是 套件 ID,必須是合法的 Go 模塊路徑,例如 github.com/user/repo。比較時不區分 ASCII 大小寫。
version string 是 套件的版本,不帶前導 v 的 SemVer 2.0.0 版本。
info object 否 供人閱讀的資訊。參見 Info。
variants object 是 把每個變體名映射到其條目。參見變體。

對於 git 儲存庫中的套件,id 必須是該儲存庫的路徑:https://github.com/user/repo.git 中的 lip.toml 必須寫 id = "github.com/user/repo"。在版本標籤 v<version> 處,version 必須 等於標籤版本。否則該提交不是套件,lip 不會安裝它。

Info

欄位 類型 說明
name string 顯示名稱。
description string 簡短描述。
tags string[] 標籤。參見推薦標籤。
logo string 徽標圖片的 URL,必須以 https:// 開頭;其響應(直接或經重定向後)即為該圖片。

lip 不使用 info。

推薦標籤

info.tags 幫助人們在模組清單(例如介面的「取得模組」頁面和 LeviMC 模組)中找到你的套件;lip 自己忽略標籤。清單會優先顯示下面這些標籤,配上翻譯後的名稱,並允許使用者按它們篩選。請按這裡的寫法填寫 ID,使用小寫;還可以再加上你喜歡的其他標籤:

toml
[info]
tags = ["management", "economy"]
標籤 名稱 適用於
library 前置庫 / API 其他模組相依的庫或 API,例如事件、表單或導出函數。
utility 實用工具 玩家日常使用的工具,例如背套件輔助、資訊顯示、物品提示和配方檢視。
management 伺服器管理 運營伺服器,例如備份、封禁、白名單、登入、命令和領地。
game-mechanics 遊戲機制 改變遊戲玩法,例如原版增強功能和成就。
adventure 內容與冒險 可供探索的新內容,例如世界生成、地形和生物群系。
visual 視覺與介面 玩家看到的內容,例如 HUD、側邊欄、光影、回放和錄製。
economy 經濟 貨幣、商店和交易。
teleport 傳送 傳送命令、家園、傳送點和傳送石碑。
anticheat 反作弊 檢測和阻止作弊,例如反礦透。
optimization 性能優化 提升性能,例如實體和掉落物清除。
bugfix 錯誤修復 修復遊戲的錯誤。
technology 技術與紅石 紅石、活塞和自動化。
protocol 協議與多版本 網路協議,例如讓多個遊戲版本的客戶端加入。

不需要用標籤標明執行端或平臺,也不需要標明這個套件是 LeviLamina 模組:條目和 deps 已經說明了這些。

變體

variants 把每個變體名映射到一個非空的條目陣列。變體 "" 是預設變體;其他名稱須符合 ^[a-z0-9_]+(/[a-z0-9_]+)?$,例如 lua 或 quickjs。使用者在來源後加上 #<variant> 來選擇變體,例如 lip install github.com/LiteLDev/LegacyScriptEngine#lua;不帶 # 的來源選擇 ""。

每個條目恰好適用於一個執行端和一個平臺。lip 解析套件時,取所選變體中 side 和 platform 與工作區環境完全相同的那個條目。沒有通配符:支援多個平臺的套件要為每個平臺各寫一個條目。 若該變體沒有這樣的條目,則該套件不是該環境下的候選。同一變體中的任意兩個條目不得具有相同的 side 和 platform。

條目

欄位 類型 必填 說明
side string 是 "server" 或 "client"。
platform string 是 .NET RID,例如 win-x64。
deps object 否 參見相依。
assets array 否 參見資源。
preserve string[] 否 需保留檔案的 glob:安裝時不覆寫已存在的檔案,解除安裝時也不刪除它。
purge string[] 否 解除安裝時額外刪除的路徑的 glob。符合到的目錄會連同其下所有內容一起刪除。
hooks object 否 參見鉤子。

相依

deps 把 <包 ID> 或 <包 ID>#<variant> 映射到版本範圍:

toml
[variants."".deps]
"github.com/LiteLDev/LeviLamina" = ">=1.0.0 <2.0.0"
"github.com/LiteLDev/LegacyScriptEngine#lua" = "^0.9.0"

對每個相依,lip 從該儲存庫的版本標籤中安裝一個版本在範圍內、且有同一環境條目的版本(及變體)。從 git 引用(例如 @branch:main)安裝的套件,只要版本在範圍內,且該儲存庫有 lip 可為該相依安裝的版本,也能滿足對同一套件 ID 和變體的相依。

版本範圍採用 Semver for .NET 3.0.0 中 SemVersionRange.Parse 在預設選項下的語法和語義,例如 ^1.2.0、~1.2.0、>=1.0.0 <2.0.0、 1.2.* 或 >=1.0.0 || 0.9.0。不帶運算符的完整版本(如 1.2.3)只符合該版本。

資源

assets 列出套件的檔案從哪裡來。每個資源都有一個 type:

類型 欄位 說明
self place(可選) lip.toml 自身所在的歸檔,例如標籤處的儲存庫。寫了 urls 也會被忽略。
zip urls、place(可選) 通過 HTTPS 下載的 ZIP 歸檔。
mcmod urls 通過 HTTPS 下載、包含一個 LeviLamina 模組的 ZIP 歸檔;它沒有 place。參見 模組。

urls 是同一檔案的 HTTPS URL 組成的非空陣列,按順序嘗試。一個條目最多有一個 mcmod 資源。資源按 順序寫入;兩個資源或放置規則寫入同一路徑時,以後者為準。

放置規則

place 的每個成員都是一條帶有 src 和 dest 的放置規則,把資源歸檔中的檔案寫入工作區。src 是歸檔中的路徑,dest 是 相對於工作區的路徑。兩者都以 / 分隔,不得以 / 或盤符開頭,也不得包含 //、.. 段或 \。 放置規則的形式由 src 決定:

  • glob 形式:src 含有 *、? 或 [。所有與 glob 符合的檔案都寫到 dest("" 或以 / 結尾)之下,並保留其相對於 src 中開頭那些不含通配符的段的路徑。不符合任何檔案的 glob 不寫入任何 內容。
  • 目錄形式:src 為 "" 或以 / 結尾。src 之下的所有檔案都寫到 dest("" 或以 / 結尾) 之下,保留其相對於 src 的路徑。src 之下必須至少有一個檔案。
  • 檔案形式:其他情況。檔案 src 寫入 dest,dest 不得以 / 結尾。該檔案必須存在。
toml
[[variants."".assets]]
type = "zip"
urls = ["https://example.com/tool-1.0.0-win-x64.zip"]
place = [
  { src = "bin/", dest = "tools/" },
  { src = "README.md", dest = "tools/README.md" },
  { src = "plugins/*.dll", dest = "tools/plugins/" },
]

套件根部的 lip.toml 永遠不會被寫入。

有些路徑 lip 拒絕寫入:.lip 及其下的一切、其他已安裝的套件擁有的檔案,以及某一段含有 : 或以 . 或 空格結尾的路徑(參見檔案名稱)。此時安裝失敗。

glob

preserve、purge 以及 glob 形式的放置規則使用 POSIX fnmatch 模式,按段逐一符合: * 符合除 / 以外的任意字元(包括開頭的 .),? 符合除 / 以外的單個字元,[...] 符合集合中的 單個字元。** 段符合零個或多個段;以 / 結尾的模式符合一個目錄及其下的所有內容。沒有轉義字元。 glob 不得為空、不得以 / 開頭,也不得包含 // 或 \。

preserve 和 purge 符合的是相對於工作區的路徑,對模組也是如此:應寫 mods/MyMod/config/,而不是 config/。purge 永遠不會符合工作區根目錄下的 mods 或 .lip,也不會符合 .lip 之下的任何內容;mods 之下的路徑不會僅因 mods 符合而符合: mods/ 和 */ 不會刪除 mods 之下的任何內容。

鉤子

欄位 類型 說明
pre_install string[] 寫入檔案之前執行的命令。
post_install string[] 寫入檔案之後執行的命令。
pre_uninstall string[] 刪除檔案之前執行的命令。
post_uninstall string[] 刪除檔案之後執行的命令。

命令在工作區根目錄中以 lip 的環境變數執行:工作區環境的平臺為 Windows 平臺時以 cmd /s /c "<命令>" 執行,使 cmd 按原樣執行該命令,否則以 sh -c <命令> 執行,sh 通過 PATH 查找; 在 Windows 以外的系統上,Windows 平臺的命令通過 Wine 執行(參見 Linux 和 macOS),此時含有 " 的命令無法按原樣到達 cmd。以非零結束代碼結束的命令會使操作失敗。操作失敗時,lip 會復原其檔案改動,但不會復原鉤子命令已經做過的事,因此鉤子命令應當可以 安全地再次執行。

模板

與 lip v0.37.0 的 tooth.json 一樣,lip.toml 中除鍵以外的每個字串都是 Scriban 語言的模板。lip 在讀取檔案之前 先渲染每個模板,因此上文所述的一切,例如版本檢查以及 URL 和 glob 的校驗,都作用於渲染後的值。變數是按原樣書寫的 頂層欄位:{{version}}、{{id}}、{{format}}、{{info.name}}、{{variants}},以及你新增的任何其他頂層鍵。 變數儲存的是欄位的原樣內容,其中的模板不會先被渲染。

toml
version = "1.2.3"

[[variants."".assets]]
type = "mcmod"
urls = ["https://github.com/example/MyMod/releases/download/v{{version}}/MyMod-{{version}}.zip"]

模板中可以使用任何 Scriban 表達式,例如 {{version | string.replace "." "_"}}。未定義的變數渲染為空。 無法解析或渲染失敗的模板(例如 {{ if }})會使該歸檔不是套件。要原樣寫出 {{,請寫成 {{ "{{" }}。 lip pkg view 顯示渲染後的套件檔,狀態檔中記錄的也是渲染後的套件檔。

模組

帶有 mcmod 資源的條目是 模組;否則該套件是檔案套件,只放置檔案。

mcmod 資源的歸檔根部必須有該模組的 LeviLamina manifest.json,它是一個 JSON 物件,其 name 須符合 ^[A-Za-z0-9][A-Za-z0-9._-]*$。這個 name 就是 模組名稱。lip 把整個歸檔按原路徑寫入 mods/<模组名称>/。

lip 唯讀取 manifest.json 的 name,用來命名模組目錄。它不檢查也不修改其中的任何其他內容: manifest.json 與其他檔案一樣,按歸檔中的原樣寫入模組目錄。讓其 dependencies 與條目的 deps 保持一致由你自己負責。缺少 manifest.json,或其中沒有有效的 name,會在任何修改之前 使安裝失敗。

兩個模組名稱相同(不區分 ASCII 大小寫)的模組不能安裝在同一個工作區中。

條目在 mcmod 資源之外還可以有其他資源,例如一個把檔案放到 mods/ 之外的 zip 資源。

身份

已安裝套件的身份是其套件 ID,當變體不為 "" 時再加上 #<variant>,例如 github.com/LiteLDev/LegacyScriptEngine#lua。一個工作區中每個身份至多有一個套件; lip list 顯示身份,lip uninstall 也接受 身份。

身份來自套件的 id,而不是安裝來源:lip.toml 寫有 id = "github.com/user/repo" 的 ZIP 檔案, 與來自該儲存庫的套件身份相同,因此兩者不能同時安裝。

環境

工作區的環境是一個二元組 (side, platform):

  • 執行端(side):server 或 client,即工作區是遊戲的哪一端。lip 只管理服務端工作區,因此始終使用 server。客戶端工作區由 LeviLauncher 等啟動器管理;若工作區的狀態檔記錄的是 client,lip 會拒絕處理。
  • 平臺(platform):一個 .NET RID,始終為 win-x64, 無論 lip 執行在什麼系統上。在 Windows 以外的系統上,lip 通過 Wine 執行工作區的程式(參見 Linux 和 macOS)。Linux 版伺服器不是另一個平臺,而是 github.com/LiteLDev/bds 的變體 linux,其條目的平臺是 win-x64。早期 lip 寫下的、記錄 linux-x64 的狀態檔會被當作 win-x64 的狀態檔讀取 (參見狀態檔)。以 win 開頭的平臺是 Windows 平臺。

早期格式

lip v0.39 的 lip.toml 同樣是格式 4,但把執行端寫作 platform、把平臺寫作 runtime,例如 platform = "server" 和 runtime = "win-x64"。lip 不讀取這樣的條目:含有 runtime、或 platform 為 "server" 或 "client" 的條目會使該歸檔不是套件,並給出消息,提示把 platform 改名為 side、把 runtime 改名為 platform。把每個條目的這兩個鍵改名即可,其餘內容保持不變。

lip v0.37.0 及更早版本的套件沒有 lip.toml,而是有格式版本 1、2 或 3 的 tooth.json。lip 仍會安裝它們, 但從不寫入它們;請使用 lip pkg migrate 把你的套件轉換為 lip.toml。帶有 lip.toml 的歸檔從 lip.toml 讀取,不論它是否還有 tooth.json;其他格式的 tooth.json 不會被讀取。

格式 1 和 2 先像 lip v0.37.0 那樣讀取為格式 3。格式 3 的 tooth.json 隨後針對工作區的環境被完整地 轉換為一個套件檔,lip 只使用轉換結果: lip 解析、安裝並記錄到狀態檔中的都是它。安裝時不再保留任何格式 3 的語義。

  • tooth 變為 id。version 為套件的版本:在版本標籤處為標籤版本,而不論 tooth.json 的 version 寫的是 什麼;否則為該 version。
  • 保留 info,但其 avatar_url 以 https:// 開頭時變為 logo,否則被丟棄。
  • 對每個標籤,將該標籤下 platform 為空或與環境的平臺符合(tooth.json 的 platform 是 RID 模式, 例如 win-*)的變體,按 lip v0.37.0 的方式合併為一個對應該環境執行端和平臺的條目。 沒有這類變體的標籤不構成變體。
  • dependencies 原樣變為 deps。
  • 每個資源保留其 type 和 urls,其 placements 變為 place(見下文)。類型為 tar、tgz 或 uncompressed 的資源在 lip.toml 中不存在,會使該標籤在該環境下沒有變體。
  • preserve_files 變為 preserve:\ 取代為 /,不含 / 的模式加上前綴 **/,因此 config.json 變為 **/config.json。
  • remove_files 變為 purge:\ 取代為 /,不以 / 結尾的模式還會再加上一個以 / 結尾的形式,因此 logs 變為 logs 和 logs/。
  • scripts 變為 hooks:pre_install 仍為 pre_install;install 和隨後的 post_install 變為 post_install;pre_uninstall 和隨後的 uninstall 變為 pre_uninstall;post_uninstall 仍為 post_uninstall。

放置規則 { "type": ..., "src": ..., "dest": ... } 在 src 和 dest 中的 \ 取代為 /、空段和 . 段被移除 後,變為 place 的一個成員:

放置規則 place 成員
type 為 dir src 和 dest 各自加上 /(為空時除外):目錄形式。
type 為 file,src 含 *、? 或 [ src,以及加上 / 的 dest(為空時除外):glob 形式。
type 為 file,其他 src src 和 dest:檔案形式。

轉換後在套件檔中無效的 glob 或放置規則會被略去。隨後放置規則按 lip.toml 的方式執行:例如,缺失的檔案現在會使安裝 失敗,套件的 tooth.json 也永遠不會被寫入。

早期格式的套件始終是檔案套件。其身份遵循同樣的規則,例如 github.com/LiteLDev/LegacyScriptEngine#lua。

格式 3 的 schema 是 lip v0.37.0 的 manifest.schema.json, lip v0.37.0 在其套件清單頁面 中記錄了這一格式:

json
{
  "format_version": 3,
  "format_uuid": "289f771f-2c9a-4d73-9f3f-8492495a924d",
  "tooth": "github.com/user/repo",
  "version": "1.0.0",
  "info": { "name": "My Package", "description": "A short description" },
  "variants": [
    {
      "label": "",
      "platform": "win-x64",
      "dependencies": { "github.com/other/package": ">=1.0.0" },
      "assets": [
        {
          "type": "self",
          "placements": [{ "type": "dir", "src": "bin/", "dest": "bin/" }]
        }
      ],
      "preserve_files": ["config/*.json"],
      "remove_files": ["temp/"],
      "scripts": { "post_install": ["echo installed"] }
    }
  ]
}

另請參閱