Skip to content

CURSEFORGE_INTEGRATION.md

Latest commit

 

History

History
104 lines (68 loc) · 4.51 KB

CURSEFORGE_INTEGRATION.md

File metadata and controls

104 lines (68 loc) · 4.51 KB
Raw

CurseForge 官方 API 整合

BlockPilotMC 現在只使用 CurseForge 官方 Core API；所有 CurseForge 搜尋、分析、版本與下載流程都統一走官方協議。

設定

在部署主機的BlockPilot 設定頁：

不要把實際 Key 寫入：

  • GitHub 原始碼
  • .env.example
  • Issue / Discussion
  • Release ZIP
  • 前端 JavaScript
  • 畫面或日誌

API Key 只由 BlockPilot API 後端讀取，前端不會取得 Key。

官方協議

  • Base URL：https://api.curseforge.com
  • Header：x-api-key
  • Search：GET /v1/mods/search
  • Project：GET /v1/mods/{modId}
  • Description：GET /v1/mods/{modId}/description
  • Files：GET /v1/mods/{modId}/files
  • File：GET /v1/mods/{modId}/files/{fileId}
  • Download URL：GET /v1/mods/{modId}/files/{fileId}/download-url
  • Batch Projects：POST /v1/mods

完整 Endpoint 與 Enum Code：CURSEFORGE_API_REFERENCE.md。

模組即時搜尋

使用者在「插件及模組」選擇 CurseForge 時：

  1. BlockPilot 依目前伺服器 Minecraft 版本、Loader 與關鍵字呼叫 Search Mods。
  2. 不建立 CurseForge 全站本地 catalog。
  3. 點「模組分析」才讀取 Project、完整 Description、Files 與 File dependencies。
  4. 點「安裝」才取得指定 File 的官方 Download URL。
  5. allowModDistribution=false 時不直接下載，改提示前往原始頁面。

模組分析

官方 Core API 的 Project metadata 可提供名稱、作者、摘要、分類、版本/檔案等；完整說明由 Mod Description endpoint 取得。

CurseForge Core API 的 Mod schema 沒有獨立 license 或 client/server environment 欄位。因此：

  • 「這個模組是什麼」：以 summary + full description 整理。
  • Dedicated server / Environment：官方 Core API 目前沒有結構化欄位可直接判斷，因此 BlockPilot 顯示「未知」，不使用搜尋引擎或自製推測服務補值。

File dependencies 會依官方 FileRelationType 顯示。RequiredDependency=3 可供安裝流程自動處理。官方 Core API 沒有反向 dependents endpoint，所以 BlockPilot 不會偽造「哪些專案依賴此模組」。

Modpack / Server Pack

CurseForge 模組包使用 Mods class 4471 搜尋。選擇版本後：

  1. 取得 Client File。
  2. 檢查 serverPackFileId / isServerPack。
  3. 取得真正 Server Pack File。
  4. 檢查作者第三方散布設定。
  5. 取得官方 Download URL。
  6. 下載 ZIP 後沿用 BlockPilot 原本的路徑、符號連結、加密 ZIP、容量安全檢查。

貼入 curseforge.com/minecraft/modpacks/... 網頁時，BlockPilot 只從網址取出 slug / fileId，再使用官方 API 解析，不抓 CurseForge HTML 或網站內部 /api/v1/...。

測試

填入 .env 後可執行：

Test-CurseForge-API.bat

或：

在 BlockPilot「設定 → CurseForge 官方 API」按「測試連線」

測試只讀取 API，不會下載或安裝模組；會確認 Minecraft Game、Classes 與一筆 Search Mods。

CurseForge 官方 API Details 與 Environment

  • GET /v1/mods/{modId}（Get Mod / Details）使用公開 Mod schema；目前沒有 environment、clientSide 或 serverSide 欄位。
  • GET /v1/mods/{modId}/description 只回傳模組完整描述內容，不是 CurseForge 網站右側 Details 面板的所有結構化欄位。
  • BlockPilot 不使用搜尋引擎、網頁爬取或自製 Environment Resolver 補值。CurseForge 官方 API 用於 Project、File、Loader、Minecraft Version、Dependencies、Fingerprint 與下載資訊；Environment 維持未知。

CurseForge Server Pack 啟動腳本

CurseForge 作者提供的 Server Pack 常會包含 startserver.bat、start-server.bat、run.bat 或相對應的 Linux .sh 啟動腳本。這些腳本可能在第一次啟動時自行下載／安裝 Forge、NeoForge 或其他必要的 Loader／核心。

BlockPilot 對 CurseForge Server Pack 不再自動補核心。安裝時會：

  1. 解壓作者提供的 Server Pack。
  2. 優先辨識 startserver.bat / start-server.bat / run.bat / start.bat / Linux .sh 等啟動腳本。
  3. 將作者腳本直接保存為伺服器啟動指令，不額外附加 nogui 等參數。
  4. 第一次啟動時讓模組包自己的腳本完成核心／Loader 安裝。
  5. 腳本啟動 Java 後，BlockPilot 仍會追蹤實際 Java PID、CPU、RAM 與主控台。

若 CurseForge Server Pack 既沒有作者啟動腳本，也沒有可辨識的既有核心，BlockPilot 會停止並提示使用者，不會擅自替該模組包安裝另一個核心。