原创 开源 工具 世界管理 Carpenter's axe 木匠斧 2.0.0

[MD] # Carpenter's axe 木匠斧 手持木斧即可实现**选区填充 / 全填 / 清除**的 Paper 插件。左击选块、右击设点、右击空气切换模式、潜行右击确认执行，支持撤销、经验消耗、黑名单保护、粒子选区预览与中英文语言。 ## 环境要求 - Paper 26.2+（支持 Folia，`folia-supported: true`） - Java 21+（推荐 25/26） - 构建：JDK 26 + Gradle wrapper 9.5.1（已随项目提供） ## 安装 1. 将 `build/libs/CarpentersAxe-2.0.0.jar` 放入服务器的 `plugins/` 目录 2. 重启服务器 3. 首次启动会自动生成： - `plugins/CarpentersAxe/config.yml` —— 配置文件（含中文注释） - `plugins/CarpentersAxe/lang/zh_CN.yml`、`lang/en_US.yml` —— 可编辑的语言文件 - `plugins/CarpentersAxe/exp.json` —— 经验池欠费记录（自动管理，一般无需手动修改） ## 基本使用 手持**任意木斧**（无需改名）即可使用： | 操作 | 效果 | | --- | --- | | 左击方块 | 选择方块类型并设为位置 1（方块不会被破坏） | | 右击方块 | 设为位置 2，显示选区尺寸与方块数 | | 右击空气 | 切换模式：**填充 → 全填 → 清除** | | 潜行 + 右击（方块或空气） | 确认执行当前模式的操作 | | 蹲下 + 左击空气 | 撤销上一次操作 | | `/carpentersaxe cancel` | 取消选择 | 选择完成后，选区内会显示**末地烛粒子框**（沿方块角点绘制）。 ### 模式说明 | 模式 | 行为 | | --- | --- | | 填充 | 只在空位（空气/水/岩浆）放置方块，逐块消耗背包物品，单次上限 192 块 | | 全填 | 覆盖选区内所有方块（含已有方块），仍受黑名单限制，单次上限 192 块 | | 清除 | 清除选区内的方块，掉落物先入背包、满则掉脚边，黑名单方块不动，单次上限 1280 块 | ## 黑名单 `config.yml` 中的 `blacklist` 默认包含水、岩浆、基岩、传送门、命令方块、屏障、刷怪笼等方块： - **默认**：选区内存在黑名单方块时，操作被拒绝 - **跳过**（`/carpentersaxe bypass`，所有玩家可用）：操作不动黑名单方块，只处理其他方块 - **强制**（`/carpentersaxe force`，仅 OP）：完全无视黑名单，可操作黑名单方块 两者均为默认单次生效，追加 `toggle` 参数切换持续开关。 ## 经验消耗 `config.yml` 中 `exp` 段（默认开启）： ```yaml exp: enabled: true # 是否开启 blocksPerExp: 10 # 每多少个方块计一次费 expAmount: 1 # 每次计费消耗几点经验 ``` - 按**比例**扣费：操作不足一个计费周期时零头累计，满 1 点后统一扣除（保留一位小数） - 经验不足时操作被拒绝 - 撤销操作会返还对应经验（含累计零头） - 未扣完的零头持久化到 `exp.json`，跨会话保留，只记录欠费玩家 ## 命令 主命令：`/carpentersaxe`（别名 `/caxe`） | 命令 | 说明 | 权限 | | --- | --- | --- | | `/carpentersaxe give [玩家]` | 获取一把木匠斧 | `carpentersaxe.give`（OP） | | `/carpentersaxe clear` | 清空当前选区 | `carpentersaxe.clear`（所有玩家） | | `/carpentersaxe cancel` | 取消当前选择 | `carpentersaxe.cancel`（所有玩家） | | `/carpentersaxe undo` | 撤销上一次填充/清除（最多 20 步） | `carpentersaxe.undo`（所有玩家） | | `/carpentersaxe bypass [toggle]` | 跳过黑名单，不动黑名单方块 | `carpentersaxe.bypass`（所有玩家） | | `/carpentersaxe force [toggle]` | 强制模式，可操作黑名单方块 | `carpentersaxe.force`（OP） | | `/carpentersaxe help` | 查看使用说明 | — | | `/carpentersaxe reload` | 重载配置与语言文件 | `carpentersaxe.reload`（OP） | ## 配置（config.yml） ```yaml enabled: true # 插件总开关 maxSelection: 1280 # 选区体积上限（长×宽×高） blacklist: [...] # 黑名单方块列表 exp: { ... } # 经验消耗设置 ``` 修改配置后执行 `/carpentersaxe reload` 生效。 ## 语言 - 语言文件位于 `plugins/CarpentersAxe/lang/`，可直接编辑 - 自动按玩家客户端语言选择（`zh*` → 中文，其他 → English），控制台默认英文 - 语言文件内置版本号，插件升级后自动覆盖旧版本，管理员自定义内容（版本一致时）不会被覆盖 ## 其他特性 - **撤销**：填充/清除前自动记录快照，最多保留 20 步；填充撤销返还物品，经验按比例返还 - **粒子预览**：选区成立后沿方块角点显示末地烛粒子框，模式切换不影响 - **物理更新**：清除方块后触发周围方块状态更新（水流、沙子下落、红石等） - **物品名**：提示中的方块名按玩家客户端语言显示 ## 构建 ```bat gradlew.bat build ``` 产物位于 `build/libs/CarpentersAxe-2.0.0.jar`。 ## 文件结构 ``` src/main/java/org/little100/carpentersaxe/ ├── CarpentersAxePlugin.java # 主类（消息发送、反馈管理） ├── ConfigManager.java # config.yml 配置 ├── LangManager.java # 语言文件加载与自动检测 ├── WandManager.java # 核心逻辑（选择/填充/清除/撤销/粒子/经验） ├── WandState.java # 每玩家状态 ├── command/AxeCommand.java # 命令 └── listener/AxeListener.java # 交互监听 ``` ## 更新日志 - **2.0.0**：新增全填模式、常显提示（后移除）、模式顺序调整（填充/全填/清除）、经验按比例扣费与持久化、物品名本地化、语言文件版本机制、图标 - **1.1.0**：插件更名为 CarpentersAxe，新增语言文件/撤销/黑名单三态/粒子预览 - **1.0.0**：初始版本（建筑棒） [/MD]