说明文档:
[MD]
# 兑换码系统 (CDK) 使用手册
## 功能介绍
兑换码系统允许服务器管理员创建和管理兑换码，玩家可以通过GUI界面或命令兑换物品奖励和存款。
**核心功能：**
- 支持物品奖励（含NBT数据）
- 支持存款奖励（llmoney）
- 物品+存款混合奖励
- 使用次数限制
- 每人限用一次
- 过期时间设置
- 自定义兑换播报
- 预发布兑换码（定时发布）
- 发布提示开关
## 指令说明
### 玩家指令
| 指令 | 说明 |
|------|------|
| `/rcode` | 打开兑换码输入界面 |
| `/rcode <兑换码>` | 直接兑换指定兑换码 |
### 管理员指令
| 指令 | 说明 |
|------|------|
| `/rcode admin` | 打开管理面板 |
| `/rcode create` | 创建兑换码 |
| `/rcode list` | 查看兑换码列表 |
| `/rcode info <兑换码>` | 查看兑换码详情 |
| `/rcode delete <兑换码>` | 删除兑换码 |
| `/rcode scheduled` | 查看预发布列表 |
## 管理面板功能
### 创建兑换码
1. 输入兑换码名称
2. 从背包选择奖励物品（或选择"无"）
3. 设置存款奖励金额
4. 设置自定义播报消息（可选）
5. 设置最大使用次数（-1为无限）
6. 设置过期日期（可选）
7. 设置是否每人限用一次
### 预发布兑换码
预发布功能允许管理员预设兑换码，在指定时间自动发布。
**创建预发布：**
1. 设置兑换码和奖励（同普通创建）
2. 设置发布日期（YYYY-MM-DD格式）
3. 设置发布时间（HH:MM格式，24小时制）
4. 选择是否启用发布提示
5. 设置自定义发布提示（可选）
**预发布状态：**
- §e待发布 - 等待发布时间
- §a已发布 - 已自动发布
- §c已取消 - 被管理员取消
**预发布管理：**
- 立即发布 - 不等待，立即发布
- 取消发布 - 取消待发布的兑换码
- 删除记录 - 删除预发布记录
## 文件路径
| 文件 | 说明 |
|------|------|
| `./Meowdata/CDK/config.json` | 兑换码数据 |
| `./Meowdata/CDK/scheduled.json` | 预发布数据 |
## 配置文件结构
### config.json
```json
{
"codes": {
"EXAMPLE2024": {
"code": "EXAMPLE2024",
"reward": {
"snbt": "...",
"name": "钻石",
"type": "minecraft:diamond",
"count": 5
},
"money": 1000,
"broadcastMessage": "玩家 {player} 兑换了 {code}，获得了 {reward}！",
"maxUses": 100,
"currentUses": 0,
"singleUsePerPlayer": true,
"usedBy": [],
"expirationDate": "2025-12-31",
"enabled": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"createdBy": "Admin"
}
},
"settings": {
"language": "zh_CN",
"saveInterval": 5000
}
}
```
### scheduled.json
```json
{
"items": [
{
"id": "unique_id",
"code": "NEWYEAR2025",
"reward": { ... },
"money": 500,
"broadcastMessage": "",
"maxUses": -1,
"singleUsePerPlayer": true,
"expirationDate": null,
"createdBy": "Admin",
"publishTime": "2025-01-01T00:00:00.000Z",
"enableBroadcast": true,
"customBroadcast": "§6新年兑换码已发布: §b{code}",
"status": "pending",
"createdAt": "2024-12-25T00:00:00.000Z"
}
]
}
```
## 播报消息变量
### 兑换播报（兑换成功时）
| 变量 | 说明 |
|------|------|
| `{player}` | 玩家名称 |
| `{code}` | 兑换码 |
| `{reward}` | 奖励内容 |
### 发布提示（预发布发布时）
| 变量 | 说明 |
|------|------|
| `{code}` | 兑换码 |
## API 接口
插件通过 `exports.API` 导出接口供其他插件调用：
### 兑换码操作
#### createCode(code, options)
创建兑换码
```javascript
$Y.i.createCode("EXAMPLE2025", {
reward: { // 物品奖励（可选）
snbt: "...", // 物品SNBT数据
name: "钻石",
type: "minecraft:diamond",
count: 5
},
money: 1000, // 存款奖励（可选）
broadcastMessage: "", // 自定义播报消息
maxUses: 100, // 最大使用次数，-1为无限
singleUsePerPlayer: true, // 每人限用一次
expirationDate: "2025-12-31", // 过期日期
createdBy: "Admin" // 创建者
});
// 返回: { success: true, message: "..." }
```
#### deleteCode(code)
删除兑换码
```javascript
$Y.i.deleteCode("EXAMPLE2025");
// 返回: { success: true, message: "..." }
```
#### updateCode(code, updates)
更新兑换码属性
```javascript
$Y.i.updateCode("EXAMPLE2025", { enabled: false });
// 返回: { success: true, message: "..." }
```
#### getCodeList()
获取所有兑换码列表
```javascript
const codes = $Y.i.getCodeList();
// 返回: ["CODE1", "CODE2", ...]
```
#### getCodeInfo(code)
获取兑换码详情
```javascript
const info = $Y.i.getCodeInfo("EXAMPLE2025");
// 返回: { code, reward, money, maxUses, currentUses, ... } 或 null
```
#### validateCode(code, playerXuid)
验证兑换码是否可用
```javascript
const result = $Y.i.validateCode("EXAMPLE2025", player.xuid);
// 返回: { valid: true/false, error: "错误信息", errorCode: "CODE_NOT_FOUND", codeData: {...} }
```
#### redeemCode(code, player)
兑换兑换码
```javascript
const result = $Y.i.redeemCode("EXAMPLE2025", player);
// 返回: { success: true/false, message: "..." }
```
### 预发布操作
#### createScheduled(options)
创建预发布兑换码
```javascript
$Y.i.createScheduled({
code: "NEWYEAR2025",
reward: { ... }, // 物品奖励
money: 500, // 存款奖励
broadcastMessage: "", // 兑换时播报消息
maxUses: -1,
singleUsePerPlayer: true,
expirationDate: null,
createdBy: "Admin",
publishTime: "2025-01-01T00:00:00.000Z", // 发布时间（ISO格式）
enableBroadcast: true, // 是否启用发布提示
customBroadcast: "§6新兑换码: §b{code}" // 自定义发布提示
});
// 返回: { success: true, message: "...", id: "unique_id" }
```
#### getScheduledList(status)
获取预发布列表
```javascript
$Y.i.getScheduledList(); // 获取全部
$Y.i.getScheduledList("pending"); // 仅待发布
$Y.i.getScheduledList("published"); // 仅已发布
$Y.i.getScheduledList("cancelled"); // 仅已取消
// 返回: [{ id, code, status, publishTime, ... }, ...]
```
#### getScheduledInfo(id)
获取预发布详情
```javascript
const info = $Y.i.getScheduledInfo("unique_id");
// 返回: { id, code, status, ... } 或 null
```
#### publishScheduled(id)
立即发布预发布兑换码
```javascript
$Y.i.publishScheduled("unique_id");
// 返回: true/false
```
#### cancelScheduled(id)
取消预发布
```javascript
$Y.i.cancelScheduled("unique_id");
// 返回: { success: true/false, message: "..." }
```
#### deleteScheduled(id)
删除预发布记录
```javascript
$Y.i.deleteScheduled("unique_id");
// 返回: { success: true/false, message: "..." }
```
### GUI 操作
#### showAdminMenu(player)
打开管理面板
```javascript
$Y.i.showAdminMenu(player);
```
#### showRedeemForm(player)
打开兑换界面
```javascript
$Y.i.showRedeemForm(player);
```
## 使用示例
### 创建限时活动兑换码
1. `/rcode admin` → 创建兑换码
2. 输入兑换码：`SPRING2025`
3. 选择奖励物品（从背包）
4. 存款奖励：`500`
5. 最大使用次数：`100`
6. 过期日期：`2025-03-31`
7. 每人限用一次：开启
### 创建预发布新年兑换码
1. `/rcode admin` → 预发布兑换码
2. 输入兑换码：`NEWYEAR2025`
3. 设置奖励
4. 发布日期：`2025-01-01`
5. 发布时间：`00:00`
6. 发布时全服提示：开启
7. 自定义发布提示：`§6[新年快乐] §e新年兑换码已发布: §b{code}`
## 注意事项
1. 物品奖励会保留完整NBT数据，包括附魔、名称等
2. 预发布的定时器在服务器重启后会自动恢复
3. 已发布或已取消的预发布记录可以删除以清理数据
4. 兑换码区分大小写
## 问题排查
兑换失败提示"背包已满"
清理背包空间后重试
预发布没有按时发布
检查服务器时间是否正确，查看控制台日志
物品奖励显示异常
确保创建时背包中的物品是正常的
---
> 技术支持：伊希娅 QQ3529832433
[/MD]
