转载 工具 GhostBlocks 1.0

[MD]
# GhostBlocks：客户端幽灵方块与隐形实体墙

**两条命令，两种视觉效果，无需 NMS。**

GhostBlocks 可创建两类特殊方块：

- **幽灵方块（Ghost Blocks）**：玩家能看见方块，但可以直接穿过。
- **反转幽灵方块（Inverted Ghost Blocks）**：玩家看不见方块，却无法穿过。

适用于跑酷地图、解谜房间、隐藏入口、密室逃脱、冒险地图、秘密通道、陷阱竞技场及小游戏大厅等场景。

插件基于官方 Paper API 开发，要求 Java 21；无需 NMS、反射或 ProtocolLib。

## 功能特性

- **幽灵方块**：客户端会显示为实体方块，但服务端实际保留为空气，玩家可直接穿过。
- **反转幽灵方块**：客户端显示为空气，服务端则保留真实方块，形成真正的隐形屏障。
- **数据持久化**：所有幽灵方块都会保存至 `ghosts.yml`，重启或重载后可自动恢复，包括正确的服务端方块状态。
- **防不同步机制**：玩家加入、切换世界、重生、传送或交互时自动重新同步；同时支持配置定时刷新任务。
- **完整保护**：阻止破坏、放置、方块物理更新、活塞推动、液体流动及爆炸等行为破坏幽灵方块。
- **管理工具**：支持列出、移除、按世界清除幽灵方块，重载配置以及在游戏内查看插件信息。
- **消息可完全配置**：`messages.yml` 支持 MiniMessage 与 HEX 颜色。动态输入会在解析前经过安全处理，避免旧式 `§` 颜色代码破坏文本格式。
- **安全限制**：可设置最大操作距离、每名玩家或每个世界允许创建的最大幽灵方块数量，以及方块材料黑名单。
- **轻量高效**：仅发送数据包级别的方块变更，不使用实体，也不依赖高频 Tick 逻辑。

## 命令

| 命令 | 别名 | 说明 |
|---|---|---|
| `/ghostblock [material] [x y z]` | `/gblock`、`/ghost` | 创建幽灵方块：可见，但可穿过 |
| `/invertedghostblock [material] [x y z]` | `/igblock`、`/invghost` | 创建反转幽灵方块：不可见，但不可穿过 |
| `/ghostblocks remove` | — | 移除当前正在查看的幽灵方块 |
| `/ghostblocks list` | — | 列出附近的幽灵方块 |
| `/ghostblocks clear [world]` | — | 清除指定世界中的全部幽灵方块 |
| `/ghostblocks reload` | — | 重载 `config.yml` 与 `messages.yml` |
| `/ghostblocks info` | — | 显示插件信息 |

未填写坐标时，插件会使用玩家当前视线所指向的方块。未指定材料时，则使用配置文件中设定的默认材料。

## 权限

| 权限 | 说明 | 默认值 |
|---|---|---|
| `ghostblocks.create.ghost` | 创建幽灵方块 | op |
| `ghostblocks.create.inverted` | 创建反转幽灵方块 | op |
| `ghostblocks.remove` | 移除幽灵方块 | op |
| `ghostblocks.admin` | 完整管理权限，包括列表、清除、重载和信息查看 | op |

## 配置

- `config.yml`：用于配置默认材料、最大操作距离、列表与清除半径、单人限制、重新同步间隔及材料黑名单。
- `messages.yml`：包含插件发送的所有消息，支持 MiniMessage 与 HEX 颜色。

## 安装方法

1. 下载 `GhostBlocks-1.0.0.jar`。
2. 将其放入服务器的 `plugins/` 文件夹。
3. 重启服务器。
4. 编辑 `config.yml` 和 `messages.yml`，然后执行 `/ghostblocks reload`。

**运行要求：**Paper 或其分支服务端（如 Purpur）**1.21.11**、**Java 21**，且无需额外依赖。

## 常见问题

### 是否需要 ProtocolLib？

不需要。插件仅使用官方 Paper API。

### 幽灵方块会在服务器重启后保留吗？

会。它们会存储在 `ghosts.yml` 中，并在重启后完整恢复，包括服务端方块状态。

### 玩家能否破坏或利用幽灵方块进行恶意操作？

不能。插件会处理方块破坏、放置、物理更新、活塞、液体和爆炸事件。只有拥有 `ghostblocks.remove` 权限的玩家才能删除幽灵方块。

### 是否支持 Spigot？

插件基于 Paper API 构建并测试，建议使用 Paper 或 Paper 分支服务端。
[/MD]