
物品市场
添加用于购买和出售物品的GUI的Mod。 | 添加用于购买和出售物品的GUI的Mod。
ItemMarket — 游戏内物品买卖市场(Fabric)
中文 ItemMarket 添加了一个简单、快速的游戏内市场 GUI,玩家可以使用按世界保存的内置金币余额来购买和出售物品。价格可通过简单的 JSON 文件完全配置,并且该模组暴露了一个小型 Java/Fabric API,以便其他模组读取/写入玩家余额并监听市场交易。
致谢: 由 TNTStudios 开发 — 网站:TNTStudios.space — 社交账号:@TNTStudiosn
特性
中文
- ✅ 客户端 GUI 市场(默认按 M 键打开)
- ✅ 一次购买 1 个物品(以服务端为准)
- ✅ 出售背包中某物品的 1 个或全部
- ✅ 内置经济系统按世界存储(PersistentState)
- ✅ 通过 JSON 配置价格(每个价格一个文件,内部为物品列表)
- ✅ 加入时客户端价格同步
- ✅ 公开 API(
ItemMarketAPI)用于获取/增加/扣除金币 - ✅ 交易成功时的事件回调(
MarketTransactionCallback)
需求
中文
- Minecraft: 基于 Fabric 的环境(客户端 + 服务端)
- Fabric Loader + Fabric API
- 需同时安装在服务端和客户端(因为市场是客户端 GUI,需与服务端通信)
如果只在服务端安装,玩家将没有 GUI/按键绑定,无法使用市场。
安装
中文
- 为你的 Minecraft 版本安装 Fabric Loader 和 Fabric API。
- 将 ItemMarket 的
.jar放入:- 客户端:
mods/ - 服务端:
mods/
- 客户端:
- 启动游戏/服务端一次以生成配置文件夹。
使用方法(玩家)
中文
- 加入世界/服务器。
- 按 M 键打开市场。
- 你可以在 选项 → 控制 中重新绑定按键(搜索 “ItemMarket”)。
- 选择:
- 购买(绿色)—— 使用你的金币购买物品
- 出售(金色)—— 出售你背包中的物品
- 滚动物品列表并点击物品:
- 购买: 确认购买 1 个
- 出售: 选择 出售 1 或 出售全部
- 你的余额显示在屏幕右上角。
购买时会发生什么?
中文
- 服务端检查该物品配置的购买价格。
- 如果你有足够的金币,扣除金币并给予你 1 个物品。
出售时会发生什么?
中文
- 服务端检查该物品配置的出售价格。
- 如果你拥有该物品:
- 出售 1: 移除 1 个物品,增加金币
- 出售全部: 移除该物品的所有堆叠,按总数量增加金币
经济系统(金币如何保存)
中文
- 余额存储在服务端,使用
PersistentState,按世界保存。 - 数据键:
itemmarket_economy - 每个玩家 UUID 的金钱以 Long 类型存储。
- 新玩家初始为 0 金币,除非其他模组(或你的自定义代码)通过 API 添加金币。
价格配置(JSON)
ItemMarket 从以下目录读取价格:
config/ItemMarket/compra/
config/ItemMarket/venta/
中文
compra/= 购买价格(玩家支付金币获得物品)venta/= 出售价格(玩家出售物品获得金币)
文件命名规则
中文
每个 .json 文件名必须是数字,该数字即为价格。
示例:
config/ItemMarket/compra/100.json→ 购买价格 = 100 金币config/ItemMarket/venta/25.json→ 出售价格 = 25 金币
如果文件名不是纯数字,将被跳过。
重要:价格 0 作为文件名是有效的(
0.json),但在游戏中不会生效,因为交易要求price > 0。请使用 1+。
JSON 格式
中文 每个文件是一个物品 ID(字符串)的 JSON 数组:
[
"minecraft:diamond",
"minecraft:emerald",
"minecraft:iron_ingot"
]
购买配置示例
中文 创建:
config/ItemMarket/compra/250.json
[
"minecraft:diamond",
"minecraft:netherite_ingot"
]
结果:
- 购买 diamond 花费 250
- 购买 netherite_ingot 花费 250
出售配置示例
中文 创建:
config/ItemMarket/venta/50.json
[
"minecraft:iron_ingot",
"minecraft:gold_ingot"
]
结果:
- 出售 iron_ingot 每个获得 50
- 出售 gold_ingot 每个获得 50
如果物品出现在多个文件中会怎样?
中文 每个物品在内存中只能有一个价格(映射会按物品覆盖)。如果将同一物品放入多个价格文件,最后加载的文件将生效——文件顺序可能取决于操作系统,因此不要依赖它。请确保每个文件夹内的列表唯一。
如果物品 ID 错误或模组缺失会怎样?
中文
- 无效 ID 会被跳过并记录日志消息。
- 在注册表中找不到的物品(通常是“模组缺失”)会被跳过。
需要重启才能应用更改吗?
中文
是的。价格在启动时由 MarketConfig.init() 加载。目前没有内置的实时重载命令,因此你应该:
- 重启服务端,或
- 重启客户端并重新加入(价格同步在加入时发生)
开发者 API(Java/Fabric API)
ItemMarket 提供了一个Java API,面向其他 Fabric 模组。
中文 这不是 HTTP/REST API。你通过将 ItemMarket 添加为依赖并调用其类来“连接”。
API:读取/写入余额
类:com.TNTStudios.itemmarket.api.ItemMarketAPI
方法:
getBalance(ServerPlayerEntity player) -> longaddBalance(ServerPlayerEntity player, long amount) -> longremoveBalance(ServerPlayerEntity player, long amount) -> boolean
中文(示例:玩家加入时给予金币)
import com.TNTStudios.itemmarket.api.ItemMarketAPI;
import net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents;
public class MyMod {
public static void init() {
ServerPlayConnectionEvents.JOIN.register((handler, sender, server) -> {
var player = handler.getPlayer();
// 首次加入时给予 100 金币(简单示例)
ItemMarketAPI.addBalance(player, 100);
});
}
}
注意(中文)
addBalance()和removeBalance()还会在玩家打开市场界面时通过MarketNetwork.openMarketForPlayer触发 UI 同步。removeBalance()在玩家资金不足时返回false。
事件:交易回调
接口:com.TNTStudios.itemmarket.api.MarketTransactionCallback
仅在交易成功时调用。
签名:
void onTransaction(ServerPlayerEntity player, Item item, int count, long totalPrice, boolean isBuy);
中文(示例:记录每笔交易)
import com.TNTStudios.itemmarket.api.MarketTransactionCallback;
public class MyMod {
public static void init() {
MarketTransactionCallback.EVENT.register((player, item, count, totalPrice, isBuy) -> {
String type = isBuy ? "BUY" : "SELL";
System.out.println("[MyMod] " + player.getName().getString() +
" " + type + " " + count + "x " + item.getName().getString() +
" for " + totalPrice + " coins");
});
}
}
网络与安全(内部工作原理)
中文
- 玩家加入时,服务端向客户端发送:
- 所有购买价格
- 所有出售价格 到客户端(价格缓存)。
- 玩家按 M 时,客户端请求打开市场。
- 服务端响应玩家的当前余额,客户端打开 GUI。
- 玩家点击物品时:
- 客户端发送交易请求(
购买/出售、物品 ID、sellAll 标志) - 服务端验证所有内容(价格、余额、背包)
- 服务端应用更改并更新客户端 GUI
- 客户端发送交易请求(
中文 服务端是权威的,因此客户端无法通过数据包伪造价格或余额。
故障排除
中文 市场无法打开(按 M 无反应)
- 确保模组已安装在客户端
- 检查按键冲突并在控制中重新绑定
- 确保已安装 Fabric API
物品显示但无法购买/出售
- 检查你的 JSON 文件名是否为数字(例如
100.json) - 确保物品 ID 正确
- 确保价格 >= 1
某些物品缺失
- 该物品的模组可能未安装在服务端
- 当 ID 缺失时,模组会记录“Item not found”
致谢与链接
中文
- 由 TNTStudios 开发
- 网站:TNTStudios.space
- 社交账号:@TNTStudiosn
ItemMarket — 游戏内物品买卖市场(Fabric)
西班牙语 ItemMarket 添加了一个简单、快速的游戏内市场 GUI,玩家可以使用按世界保存的金币余额来购买和出售物品。价格可通过非常简单的 JSON 文件配置,并且该模组包含一个 Java/Fabric API,以便其他模组读取/写入余额并监听交易。
致谢: 由 TNTStudios 开发 — 网站:TNTStudios.space — 社交账号:@TNTStudiosn
特性
西班牙语
- ✅ 客户端 GUI 市场(默认按 M 键打开)
- ✅ 每笔交易购买 1 个物品(服务端验证)
- ✅ 出售背包中某物品的 1 个或全部
- ✅ 内置经济系统按世界保存(PersistentState)
- ✅ 通过 JSON 配置价格(文件 = 价格,内部为物品列表)
- ✅ 加入时价格同步
- ✅ 公开 API(
ItemMarketAPI)用于查询/增加/扣除金币 - ✅ 交易成功时的事件(
MarketTransactionCallback)
需求
西班牙语
- Minecraft: 基于 Fabric 的环境(客户端 + 服务端)
- Fabric Loader + Fabric API
- 需安装在服务端和客户端(因为 GUI 在客户端并与服务端通信)
如果只在服务端安装,玩家将没有 GUI/按键,无法使用市场。
安装
西班牙语
- 为你的 Minecraft 版本安装 Fabric Loader 和 Fabric API。
- 将 ItemMarket 的
.jar放入:- 客户端:
mods/ - 服务端:
mods/
- 客户端:
- 启动游戏/服务端一次以生成配置文件夹。
使用方法(玩家)
西班牙语
- 进入世界/服务器。
- 按 M 键打开市场。
- 你可以在 选项 → 控制 中更改按键(搜索 “ItemMarket”)。
- 选择:
- 购买(绿色)—— 使用你的金币购买
- 出售(金色)—— 出售背包中的物品
- 滚动列表并点击物品:
- 购买: 确认购买 1 个
- 出售: 选择 出售 1 或 出售全部
- 你的余额显示在右上角。
购买时会发生什么?
西班牙语
- 服务端检查配置的购买价格。
- 如果你有足够的金币,扣除并给予你 1 个物品。
出售时会发生什么?
西班牙语
- 服务端检查配置的出售价格。
- 如果你拥有该物品:
- 出售 1: 移除 1 个并增加金币
- 出售全部: 移除该物品的所有堆叠并按总数量增加金币
经济系统(金币如何保存)
西班牙语
- 余额存储在服务端,使用
PersistentState,按世界保存。 - 保存键:
itemmarket_economy - 每个玩家 UUID 的金钱以 Long 类型存储。
- 新玩家初始为 0 金币,除非其他模组(或你的代码)通过 API 添加金币。
价格配置(JSON)
ItemMarket 从以下目录读取价格:
config/ItemMarket/compra/
config/ItemMarket/venta/
西班牙语
compra/= 购买价格(支付金币获得物品)venta/= 出售价格(出售物品获得金币)
文件命名规则
西班牙语
每个 .json 必须命名为数字,该数字即为价格。
示例:
config/ItemMarket/compra/100.json→ 购买价格 = 100 金币config/ItemMarket/venta/25.json→ 出售价格 = 25 金币
如果名称不是 100% 数字,将被忽略。
重要:
0.json存在,但在游戏中不会生效,因为交易要求price > 0。请使用 1+。
JSON 格式
西班牙语 每个文件是一个物品 ID(字符串)的 JSON 数组:
[
"minecraft:diamond",
"minecraft:emerald",
"minecraft:iron_ingot"
]
购买示例
西班牙语 创建:
config/ItemMarket/compra/250.json
[
"minecraft:diamond",
"minecraft:netherite_ingot"
]
结果:
- 购买 diamond 花费 250
- 购买 netherite_ingot 花费 250
出售示例
西班牙语 创建:
config/ItemMarket/venta/50.json
[
"minecraft:iron_ingot",
"minecraft:gold_ingot"
]
结果:
- 出售 iron_ingot 每个获得 50
- 出售 gold_ingot 每个获得 50
如果物品出现在多个文件中会怎样?
西班牙语 每个物品在内存中只能有一个价格(映射会按物品覆盖)。如果在多个文件中重复同一物品,最后加载的文件将生效——顺序可能因操作系统而异。最好不要重复物品。
如果 ID 错误或缺少模组会怎样?
西班牙语
- 无效 ID 会被忽略(并在日志中记录消息)。
- 注册表中不存在的物品(通常是“缺少模组”)会被忽略。
需要重启才能应用更改吗?
西班牙语
是的。价格在启动时由 MarketConfig.init() 加载。目前没有通过命令实时重载的功能,因此:
- 重启服务端,或
- 重启客户端并重新加入(同步在加入时发生)
开发者 API(Java/Fabric)
ItemMarket 包含一个面向其他 Fabric 模组的 Java API。
西班牙语 这不是 HTTP/REST API。你通过将 ItemMarket 添加为依赖并调用其类来“连接”。
API:读取/写入余额
类:com.TNTStudios.itemmarket.api.ItemMarketAPI
方法:
getBalance(ServerPlayerEntity player) -> longaddBalance(ServerPlayerEntity player, long amount) -> longremoveBalance(ServerPlayerEntity player, long amount) -> boolean
西班牙语(示例:加入时给予金币)
import com.TNTStudios.itemmarket.api.ItemMarketAPI;
import net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents;
public class MiMod {
public static void init() {
ServerPlayConnectionEvents.JOIN.register((handler, sender, server) -> {
var player = handler.getPlayer();
ItemMarketAPI.addBalance(player, 100);
});
}
}
注意(西班牙语)
addBalance()和removeBalance()还会在相应时通过打开/更新市场界面来同步 UI。removeBalance()在资金不足时返回false。
事件:交易回调
接口:com.TNTStudios.itemmarket.api.MarketTransactionCallback
仅在交易成功时调用。
签名:
void onTransaction(ServerPlayerEntity player, Item item, int count, long totalPrice, boolean isBuy);
西班牙语(示例:在控制台记录交易)
import com.TNTStudios.itemmarket.api.MarketTransactionCallback;
public class MiMod {
public static void init() {
MarketTransactionCallback.EVENT.register((player, item, count, totalPrice, isBuy) -> {
String tipo = isBuy ? "COMPRA" : "VENTA";
System.out.println("[MiMod] " + player.getName().getString() +
" " + tipo + " " + count + "x " + item.getName().getString() +
" por " + totalPrice + " monedas");
});
}
}
网络与安全(内部工作原理)
西班牙语
- 加入时,服务端向客户端发送:
- 购买价格
- 出售价格 (价格缓存)。
- 按 M 时,客户端请求打开市场。
- 服务端响应余额,客户端打开 GUI。
- 点击时:
- 客户端发送请求(
购买/出售、物品 ID、sellAll) - 服务端验证(价格、余额、背包)
- 应用更改并更新 GUI
- 客户端发送请求(
西班牙语 服务端是权威的,因此客户端无法伪造价格或余额。
故障排除
西班牙语 市场无法打开(按 M 无反应)
- 确保模组已安装在客户端
- 检查按键冲突并在控制中更改
- 验证已安装 Fabric API
物品显示但无法购买/出售
- 检查 JSON 文件名是否为数字(例如
100.json) - 检查 ID 是否正确
- 确保价格 >= 1
缺少某些物品
- 服务端可能缺少该物品的模组
- 当 ID 缺失时,模组会在日志中输出“Item no encontrado”
致谢与链接
西班牙语
- 由 TNTStudios 开发
- 网站:TNTStudios.space
- 社交账号:@TNTStudiosn
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。