Buying Chunks — FTB Chunks Addon

🏪 Buying Chunks — FTB Chunks 附加模组

一个适用于 NeoForge 1.21.1 的 FTB Chunks 附加模组，为你的服务器添加功能完备的区块商店与市场。管理员可以设置全服认领定价和商店区域，玩家可以买卖自己认领的区块，一切操作都通过游戏内 GUI 完成——再也不用记命令了。

---

✨ 特性

• FTB 商店 GUI —— 完整的游戏内面板（/ftbshop gui），包含市场、出售区块界面、我的上架和快速购买开关
• 管理员面板 —— 在一屏内管理基础费用、玩家出售、团队价格、购买限制、玩家收入、自动回收以及完整的服务器团队管理（/ftbshop admin）
• 玩家市场 —— 玩家可以自定义价格上架自己认领的区块（需管理员开启），浏览所有上架信息，按团队名称搜索，按价格或距离排序，并标记收藏
• 世界内购买悬浮层 —— 当你靠近待售区块时，HUD 面板会自动弹出，显示价格、卖家团队和实时背包对比，并带有可点击的购买按钮
• 购买快捷键 —— 按下按键（默认 B）即可立即购买你所在的区块
• 地图图标可视化 —— 待售区块仍会以图标形式显示在 FTB Chunks 地图上，现在会按卖家团队着色，并带有更丰富的提示信息
• 粒子区块边界 —— 附近的待售区块会用粒子描边（半径/密度可配置）
• 团队商店系统 —— 创建服务器团队并设定每区块固定价格；该团队认领的任何区块都会自动上架出售
• 基础费用 —— 可选择要求对服务器上任何区块认领支付一种通用物品，独立于市场/团队商店
• 多维度支持 —— 市场、基础费用和上架信息现在在所有维度均可使用，不再仅限于主世界
• 快速购买 —— 可选择完全跳过购买确认界面
• 购买特效与提示 —— 购买时有视觉/音效反馈，购买和上架时还有提示通知
• 欢迎消息 —— 玩家首次加入时显示的可配置消息
• Discord Webhook 集成 —— 可选择将购买/出售/移除事件以嵌入消息形式发送到 Discord 频道（或任意 Webhook URL）
• 自动同步 —— 区块被上架、购买或移除时，所有客户端都会实时更新
• 过期上架清理 —— 不再实际被认领的区块的上架信息会自动移除
• 多语言 —— 可通过 https://crowdin.com/project/buying-chunks 完整翻译（可添加更多语言）

---

📦 依赖

模组	版本
NeoForge	21.1.224
FTB Chunks (NeoForge)	2101.1.14+
FTB Teams (NeoForge)	2101.1.9+
FTB Library (NeoForge)	2101.1.30+
Architectury (NeoForge)	13.0.8+

所有依赖都必须安装在服务端和每个客户端上。

---

🚀 安装

1. 下载 buyingchunks-1.2.0.jar
2. 将其放入服务器的 mods/ 文件夹以及所有客户端
3. 确保上面列出的所有依赖也已安装
4. 启动服务器——无需额外配置（配置文件会自动生成；见下方配置）

---

🔔 Discord Webhook 集成

Buying Chunks 可以在区块每次在市场上易手时，自动向 Discord 频道（或任意自定义端点）发送一条消息——这对于公开的 #shop-log 频道非常方便，玩家无需在线也能看到动态。

触发消息的事件

事件	触发时机…	嵌入颜色	嵌入标题
购买	玩家购买一个已上架的区块（地图、叠加层或市场界面——任意途径）	绿色	✅ 区块已购买
上架	玩家通过 /ftbshop gui → 出售区块 上架自己的区块	青色	🧾 区块已上架出售
移除	玩家通过 我的上架 → 移除 移除自己的上架	橙色	🗑️ 区块已下架

注意：此功能仅在玩家于市场上进行明确操作（购买 / 出售 / 移除）时触发。当服务器团队在认领时自动上架区块（团队商店系统）时不会触发——只有玩家手动上架和购买才会被报告。

负载格式

每条消息都是一个包含以下字段的 Discord 嵌入：

• 区块 — [x, z]
• 维度 — 例如 minecraft:overworld
• 买家（购买事件）或 卖家（上架/移除事件）——触发操作的玩家名称
• 团队 — 与该上架关联的商店团队名称
• 价格 — <count>x <item>
• 时间戳（ISO-8601，由 Discord 按用户本地时间显示）

JSON 就是普通的 {"embeds":[{...}]}——标准 Discord webhook 格式。由于它只是向你所配置的任意 URL 发送 HTTP POST，因此实际上并不局限于 Discord：如果你想要自定义处理，可以将 apiUrl 指向你自己的机器人/API 端点，并自行解析相同的 JSON。

设置

这是该模组中唯一不通过 /ftbshop admin 配置的部分——它位于服务器配置文件中，而非游戏内 GUI：

1. 在 Discord 中：服务器设置 → 整合 → Webhook → 新建 Webhook，选择一个频道，然后复制 Webhook URL。
2. 在你的服务器上，打开 config/buyingchunks-server.toml 并设置：

   [Webhook API]
       apiEnabled = true
       apiUrl = "https://discord.com/api/webhooks/XXXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

1. 重启服务器（或重新加载配置，如果你的环境支持）。

两个值默认均为关闭 / 空——除非管理员主动启用，否则不会向任何地方发送内容。

行为说明

• 请求以异步方式发送，且为即发即忘：失败或缓慢的 webhook 绝不会阻塞或延迟购买/出售本身。
• 失败仅在服务器端记录日志（WebhookSender: Failed to send to ...）——没有重试，投递失败时游戏内也没有任何提示，因此如果消息不再出现，请检查服务器日志。

🛠️ 管理员设置指南

管理员所需的一切——创建商店团队、设置价格、认领区块、配置认领保护，所有这些——都通过一条命令完成：

/ftbshop admin

（需要 OP 等级 2 或更高）。日常商店管理再也不需要 /ftbteams ... 或 /ftbchunks admin ...——管理面板已完全取代它们。

设置商店区域（推荐）——100% 通过 GUI

1. /ftbshop admin → 服务器团队管理 → 在 创建新服务器团队 字段中输入名称（例如 Shopping-District）→ 点击 创建。
2. 返回 /ftbshop admin → 团队价格 → 在搜索字段中输入团队名称（自动补全下拉列表会显示匹配的团队）→ 选择它 → 使用 🔍 选择器挑选物品（或输入其 ID）→ 设置数量 → 添加。
3. 返回服务器团队管理列表，找到你的新团队并点击 ⌂（或 管理 → 打开区块地图）——这会以该团队的身份打开 FTB Chunks 认领地图，就像旧的 /ftbchunks admin open_claim_gui_as 命令一样，只需一键即可。在此处认领你想要出售的区块。
4. 当你在 服务器团队管理 → 管理 中时，你还可以设置团队的颜色并锁定其认领保护（PvP、爆炸、生物破坏、假玩家等）——见下文。

就是这样——无需其他命令。任何由 Shopping-District 认领的区块现在都会自动上架出售，价格为所配置的价格。

允许玩家出售自己的区块

默认情况下，只列出管理员管理的团队商店。要允许普通玩家上架他们自己认领的区块：

1. /ftbshop admin → 玩家出售 → 点击 启用（开启后按钮会变为 禁用）。
2. 然后玩家可以站在自己拥有的区块中，使用 /ftbshop gui → 出售区块 来上架。
3. 使用 玩家收入（按团队，在管理面板中）来决定卖家是否实际收到付款，还是款项去向无处（例如用于“回收”商店团队）。流程与团队价格相同：搜索团队，点击 切换。

三种定价系统

购买区块支持三种独立、可叠加的定价机制，全部通过 /ftbshop admin 配置：

系统	设置位置	适用于
基础费用	管理面板 → 基础费用	服务器上的每个区块认领，无论属于哪个团队
团队商店	管理面板 → 团队价格	由特定（通常是服务器拥有的）团队认领的所有区块——自动上架
玩家市场	区块所有者，通过 /ftbshop gui	玩家选择上架的任何已认领区块，前提是启用了玩家出售

购买限制与自动回收

• 购买限制：限制给定团队允许从特定商店团队购买的区块数量（与团队价格相同的流程：搜索团队 → 选择物品 → 设置数量 → 添加）。
• 自动回收：当为某个服务器团队启用时（搜索团队 → 切换），被取消认领的商店区块会自动被该团队回收，以便它保持可出售状态。

服务器团队管理——完整的认领设置，无需其他模组的 GUI

/ftbshop admin → 服务器团队管理 会列出每个服务器团队（颜色色块 + 名称），每行包含：

• 管理——打开 团队详情 界面（见下文）
• ⌂——直接为该团队打开 FTB Chunks 认领地图（以该团队身份认领/取消认领区块）
• ✕——删除该团队

底部：一个名称字段 + 用于创建新服务器团队的 创建 按钮。

点击 管理 会打开 团队详情 界面——这是在购买区块内部对 FTB Teams 自身认领设置面板的完整重新实现，因此你永远不必单独打开 FTB Teams 或 FTB Chunks 来配置商店团队：

• 十六进制颜色（带有 保存）
• 五个开启/关闭保护开关：允许爆炸、允许生物破坏地形、允许 PvP、允许所有假玩家、按 ID 允许假玩家
• 七个可循环切换的模式属性（点击即可根据属性在「私人 / 盟友 / 公开」之间循环）：方块编辑模式、方块交互模式、实体交互模式、攻击非生物实体模式、领地可见性、位置模式、方块编辑与交互模式
• 删除此队伍 和 打开区块地图按钮

---

🖥️ 完整 GUI 参考

快速了解每个界面中哪些位置可以点击。

/ftbshop gui → 主面板（4 行）

行	显示内容	功能
市场	当前维度中正在出售的区块数量	打开市场
出售区块	如果你所在的区块已上架，则显示价格；否则显示提示	打开「出售区块」界面
我的商品	你当前上架的商品数量，以及待领取收入预览（如有）	打开「我的商品」界面
快速购买	已启用 / 已禁用	立即切换快速购买（不切换界面）

市场界面

• 搜索框 — 输入时按店铺/队伍名称筛选
• ★ 星标（右上角）— 仅显示收藏；每行的 ★ — 将该商品切换为收藏
• 三个排序按钮 — 价格 ↑、价格 ↓、距离（从近到远）
• 可滚动列表（使用鼠标滚轮），一次显示所有维度的商品；每行显示位置、队伍名称（使用队伍颜色）、价格、距离以及一个购买按钮
• 购买行为遵循快速购买设置：开启时立即购买并播放音效；关闭时则打开确认界面

出售区块界面

• 显示你所在的区块是否已上架（包含价格和队伍颜色）
• 物品栏（输入 ID）或点击 🔍 按钮打开可视化物品选择器
• 数量栏（1–64）
• 出售按钮 — 上架或更新区块

我的商品界面

• 统计行：当前上架的商品数量（界面中虽有「已售出」/「已赚取」计数，但尚未接入功能，目前始终显示 0）
• 待领取收入预览（物品图标 + 数量）— 仅供参考；玩家在线时会自动发放收入（存入物品栏，若物品栏已满则掉落在地上）；若出售时玩家离线，则会在下次登录时发放，并通过聊天消息确认
• 每行都有移除按钮，可取消上架

购买确认界面（快速购买未开启时显示）

• 区块位置和价格
• 你当前拥有的价格物品数量，绿色/红色表示是否充足
• 购买限额进度（例如「从 TeamX 购买了 3/5 件」），仅当店铺队伍设置了购买限额时显示
• ✔ 购买 / ✖ 取消

游戏内购买浮层（使用按键绑定切换；也可能在商品附近自动显示）

• 显示区块位置、卖家队伍、价格，以及提示你当前的购买按键绑定
• 购买按钮 — 物品不足时会变为禁用的买不起状态
• ✕关闭按钮
• 设有短暂的点击冷却时间，防止意外重复购买

/ftbshop admin → 管理员面板（7 行，每行右侧都有实时摘要）

行	实时显示的摘要
基础价格	当前价格，或“未设置”
玩家出售	已启用/已禁用
团队价格	已配置的团队数量
购买限额	设有限额的团队数量
玩家收入	已禁用收入的团队数量
自动回收	已启用的团队数量
服务器团队管理	—

管理员 → 基础价格：物品栏位 + 🔍 选择器、数量栏位、设置和移除按钮，并显示当前生效的价格。

管理员 → 玩家出售：说明文字 + 单个启用/禁用切换按钮。

管理员 → 团队价格 / 购买限额 / 玩家收入 / 自动回收：共用同一种界面布局——显示当前已配置团队的可滚动列表（每个团队都有一个⌂“打开该团队的领地地图”按钮和一个✕移除按钮）、团队搜索栏及实时自动补全下拉菜单（由 FTB Teams 提供），物品选择器 + 数量栏位（仅适用于团队价格/购买限额），以及添加/更新（团队价格/购买限额）或切换（玩家收入/自动回收）按钮。

管理员 → 服务器团队管理 / 团队详情：请参阅上文“服务器团队管理”部分。

---

🛒 玩家购买指南

现在有三种方式可以购买区块：

1. 游戏内浮层——走近待售区块，面板会自动显示价格和购买按钮。或者站在区块内时直接按购买快捷键（默认为B）。
2. FTB Chunks 地图——打开大地图（默认为M），找到店铺颜色的区块图标，将鼠标悬停查看价格/提示信息，然后左键点击购买。
3. 市场 GUI——打开/ftbshop gui → 市场，即可随时搜索、排序（按价格或距离）、收藏并购买商品。

请确保物品栏中有购买所需的物品！如果启用了快速购买（可在/ftbshop gui中切换），购买时将直接跳过确认界面。

你不能购买自己的区块或由自己团队拥有的区块；而且当你的角色属于某个服务器团队时，完全无法购买。购买后，区块会立即转让给你的团队，附近玩家也会看到购买特效。

---

💰 出售自己的区块

如果管理员启用了玩家出售：

1. 站在由你的团队拥有的区块内。
2. 打开/ftbshop gui → 出售区块。
3. 选择物品和数量作为要价（输入 ID 或使用 🔍 选择器），然后点击出售。
4. 在我的商品中查看当前挂单，也可以随时使用移除按钮删除挂单。区块售出后，款项会自动支付给你（如果你在线则立即到账，否则会在下次登录时到账）——无需手动“领取”。

---

💬 命令参考

命令	说明	权限
/ftbshop gui	打开商店面板（市场、出售、我的商品、快速购买）	所有人
/ftbshop admin	打开管理员面板——所有管理员操作都在这里（基础价格、团队价格、玩家出售、购买限额、玩家收入、自动回收、服务器团队管理，包括创建/删除团队、领地保护，以及跳转到团队的区块地图）	OP 2+

所有过去需要输入 /claimshop ... 命令（set、remove、info、teamprice、playersell、playerincome、basecost、autoreclaim、setting）才能完成的配置，以及过去需要使用 /ftbteams server create 或 /ftbchunks admin open_claim_gui_as 命令的团队管理操作，现在都已移至 /ftbshop admin 图形界面。实际上，你只需要输入 /ftbshop admin 这条命令。

---

⚙️ 配置

在 config/ 下会生成两个配置文件：

• 客户端配置 — 粒子覆盖层设置：半径（区块）、粒子间距和生成间隔。
• 服务端配置:
  • welcomeEnabled / welcomeMessage — 首次加入时显示的欢迎消息（支持 § 颜色代码）。
  • apiEnabled / apiUrl — 启用并设置 Discord 风格的 Webhook URL，以嵌入消息的形式接收区块购买、上架和移除事件通知。

---

🌍 翻译

此模组支持完整翻译。
你也可以在这里进一步完善翻译：https://crowdin.com/project/buying-chunks

---

⚙️ 工作原理

• 商店数据会使用 Minecraft 的 SavedData 系统按维度保存在服务端，因此重启后仍会保留。
• 玩家加入时（或数据发生变化时），所有维度的当前商店列表、基础费用、购买限制和已购买数量都会同步至客户端。
• 购买区块时，原有认领会被移除，随后该区块会由买家的团队重新认领；商店购买会跳过基础费用（如有），以避免重复扣费。
• 物品会直接从买家的背包中扣除。
• 同步期间，不再处于实际认领状态的区块上架信息会自动清理。

---

🐛 已知限制

• 玩家必须加入非服务端团队才能购买区块。
• 我的上架界面中的“已售出”和“已赚取”计数器尚未接入功能，目前始终显示 0；只有活跃上架数量准确。
• 一次性大量认领区块（100 个及以上）可能会在同步期间造成短暂卡顿。
• Discord Webhook 集成采用发送后即不再处理的方式（失败时不会重试）；如果不再收到事件通知，请检查服务端日志。

---

📄 许可证

MIT 许可证 ©snoopypup