# Cardinal Cooperative Capitalism: Market Economy

[简体中文](#简体中文) | [English](#english)

---

## 简体中文

一个基于 Fabric 的服务端经济模组，将 Minecraft 服务器变成一个运行中的市场经济体。玩家可以持有多种货币、互相转账、兑换汇率、发起付款请求；管理员可以发行货币、调控汇率、审计余额。模组内置一套可视化 BossBar 驱动的"事件演出"系统（爆炸、陨石、波纹、球体演示）用于运营活动与压力测试。

> 未来将与 [gerp.gvsds.com](https://gerp.gvsds.com) 企业管理系统深度整合，把游戏内经济接入真实企业管理后端，打造沉浸式"市场经济游戏"。

### 玩法

- **多货币体系**：管理员可发行任意数量、带符号、可交易标志的货币，每名玩家对每种货币独立记账。
- **玩家对玩家转账**：`/cme pay` 即时到账，双方均收到聊天框提示与音效。
- **付款请求**：`/cme apay` 发起请求，对方可 `/cme requests accept|reject`，发起方可 `/cme requests cancel`。接受/拒绝/撤回均双向通知 + 音效 + action bar。
- **汇率兑换**：管理员为每种货币设定汇率，玩家 `/cme convert` 预览后 `confirm` 真正兑换。
- **国际化**：内置 `zh_cn` / `en_us`，玩家 `/cme lang` 自助切换，所有消息按玩家 UUID 持久化。
- **事件演出**：OP 可用 `/cme test` 系列指令放出 BossBar 全流程演出 —— 核心凝聚 → 合并 → 坍缩 → 爆发，附带闪电、粒子、音效。每个事件有唯一 ID，可随时 `/cme test cancel <id>` 取消并恢复方块。

### 命令一览

#### 普通玩家（权限 0）

| 命令 | 说明 |
| --- | --- |
| `/cme wallet` | 查看自己所有货币余额 |
| `/cme lang` | 查看可选语言列表 |
| `/cme lang <语言>` | 切换语言（如 `zh_cn`、`en_us`） |
| `/cme convert <金额> <从> <到>` | 预览兑换结果 |
| `/cme convert <金额> <从> <到> confirm` | 确认执行兑换 |
| `/cme pay <玩家> <金额> [货币]` | 向玩家转账 |
| `/cme apay <玩家> <金额> [货币]` | 向玩家发起付款请求 |
| `/cme requests` | 列出自己的待处理请求 |
| `/cme requests accept <id>` | 接受付款请求 |
| `/cme requests reject <id>` | 拒绝付款请求 |
| `/cme requests cancel <id>` | 撤回自己发起的请求 |

#### 管理员（权限 4）

| 命令 | 说明 |
| --- | --- |
| `/cme admin coin add <名称> <符号> <可交易>` | 发行新货币 |
| `/cme admin coin delete <名称>` | 删除货币 |
| `/cme admin coin rename <旧名> <新名>` | 重命名货币 |
| `/cme admin coin edit <名称> <符号> <可交易>` | 编辑货币属性 |
| `/cme admin coin tradable <名称> <可交易>` | 切换可交易标志 |
| `/cme admin coin list` | 列出全部货币与汇率 |
| `/cme admin coin rate [货币名] [汇率]` | 查看或设置汇率 |
| `/cme admin balance check <玩家> <货币名>` | 查看玩家余额 |
| `/cme admin balance add <玩家> <货币名> <金额>` | 增加玩家余额 |
| `/cme admin balance remove <玩家> <货币名> <金额>` | 扣除玩家余额 |

#### UI 演示

| 命令 | 说明 |
| --- | --- |
| `/cme uidemo alert` | 警告弹窗 |
| `/cme uidemo confirm` | 确认弹窗 |
| `/cme uidemo input` | 输入弹窗 |
| `/cme uidemo smallchest` | 小箱子界面 |
| `/cme uidemo mediumchest` | 中箱子界面 |
| `/cme uidemo largechest` | 大箱子界面 |
| `/cme uidemo anvil` | 铁砧界面 |

#### 测试 / 演出（权限 2）

| 命令 | 说明 |
| --- | --- |
| `/cme test boom [x y z] [range] [depth]` | 爆炸序列：核心凝聚→合并→坍缩→爆发，附带闪电与小爆炸 |
| `/cme test meteo [x y z]` | 陨石斜飞砸向目标点，爆炸后生成矿脉与宝箱 |
| `/cme test line [x z] [range]` | 圆环波纹从中心向外扩散，方块短暂染色后自动恢复 |
| `/cme test sq [x y z] [range]` | 纯球体演示（boom 的无爆炸版本） |
| `/cme test list` | 列出所有活动事件及其 ID、阶段、tick 进度 |
| `/cme test cancel <id>` | 取消指定事件并恢复所有被替换的方块 |

> 省略坐标时自动对准视线落点；`depth = -1` 表示炸到基岩层。

### 技术栈

- **平台**：Minecraft Fabric，MC 1.21.10，Yarn 映射，Java 21，Loom 1.16-SNAPSHOT
- **环境**：客户端 + 服务端（`environment: *`），经济逻辑在服务端运行
- **数据库**：SQLite（默认，零配置）或 MySQL，通过 HikariCP 连接池管理，所有表自动建表
- **架构**：
  - `manager/` — 业务管理器（Currency / Balance / Transaction / PaymentRequest / ExchangeRate / PlayerSettings）
  - `model/` — 数据模型（Currency / PlayerBalance / Transaction / PaymentRequest）
  - `command/` — Brigadier 命令树 + tick 调度的 Session 演出引擎
  - `gui/` — 服务端驱动的 ScreenHandler UI API
  - `i18n/` — 按 UUID 持久化的双语消息系统
  - `database/` — DatabaseManager 抽象 SQLite/MySQL 差异（含 upsert 语法适配）
  - `config/` — 数据库与表名配置
- **演出引擎**：基于 `ServerTickEvents.END_SERVER_TICK` 的 Session 调度器，全局 `GlobalBlockRegistry` 引用计数机制确保多个事件在同一位置叠加时方块仍能正确恢复。

### 部署

1. 将构建产物 `cardinal-cooperative-capitalism-market-economy-1.0.0.jar` 放入服务器 `mods/` 目录。
2. 首次启动会在 `./config/cardinal-economy/` 生成默认 SQLite 数据库。
3. 如需切换 MySQL，编辑 `./config/cardinal-economy/config.json` 设置 `type=mysql` 并填写连接信息。
4. 依赖（SQLite/MySQL/HikariCP）已打包进 jar，无需额外安装。

### 未来路线

- **与 [gerp.gvsds.com](https://gerp.gvsds.com) 深度整合**：把游戏内货币、交易、企业账号与真实企业管理系统打通，玩家在 Minecraft 里的经济行为映射到企业后端的真实数据。
- **模拟股票系统**：基于企业管理系统的真实经营数据，在游戏内呈现可交易股票，玩家可买入卖出、分红、参与企业经营决策。
- **沉浸式市场经济游戏**：通过真实企业管理后端驱动游戏内事件（如企业业绩影响汇率、经营危机触发服务器内金融危机），让"市场经济"不再只是数字加减。
- **闭源商业管理设施**：部署在总服务器的闭源后端，负责跨服结算、风控、审计、反作弊，游戏内仅暴露玩法扩展与普通交易接口。

> 目前阶段：玩法扩展与普通交易已可用；企业管理后端整合、股票系统、闭源设施规划中。

---

## English

A server-side economy mod for Fabric that turns a Minecraft server into a running market economy. Players hold multiple currencies, transfer funds, convert at admin-set exchange rates, and raise payment requests. Admins issue currencies, tune rates, and audit balances. The mod ships with a BossBar-driven "event show" system (explosions, meteors, ripples, sphere demos) for live events and stress testing.

> The roadmap binds this mod tightly to the [gerp.gvsds.com](https://gerp.gvsds.com) enterprise management system, piping in-game economics into a real business backend for an immersive "market-economy game".

### Gameplay

- **Multi-currency**: admins can mint any number of currencies with custom symbols and tradable flags; each player is tracked per currency.
- **Player-to-player transfer**: `/cme pay` settles instantly with chat + sound feedback to both sides.
- **Payment requests**: `/cme apay` raises a request the recipient can `accept`/`reject`; the sender can `cancel`. All outcomes notify both parties with sound + action bar.
- **Exchange conversion**: admins set per-currency rates; players `/cme convert` to preview then `confirm` to execute.
- **i18n**: ships `zh_cn` and `en_us`; players switch via `/cme lang`, persisted per UUID.
- **Event shows**: OPs trigger full BossBar sequences — core formation → merge → collapse → detonation with lightning, particles, and sound. Each event gets a unique ID and can be cancelled with `/cme test cancel <id>` to restore blocks.

### Command Reference

#### Player (permission 0)

| Command | Description |
| --- | --- |
| `/cme wallet` | Show all your balances |
| `/cme lang` | List available languages |
| `/cme lang <language>` | Switch language (e.g. `zh_cn`, `en_us`) |
| `/cme convert <amount> <from> <to>` | Preview conversion |
| `/cme convert <amount> <from> <to> confirm` | Execute conversion |
| `/cme pay <player> <amount> [currency]` | Pay a player |
| `/cme apay <player> <amount> [currency]` | Request payment from a player |
| `/cme requests` | List your pending requests |
| `/cme requests accept <id>` | Accept a payment request |
| `/cme requests reject <id>` | Reject a payment request |
| `/cme requests cancel <id>` | Revoke your own request |

#### Admin (permission 4)

| Command | Description |
| --- | --- |
| `/cme admin coin add <name> <symbol> <tradable>` | Mint a new currency |
| `/cme admin coin delete <name>` | Delete a currency |
| `/cme admin coin rename <old> <new>` | Rename a currency |
| `/cme admin coin edit <name> <symbol> <tradable>` | Edit currency properties |
| `/cme admin coin tradable <name> <tradable>` | Toggle tradable flag |
| `/cme admin coin list` | List all currencies and rates |
| `/cme admin coin rate [name] [rate]` | View or set exchange rate |
| `/cme admin balance check <player> <currency>` | Check a player's balance |
| `/cme admin balance add <player> <currency> <amount>` | Credit a player |
| `/cme admin balance remove <player> <currency> <amount>` | Debit a player |

#### UI demos

| Command | Description |
| --- | --- |
| `/cme uidemo alert` | Alert dialog |
| `/cme uidemo confirm` | Confirm dialog |
| `/cme uidemo input` | Input dialog |
| `/cme uidemo smallchest` | Small chest UI |
| `/cme uidemo mediumchest` | Medium chest UI |
| `/cme uidemo largechest` | Large chest UI |
| `/cme uidemo anvil` | Anvil UI |

#### Test / shows (permission 2)

| Command | Description |
| --- | --- |
| `/cme test boom [x y z] [range] [depth]` | Full detonation sequence with lightning and micro-explosions |
| `/cme test meteo [x y z]` | Meteor slams into the target, spawns ore veins and a loot chest |
| `/cme test line [x z] [range]` | Ripple waves expand outward, briefly dyeing blocks then auto-restoring |
| `/cme test sq [x y z] [range]` | Sphere-only demo (boom without the explosion) |
| `/cme test list` | List all active events with ID, phase, tick progress |
| `/cme test cancel <id>` | Cancel an event and restore every replaced block |

> Omitting coordinates targets the block you are looking at; `depth = -1` digs to bedrock.

### Tech stack

- **Platform**: Minecraft Fabric, MC 1.21.10, Yarn mappings, Java 21, Loom 1.16-SNAPSHOT
- **Environment**: client + server (`environment: *`); economy logic runs server-side
- **Database**: SQLite (default, zero-config) or MySQL via HikariCP connection pool; all tables auto-created
- **Architecture**:
  - `manager/` — business managers (Currency / Balance / Transaction / PaymentRequest / ExchangeRate / PlayerSettings)
  - `model/` — data models (Currency / PlayerBalance / Transaction / PaymentRequest)
  - `command/` — Brigadier command tree + tick-scheduled Session show engine
  - `gui/` — server-driven ScreenHandler UI API
  - `i18n/` — per-UUID persisted bilingual messages
  - `database/` — DatabaseManager abstracts SQLite/MySQL differences (including upsert syntax)
  - `config/` — database and table-name configuration
- **Show engine**: a Session scheduler on `ServerTickEvents.END_SERVER_TICK`; a global `GlobalBlockRegistry` reference-counting layer guarantees correct block restoration even when multiple overlapping events touch the same position.

### Deployment

1. Drop the built `cardinal-cooperative-capitalism-market-economy-1.0.0.jar` into your server's `mods/` folder.
2. First boot creates a default SQLite database under `./config/cardinal-economy/`.
3. To switch to MySQL, edit `./config/cardinal-economy/config.json`, set `type=mysql`, and fill in the connection details.
4. Dependencies (SQLite/MySQL/HikariCP) are shaded into the jar — no extra installs needed.

### Roadmap

- **Deep integration with [gerp.gvsds.com](https://gerp.gvsds.com)**: pipe in-game currencies, transactions, and enterprise accounts into a real enterprise management backend so player economic actions map to real business data.
- **Simulated stock market**: surface tradable shares driven by real enterprise performance data; players can buy, sell, collect dividends, and vote on enterprise decisions — all inside the game.
- **Immersive market-economy game**: let the real enterprise backend drive in-game events (enterprise results move exchange rates, business crises trigger in-server financial shocks) so the "economy" is more than number arithmetic.
- **Closed-source commercial facility**: a closed-source backend on the master server handling cross-server settlement, risk control, audit, and anti-fraud. The mod itself only exposes gameplay extensions and ordinary trading.

> Current state: gameplay extensions and ordinary trading are live; enterprise backend integration, stock system, and the closed-source facility are planned.

## License

This template is available under the CC0 license.