Skip to content

Commit e9f08b1

Browse files
54895y54895y
committed
Document MatrixShop economy module
1 parent fcff024 commit e9f08b1

9 files changed

Lines changed: 325 additions & 29 deletions

File tree

‎docs/matrixshop/configuration-structure.mdx‎

Lines changed: 55 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,12 @@ description: MatrixShop 顶层配置、模块目录和入口文件的详细结
55

66
# 配置结构
77

8-
当前 MatrixShop 的配置不是“一个总配置文件解决所有问题”，而是三层：
8+
当前 MatrixShop 的配置不是“一个总配置文件解决所有问题”，而是四层：
99

1010
1. 顶层全局文件
11-
2. 模块目录
12-
3. 模块内部的 `settings.yml`、`shops/*.yml`、`ui/*.yml`
11+
2. 统一经济定义
12+
3. 模块目录
13+
4. 模块内部的 `settings.yml`、`shops/*.yml`、`ui/*.yml`
1314

1415
## 顶层文件
1516

@@ -106,10 +107,54 @@ Database:
106107

107108
> 当前文档仍建议把 `SQLITE` 和 `MYSQL` 作为主要选项来理解，Redis 不要当作稳定主存储来写运营说明。
108109

110+
### `Economy/currency.yml`
111+
112+
这是 MatrixShop 当前的统一货币定义文件。
113+
114+
```yaml
115+
vault:
116+
Mode: vault
117+
Display-Name: '金币'
118+
Symbol: '$'
119+
Decimal: true
120+
121+
playerpoints:
122+
Mode: playerpoints
123+
Display-Name: '点券'
124+
Decimal: false
125+
```
126+
127+
字段解释：
128+
129+
| 字段 | 说明 |
130+
| --- | --- |
131+
| `Mode` | 货币模式，可写 `vault`、`playerpoints` 或 PlaceholderAPI 占位符。 |
132+
| `Display-Name` | 菜单和提示中显示的货币名。 |
133+
| `Symbol` | 可选符号。 |
134+
| `Decimal` | 是否允许小数。 |
135+
| `Actions.Take / Give / Deny` | 自定义货币的结算与余额不足动作。 |
136+
137+
## 货币优先级
138+
139+
当前版本的货币 key 解析顺序是：
140+
141+
1. 商品级
142+
2. 商店级
143+
3. 模块级
144+
4. 默认回退 `vault`
145+
146+
具体表现：
147+
148+
- `SystemShop`：商品级 `currency` > 商店级 `Currency.Key` > 模块级 `SystemShop/settings.yml`
149+
- `PlayerShop / GlobalMarket / Auction / Transaction`：商店级 `Currency.Key` > 模块级 `settings.yml`
150+
- `ChestShop`：模块级 `settings.yml`
151+
- `Cart / Record`：不配置经济
152+
109153
## 模块目录
110154

111155
默认资源目录如下：
112156

157+
- `Economy/`
113158
- `Menu/`
114159
- `SystemShop/`
115160
- `PlayerShop/`
@@ -145,6 +190,7 @@ Database:
145190

146191
- 命令候选关键字
147192
- 模块开关
193+
- 模块级货币 key
148194
- 权限条件
149195
- 运行参数
150196

@@ -183,6 +229,12 @@ Database:
183229

184230
## 从哪里继续读
185231

232+
如果你正在处理货币、点券或自定义积分，请直接继续看：
233+
234+
- [经济模块](./economy)
235+
236+
## 从哪里继续读
237+
186238
如果你要改具体模块，请直接进入新的详细页：
187239

188240
- [Menu](./shop-types/menu)

‎docs/matrixshop/economy.mdx‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: 经济模块
3+
description: MatrixShop 的统一货币定义、优先级规则和模块配置方式。
4+
---
5+
6+
# 经济模块
7+
8+
MatrixShop 当前已经引入独立的经济模块，用来统一管理货币定义和交易动作。
9+
10+
它和旧版“每个商店自己随便写货币逻辑”的思路不同，当前版本采用的是：
11+
12+
1. 统一定义货币
13+
2. 模块、商店或商品只引用货币 key
14+
3. 未定义时默认回退到 `vault`
15+
16+
## 核心结论
17+
18+
- `Economy` 是核心模块，始终启用，不支持关闭。
19+
- 默认货币定义文件是 `plugins/MatrixShop/Economy/currency.yml`
20+
- 支持的货币模式：
21+
- `vault`
22+
- `playerpoints`
23+
- `PlaceholderAPI` 占位符货币
24+
- `Cart` 和 `Record` 不提供独立经济配置
25+
26+
## 默认文件
27+
28+
```text
29+
plugins/MatrixShop/Economy/currency.yml
30+
```
31+
32+
默认资源示例：
33+
34+
```yml
35+
vault:
36+
Mode: vault
37+
Display-Name: "金币"
38+
Symbol: "$"
39+
Decimal: true
40+
41+
playerpoints:
42+
Mode: playerpoints
43+
Display-Name: "点券"
44+
Symbol: "点"
45+
Decimal: false
46+
47+
custom_points:
48+
Mode: "%custom_points%"
49+
Display-Name: "自定义积分"
50+
Symbol: ""
51+
Decimal: false
52+
Actions:
53+
Take:
54+
- "console: custompoints take {player} {amount}"
55+
Give:
56+
- "console: custompoints give {player} {amount}"
57+
Deny:
58+
- "tell:&c货币不足，需要 &e{need} &c，当前为 &e{balance}"
59+
```
60+
61+
## 货币定义字段
62+
63+
| 字段 | 说明 |
64+
| --- | --- |
65+
| `Mode` | 货币类型。可写 `vault`、`playerpoints` 或 PlaceholderAPI 占位符。 |
66+
| `Display-Name` | 菜单和提示中显示的货币名。 |
67+
| `Symbol` | 可选符号。当前主要用于展示，不直接控制结算。 |
68+
| `Decimal` | 是否允许小数。`playerpoints` 一般应设为 `false`。 |
69+
| `Actions.Take` | 自定义货币扣除动作。 |
70+
| `Actions.Give` | 自定义货币发放动作。 |
71+
| `Actions.Deny` | 余额不足时执行的提示动作。 |
72+
73+
说明：
74+
75+
- `vault` 和 `playerpoints` 模式优先走插件 API
76+
- 自定义占位符货币主要依赖 `Actions.Take / Give / Deny`
77+
- 如果没有定义动作，就只能用于读取余额，不能安全完成结算
78+
79+
## 配置优先级
80+
81+
当前版本的货币 key 解析优先级是：
82+
83+
1. 商品级
84+
2. 商店级
85+
3. 模块级
86+
4. 默认回退 `vault`
87+
88+
### 商品级
89+
90+
当前主要体现在 `SystemShop`：
91+
92+
```yml
93+
goods:
94+
diamond_sword:
95+
material: 'DIAMOND_SWORD'
96+
price: 420
97+
currency: playerpoints
98+
```
99+
100+
### 商店级
101+
102+
适用于带 `shops/*.yml` 的模块，例如：
103+
104+
- `SystemShop`
105+
- `PlayerShop`
106+
- `GlobalMarket`
107+
- `Auction`
108+
- `Transaction`
109+
110+
示例：
111+
112+
```yml
113+
Currency:
114+
Key: vault
115+
```
116+
117+
### 模块级
118+
119+
适用于：
120+
121+
- 没有 `shops/*.yml` 的模块
122+
- 或作为带 `shops/*.yml` 模块的兜底值
123+
124+
示例：
125+
126+
```yml
127+
Currency:
128+
Key: vault
129+
```
130+
131+
## 各模块当前支持方式
132+
133+
| 模块 | 支持方式 |
134+
| --- | --- |
135+
| `SystemShop` | 商品级 `currency` > 商店级 `Currency.Key` > 模块级 `SystemShop/settings.yml` |
136+
| `PlayerShop` | 商店级 `Currency.Key` > 模块级 `PlayerShop/settings.yml` |
137+
| `GlobalMarket` | 商店级 `Currency.Key` > 模块级 `GlobalMarket/settings.yml` |
138+
| `Auction` | 商店级 `Currency.Key` > 模块级 `Auction/settings.yml` |
139+
| `Transaction` | 商店级 `Currency.Key` > 模块级 `Transaction/settings.yml` |
140+
| `ChestShop` | 模块级 `ChestShop/settings.yml` |
141+
| `Cart` | 不配置经济 |
142+
| `Record` | 不配置经济 |
143+
144+
## 当前不建议的写法
145+
146+
当前 MatrixShop 不建议把完整货币动作直接内联在商店配置里。
147+
148+
推荐做法是：
149+
150+
1. 在 `Economy/currency.yml` 里统一定义货币
151+
2. 在模块、商店或商品里只写 key
152+
153+
也就是说，优先写：
154+
155+
```yml
156+
Currency:
157+
Key: playerpoints
158+
```
159+
160+
而不是在每个商店文件里重复写整段货币动作。
161+
162+
## 管理与排查
163+
164+
建议先执行：
165+
166+
```text
167+
/matrixshopadmin status
168+
```
169+
170+
重点看：
171+
172+
- `Economy provider`
173+
- 启动摘要中的经济系统信息
174+
175+
如果某种货币不可用，通常有三类原因：
176+
177+
1. 对应依赖插件没装
178+
2. `currency.yml` 里写的模式或占位符不正确
179+
3. 自定义货币动作只定义了读取，没有定义 `Take / Give / Deny`

‎docs/matrixshop/faq.mdx‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,30 @@ description: MatrixShop 当前实现的常见误区与排错入口。
55

66
# 常见问题
77

8-
## 为什么文档里不再写 `currency.yml`
8+
## 现在货币应该写在哪里
99

10-
因为当前源码默认资源里没有 `currency.yml`。旧版文档提到的货币总表不适用于现在这套实现。
10+
当前版本已经重新引入统一货币定义文件：
1111

12-
当前示例里的货币字段通常直接写：
13-
14-
```yaml
15-
currency: 'vault'
12+
```text
13+
plugins/MatrixShop/Economy/currency.yml
1614
```
1715

16+
推荐写法是引用货币 key，而不是在每个业务配置里重复写整段货币逻辑。
17+
18+
优先级如下：
19+
20+
1. 商品级
21+
2. 商店级
22+
3. 模块级
23+
4. 默认回退 `vault`
24+
25+
如果你在改：
26+
27+
- `SystemShop`：可写商品级 `currency`
28+
- `PlayerShop / GlobalMarket / Auction / Transaction`：优先写商店级 `Currency.Key`
29+
- `ChestShop`：写模块级 `Currency.Key`
30+
- `Cart / Record`：不需要配置货币
31+
1832
## 为什么改了 `shops/*.yml` 文件名后，原来的入口和数据不见了
1933

2034
因为现在的 `shopId` 就是文件名。对这些模块来说，改文件名相当于改了运行时作用域：

‎docs/matrixshop/index.mdx‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: MatrixShop 当前模块化实现的总览与阅读入口。
66

77
# MatrixShop 文档
88

9-
MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当前主线版本已经具备正式部署所需的核心模块、统一命令体系、统一菜单框架、统一权限校验和 JDBC 优先的数据层。
9+
MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当前主线版本已经具备正式部署所需的核心模块、统一命令体系、统一菜单框架、统一权限校验、统一经济模块和 JDBC 优先的数据层。
1010

1111
## 当前版本状态
1212

@@ -17,6 +17,7 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
1717

1818
## 当前实现的模块
1919

20+
- `economy`
2021
- `menu`
2122
- `system-shop`
2223
- `player-shop`
@@ -34,12 +35,13 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
3435
3. 初始化记录服务
3536
4. 同步数据库 schema
3637
5. 导入旧版数据
37-
6. 加载经济桥接、模块与命令
38+
6. 加载经济模块、业务模块与命令
3839

3940
## 当前文档覆盖的重点
4041

4142
- 真实目录结构与文件职责
4243
- 命令绑定、独立命令与 `shopId` 解析规则
44+
- 统一经济模块与货币优先级规则
4345
- SQLite / MySQL / 文件回退行为
4446
- 各模块当前能力和配置边界
4547
- 每个模块默认配置的完整示例与字段解读
@@ -51,10 +53,11 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
5153

5254
1. [快速开始](./quick-start)
5355
2. [配置结构](./configuration-structure)
54-
3. [命令与权限](./commands-and-permissions)
55-
4. [数据库与存储](./database-and-storage)
56-
5. [模块总览](./modules-overview)
57-
6. [商店与模块详解](./shop-types)
56+
3. [经济模块](./economy)
57+
4. [命令与权限](./commands-and-permissions)
58+
5. [数据库与存储](./database-and-storage)
59+
6. [模块总览](./modules-overview)
60+
7. [商店与模块详解](./shop-types)
5861

5962
## 发布前建议
6063

‎docs/matrixshop/modules-overview.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,13 @@ description: MatrixShop 各模块职责、默认文件和详细文档入口。
55

66
# 模块总览
77

8-
当前 MatrixShop 默认启用了九个模块。为了让文档更容易查找，本站现在把每个模块都拆成了单独页面。
8+
当前 MatrixShop 默认包含十个模块，其中 `economy` 是核心模块，始终启用；其余九个模块按业务拆分。
99

1010
## 模块清单
1111

1212
| 模块 | 作用 | 关键文件 | 详细页 |
1313
| --- | --- | --- | --- |
14+
| `economy` | 统一货币定义与结算入口 | `Economy/currency.yml` | [经济模块](./economy) |
1415
| `menu` | 总入口导航菜单 | `Menu/settings.yml`、`Menu/shops/main.yml` | [Menu](./shop-types/menu) |
1516
| `system-shop` | 静态系统商店 | `SystemShop/settings.yml`、`SystemShop/shops/*.yml` | [SystemShop](./shop-types/system-shop) |
1617
| `player-shop` | 玩家个人商店 | `PlayerShop/settings.yml`、`PlayerShop/shops/default.yml` | [PlayerShop](./shop-types/player-shop) |
@@ -28,8 +29,9 @@ description: MatrixShop 各模块职责、默认文件和详细文档入口。
2829
建议顺序：
2930

3031
1. [配置结构](./configuration-structure)
31-
2. [商店与模块详解](./shop-types)
32-
3. 你实际会用到的模块页
32+
2. [经济模块](./economy)
33+
3. [商店与模块详解](./shop-types)
34+
4. 你实际会用到的模块页
3335

3436
### 如果你在排查某个商店为什么打不开
3537

@@ -51,6 +53,7 @@ description: MatrixShop 各模块职责、默认文件和详细文档入口。
5153

5254
为了避免把 MatrixShop 理解成“所有模块都完全一样”，这里再强调一次：
5355

56+
- `Economy` 负责统一货币定义，不建议在业务模块里重复实现结算逻辑。
5457
- `SystemShop` 主要是静态 YAML 商品。
5558
- `PlayerShop`、`GlobalMarket`、`Auction` 主要是运行时上架数据。
5659
- `ChestShop` 有箱子、库存、告示牌这套线下交互。

0 commit comments

Comments
 (0)