💰 Viper Economy 🏦

Viper Economy is a comprehensive, server-side only Fabric economy mod for Minecraft 1.21 through 1.21.11, 26.1 through 26.1.2, and 26.2.x. It provides a complete virtual/physical currency system with server shops, chest shops, daily rewards, tax mechanics, PvP balance loss, and scoreboard integration — all configurable without client mods. 🔌✨

Supported Versions

Version	Java	Status
1.21.x	21	✅ Full support
26.1.x	25	✅ Full support
26.2.x	25	✅ Full support

---

🛠️ Purpose & Function

The core engineering philosophy behind Viper Economy is to deliver a zero-dependency, server-side economy that works out-of-the-box on any Fabric server. By implementing asynchronous storage backends (JSON files), the mod avoids database overhead while maintaining atomic transactions. Fabric Mixins hijack player interactions (signs, chests, packets) to enforce chest-shop protection and server-shop GUIs without client-side registry synchronization. Pure server-side execution means vanilla clients connect seamlessly — no resource packs, no client mods, no version mismatch errors. 🍦

• Virtual & Physical Currency Modes: Toggle between balance-as-number (VIRTUAL) or balance-as-items (PHYSICAL with custom currency item, default diamond). 💎
• Server Shop GUI: Paginated, category-driven shop interface opened via /shop — fully configurable prices, categories, and display items via prices.json. 🛍️
• Chest Shops: Players create shops by placing a sign on a chest — auto-detected via sign interaction mixin. Supports buy/sell, price display, and ownership protection. 📦
• Daily Rewards & Sell Limits: Configurable daily login bonus and per-player daily sell cap to prevent economy inflation. 📅
• Tax System: Automatic percentage tax on shop purchases, configurable via taxRate. 💸
• PvP Balance Loss: Optional percentage of victim's balance dropped on PvP death. ⚔️
• Scoreboard Integration: Live balance display on sidebar scoreboard (toggleable). 📊

---

✨ Key Features

Feature	Description
💵 Dual Currency Modes	VIRTUAL (database balances) or PHYSICAL (currency items in inventory/ender chest).
🛒 Server Shop GUI	6-row paginated inventory with category rings, item lore pricing, shift-click stack buying.
📦 Chest Shop System	Sign-on-chest detection, holographic price display via custom name, buy/sell perms, admin bypass.
🔐 Chest Protection	Mixin-enforced: non-owners cannot open shop chests; shift-click bypass for admins.
📅 Daily Login Rewards	Configurable dailyAmount granted on first join each day (UTC reset).
🚫 Daily Sell Limit	dailySellLimit caps total sell value per player per day.
💸 Purchase Tax	taxRate (default 10%) applied on all server shop buys; goes to void.
⚔️ PvP Economics	pvpBalanceLossPercentage (default 0%) — loser drops % of balance to winner.
📊 Sidebar Scoreboard	Real-time balance display; scoreboardEnabled toggle.
⚙️ Hot-Reloadable Configs	/economy reload refreshes config.json, prices.json, permissions.json without restart.
🔧 Permissions System	Granular command/shop permissions via permissions.json (LuckPerms-compatible nodes).

---

🎮 Commands & Permissions

Command	Permission	Description
/balance / /bal	viper.economy.balance	View your balance (or target player's with viper.economy.balance.others).
/pay <player> <amount>	viper.economy.pay	Transfer balance to another player.
/baltop	viper.economy.baltop	Leaderboard of top 10 balances (paginated).
/daily	viper.economy.daily	Claim daily login reward.
/shop	viper.economy.shop	Open server shop GUI.
/worth <item>	viper.economy.worth	Check server shop buy/sell price for held/item.
/sell	viper.economy.sell	Sell held item to server shop (if enabled).
/economy reload	viper.economy.admin.reload	Hot-reload all configs.
/economy give <player> <amount>	viper.economy.admin.give	Add balance to player.
/economy take <player> <amount>	viper.economy.admin.take	Remove balance from player.
/economy set <player> <amount>	viper.economy.admin.set	Set player's exact balance.
/economy toggle <physical|virtual>	viper.economy.admin.toggle	Switch economy mode at runtime.

---

⚙️ Configuration Files

All configs live in <run-dir>/config/viper-economy/ and are hot-reloadable via /economy reload.

config.json (Global Settings)

{
  "economyMode": "VIRTUAL",
  "physicalCurrencyItem": "minecraft:diamond",
  "startingBalance": 1000.0,
  "dailyAmount": 100.0,
  "dailySellLimit": 10000.0,
  "taxRate": 0.1,
  "pvpBalanceLossPercentage": 0.0,
  "standaloneCommands": true,
  "standaloneAdminCommands": false,
  "scoreboardEnabled": true,
  "serverShopEnabled": true
}

Field	Description
economyMode	VIRTUAL (balances in storage) or PHYSICAL (currency items).
physicalCurrencyItem	Item ID used as currency when PHYSICAL mode active.
startingBalance	Balance given to new players on first join.
dailyAmount	Free money granted via /daily (once per UTC day).
dailySellLimit	Max total sell value per player per day.
taxRate	Fraction (0.0–1.0) taxed on server shop purchases.
pvpBalanceLossPercentage	% of victim's balance dropped on PvP death.
standaloneCommands	Allow non-op players to use basic commands.
standaloneAdminCommands	Allow non-op players to use admin commands.
scoreboardEnabled	Show balance on sidebar scoreboard.
serverShopEnabled	Enable /shop GUI.

prices.json (Server Shop Items)

Defines all purchasable/sellable items, organized by category:

{
  "items": {
    "minecraft:diamond": {
      "category": "gems",
      "stack": 64,
      "unit_buy": 100.0,
      "unit_sell": 50.0
    }
  },
  "categories": {
    "gems": {
      "name": "§6Gems",
      "display_item": "minecraft:diamond"
    }
  }
}

Field	Description
category	Category key (must exist in categories).
stack	Stack size for buy/sell operations.
unit_buy	Price to buy 1 from server shop (0 = not buyable).
unit_sell	Price to sell 1 to server shop (0 = not sellable).

Tip: A massive default prices.json (671 KB, 500+ items) is bundled and auto-deployed on first run.

permissions.json (LuckPerms-Compatible)

{
  "default": [
    "viper.economy.balance",
    "viper.economy.pay",
    "viper.economy.baltop",
    "viper.economy.daily",
    "viper.economy.shop",
    "viper.economy.worth",
    "viper.economy.sell"
  ],
  "admin": [
    "viper.economy.admin.reload",
    "viper.economy.admin.give",
    "viper.economy.admin.take",
    "viper.economy.admin.set",
    "viper.economy.admin.toggle"
  ]
}

Assign viper.economy.default group to regular players, viper.economy.admin to staff.

---

💡 Usage Walkthrough

1. First Run (Auto-Setup):

• Drop the mod JAR in mods/, start server.
• config/viper-economy/config.json and prices.json are generated from bundled defaults.
• Edit config.json if you want PHYSICAL mode or different rates.
• Run /economy reload to apply changes.

2. Virtual Economy (Default):

• Players join → get startingBalance (1000).
• /shop opens GUI with 25+ categories, 500+ items.
• Buy with left-click, sell with right-click, shift-click for stacks.
• Tax (taxRate) applied automatically on purchases.

3. Chest Shops (Player-Run):

1. Place a chest.
2. Place a sign on it.
3. Line 1: [Shop] (auto-detected).
4. Line 2: B 10 (buy price) or S 5 (sell price) or B 10 S 5.
5. Line 3: Item name or ? (auto-detect from chest).
6. Line 4: Optional owner name (defaults to placer).
7. Fill chest with stock → players interact with sign to buy/sell.

4. Physical Economy (Hardcore/Roleplay):

• Set "economyMode": "PHYSICAL" in config.json.
• Set "physicalCurrencyItem": "minecraft:gold_ingot" (or custom item).
• Balances stored as items in player inventory/ender chest.
• /balance counts currency items; /pay moves items.

5. PvP Server Economy:

• Set "pvpBalanceLossPercentage": 0.05 (5% loss on death).
• Winner picks up dropped balance as currency items (physical) or gets credited (virtual).

---

⚠️ Important Notes

• Server-side only — clients need zero mods. Works with vanilla, Forge (via Fabric hybrid), or any client.
• Java 21 for 1.21.x, Java 25 for 26.x builds (enforced via java dependency in fabric.mod.json).
• Storage: Default JSON file storage in world/viper-economy/. Atomic writes, no external DB required.
• Version ranges: Built on 1.21.11 / 26.1.1 / 26.2 but declared compatible with ~1.21 / ~26.1 / ~26.2.
• /economy reload hot-reloads all configs — no restart needed for price/permission changes.
• Chest shops use Mixin injection on ServerGamePacketListenerImpl.handleUseItemOn — compatible with all 1.21.x and 26.x versions.

---

Built with Fabric Loom 1.17.x • Zero external dependencies • MIT/CC0 Licensed