docs: 整理 README 与仓库配置

merge: 合并 dev-26.1 的 Paper 26.1 适配
2026-04-24 05:12:56 +08:00 · 2026-04-24 04:38:38 +08:00
5 changed files with 139 additions and 164 deletions
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -11,25 +11,28 @@ permissions:
 jobs:
  build:
    runs-on: ubuntu-latest
-    
+
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
-      
-      - name: 设置 Java
+
+      - name: 设置 Java 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
-          cache: maven
-      
-      - name: 构建插件
-        run: mvn clean package -B
-      
+          cache: gradle
+
+      - name: 授予执行权限
+        run: chmod +x gradlew
+
+      - name: 构建全部版本
+        run: ./gradlew buildAllVersions
+
      - name: 创建发行版
        uses: softprops/action-gh-release@v1
        with:
-          files: target/essentialsc-*.jar
+          files: build/libs/EssentialsC*.jar
          generate_release_notes: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,7 @@
 # Log files
 *.log

-# Package Files
+# Package files
 *.jar
 *.war
 *.nar
@@ -50,14 +50,14 @@ bin/
 # VS Code
 .vscode/

-# macOS
+# System files
 .DS_Store
 Thumbs.db

-# Test server (不要上传测试服务器文件)
+# 测试服务器目录
 test-server/

-# Reference files (不要上传参考资料)
+# 参考资料目录
 references/

 # Plugin build output
--- a/README.md
+++ b/README.md
@@ -1,189 +1,157 @@
 # EssentialsC

-> 一个轻量级的 Paper 服务器插件，灵感来自 CMI，但更加精简、易用且现代化。
+轻量、现代、面向 Paper 服务端的基础功能插件，灵感来自 CMI，但更聚焦于常用能力与模块化构建。

 [![Version](https://img.shields.io/github/v/release/Coldsmiles/EssentialsC?style=flat-square)](https://github.com/Coldsmiles/EssentialsC/releases)
 [![License](https://img.shields.io/github/license/Coldsmiles/EssentialsC?style=flat-square)](LICENSE)
-[![Paper](https://img.shields.io/badge/Paper-1.21+-8A2BE2?style=flat-square)](https://papermc.io/)
-[![Java](https://img.shields.io/badge/Java-21+-orange?style=flat-square)](https://www.oracle.com/java/)
+[![Paper](https://img.shields.io/badge/Paper-1.21.11%2B-blue?style=flat-square)](https://papermc.io/)
+[![Java](https://img.shields.io/badge/Java-21-orange?style=flat-square)](https://adoptium.net/)

-## ✨ 核心特性
+## 项目定位

-### 🎯 随身功能方块
-随时随地打开各种功能性方块，无需放置实体方块：
- **工作台** (`/workbench`, `/wb`)
- **铁砧** (`/anvil`)
- **制图台** (`/cartographytable`, `/ct`)
- **砂轮** (`/grindstone`, `/gs`)
- **织布机** (`/loom`)
- **锻造台** (`/smithingtable`, `/st`)
- **切石机** (`/stonecutter`, `/sc`)
- **末影箱** (`/enderchest`, `/ec`)
+- 最低支持版本为 `Paper 1.21.11`
+- 已适配 `Paper 26.1.2`
+- 构建环境固定为 `Java 21`
+- 配置与文本分离：行为配置放在 `config.yml`，提示文本放在 `lang/`
+- 支持模块裁剪，便于按需构建不同版本

-### 📦 智能容器管理
- **潜影盒快捷打开** - 潜行+右键直接打开（类似 CMI）
-  - ✅ 支持自定义标题（可配置）
-  - ✅ 防刷物品机制（快照验证 + 数量检查）
-  - ✅ 防止套娃（不能放入另一个潜影盒）
-  - ✅ 异常恢复（物品丢失自动掉落）
+## 主要功能

-### 🔧 实用工具
- **帽子** (`/hat`) - 将手中物品戴在头上
- **自杀** (`/suicide`, `/die`) - 快速自杀
- **飞行** (`/fly`) - 切换飞行模式
- **修复** (`/repair`, `/rep`) - 修复手中或所有物品
- **饱食** (`/feed`) - 补满饱食度
+### 便捷方块

-### 💚 生存辅助
- **治疗** (`/heal`) - 恢复生命值和饱食度
- **隐身** (`/vanish`, `/v`) - 管理员隐身模式
+- `/workbench` `(/wb)`
+- `/anvil`
+- `/cartographytable` `(/ct, /cartography)`
+- `/grindstone` `(/gs)`
+- `/loom`
+- `/smithingtable` `(/st, /smithing)`
+- `/stonecutter` `(/sc)`
+- `/enderchest` `(/ec)`
+- `/essc blocks` 打开便捷菜单

-### 📊 管理功能
- **玩家查询** (`/seen`, `/info`) - 查看玩家上线时间和信息
- **功能方块菜单** (`/essc blocks`) - GUI 方块集合面板
- **配置重载** (`/essc reload`) - 重新加载配置文件
+### 玩家功能

---
+- `/fly`
+- `/nightvision` `(/nv)`
+- `/glow`
+- `/heal`
+- `/feed`
+- `/repair` `(/rep)`
+- `/hat`
+- `/suicide` `(/die)`
+- `/vanish` `(/v)`
+- `/seen` `(/info)`
+- `/tpsbar`
+- `/essc admin` 管理模式切换

-## 🌍 多语言支持
+### 其它功能

- ✅ 完整的中文和英文配置
- ✅ 方块标题自动跟随客户端语言
- ✅ 可自定义所有消息文本
+- Shift + 右键快捷打开潜影盒
+- 潜影盒交互保护，尽量避免刷物品、吞物品和嵌套放入问题
+- 管理模式独立背包、装备栏与状态切换
+- Enderman 掉落方块控制
+- JEI 配方同步修复

-## ⚡ 权限系统
+## 构建变体

- ✅ 精细的权限管理
- ✅ 帮助菜单智能显示（只显示有权限的命令）
- ✅ 默认仅 OP 可用，可通过权限插件授权
- ✅ CMI 风格的命令别名支持
+项目目前提供三个常用构建版本：

-## 📦 快速开始
+| 版本 | 产物名 | 说明 |
+| --- | --- | --- |
+| 标准版 | `EssentialsC-<version>.jar` | 默认版本，不包含 `mob-drops` 模块 |
+| 完整版 | `EssentialsC-all-<version>.jar` | 包含全部模块 |
+| 精简版 | `EssentialsC-lite-<version>.jar` | 仅排除 `blocks` 模块，保留 `mob-drops` |

-### 系统要求
- **服务器**: Paper 1.21+
- **Java**: 21+
+如果需要进一步裁剪模块，也可以使用自定义构建参数生成 `custom` 版本。

-### 安装步骤
-1. 下载最新版本的 [`essentialsc-*.jar`](https://github.com/Coldsmiles/EssentialsC/releases)
-2. 将文件放入服务器的 `plugins` 文件夹
-3. 重启服务器
-4. 编辑 `plugins/EssentialsC/config.yml` 配置语言
-5. （可选）使用权限插件为玩家授予相应权限
+## 安装说明

-## 🎮 命令列表
+1. 从 [Releases](https://github.com/Coldsmiles/EssentialsC/releases) 下载所需版本。
+2. 将插件放入服务端的 `plugins/` 目录。
+3. 启动一次服务端以生成配置文件。
+4. 按需修改 `plugins/EssentialsC/config.yml` 与 `plugins/EssentialsC/lang/` 下的语言文件。
+5. 如有需要，使用权限插件为玩家授权。

-### 基础命令
-| 命令 | 说明 |
-|------|------|
-| `/essc help` | 显示帮助菜单（根据权限动态显示） |
-| `/essc reload` | 重载配置（管理员） |
-| `/essc blocks` | 打开功能方块菜单 |
+## 配置说明

-### 功能方块命令
-| 命令 | 别名 | 说明 |
-|------|------|------|
-| `/workbench` | `/wb` | 打开工作台 |
-| `/anvil` | - | 打开铁砧 |
-| `/cartographytable` | `/ct` | 打开制图台 |
-| `/grindstone` | `/gs` | 打开砂轮 |
-| `/loom` | - | 打开织布机 |
-| `/smithingtable` | `/st` | 打开锻造台 |
-| `/stonecutter` | `/sc` | 打开切石机 |
-| `/enderchest` | `/ec` | 打开末影箱 |
+当前配置结构以“行为配置”和“文本配置”分离为原则：

-### 其他命令
-| 命令 | 别名 | 说明 |
-|------|------|------|
-| `/hat` | - | 将手中物品戴在头上 |
-| `/suicide` | `/die` | 自杀 |
-| `/fly` | - | 切换飞行模式 |
-| `/heal` | - | 恢复生命值和饱食度 |
-| `/vanish` | `/v` | 切换隐身模式（管理员） |
-| `/seen` | `/info` | 查看玩家信息（管理员） |
-| `/feed` | - | 补满饱食度 |
-| `/repair` | `/rep` | 修复手中或所有物品 |
+- `config.yml`
+  - 语言选择
+  - 管理模式行为
+  - JEI 同步开关
+  - 掉落控制
+  - TPSBar 模式
+  - 便捷菜单布局
+- `lang/zh_CN.yml`、`lang/en_US.yml`
+  - 命令反馈
+  - 帮助信息
+  - 菜单文本
+  - 管理模式文本
+  - TPSBar 文本

-> 💡 **提示**: 使用 `/repair all` 可以修复背包中的所有物品
+配置文件包含 `config-version`，后续如有结构升级，可基于版本号进行迁移与重建。

-## ⚙️ 配置说明
+## 权限示例

-### config.yml
-```yaml
-# 语言设置 (en_US, zh_CN)
-language: "zh_CN"
+常用权限节点：

-# 通用设置
-settings:
-  enable-feedback: true  # 启用命令反馈消息
-
-# 潜影盒设置
-shulkerbox:
-  default-title: "&e潜影盒"  # 默认标题（支持颜色代码）
+```text
+essentialsc.command.blocks
+essentialsc.command.workbench
+essentialsc.command.enderchest
+essentialsc.command.fly
+essentialsc.command.nightvision
+essentialsc.command.glow
+essentialsc.command.heal
+essentialsc.command.feed
+essentialsc.command.repair
+essentialsc.command.vanish
+essentialsc.command.seen
+essentialsc.command.admin
+essentialsc.command.tpsbar
+essentialsc.shulkerbox.open
+essentialsc.mobdrops.enderman
+essentialsc.*
 ```

-### 自定义语言
-编辑 `plugins/EssentialsC/lang/` 目录下的语言文件来自定义所有消息文本。
+具体默认值与完整节点以 `paper-plugin.yml` 为准。

-## 🔐 权限节点
-
-所有命令默认需要 OP 权限。使用权限插件授予权限：
-
-### 基础权限
-```
-essentialsc.command.workbench         # 工作台
-essentialsc.command.anvil             # 铁砧
-essentialsc.command.cartographytable  # 制图台
-essentialsc.command.grindstone        # 砂轮
-essentialsc.command.loom              # 织布机
-essentialsc.command.smithingtable     # 锻造台
-essentialsc.command.stonecutter       # 切石机
-essentialsc.command.enderchest        # 末影箱
-essentialsc.command.hat               # 帽子
-essentialsc.command.suicide           # 自杀
-essentialsc.command.fly               # 飞行
-essentialsc.command.heal              # 治疗
-essentialsc.command.vanish            # 隐身
-essentialsc.command.seen              # 玩家查询
-essentialsc.command.feed              # 饱食度
-essentialsc.command.repair            # 修复
-essentialsc.shulkerbox.open           # 潜行+右键潜影盒
-```
-
-### 管理权限
-```
-essentialsc.command.blocks            # 功能方块菜单
-essentialsc.command.reload            # 重载配置
-essentialsc.command.help              # 帮助（默认开放）
-```
-
-### 通配符
-```
-essentialsc.*                         # 所有权限
-```
-
-## 🔨 从源码构建
+## 从源码构建

 ```bash
 git clone https://github.com/Coldsmiles/EssentialsC.git
 cd EssentialsC
-./gradlew build
+./gradlew buildAllVersions
 ```

-编译后的文件位于 `build/libs/essentialsc-*.jar`
+Windows 可使用：

-## 🤝 贡献
+```powershell
+.\gradlew.bat buildAllVersions
+```

-欢迎提交 Issue 和 Pull Request！
+构建产物输出到 `build/libs/`。

-## 📄 许可证
+常用任务：

-本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
+```bash
+./gradlew shadowJarStandard
+./gradlew shadowJarAll
+./gradlew shadowJarLite
+```

-## 👨‍💻 作者
- GitHub: [@Coldsmiles](https://github.com/Coldsmiles)
- 网站: www.infstar.cn
+## 开发说明

-## ⭐ 支持
+- 使用 `paperweight-userdev` 进行 Paper 开发
+- 运行时通过反射加载可选模块，避免裁剪版本因类缺失而启动失败
+- 发布流程基于 GitHub Actions 和 Gradle Wrapper

-如果觉得这个插件对你有帮助，请考虑在 GitHub 上给它一个 Star！
+## 许可证
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+## 仓库
+
+- GitHub: <https://github.com/Coldsmiles/EssentialsC>
+- Gitea: <https://git.infstar.cn/InfStarMC/EssentialsC>
--- a/settings.gradle
+++ b/settings.gradle
@@ -1,13 +1,13 @@
 pluginManagement {
    repositories {
-        // 阿里云 Gradle 插件镜像（优先）
+        // 阿里云 Gradle 插件镜像，优先使用以提升国内拉取稳定性
        maven {
            name = 'aliyun-gradle-plugin'
            url = uri('https://maven.aliyun.com/repository/gradle-plugin')
        }
        // Gradle 官方插件仓库
        gradlePluginPortal()
-        // PaperMC 官方仓库（用于 paperweight 插件）
+        // PaperMC 官方仓库，用于解析 paperweight 插件
        maven {
            name = 'papermc'
            url = uri('https://repo.papermc.io/repository/maven-public/')
--- a/src/main/resources/paper-plugin.yml
+++ b/src/main/resources/paper-plugin.yml
@@ -1,5 +1,5 @@
 name: EssentialsC
-description: 适用于 Paper 服务端的轻量基础插件。
+description: 适用于 Paper 服务端的轻量基础功能插件。
 version: ${version}

 main: cn.infstar.essentialsC.EssentialsC
@@ -69,7 +69,7 @@ permissions:
    description: 允许使用 /feed
    default: op
  essentialsc.command.feed.others:
-    description: 允许为其他玩家补食
+    description: 允许为其他玩家补充饥饿值
    default: op
  essentialsc.command.repair:
    description: 允许使用 /repair
@@ -86,11 +86,14 @@ permissions:
  essentialsc.command.reload:
    description: 允许使用 /essc reload
    default: op
+  essentialsc.command.tpsbar:
+    description: 允许使用 /tpsbar
+    default: op
  essentialsc.shulkerbox.open:
    description: 允许通过 Shift+右键快捷打开潜影盒
    default: op
  essentialsc.mobdrops.enderman:
-    description: 允许控制末影人掉落
+    description: 允许控制末影人掉落方块
    default: op
  essentialsc.*:
    description: 授予 EssentialsC 的全部权限
@@ -121,5 +124,6 @@ permissions:
      essentialsc.command.admin: true
      essentialsc.command.help: true
      essentialsc.command.reload: true
+      essentialsc.command.tpsbar: true
      essentialsc.shulkerbox.open: true
      essentialsc.mobdrops.enderman: true
Author	SHA1	Message	Date
Coldsmile	0a45be832b	docs: 整理 README 与仓库配置	2026-04-24 05:12:56 +08:00
Coldsmile	376d63e906	merge: 合并 dev-26.1 的 Paper 26.1 适配	2026-04-24 04:38:38 +08:00