[MD]# Point — 点券 + 点券商城
A地下城点券系统。提供点券存储/转账/兑换/排行榜 + 完整的点券商城（支持物品和命令商品）+ OP 游戏内可视化管理。
## 目录
- [命令速查](#命令速查)
- [玩家使用](#玩家使用)
- [点券面板 /point](#点券面板-point)
- [转账](#转账)
- [兑换银币](#兑换银币)
- [排行榜](#排行榜)
- [商城购物 /pshop](#商城购物-pshop)
- [OP 管理](#op-管理)
- [管理命令](#管理命令)
- [商城管理 GUI](#商城管理-gui)
- [配置文件](#配置文件)
- [config.yml](#configyml)
- [shop.yml](#shopyml)
- [商品类型说明](#商品类型说明)
- [自动迁移](#自动迁移)
- [软依赖](#软依赖)
---
## 命令速查
| 命令 | 权限 | 说明 |
|------|------|------|
| `/point` | `point.use` | 打开点券面板（余额/兑换/排行榜） |
| `/point pay <玩家> <数量>` | `point.use` | 转账给在线玩家 |
| `/point add <玩家> <数量>` | `point.admin` | 【OP】增加点券 |
| `/point remove <玩家> <数量>` | `point.admin` | 【OP】扣除点券 |
| `/point set <玩家> <数量>` | `point.admin` | 【OP】设置点券为指定值 |
| `/pshop` | `point.use` | 打开点券商城 |
| `/pshop admin` | OP | 打开商城管理界面 |
别名: `/点券` → `/point`, `/点券商店` / `/pointshop` → `/pshop`
---
## 玩家使用
### 点券面板 /point
输入 `/point` 打开点券面板，显示：
- **当前余额**：你拥有的点券数量
- **汇率**：1 点券 = N 银币（由服主在 config.yml 配置）
面板提供三个功能按钮：
```
[转账点券] → 提示使用 /point pay 命令
[兑换银币] → 打开兑换界面
[排行榜] → 查看点券富豪榜 TOP 10
[关闭] → 关闭面板
```
### 转账
```
/point pay <玩家名> <数量>
```
将点券转账给另一位**在线**玩家。双方都会收到转账提示。
例: `/point pay Steve 500` — 转给 Steve 500 点券
### 兑换银币
在点券面板点击 **"兑换银币"**，进入兑换界面：
- **兑换全部**：将所有点券按汇率兑换为银币
- **兑换一半**：将一半点券兑换（向下取整）
- **返回**：返回主面板
> 兑换依赖 EconomyAPI 插件。如果 EconomyAPI 未加载，兑换功能不可用。
### 排行榜
在点券面板点击 **"排行榜"**，查看点券最多的前 10 名玩家及其余额。
### 商城购物 /pshop
输入 `/pshop` 打开商城，流程如下：
```
选择分类 → 选择商品 → 确认购买 → 扣点券 → 获得商品
```
1. **分类列表**：显示所有商品分类（带图标），顶部显示你的点券余额
2. **商品列表**：显示该分类下所有商品，每项显示名称、价格、简介
3. **确认页**：显示商品详情（类型/价格/余额/介绍），点击 **"确认购买"** 完成交易
**购买保障**：
- 余额不足时提示"点券不足"，不会扣费
- 物品类商品：背包空间不足时提示"请整理背包"，不会扣费
- 购买成功后自动返回分类列表，可继续购物
> OP（管理员）在商城底部会看到额外的 **"OP系统"** 按钮，点击进入管理界面。
---
## OP 管理
### 管理命令
```
/point add <玩家> <数量> 给玩家增加点券
/point remove <玩家> <数量> 从玩家扣除点券
/point set <玩家> <数量> 将玩家点券设为指定值
```
> 目标玩家必须在线。
### 商城管理 GUI
输入 `/pshop admin` 或在商城底部点击 **"OP系统"** 进入。
```
OP管理系统
├── [1] 添加类型 — 新建商品分类
├── [2] 添加商品 — 在某分类下新建商品
├── [3] 商品里新增商品 — 给已有商品追加物品/命令条目
├── [4] 删除商品 — 删除某分类下的商品
├── [5] 删除类型 — 删除整个分类
└── [6] 返回
```
#### ① 添加类型
弹出自定义表单，填写：
- **类型名称**（必填）：如 "武器"、"消耗品"、"道具"
- **类型图标路径**（选填）：Minecraft 纹理路径，默认 `textures/items/apple`
常见图标：
```
textures/items/diamond_sword 钻石剑
textures/items/emerald 绿宝石
textures/items/gold_ingot 金锭
textures/items/apple 苹果
textures/items/potion_bottle 药水瓶
textures/blocks/chest_front 箱子
textures/items/book_normal 书
```
#### ② 添加商品
第一步选择目标分类 → 弹出自定义表单，填写：
- **商品名称**（必填）
- **所需点券**（必填，数字）：购买价格
- **商品介绍**（选填）：描述文字，下划线 `_` 在客户端显示为换行
- **商品图标路径**（选填）：默认 `textures/items/apple`
- **商品类型**（下拉选择）：`item`（物品）或 `cmd`（命令）
> 新创建的商品还没有具体的物品/命令内容，需要使用 **"商品里新增商品"** 来添加。
#### ③ 商品里新增商品
第一步选择分类 → 第二步选择目标商品 → 弹出自定义表单，填写：
- **物品/命令**：
- item 类型: `物品ID:特殊值:数量` 如 `276:0:1`（钻石剑×1）、`264:0:64`（钻石×64）
- cmd 类型: `控制台命令`，`@p` 会被替换为购买者名字，如 `givemoney @p 5000`
> 一个商品可以包含多条物品/命令条目，重复操作"商品里新增商品"即可追加。
#### ④ 删除商品
选择分类 → 选择商品 → 直接删除（无二次确认，请谨慎）。
#### ⑤ 删除类型
选择分类 → 直接删除该分类及其下所有商品（无二次确认，请谨慎）。
---
## 配置文件
### config.yml
```yaml
# 点券兑换银币汇率: 1点券 = N银币
exchange-rate: 1000
```
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `exchange-rate` | 1000 | 1 点券可兑换的银币数量（EconomyAPI） |
### shop.yml
商城商品配置。支持游戏内 OP GUI 管理，也可手动编辑。
```yaml
# 格式说明
<类别名>:
img: "textures/items/..." # 类别图标
商品:
<商品名>:
类型: "item" | "cmd" # item=物品, cmd=命令
所需点券: <数量> # 购买价格
商品: # 物品列表或命令列表
- "ID:meta:count" # item 格式
- "命令 @p" # cmd 格式，@p=购买玩家
商品介绍: "描述文字" # _ 显示为换行
img: "textures/items/..." # 商品图标
```
**示例**：
```yaml
武器:
img: "textures/items/diamond_sword"
商品:
测试剑:
类型: "item"
所需点券: 100
商品:
- "276:0:1"
商品介绍: "一把测试用钻石剑"
img: "textures/items/diamond_sword"
消耗品:
img: "textures/items/emerald"
商品:
大钱袋:
类型: "cmd"
所需点券: 50
商品:
- "givemoney @p 5000"
商品介绍: "获得5000银币"
img: "textures/items/gold_ingot"
新人礼包:
类型: "item"
所需点券: 200
商品:
- "276:0:1" # 钻石剑
- "310:0:1" # 钻石头盔
- "311:0:1" # 钻石胸甲
- "312:0:1" # 钻石护腿
- "313:0:1" # 钻石靴子
- "322:0:16" # 金苹果×16
商品介绍: "新手武器+防具+食物_一应俱全"
img: "textures/items/diamond_chestplate"
```
---
## 商品类型说明
### item（物品）
`商品` 列表中每项格式为 `物品ID:特殊值:数量`。
- `276:0:1` → 钻石剑 ×1
- `264:0:64` → 钻石 ×64
- `1:0:64` → 石头 ×64（仅写 `1` 等同于 `1:0:1`）
> 只支持原版物品 ID。不支持自定义 NBT 物品（如需 NBT 物品请使用 cmd 类型调用 Gadget 等插件命令）。
### cmd（命令）
`商品` 列表中每项为一条**以控制台身份执行**的命令。`@p` 会被替换为购买玩家的名字。
```yaml
商品:
- "givemoney @p 5000" # EconomyAPI 给钱
- "gadget give 大钱袋 @p" # Gadget 给道具
- "title @p title §6恭喜获得VIP礼包" # 发送称号
```
> 多条命令会按顺序全部执行。
---
## 自动迁移
如果你的 `shop.yml` 是从旧版 Point 插件保留下来的（使用 `价格`/`简介` 字段名），插件启动时会自动迁移：
| 旧字段 | → | 新字段 |
|--------|---|--------|
| `价格` | → | `所需点券` |
| `简介` | → | `商品介绍` |
| *(无)* | → | `img`（补默认苹果图标） |
迁移后控制台会输出 `shop.yml 已自动迁移到 v2 格式`。旧字段保留在原文件中不影响功能。
---
## 软依赖
| 插件 | 作用 | 缺失时影响 |
|------|------|-----------|
| **EconomyAPI** | 点券→银币兑换 | 兑换功能不可用，商城/转账/排行榜正常 |
| **Gadget** | cmd 类型商品可调用 `/gadget give` | 仅影响使用 Gadget 命令的商品 |
---
## 数据文件
| 文件 | 位置 | 内容 |
|------|------|------|
| `config.yml` | `plugins/Point/` | 汇率配置 |
| `shop.yml` | `plugins/Point/` | 商城商品数据 |
| `points.yml` | `plugins/Point/` | 玩家点券余额（自动生成，不要手动编辑） |
---
## 常见问题
**Q: 玩家买了东西没收到？**
A: item 类型检查背包是否有空间。cmd 类型检查控制台是否有报错（命令不存在/参数错）。
**Q: 怎么卖带自定义名称/NBT 的物品？**
A: 使用 cmd 类型调用能产出该物品的插件命令（如 `/gadget give`、`/bgive` 等）。
**Q: OP 系统按钮看不到？**
A: 确认你是 OP（`/op 玩家名`），或拥有 `point.admin` 权限。也可以直接用 `/pshop admin` 进入。
**Q: 可以给离线玩家发点券吗？**
A: `/point add/remove/set` 需要目标在线。如需离线操作，手动编辑 `points.yml` 后重启服务器或 `/point reload`（如果有）。[/MD]
