diff --git a/.gitattributes b/.gitattributes index 20dd8f0..afd59d8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -6,6 +6,3 @@ # These are Windows script files and should use crlf *.bat text eol=crlf - -/build/ -/.gradle/ \ No newline at end of file diff --git a/README.md b/README.md index fc07760..2d9aa0d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,219 @@ # Cardinal Cooperative Capitalism: Market Economy -## Setup +[简体中文](#简体中文) | [English](#english) -For setup instructions, please see the [Fabric Documentation page](https://docs.fabricmc.net/develop/getting-started/creating-a-project#setting-up) related to the IDE that you are using. +--- + +## 简体中文 + +一个基于 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 ` 取消并恢复方块。 + +### 命令一览 + +#### 普通玩家(权限 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 ` | 接受付款请求 | +| `/cme requests reject ` | 拒绝付款请求 | +| `/cme requests cancel ` | 撤回自己发起的请求 | + +#### 管理员(权限 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 ` | 取消指定事件并恢复所有被替换的方块 | + +> 省略坐标时自动对准视线落点;`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 ` to restore blocks. + +### Command Reference + +#### Player (permission 0) + +| Command | Description | +| --- | --- | +| `/cme wallet` | Show all your balances | +| `/cme lang` | List available languages | +| `/cme lang ` | Switch language (e.g. `zh_cn`, `en_us`) | +| `/cme convert ` | Preview conversion | +| `/cme convert confirm` | Execute conversion | +| `/cme pay [currency]` | Pay a player | +| `/cme apay [currency]` | Request payment from a player | +| `/cme requests` | List your pending requests | +| `/cme requests accept ` | Accept a payment request | +| `/cme requests reject ` | Reject a payment request | +| `/cme requests cancel ` | Revoke your own request | + +#### Admin (permission 4) + +| Command | Description | +| --- | --- | +| `/cme admin coin add ` | Mint a new currency | +| `/cme admin coin delete ` | Delete a currency | +| `/cme admin coin rename ` | Rename a currency | +| `/cme admin coin edit ` | Edit currency properties | +| `/cme admin coin 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 ` | Check a player's balance | +| `/cme admin balance add ` | Credit a player | +| `/cme admin balance remove ` | 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 ` | 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. Feel free to learn from it and incorporate it in your own projects. +This template is available under the CC0 license.