merchantmind

# Merchant Mind

**Merchant Mind** is a comprehensive AI shopkeeper mod for Minecraft that adds a dynamic, rotating shop to your server or singleplayer world. Driven by a custom economy and "neural" appraisers, it offers a unique way to trade, sell, and restock your gear — along with a handful of quality-of-life combat tweaks.

## Features

### The AI Shopkeeper
The mod introduces a "Quest Shop" accessible via the pause menu or a dedicated keybind. The shop features a rotating catalog of items organized into 11 categories: Weapon, Armor, Tools, Throwables, Resources, Blocks, Utility, Food, Redstone, Decor, and Rare. Each category maintains its own independent restock timer and shelves a random selection from its item pool. When a category sells out or a scheduled timer runs out, the shelves are cleared and refilled with new random items.

### Iron Restock Shortcut
Restocking takes **2 minutes and 30 seconds** (150 seconds) by default. During an active restock, an optional iron slot opens on the shop screen. Players can submit **4 Iron Ingots** to instantly finish the restock, providing a strategic choice between waiting for free or paying iron to skip ahead. Iron is never required to start a restock — it is purely an optional speed-up.

### Per-World Saves
The shop's inventory, restock timers, and player coin balances are saved locally to the specific world folder (`<save>/data/merchantmind_shop.json`). Every world maintains a completely separate economy. If you open a second world in the same session, it starts with a clean shop — it does not inherit stock, balances, or timers from the first world.

### Intelligent Trading (Barter System)
The "Trade" tab lets you swap items directly rather than going through coins. The mod calculates the **true worth** of the items you offer and matches them against the shop's current inventory using a deterministic value-matching algorithm. It selects the best return item based on both total value and unit value, with a square-root bundle curve that prevents mass-conversion exploits (e.g., turning 64 oak logs into 64 arrows). Any leftover value that the returned bundle could not absorb comes back to you as coins.

### Smart Selling
The "Sell" tab lets you sell items for coins. The appraiser calculates a base value from the item's worth and applies a **capped bulk bonus of up to +35%** for larger hauls — meaning selling in bulk always yields a better per-item rate, never worse. The payout is additionally clamped to **70% of the goods' true worth**, which makes arbitrage impossible: buying from the shop and immediately selling back will always be a net loss at any volume.

### Charge & Slam Combat
Hold the Slam key (default: `V`) to charge your weapon. The longer you hold, the more damage your next sword or axe attack will deal — up to a maximum bonus of **+14.0 damage** at full charge (38 ticks, roughly 1.9 seconds). The bonus scales on a smooth curve, so even a partial hold gives a meaningful boost. A custom HUD bar above the hotbar displays your charge percentage and the resulting bonus damage in real time, along with a screen-stretch wind-up effect that intensifies as you charge. The charge is consumed the moment a qualifying hit lands.

### Combat Tweaks
The mod includes several server-side combat adjustments:

- **Arrow Reflect:** Arrows shot at the player by mobs are reflected back, dealing **3x** the damage to the shooter.
- **Instant Pearl Heal:** The moment a thrown Ender Pearl lands or despawns, the player instantly receives a massive regeneration effect (6 hearts + Regeneration III).
- **Jump Crits:** Landing a critical hit on a hostile mob while airborne grants a small bonus damage boost.
- **Mob Suppression:** Skeletons and baby zombies have an **83% chance** to be culled upon spawning, significantly reducing combat clutter.
- **Item Clearing:** A dedicated keybind instantly clears all dropped items in the world.
- **Cinematic Respawn (Optional):** If the Cinematic Respawn mod is installed, the player automatically switches to a third-person cinematic view upon death and returns to first-person after moving.

### Keybinds
All keybinds are configurable in the Minecraft controls menu. By default:

| Key | Action |
|-----|--------|
| `B` | Open Merchant Shop |
| `K` | Clear Dropped Items |
| `V` | Charge & Slam (hold to charge) |

## Version Scheme

Merchant Mind follows **Semantic Versioning + build metadata** in the format `MAJOR.MINOR.PATCH+mc<minecraft_version>`. The version number is always maintained in `gradle.properties` (`mod_version`), and `fabric.mod.json` reads it automatically via `${version}` — it is never hardcoded.

| Component | When to increment | Notes |
|-----------|-------------------|-------|
| **MAJOR** | Breaking change — old saves or configs no longer work | Reset MINOR and PATCH to 0 |
| **MINOR** | New feature added, everything old still works | Reset PATCH to 0 |
| **PATCH** | Bug-fix-only, no new features, nothing broken | |
| **+mc\*** | Minecraft version this build targets | No effect on version comparison |

Only one position is incremented per release, matching the **biggest change** in that release. If a release contains both bug fixes and new features, only **MINOR** is incremented — a new feature always outranks a bug fix.

## Technical Details

| | |
|---|---|
| **Mod Loader** | Fabric |
| **Minecraft** | 26.1.2 |
| **Dependencies** | Fabric API, Fabric Loader (>=0.19.3) |
| **License** | MIT |
| **Optional** | Cinematic Respawn |

> **Note:** The mod's internal economy assigns a fixed "worth" to every item, which determines its buy and sell prices. The buy price is 125% of worth and the sell price is 45% of worth, making arbitrage structurally impossible.

---

*This mod — and this description — was made entirely with AI assistance, in Thailand. Everything you see here is AI-generated. Is the mod good? Yes, I think so. But if you have a problem with people using AI to make mods, that is your problem, not mine. Don't believe this summary was written by AI? That is also your problem.*

---

### Future Plans
I might add features, fixes, or other things in the future — things that neither you nor I know about yet. Confused why I am telling you this? Because I might think of a feature at any moment. That is all.

### Contact & Feedback
Found a bug? Want a new feature? Have an idea? Email me at **mattrixthai9911@zohomail.com** — I will review it and decide whether it is worth adding. The source code is available on GitHub, but it is source code only — there is no issue tracker for bug reports. Please use the email above instead.

This mod does not use any external libraries. The only dependency is **Fabric API**.

### A Note About the Shop Menu
You might notice the shop menu stutters when you open it. Your FPS is probably fine — it is the shop menu itself. There is a known bug that AI tried to fix, and then tried to fix again, and it still does the same thing. If you can tolerate that kind of behavior, congratulations — this mod is for you.