WebshopLink

A Minecraft Forge mod that lets players browse and use an external web shop inside an in-game browser window, then have the purchased items applied straight to their inventory.

Throughout the docs this project is referred to as a "mod", even where a plugin version is discussed — the functionality is the same regardless.

WebshopLink only handles the in-game side. The actual shop (catalog, pricing, what items a player gets) lives in an external web service that you run and that speaks WebshopLink's HTTP protocol. See the Wiki for the contract, and demo/ for a working reference implementation.

How it works

1. A player runs /shop <type> in game.
2. WebshopLink (server side) sends the player's current inventory to your shop API and gets back a session URL.
3. The URL opens in a full-screen in-game browser (rendered with MCEF) floating over the game world, with a small button bar at the bottom.
4. The player builds their cart on the web page, then clicks Finish Trade.
5. WebshopLink fetches the resulting inventory from your API, verifies the player's inventory hasn't changed since the session started, and applies it. Closing the window (or Cancel / ESC) cancels the session.

Player ──/shop──▶ WebshopLink (server) ──HTTP──▶ Your shop API │ │ └──── opens in-game browser ───┘ │ Finish Trade ▼ inventory applied to player

Features

• In-game shopping — the web shop renders in a Chromium browser overlaid on the game; no alt-tabbing to an external browser.
• Inventory verification — purchases are rejected if the player's inventory changed between starting the session and confirming, preventing duping/race exploits.
• Two-factor session code — an anti-tampering code is exchanged with your API on every call so sessions can't be forged from outside.
• API key support — every request to your shop API carries a configurable X-Webshop-Api-Key header.
• Main inventory + Ender Chest support, with full NBT serialization for complex items.
• Balance overlay (optional) — a small HUD box in a configurable screen corner renders your shop's balance page, so players always see their balance. On by default; position, size, and URL are client-side config. See Balance overlay.
• Optional networking — the mod registers its network channel as optional, so vanilla clients (or clients without the mod) can still connect to the server; they just can't open the browser.

Requirements

Side Required Server WebshopLink mod Client WebshopLink mod + MCEF Elsewhere An external web shop implementing the WebshopLink API

• Minecraft 1.20.1, Forge 47.x
• MCEF 2.2.0+ (client only — the dedicated server never loads it)

Players whose client is missing the mod/MCEF will be told to install them when they run /shop.

Commands

Command Description /shop <type> [label] Cancels any unfinished session, then starts a new shop session of the given type (the shopSlug sent to your API). Optional label is shown in the confirmation UI. Opens the in-game browser. /shopFinish <uuid> Manual backstop for checkout (the browser's Finish Trade button does this automatically). Fetches the new inventory and offers a clickable confirm link in chat. /confirmFinish <uuid> Applies the checked-out inventory changes. /shopCancel <uuid> Cancels the session both locally and with your API.

Normal play only needs /shop — the browser's buttons drive the rest. The other commands exist as fallbacks and for clients without the in-game browser.

By default anyone can run /shop. To restrict it to operators/command blocks (so shops only open at specific locations) set shopCommandPermissionLevel in the config — see Locking down /shop.

Installation

Server

1. Download the latest WebshopLink release JAR.
2. Drop it into the server's mods/ folder.
3. Start the server once to generate config/webshoplink-common.toml, then point it at your shop API (see the Wiki).
4. Restart.

Client (each player)

1. Install MCEF.
2. Install the WebshopLink mod.

Documentation

• Wiki — server-operator setup: full config reference, the HTTP API your shop must implement, inventory data format, and the security model.
• demo/ — a small, fully-commented reference shop (Bun + Tailwind) you can run locally to try the mod or learn the contract.

License

See LICENSE.