[MD] # MineBank商店系统使用文档 [/MD]
[MD] ## 项目简介 这个项目源于一个简单的需求：我和我的朋友想在Minecraft世界中创建一个经济系统，让玩家可以进行物品交易、货币转账和商店管理。(最初我搭建了一个宠物商店，完全由我个人经营，但应付不过来，所以构造了此项目) **MineBank**专门为MCBE设计，它提供了一个完整的银行和商店解决方案，支持多种交易类型和丰富的用户界面。 ## 主要特性 [/MD]
[MD]
### 1. **完整的银行系统**
- **余额管理**：每个玩家都有独立的账户余额
- **安全交易**：事务队列机制确保交易安全可靠
- **负余额检测**：自动检测并阻止透支交易
[/MD][MD] ### 2. **多功能商店界面** - **分类浏览**：按类别（武器、盔甲、食物等）浏览商品 - **搜索功能**：支持关键字搜索商品 - **分页系统**：大量商品时分页显示 ### 3. **多种交易类型** - **物品交易**：购买和出售游戏物品 - **命令执行**：购买后可执行特定命令 - **脚本执行**：购买后可执行JavaScript代码 - **简单转账**：玩家间的货币转账 ### 4. **智能管理功能** - **OP管理员工具**：管理员可以管理商店和玩家余额 - **数据持久化**：商店数据自动保存和加载 - **计分板集成**：可将余额同步到计分板 ## 如何开始 首先你需要从附件页下载文件，然后把它导入到MC中。导入之后新建一个世界，打开作弊和实验性选项中的Beta API(测试版API)，然后就可以使用命令来启动它了。 ### 基础命令 #### 商店菜单命令 ``` /shop:shop ``` 打开商店主菜单，可以通过UI界面进行购买、出售和转账操作。（用`/give @s shop:menu`可以获得一个直接打开主菜单的物品） #### 银行相关命令 ``` /shop:showbalance [玩家] # 查看余额 /shop:addbalance 玩家 金额 # 添加余额（管理员） /shop:clearbalance 玩家 # 清除余额（管理员） /shop:recordbalances 计分板 # 记录余额到计分板 ``` ### 物品出售命令 使用商店菜单中的出售功能更方便，也可以直接使用命令： ``` /shop:sell 格子 分类 价格 显示名称 ``` ## 详细功能说明 ### 1. 商店主菜单 商店系统提供直观的图形界面： | 功能 | 说明 | |------|------| | **购买** | 浏览商品分类，购买物品、命令或脚本 | | **出售** | 出售物品到商店，有三种出售方式 | | **转账** | 向其他在线玩家转账 | | **关闭** | 退出商店界面 | ### 2. 商品分类系统 商店商品按以下分类组织： | 分类 | 说明 | |------|------| | **Official** | 官方商品（管理员设置）（可在商店页面中永久保存，购买后不消失） | | **Special** | 特殊商品（管理员设置） | | **Weapons** | 各种武器 | | **Tools** | 各种工具 | | **Armor** | 防具和装备 | | **Food** | 食物和消耗品 | | **Materials** | 基础材料和资源 | | **Blocks** | 建筑方块 | | **Misc** | 其他各种物品 | ### 3. 交易处理流程 商店系统的交易处理采用队列机制，确保交易安全： ``` 1. 买家发起购买请求 2. 检查买家余额是否充足 3. 处理物品交付（或命令/脚本执行） 4. 扣除买家余额 5. 增加卖家余额 6. 交易完成通知 ``` 如果任何步骤失败，交易将被取消并回滚。 ## 原理介绍 商店系统由两个主要模块组成：银行系统和商店界面。 ### 银行系统核心机制 ```javascript // ==================== 核心常量 ==================== const EVENTS = new SafeQueue(); // 交易事件队列 const HANDLER_INTERVAL = 2; // 处理间隔（游戏刻） const DEFAULT_BALANCE = "0"; // 默认余额 const MONEY_PROPERTY_KEY = "money"; // 余额存储键 // ==================== 交易事件结构 ==================== /** * 业务事件结构 * @typedef {Object} BusinessEvent * @property {string|null} buyer - 买家玩家名称或null * @property {string|null} seller - 卖家玩家名称或null * @property {ItemStack|string|null} item - ItemStack或命令字符串或JS代码字符串或null * @property {"Item"|"CommandString"|"EvalJsString"|"SimpleTransfer"} itemType - 物品类型 * @property {number} money - 交易金额（整数） * @property {string} id - 唯一标识符 */ ``` ### 商店数据结构 商店使用`NamedUUIDTable`来存储商品信息，每个商品包含： ```javascript { displayName: string, // 显示名称 price: integer, // 价格 seller: string, // 卖家 Player.name itemType: string, // "Item" | "CommandString" | "EvalJsString" itemId?: string, // 物品ID / 命令串 / JS代码串 item?: ItemStack, // 如果itemId为空，则此项必存在 amount?: integer, // 数量 iconPath?: string // 图标路径 } ``` ## 常见问题 **Q:** 该项目开源吗？项目地址在哪？以何种形式开源？ **A:** 该项目开源，最初只是为了个人使用，是我发现世界上很多人在求这种原生的SHOP，所以才发出来的。与另外一个项目一样，不发布于Github。开源协议是MIT。 **Q:** 使用前还需要干些什么？ **A:** 你需要导入插件并确保Beta API已启用。首次使用需要OP权限来初始化系统。普通玩家可以通过`/shop`命令或对应物品打开商店界面。 **Q:** 如何管理商店数据？ **A:** 管理员可以使用以下命令管理商店数据： - `/shop:resetshopdata` - 重置商店数据 - `/shop:saveshopdata` - 手动保存商店数据 - `/shop:printshopdata` - 打印商店数据（调试用） **Q:** 支持多人游玩吗？ **A:** 完全支持多人游戏。多个玩家可以同时使用商店系统，每个玩家的余额独立管理。交易是安全的，使用队列机制确保不会出现并发问题。 **Q:** 如何设置官方商品？ **A:** OP管理员可以在商店菜单中选择"特殊出售"，然后选择"Official"分类。这些商品将永久存在，不会被玩家购买后移除。 **Q:** 如何修改玩家余额？ **A:** OP管理员可以使用`/shop:addbalance 玩家 金额`来增加玩家余额，使用`/shop:clearbalance 玩家`来重置玩家余额。 **Q:** 支持版本？ **A:** `1.21`以上版本均可正常运行，理论上`26.x`API版本以上都可运行，建议使用最新稳定版。 **Q:** `EvalJsString`太不安全了怎么办？ **A:** 事实上命令和JSString只有OP才可以编辑，但如果你不对OP完全信任的话，附件中我们提供了一个取消后的版本（UI接口还存在，但已经不能正常使用了）。 ## 数据安全与性能 ### 数据持久化 商店数据自动保存到世界动态属性中，采用分块存储机制处理大量数据： ```javascript // 数据分块存储，每块最大512字符（1024字节的一半） const maxBytesPerChunk = 1024; const chunkSize = Math.floor(maxBytesPerChunk / 2); ``` ### 性能优化 - 交易处理使用队列机制，避免阻塞主线程 - 商店界面采用异步操作，提高响应速度 - 商品数据分页加载，减少内存占用 ## 自定义扩展 如果你有编程经验，可以修改以下文件来扩展功能： | 文件 | 作用 | 可修改内容 | |------|------|------------| | `bank.js` | 银行系统核心 | 交易逻辑、余额管理、命令注册 | | `shop.js` | 商店界面逻辑 | UI界面、商品分类、交易流程 | | `untils.js` | 工具函数 | 辅助函数、工具类 | | `_until_name_uuid_table.js` | 数据存储 | 商品数据结构和序列化 | ## 故障排除 如果遇到问题，请按以下步骤检查： 1. **确保Beta API已启用** 2. **检查是否为OP权限**（首次使用需要OP） 3. **查看控制台错误信息** 4. **尝试重载脚本**：`/reload` 5. **重置商店数据**（仅作为最后手段） ## MIT License MIT License Copyright (c) 2026 TickPoints Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. [/MD]
