FutureShops

🏪 FutureShops — 终极 Minecraft 经济与商店模组

🎮 Minecraft Forge 1.20.1 · 服务端经济 · 玩家商店 · 以物易物 · 实体货币

---

将你的 Minecraft 服务器打造成繁荣的市场。 FutureShops 为 Minecraft 带来功能完备的亚马逊式经济系统——包含服务器商店、玩家自有店铺、实体货币、以物易物、促销活动、排行榜以及精美的现代 UI——且完全无需任何外部纹理。

---

✨ 功能亮点

🛒 服务器商店（/shop）

浏览拥有无限库存的管理员商店，配有精美的深色主题 GUI。分类、搜索、筛选——就像在线购物，只不过是在 Minecraft 里。

• 📂 分类侧边栏，带有可滚动的标签页与物品图标
• 🔍 实时搜索——瞬间找到任何物品
• 🏷️ 动态促销徽章——促销物品上脉动的红色 -X% 折扣标签
• 🛍️ 购物车——将购买项加入队列、调整数量、一次性结账
• 📜 交易历史——支持搜索、排序、时间窗口筛选的可过滤日志，并实时推送更新
• 💰 余额显示——随时了解你拥有多少钱

---

🏠 玩家自有商店方块

放置一个商店方块，配置你的商品列表，连接你的箱子，然后开门营业。

• 👤 放置时自动分配所有者——你的方块，你的商店
• 📦 单物品或多物品模式——每个方块可出售一件物品，或多达 12 件
• 🏷️ 自定义商店名称——为你的店铺打造品牌
• 💵 三种交易模式：金钱、以物易物，或同时启用两者
• 🔗 存储链接——连接箱子、木桶，或整个 Refined Storage 网络以实现自动库存管理
• 📊 店主仪表盘——收入追踪、结算领取、库存警报
• 🎁 店主促销编辑器——设置百分比折扣、买 X 送 Y 优惠、限时特卖以及定时窗口
• 👁️ 店主预览——Shift+右键以访客身份测试你的商店
• 🛒 买家体验——与服务器商店同样精致的 UI，熟悉而直观

---

💰 完整的经济系统

一个由服务器主导的经济系统，确保你的服务器公平公正。

• /balance——通过精美的仪表盘查看你的资金
• /pay <player> <amount>——向朋友转账
• /baltop——包含玩家头像、最高余额、最多交易、最佳卖家以及最热门商品的排行榜
• /withdraw <amount> [yes|no]——将余额转换为实体硬币
  • 智能面额：$1、$5、$10、$20、$50、$100、$1,000 纸币
  • 示例：/withdraw 132 yes → 1×$100 + 1×$20 + 1×$10 + 2×$1
• /deposit——将硬币转换回余额

🪙 实体货币（CoinItem）

将你的财富握在手中——或者亲自用于交易。

• 🖱️ 右键存入——只需手持任意硬币右键，即可立即将其全部价值存入余额。无需命令！
• 🔐 防复制保护——每枚硬币在铸造时都带有唯一 ID、加密校验和以及服务端已花费铸造记录追踪
• 📝 基于 NBT 的面额——硬币在悬停时显示其价值
• ♻️ 存入验证——先前已花费的铸造 ID 将被永久拒绝并销毁
• 🗑️ 无效硬币自动销毁——被篡改或复制的硬币在使用时自动销毁

---

⚒️ 以物易物系统

并非所有东西都必须用钱交易。

• 🔄 物品对物品交易——用钻石换绿宝石，或你配置的任何物品
• 🎨 专用交易界面——整洁的对半分布局："你获得" ⟵⟶ "你给出"
• 📋 同一物品支持多个配方——不同交易选项的标签页
• 🤝 同样适用于玩家商店——店主可以设置以物易物的物品与数量
• 🧮 智能最大值按钮——根据你的背包自动计算最多可交易的数量

---

📊 仪表盘与排行榜

了解你在经济中的位置。

• 🧑 玩家档案——你的头像、余额、收入、商店数量、供应警报
• 🏆 Baltop 排行榜——前 10 名余额及玩家头像
• 📈 交易聚焦——最多交易、最佳卖家、最热门商品
• 🏪 店铺管理——查看你所有已放置的商店、库存水平以及低供应警告

---

🎉 促销与折扣系统

像真正的生意一样开展促销活动。

• 💥 百分比折扣——带有 -X% 文字的脉动红色动态徽章
• 🎁 买 X 送 Y——促销捆绑包
• ⏰ 定时窗口——为限时特卖设置开始/结束时间
• 🔥 限时特卖开关——限时紧迫感
• 🏷️ 处处可用——服务器商店、玩家商店、所有交易模式

---

🖼️ 完整 UI 展示

所有 UI 完全使用 Minecraft 内置的绘图原语渲染——无需任何外部纹理！

界面	描述
ShopMainScreen	深色现代网格布局，包含分类侧边栏、动态促销徽章、个人资料页脚
ItemDetailScreen	大号物品预览、定价信息、数量控制、购买/出售/以物易物操作
CartScreen	基于行的结账界面，包含内联数量控制与金色点缀的总额
BarterScreen	对半分的"你获得 ⟵⟶ 你给出"布局，带有配方标签页
TransactionHistory	可过滤日志，包含全部/购买/出售/以物易物标签页、时间窗口、搜索
Player Shop	店主配置面板 + 访客店铺——与服务器商店同样精致
Promo Editor	用于设置折扣类型、数值、买 X 送 Y、时间表的模态覆盖层
Balance Dashboard	玩家头像、余额、收入、商店统计、低库存警告
Leaderboard	前 10 名及头像、交易/卖家/商品聚焦
Settlement History	分页收入日志，支持出售/领取/回滚筛选

---

🎮 命令

命令	描述
/shop	打开服务器商店店面
/shop <shopId>	打开指定的具名商店
/balance 或 /bal	查看你的余额与仪表盘
/balance ui	打开完整的余额仪表盘 GUI
/baltop	查看经济排行榜
/baltop ui	打开排行榜 GUI
/pay <player> <amount>	向另一位玩家转账
`/withdraw [yes	no]`
/deposit	将手持的货币转换回余额
/link	确认存储链接（请先看向箱子）

🔧 管理员命令

命令	描述
/shopadmin reload	从配置热重载商店目录
/shopadmin coinaudit	检查每位玩家的活跃与已消耗铸造记录
/shopadmin promo set <shop> <item> <type> <value>	为目录物品设置促销
/shopadmin promo clear <shop> <item>	移除目录物品的促销

---

⚙️ 配置

商店目录定义在以下位置的 JSON 文件中：

config/futureshops/shops/*.json

每个文件定义分类、物品、价格、以物易物配方、促销规则以及库存设置。可通过 /shopadmin reload 热重载。

服务器经济配置位于：

config/futureshops-common.toml

---

🔒 安全与防复制

FutureShops 严肃对待服务器完整性：

• ✅ 服务端主导交易——所有购买/出售/以物易物均在服务端验证
• ✅ 加密硬币校验和——被篡改的硬币将被拒绝
• ✅ 已花费铸造注册表——已存入的硬币被永久追踪，防止重复使用
• ✅ 每商店交易锁定——防止玩家商店上的竞态条件
• ✅ 分阶段回滚——失败的交易会干净地还原物品与余额
• ✅ 射线检测存储链接——对已链接容器进行防作弊验证
• ✅ 会话管理——商店在登出、死亡或超出距离时自动关闭

---

📦 安装

1. 安装 Minecraft Forge 1.20.1（47.x）
2. 安装 GeckoLib 4.4+ 依赖（客户端与服务端均需要）
3. 将 futureshops-1.0.jar 放入你的 mods/ 文件夹
4. 启动游戏——商店目录与配置文件会自动生成
5. 在 config/futureshops/shops/ 中配置你的商店
6. 在游戏中使用 /shop 打开店面——你开始营业了！🎉

---

🪙 货币系统 — 完整文档

FutureShops 具有一套实体货币系统，让玩家能够以真实物品的形式在背包中持有、交易和管理财富。

硬币如何运作

硬币是特殊的物品，没有合成配方——创建它们的唯一方式是通过 /withdraw 命令。每枚硬币都携带着隐藏的 NBT 数据，使其独一无二且防篡改。

获取硬币

方法	方式
从余额提取	/withdraw <amount> 或 /withdraw <amount> yes
单枚大额硬币	/withdraw <amount> no——一枚价值全额的大额硬币

智能面额拆分（/withdraw 132 yes）：

纸币	数量
$100	×1
$20	×1
$10	×1
$1	×2

可用面额：$1、$5、$10、$20、$50、$100、$1,000

存入硬币

有两种方式将硬币存回你的数字余额：

方法	方式	详情
🖱️ 右键	手持硬币并右键	立即存入你手中整组的硬币。最快的方式！
⌨️ 命令	/deposit	一次性存入你背包中所有有效硬币
⌨️ 部分存入命令	/deposit <amount>	仅存入指定金额，优先消耗最大面额的纸币

硬币提示信息

当你在背包中悬停于硬币上时，你会看到：

• 🟡 价值：$X.XX——该硬币的面额
• ⬜ 右键存入——快速存入功能的提醒

防复制安全

FutureShops 铸造的每枚硬币都包含隐藏的安全数据：

NBT 字段	用途
mint_id	唯一 UUID——没有两枚硬币共享相同的 ID
denomination	硬币以最小单位表示的价值
mint_timestamp	硬币创建的时间
mint_player	提取该硬币的玩家 UUID
mint_server	服务器身份哈希
checksum	加密完整性校验

无效硬币会发生什么：

情形	结果
被篡改的 NBT（编辑了校验和/价值）	❌ 硬币在使用时被销毁
被复制的硬币（同一铸造 ID 被使用两次）	❌ 第二份副本在存入时被销毁
已存入的硬币（铸造 ID 已被消耗）	❌ 硬币被销毁，玩家受到警告
缺失硬币数据	❌ 硬币被静默销毁

硬币行为规则

交互	行为
右键（使用）	✅ 立即存入余额
掉落在地上	✅ 允许——5 分钟后消失
玩家死亡	✅ 像普通物品一样掉落（遵循 keepInventory）
存入箱子/木桶	✅ 允许——在取出时验证
合成	❌ 无法用于配方
铁砧重命名	❌ 被服务器阻止
漏斗抽取	❌ 默认被阻止（可配置）

---

📋 技术细节

属性	值
模组加载器	Minecraft Forge
Minecraft 版本	1.20.1
Forge 版本	47.4.20+
Java 版本	17
映射	Official Mojang
需要服务端	✅ 是
需要客户端	✅ 是（用于 GUI）
依赖	🦎 GeckoLib 4.4+（客户端与服务端）

---

🤝 模组兼容性

🧠 Refined Storage 集成（已发布）

FutureShops 内置原生 Refined Storage 支持——将商店直接链接到 RS 控制器、网格、外部存储或任何 RS 网络节点，商店将直接从整个 RS 网络查询并提取库存。

• 🔌 软依赖——检测到 RS 时集成自动激活；如果未安装 RS，则一切不变。
• 🌐 全网感知——与漏斗式适配器不同，RS 桥接遍历 INetworkNodeProxy → INetworkNode → INetwork，因此你的商店能看到网络上的每一块磁盘和每一个外部存储容器，而不仅仅是单个方块。
• 🧪 NBT 严格匹配——附魔、命名和带耐久数据的物品均精确匹配（不再出售"错误的"钻石镐）。
• ⚛️ 原子提取/插入——如果交易中途出现任何失败，RS 网络上的更改会干净地回滚。
• ♻️ 优雅降级——如果 RS API 发生变化，适配器会自动回退到标准的 Forge IItemHandler 能力。
• 🏷️ 支持的模组 ID：refinedstorage、refinedstorage2 以及 refinedstorageaddons。

💡 只需看向一个控制器/网格/合成器/外部存储方块并运行 /link——就这么简单。商店现在由你的 RS 网络提供支持。

🔌 其他存储与运输

• ✅ 原版容器——箱子、木桶、潜影盒：链接任何 IItemHandler 容器
• ✅ 原版漏斗——将物品输送进已链接的商店存储
• ✅ 常见物品管道模组——任何暴露 Forge IItemHandler 能力的模组都开箱即用
• ✅ CarryOn——商店可被拾取并移动（所有权保留）
• ✅ 专用服务器——完全支持；商店在重启后仍持久保存
• 🧩 可扩展——第三方模组可通过附加 API 注册自己的 ExternalStorageAdapter，以暴露自定义存储网络

---

🗺️ 路线图

• ✅ Refined Storage 集成——已发布
• 🔜 Applied Energistics 2（AE2）适配器
• 🔜 动态定价系统（供需曲线）
• 🔜 库存刷新调度器（定时补货）
• 🔜 面向附加模组的公共 ExternalStorageAdapter 开发者 API 与事件钩子
• 🔜 漏斗/管道兼容性矩阵（Create、Mekanism 等）
• 🔜 高级分析与导出工具
• 🔜 本地化（ES、FR、DE、PT-BR、ZH-CN）

---

❓ 常见问题

问：这在专用服务器上能工作吗？ 🟢 能。从一开始就以服务端主导构建。

问：我的商店能在服务器重启后存活吗？ 🟢 能。商店、余额、商品列表以及交易历史都持久保存到磁盘。

问：玩家能从我的商店偷东西吗？ 🔴 不能。只有店主（或服务器管理员）可以修改商品列表或从已链接存储中取出物品。

问：我可以在现有世界上使用它吗？ 🟢 能。添加模组，重启，你的旧世界会正常加载。

问：它与 Fabric 兼容吗？ 🔴 不——这是一个仅限 Forge 的模组。

问：我需要 GeckoLib 吗？ 🟢 需要——3D 商店方块模型需要 GeckoLib 4.4+。CurseForge 会自动提示你安装它。

问：我可以把商店链接到 Refined Storage 网络吗？ 🟢 可以！看向任何 RS 网络方块（控制器、网格、外部存储、合成器等）并运行 /link。商店将从你的整个 RS 网络提取库存——所有磁盘、所有外部存储容器——NBT 严格匹配。

问：如果我没有安装 Refined Storage 会怎样？ 🟢 完全没问题。RS 是一个软依赖——没有它其他一切都能正常工作。标准的箱子/木桶链接仍然开箱即用。

---

❤️ 支持与社区

• 🐛 发现 Bug？ 在 Issues 标签页中报告
• 💡 有想法？ 在评论区留言
• ⭐ 喜欢这个模组？ 留下评分——这帮助很大！

---

用 ❤️ 为 Minecraft 社区打造。在制作本模组的过程中没有任何外部纹理受到伤害。 🟪⬛