插頭外掛模板

Spigot 外掛模板

您可以使用此範本輕鬆使用 Gradle 開發自己的高品質 Spigot 外掛程式。

請參閱 minecraft-server-template，以便在 30 秒內快速啟動您的 Minecraft 網路。

• 特徵
• 快速入門設定
• 發布插件的新版本
  • 提交訊息格式
• 發布你的maven包
  • 關於群組和artifactId
  • Github 套件認證
• 調試你的插件
  • 自動複製您的插件
  • 運行和調試 Minecraft 伺服器
• 參考

特徵

模板或更好的樣板附帶了許多功能，如果您想開發高品質的插件，這些功能非常有用。但是您不需要使用所有這些功能，您可以簡單地刪除不需要的功能。

• 準備使用包含大量實用任務的Gradle項目
• 使用 SpiGradle 根據專案屬性自動產生plugin.yaml
• 整合Spigot 測試伺服器，可一鍵建置、複製外掛程式並在 IntelliJ 任務中開始偵錯
• Gradle 影子插件可輕鬆透過插件傳送所需的依賴項
• 範例集成，包括註釋命令框架和 Vault 的測試。
• JUnit 5測試設置，包括 MockBukkit 和 AssertJ
• Jacoco 代碼覆蓋率報告，包括到 codecov 的上傳任務
• 完全整合的語意發布發布管道
• 基於傳統提交訊息自動產生變更日誌
• 用於建置和發布的Github Actions工作流程
• 將Maven 工件發佈到 GitHub Packages

  不再需要自架 Nexus 或神器伺服器

• Bug 和功能請求的 GitHub問題模板
• 貢獻和行為準則指南
• 漂亮的徽章可以展示您的項目

快速入門設定

• 使用此範本建立新的 Github 專案。
• 克隆新儲存庫並在 IntelliJ 中開啟它。
• 更新gradle.properties檔案並更改以下變數：
  • group ：your-maven-group-id（例如：io.github.silthus）
  • pluginName : 你的插件名稱
  • author ：你的名字
• 更新settings.gradle中的root.projectName 。這將是您的artifactId 。
• 刪除CHANGELOG.md 。它將在您的第一個版本中產生。
• 更新README以指向您的專案和 spigot 資源 ID。
• 重命名java 套件和插件以匹配您的專案。
• 然後執行prepareSpigotPlugins gradle任務，這將嘗試下載所有插件依賴項並將它們放入debug/spigot/plugins/中。
• 透過執行debugPaper任務啟動Minecraft 伺服器。這將在背景啟動伺服器，您可以使用localhost:25565位址連接到它。
• 程式碼遠離:) -一旦你準備好，將你的提交（以傳統的提交風格）推送到master。

在提交任何拉取請求或開啟問題之前，請先閱讀貢獻指南。

筆記
您可能需要在重新命名套件並重新匯入 gradle 專案後執行gradle clean任務，以解決產生plugin.yml時出現的錯誤。

發布插件的新版本

此範本的主要優點之一是，它會根據您的提交訊息在每次推送到master時自動發布新版本。這可以確保您的插件是按照語義版本控制指南發布的。為此，您必須遵循一些簡單的規則：

• 僅將工作且經過測試的程式碼提交到主分支。使用拉取請求來處理更大的功能或錯誤修復，並在準備好時合併它們。
• 每個錯誤修復、功能和更改都應該有一個與其關聯的提交。不要將多個錯誤、功能等混合到一個巨大的提交訊息中。保持較小的提交大小並經常提交。
• 您的提交訊息必須遵循傳統的提交規則。

提交訊息格式

有關該主題的更多詳細資訊和範例，請參閱常規提交主頁。但這裡有一個快速總結可以幫助您入門。

常規提交規範是提交訊息之上的輕量級約定。它提供了一組簡單的規則來創建明確的提交歷史記錄；這使得在其上編寫自動化工具變得更加容易。透過描述提交訊息中所做的功能、修復和重大更改，該約定與 SemVer 相吻合。

提交訊息的結構應如下：

 [optional scope]: 

[optional body]

[optional footer(s)]

提交包含以下結構元素，用於向庫或插件的使用者傳達意圖：

• fix:修復類型的提交會修補程式碼庫中的錯誤（這與語意版本控制中的 PATCH 相關）。
• feat:類型 feat 的提交為程式碼庫引入了一個新功能（這與語意版本控制中的 MINOR 相關）。
• BREAKING CHANGE:具有頁腳 BREAKING CHANGE: 的提交，或附加 !在類型/範圍之後，引入了重大 API 變更（與語義版本控制中的主要相關）。重大變更可以是任何類型提交的一部分。
• 允許使用 fix: 和 feat: 以外的類型，例如 @commitlint/config-conventional （基於 Angular 約定）建議build: 、 chore: 、 ci: 、 docs: 、 style: 、 refactor: 、 perf: 、 test:和其他。
• 可以提供除BREAKING CHANGE: 以外的頁腳，並遵循類似於 git Trailer 格式的約定。其他類型不是常規提交規範所強制要求的，並且對語義版本控制沒有隱式影響（除非它們包含重大更改）。

範圍可以提供給提交的類型，以提供額外的上下文信息，並且包含在括號內，例如feat(parser): add ability to parse arrays 。

以下是一些範例：

提交帶有描述和重大變更頁腳的訊息

 feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

提交沒有正文的訊息

 docs: correct spelling of CHANGELOG

提交帶有範圍的訊息

 feat(lang): add polish language

提交具有多段落正文和多個頁腳的訊息

 fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

發布你的maven包

當您發布新版本時，您的外掛程式將自動作為 Maven 套件發佈到 Github 包上。

關於群組和artifactId

您的artifactId附加的group用於在將您的專案匯入其他專案時唯一標識您的專案。當您在專案中匯入 spigot 時，您可以使用群組org.spigotmc後面跟著 artifactId spigot-api和版本。

以下內容摘自官方 Maven 命名指南。

• groupId在所有項目中唯一標識您的項目。群組 ID 應遵循 Java 的套件名稱規則。這意味著它以您控制的反向網域開頭。例如： org.apache.maven 、 org.apache.commons 。
  如果您沒有域名，您可以使用 github 域名io.github並附加您的 Github 用戶名，例如io.github.silthus
• artifactId是沒有版本的 jar 的名稱。如果您創建了它，那麼您可以選擇任何您想要的名稱，其中包含小寫字母且沒有奇怪的符號。例如：`maven，commons-math

Github 套件認證

如果你想在其他專案中使用你的maven包，你需要為Github包配置身份驗證。

1. 建立 Github 個人存取權令牌
2. 使用以下內容建立或更新C:Users%username%.gradle中的gradle.properties ，並將YOUR_GITHUB_USERNAME替換為您的 Github 使用者名稱，將YOUR_PERSONAL_ACCESS_TOKEN替換為步驟 1 中的存取權杖。

 gpr.user =YOUR_GITHUB_USERNAME
gpr.key =YOUR_PERSONAL_ACCESS_TOKEN

調試你的插件

自動複製您的插件

您可以使用GradleprepareSpigotPlugins任務將插件從工作目錄匯出到插件目錄。該任務將自動建立您的插件並將其複製到plugins/目錄中。

運行和調試 Minecraft 伺服器

您可以使用 IntelliJ 中的Server運行配置來運行或調試您的插件，以自動下載 Minecraft 伺服器、構建它、將您的插件和依賴插件複製到其中並以調試模式啟動它。

這是由於 Spigradle 調試任務的強大功能。在 Spigradle Github 頁面上了解更多。

參考

• Spigradle：提供很棒的 gradle 任務，讓你的生活變得更輕鬆
• 語義發布：在我看來每個項目都應該使用它！
• 常規提交訊息：以正確的方式提交訊息