原创 闭源 工具 luckyrules 1.0.0

# LuckyRules 插件使用说明书

## 1. 插件简介

LuckyRules 是一个为 Paper 1.21.1-1.21.11 服务器设计的规则协议插件，通过自定义 Inventory GUI 界面向玩家展示服务器规则，并要求玩家同意后才能进入游戏。

## 2. 功能特性

- 自定义 Inventory GUI 界面，不使用聊天框
- 点击纸张启动 20 秒倒计时
- 倒计时期间显示剩余时间
- 倒计时结束后才能勾选同意框
- 玩家同意后，下次登录不再显示协议
- 玩家主动关闭 GUI 时被踢出服务器
- 倒计时期间自动更新 GUI 不会踢出玩家
- 玩家在同意前无法移动和聊天
- 支持配置文件自定义所有内容
- 数据持久化存储

## 3. 安装方法

### 3.1 前置条件

- Paper 1.21.1-1.21.11 服务器
- Java 21 或更高版本

### 3.2 安装步骤

1. 从插件编译结果中获取 `luckyrules-1.0.0.jar` 文件
2. 将 `luckyrules-1.0.0.jar` 复制到服务器的 `plugins` 文件夹
3. 重启服务器，插件将自动生成配置文件
4. 根据需要修改配置文件（详见第 4 节）
5. 再次重启服务器使配置生效（或使用插件重载命令）

## 4. 配置文件说明

插件会在首次运行时在 `plugins/LuckyRules/` 目录下生成 `config.yml` 配置文件。

### 4.1 配置文件内容

```yaml
# LuckyRules Configuration

# Agreement Window Settings
agreement:
# Title of the agreement window
title: "服务器规则协议"

# Main content of the agreement
content: |
===== 服务器规则 =====
1. 遵守服务器规则，文明游戏
2. 禁止使用作弊、外挂等不公平手段
3. 禁止恶意破坏服务器环境
4. 尊重其他玩家，禁止辱骂、刷屏
5. 禁止泄露服务器信息
===== 请遵守规则 =====

# Checkbox text
checkbox-text: "我已阅读并同意服务器规则"

# Button texts
agree-button: "同意"
disagree-button: "拒绝"

# Message Settings
messages:
# Message sent when player agrees
agreed: "§a您已同意服务器规则，祝您游戏愉快!"
# Message sent when player disagrees
disagreed: "§c您已拒绝服务器规则，无法进入游戏。"
# Message shown during countdown
countdown: "§e请详细阅读协议，§6{countdown}秒§e后可勾选同意"
# Message when player needs to click the paper
click-paper: "§e您已开始阅读协议，请等待倒计时结束"
# Message when player tries to interact before allowed
not-allowed: "§c请先阅读协议并等待倒计时结束"
```

### 4.2 配置项说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `agreement.title` | 协议窗口的标题 | 服务器规则协议 |
| `agreement.content` | 协议的主要内容，支持换行 | 服务器规则列表 |
| `agreement.checkbox-text` | 勾选框的文本 | 我已阅读并同意服务器规则 |
| `agreement.agree-button` | 同意按钮的文本 | 同意 |
| `agreement.disagree-button` | 拒绝按钮的文本 | 拒绝 |
| `messages.agreed` | 玩家同意后的提示消息 | §a您已同意服务器规则，祝您游戏愉快! |
| `messages.disagreed` | 玩家拒绝或关闭GUI后的踢出消息 | §c您已拒绝服务器规则，无法进入游戏。 |
| `messages.countdown` | 倒计时期间的提示消息 | §e请详细阅读协议，§6{countdown}秒§e后可勾选同意 |
| `messages.click-paper` | 玩家点击纸张后的提示消息 | §e您已开始阅读协议，请等待倒计时结束 |
| `messages.not-allowed` | 玩家尝试在不允许时交互的提示消息 | §c请先阅读协议并等待倒计时结束 |

## 5. 使用流程

### 5.1 玩家视角流程

1. 玩家加入服务器
2. 服务器显示规则协议 GUI 界面
3. 玩家点击纸张物品，开始 20 秒倒计时
4. 倒计时期间，玩家可以阅读规则但无法勾选同意框
5. 倒计时结束后，玩家可以点击羊毛物品勾选/取消勾选同意框
6. 玩家勾选同意框后，点击绿色混凝土按钮同意规则
7. 玩家同意后，GUI 关闭，玩家可以正常游戏
8. 玩家点击红色混凝土按钮或主动关闭 GUI，将被踢出服务器

### 5.2 管理员视角流程

1. 安装并配置插件
2. 重启服务器
3. 监控插件日志，确保正常运行
4. 根据需要修改配置文件
5. 重启服务器使配置生效

## 6. 权限说明

该插件不需要额外的权限配置，所有玩家默认拥有以下权限：

- `luckyrules.agree` - 允许使用 /agree 命令（备用，主要通过 GUI 交互）
- `luckyrules.disagree` - 允许使用 /disagree 命令（备用，主要通过 GUI 交互）

## 7. 常见问题解决

### 7.1 问题：玩家无法看到规则内容
**解决方案**：检查配置文件中的 `agreement.content` 配置，确保规则内容格式正确，支持换行。

### 7.2 问题：玩家点击纸张后没有反应
**解决方案**：检查服务器日志是否有错误信息，确保插件正常运行。

### 7.3 问题：玩家在倒计时期间被踢出
**解决方案**：插件已修复此问题，确保使用最新版本。

### 7.4 问题：玩家同意后仍显示协议
**解决方案**：检查 `plugins/LuckyRules/agreed-players.txt` 文件是否有写入权限，确保玩家 UUID 能正确保存。

## 8. 命令列表

虽然插件主要通过 GUI 交互，但仍提供以下备用命令：

| 命令 | 说明 | 权限 |
|------|------|------|
| `/agree` | 同意服务器规则（备用） | luckyrules.agree |
| `/disagree` | 拒绝服务器规则（备用） | luckyrules.disagree |

## 9. 数据存储

插件使用文件存储已同意规则的玩家信息：

- **存储位置**：`plugins/LuckyRules/agreed-players.txt`
- **存储格式**：每行一个玩家 UUID
- **存储机制**：玩家同意规则后自动添加，服务器重启后自动加载
- **手动管理**：可直接编辑文件添加/删除玩家 UUID

## 10. 插件更新与维护

### 10.1 更新插件

1. 停止服务器
2. 替换 `plugins` 文件夹中的旧插件文件
3. 启动服务器
4. 插件会自动读取现有配置文件

### 10.2 重载配置

目前插件不支持热重载配置，修改配置后需要重启服务器。

## 11. 联系方式

如有问题或建议，欢迎通过以下方式联系：

- 插件开发者：Luckystar913

---

感谢您使用 LuckyRules 插件！希望它能帮助您更好地管理服务器规则。