ItemMarket — In‑Game Item Buy/Sell Market (Fabric)

EN
ItemMarket adds a simple, fast in‑game market GUI where players can buy and sell items using a built‑in coin balance saved per-world. Prices are fully configurable via easy JSON files, and the mod exposes a small Java/Fabric API so other mods can read/write player balances and listen to market transactions.

Credits: Developed by TNTStudios — Website: TNTStudios.space — Socials: @TNTStudiosn

---

Features

EN

• ✅ Client GUI market (open with M by default)
• ✅ Buy 1 item at a time (server-authoritative)
• ✅ Sell 1 or all of an item in your inventory
• ✅ Built-in economy stored per world (PersistentState)
• ✅ Price configuration via JSON (per-price file, item list inside)
• ✅ Client price sync on join
• ✅ Public API (ItemMarketAPI) to get/add/remove coins
• ✅ Event callback (MarketTransactionCallback) when a transaction succeeds

---

Requirements

EN

• Minecraft: Fabric-based environment (client + server)
• Fabric Loader + Fabric API
• Installed on both server and client (because the market is a client GUI that talks to the server)

If you only install it on the server, players won’t have the GUI/keybind and won’t be able to use the market.

---

Installation

EN

1. Install Fabric Loader and Fabric API for your Minecraft version.
2. Drop the ItemMarket .jar into:
   • Client: mods/
   • Server: mods/
3. Launch the game/server once to generate the config folders.

---

How to Use (Players)

EN

1. Join the world/server.
2. Press M to open the market.
   • You can rebind the key in Options → Controls (search for “ItemMarket”).
3. Choose:
   • Buy (green) — buy items using your coins
   • Sell (gold) — sell items from your inventory
4. Scroll the item list and click an item:
   • Buy: confirm to purchase 1
   • Sell: choose Sell 1 or Sell All
5. Your balance is shown at the top-right of the screen.

What happens when you buy?

EN

• The server checks the configured buy price for that item.
• If you have enough coins, it subtracts coins and gives you 1 item.

What happens when you sell?

EN

• The server checks the configured sell price for that item.
• If you have the item:
  • Sell 1: removes 1 item, adds coins
  • Sell All: removes all stacks of that item, adds coins for total quantity

---

Economy System (How coins are saved)

EN

• Balances are stored on the server using PersistentState, per world.
• Data key: itemmarket_economy
• Money is stored as a Long per player UUID.
• New players start with 0 coins unless another mod (or your custom code) adds coins via the API.

---

Price Configuration (JSON)

ItemMarket reads prices from:

config/ItemMarket/compra/
config/ItemMarket/venta/

EN

• compra/ = BUY prices (player pays coins to get items)
• venta/ = SELL prices (player receives coins to sell items)

File naming rule

EN Each .json filename must be a number, and that number is the price.

Examples:

• config/ItemMarket/compra/100.json → buy price = 100 coins
• config/ItemMarket/venta/25.json → sell price = 25 coins

If the filename is not purely numeric, it will be skipped.

Important: price 0 is valid as a filename (0.json) but will not work in-game because transactions require price > 0. Use 1+.

JSON format

EN Each file is a JSON array of item IDs (strings):

[
  "minecraft:diamond",
  "minecraft:emerald",
  "minecraft:iron_ingot"
]

Buy configuration example

EN Create:

config/ItemMarket/compra/250.json

[
  "minecraft:diamond",
  "minecraft:netherite_ingot"
]

Result:

• Buying a diamond costs 250
• Buying a netherite_ingot costs 250

Sell configuration example

EN Create:

config/ItemMarket/venta/50.json

[
  "minecraft:iron_ingot",
  "minecraft:gold_ingot"
]

Result:

• Selling iron_ingot gives 50 per item
• Selling gold_ingot gives 50 per item

What if an item appears in multiple files?

EN Each item can only have one price in memory (maps overwrite by item). If you put the same item in multiple price files, whichever file is loaded last will win — file ordering may depend on the OS, so don’t rely on it. Keep your lists unique per folder.

What if an item ID is wrong or the mod is missing?

EN

• Invalid IDs are skipped with a log message.
• Items not found in the registry (usually “missing mod”) are skipped.

Do I need to restart to apply changes?

EN Yes. Prices are loaded at startup by MarketConfig.init(). There is no built-in live reload command yet, so you should:

• Restart the server, or
• Restart the client & rejoin (price sync occurs on join)

---

Developer API (Java/Fabric API)

ItemMarket provides a Java API intended for other Fabric mods.

EN This is not an HTTP/REST API. You “connect” by adding ItemMarket as a dependency and calling its classes.

API: Read/Write balance

Class: com.TNTStudios.itemmarket.api.ItemMarketAPI

Methods:

• getBalance(ServerPlayerEntity player) -> long
• addBalance(ServerPlayerEntity player, long amount) -> long
• removeBalance(ServerPlayerEntity player, long amount) -> boolean

EN (Example: Give coins on player join)

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();
            // Give 100 coins on first join (simple example)
            ItemMarketAPI.addBalance(player, 100);
        });
    }
}

Notes (EN)

• addBalance() and removeBalance() will also trigger a UI sync by opening/updating the market screen if the player has it open (via MarketNetwork.openMarketForPlayer).
• removeBalance() returns false when the player doesn’t have enough funds.

Event: Transaction callback

Interface: com.TNTStudios.itemmarket.api.MarketTransactionCallback

Called only when a transaction succeeds.

Signature:

void onTransaction(ServerPlayerEntity player, Item item, int count, long totalPrice, boolean isBuy);

EN (Example: Log every transaction)

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");
        });
    }
}

---

Networking & Security (How it works internally)

EN

• On player join, the server sends:
  • all BUY prices
  • all SELL prices
    to the client (price cache).
• When the player presses M, the client requests the market to open.
• The server responds with the player’s current balance, and the client opens the GUI.
• When the player clicks an item:
  • the client sends a transaction request (buy/sell, item id, sellAll flag)
  • the server validates everything (price, balance, inventory)
  • the server applies changes and then updates the client GUI

EN The server is authoritative, so clients cannot “fake” prices or balances via packets.

---

Troubleshooting

EN Market doesn’t open (pressing M does nothing)

• Make sure the mod is installed on the client
• Check keybind conflicts and rebind in Controls
• Ensure Fabric API is installed

Items show but can’t buy/sell

• Check your JSON file names are numeric (e.g. 100.json)
• Ensure the item IDs are correct
• Ensure price is >= 1

Some items missing

• The item’s mod may not be installed on the server
• The mod logs “Item not found” when an ID is missing

---

Credits & Links

EN

• Developed by TNTStudios
• Website: TNTStudios.space
• Socials: @TNTStudiosn

---

---

ItemMarket — Mercado In‑Game para Comprar/Vender Ítems (Fabric)

ES
ItemMarket agrega un mercado simple y rápido con GUI dentro del juego para que los jugadores puedan comprar y vender ítems usando un balance de monedas guardado por mundo. Los precios se configuran con archivos JSON muy fáciles, y el mod incluye una API Java/Fabric para que otros mods puedan leer/escribir balances y escuchar transacciones.

Créditos: Desarrollado por TNTStudios — Sitio web: TNTStudios.space — Redes: @TNTStudiosn

---

Características

ES

• ✅ Mercado con GUI en el cliente (abrir con M por defecto)
• ✅ Comprar 1 ítem por transacción (validación en servidor)
• ✅ Vender 1 o todo de un ítem del inventario
• ✅ Economía integrada guardada por mundo (PersistentState)
• ✅ Configuración de precios por JSON (archivo = precio, lista de ítems dentro)
• ✅ Sincronización de precios al entrar
• ✅ API pública (ItemMarketAPI) para consultar/sumar/restar monedas
• ✅ Evento (MarketTransactionCallback) cuando una transacción es exitosa

---

Requisitos

ES

• Minecraft: entorno basado en Fabric (cliente + servidor)
• Fabric Loader + Fabric API
• Instalado en servidor y cliente (porque la GUI está en el cliente y se comunica con el servidor)

Si lo instalas solo en el servidor, los jugadores no tendrán la GUI/tecla y no podrán usar el mercado.

---

Instalación

ES

1. Instala Fabric Loader y Fabric API para tu versión de Minecraft.
2. Coloca el .jar de ItemMarket en:
   • Cliente: mods/
   • Servidor: mods/
3. Inicia el juego/servidor una vez para que se creen las carpetas de configuración.

---

Cómo usarlo (Jugadores)

ES

1. Entra al mundo/servidor.
2. Presiona M para abrir el mercado.
   • Puedes cambiar la tecla en Opciones → Controles (busca “ItemMarket”).
3. Elige:
   • Comprar (verde) — compras usando tus monedas
   • Vender (dorado) — vendes ítems del inventario
4. Desplázate por la lista y haz clic en un ítem:
   • Comprar: confirmar para comprar 1
   • Vender: elegir Vender 1 o Vender todo
5. Tu balance aparece arriba a la derecha.

¿Qué pasa al comprar?

ES

• El servidor revisa el precio de compra configurado.
• Si tienes monedas suficientes, descuenta y te entrega 1 ítem.

¿Qué pasa al vender?

ES

• El servidor revisa el precio de venta configurado.
• Si tienes el ítem:
  • Vender 1: quita 1 y suma monedas
  • Vender todo: quita todas las stacks de ese ítem y suma monedas por la cantidad total

---

Economía (Cómo se guardan las monedas)

ES

• Los balances se guardan en el servidor usando PersistentState, por mundo.
• Clave de guardado: itemmarket_economy
• El dinero se guarda como Long por UUID del jugador.
• Los jugadores nuevos empiezan con 0 monedas a menos que otro mod (o tu código) les agregue monedas con la API.

---

Configuración de Precios (JSON)

ItemMarket lee precios desde:

config/ItemMarket/compra/
config/ItemMarket/venta/

ES

• compra/ = precios de COMPRA (pagas monedas para obtener ítems)
• venta/ = precios de VENTA (recibes monedas al vender)

Regla de nombres de archivo

ES Cada .json debe llamarse con un número, y ese número es el precio.

Ejemplos:

• config/ItemMarket/compra/100.json → precio de compra = 100 monedas
• config/ItemMarket/venta/25.json → precio de venta = 25 monedas

Si el nombre no es 100% numérico, se ignora.

Importante: 0.json existe, pero no funcionará en juego porque las transacciones requieren price > 0. Usa 1+.

Formato del JSON

ES Cada archivo es un arreglo JSON de IDs de ítems (strings):

[
  "minecraft:diamond",
  "minecraft:emerald",
  "minecraft:iron_ingot"
]

Ejemplo de compra

ES Crear:

config/ItemMarket/compra/250.json

[
  "minecraft:diamond",
  "minecraft:netherite_ingot"
]

Resultado:

• Comprar diamond cuesta 250
• Comprar netherite_ingot cuesta 250

Ejemplo de venta

ES Crear:

config/ItemMarket/venta/50.json

[
  "minecraft:iron_ingot",
  "minecraft:gold_ingot"
]

Resultado:

• Vender iron_ingot da 50 por ítem
• Vender gold_ingot da 50 por ítem

¿Qué pasa si un ítem está en varios archivos?

ES Cada ítem solo puede tener un precio en memoria (los mapas sobreescriben por ítem). Si repites un ítem en varios archivos, “gana” el último que se cargue — el orden puede variar por sistema operativo. Mejor no repetir ítems.

¿Y si el ID está mal o falta un mod?

ES

• IDs inválidos se ignoran (con mensaje en logs).
• Ítems que no existen en el registro (normalmente “falta el mod”) se ignoran.

¿Debo reiniciar para aplicar cambios?

ES Sí. Los precios se cargan al iniciar con MarketConfig.init(). No hay recarga en vivo por comando (todavía), así que:

• Reinicia el servidor, o
• Reinicia el cliente y vuelve a entrar (la sincronización ocurre al entrar)

---

API para Desarrolladores (Java/Fabric)

ItemMarket incluye una API Java para otros mods Fabric.

ES Esto no es una API HTTP/REST. Te “conectas” agregando ItemMarket como dependencia y llamando sus clases.

API: Leer/Escribir balance

Clase: com.TNTStudios.itemmarket.api.ItemMarketAPI

Métodos:

• getBalance(ServerPlayerEntity player) -> long
• addBalance(ServerPlayerEntity player, long amount) -> long
• removeBalance(ServerPlayerEntity player, long amount) -> boolean

ES (Ejemplo: dar monedas al entrar)

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);
        });
    }
}

Notas (ES)

• addBalance() y removeBalance() también sincronizan la UI abriendo/actualizando la pantalla del mercado cuando corresponde.
• removeBalance() devuelve false si no hay fondos suficientes.

Evento: Callback de transacción

Interfaz: com.TNTStudios.itemmarket.api.MarketTransactionCallback

Se llama solo si la transacción fue exitosa.

Firma:

void onTransaction(ServerPlayerEntity player, Item item, int count, long totalPrice, boolean isBuy);

ES (Ejemplo: registrar transacciones en consola)

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");
        });
    }
}

---

Red & Seguridad (Cómo funciona por dentro)

ES

• Al entrar, el servidor envía al cliente:
  • precios de COMPRA
  • precios de VENTA
    (cache de precios).
• Al presionar M, el cliente solicita abrir el mercado.
• El servidor responde con el balance, y el cliente abre la GUI.
• Al hacer clic:
  • el cliente envía la solicitud (comprar/vender, id del ítem, sellAll)
  • el servidor valida (precio, balance, inventario)
  • aplica cambios y actualiza la GUI

ES El servidor manda, así que el cliente no puede falsificar precios o balances.

---

Solución de problemas

ES No abre el mercado (M no hace nada)

• Asegúrate que el mod esté instalado en el cliente
• Revisa conflictos de tecla y cámbiala en Controles
• Verifica que Fabric API esté instalado

Se ven ítems pero no deja comprar/vender

• Revisa que los nombres de JSON sean numéricos (ej. 100.json)
• Revisa IDs correctos
• Asegúrate que el precio sea >= 1

Faltan algunos ítems

• Puede faltar el mod del ítem en el servidor
• El mod imprime “Item no encontrado” en logs cuando falta un ID

---

Créditos & Links

ES

• Desarrollado por TNTStudios
• Sitio web: TNTStudios.space
• Redes: @TNTStudiosn