物品市场

物品市场

添加用于购买和出售物品的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/按键绑定,无法使用市场。


安装

中文

  1. 为你的 Minecraft 版本安装 Fabric Loader 和 Fabric API。
  2. 将 ItemMarket 的 .jar 放入:
    • 客户端: mods/
    • 服务端: mods/
  3. 启动游戏/服务端一次以生成配置文件夹。

使用方法(玩家)

中文

  1. 加入世界/服务器。
  2. 按 M 键打开市场。
    • 你可以在 选项 → 控制 中重新绑定按键(搜索 “ItemMarket”)。
  3. 选择:
    • 购买(绿色)—— 使用你的金币购买物品
    • 出售(金色)—— 出售你背包中的物品
  4. 滚动物品列表并点击物品:
    • 购买: 确认购买 1 个
    • 出售: 选择 出售 1 或 出售全部
  5. 你的余额显示在屏幕右上角。

购买时会发生什么?

中文

  • 服务端检查该物品配置的购买价格。
  • 如果你有足够的金币,扣除金币并给予你 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) -> long
  • addBalance(ServerPlayerEntity player, long amount) -> long
  • removeBalance(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/按键,无法使用市场。


安装

西班牙语

  1. 为你的 Minecraft 版本安装 Fabric Loader 和 Fabric API。
  2. 将 ItemMarket 的 .jar 放入:
    • 客户端: mods/
    • 服务端: mods/
  3. 启动游戏/服务端一次以生成配置文件夹。

使用方法(玩家)

西班牙语

  1. 进入世界/服务器。
  2. 按 M 键打开市场。
    • 你可以在 选项 → 控制 中更改按键(搜索 “ItemMarket”)。
  3. 选择:
    • 购买(绿色)—— 使用你的金币购买
    • 出售(金色)—— 出售背包中的物品
  4. 滚动列表并点击物品:
    • 购买: 确认购买 1 个
    • 出售: 选择 出售 1 或 出售全部
  5. 你的余额显示在右上角。

购买时会发生什么?

西班牙语

  • 服务端检查配置的购买价格。
  • 如果你有足够的金币,扣除并给予你 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) -> long
  • addBalance(ServerPlayerEntity player, long amount) -> long
  • removeBalance(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