💰 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

🛠️ 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

🎮 Commands & Permissions

⚙️ 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
}

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

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