NPCShopHPX Documentation
Overview
NPCShopHPX is a Hypixel-style NPC shop plugin for Minecraft servers. It offers a flexible and user-friendly trading system that allows players to easily buy and sell items via interactive NPC menus. With enhanced dynamic lore updates, quantity selection, and a built-in buyback system, NPCShopHPX creates an immersive trading experience on your server.

Features

• Buy & Sell Items:
  Trade items seamlessly with NPCs using clickable shop menus.
  
  
• Built-in Buyback System:
  Players can quickly repurchase up to the 10 most recently sold items.
  
  
• Dynamic Quantity Selection:
  Choose the desired quantity when purchasing items via a dedicated quantity menu.
  
  
• Configurable Prices:
  Set individual buy/sell prices for each item or per NPC directly through the config.yml file.
  
  
• Multi-Language Support:
  NPCShopHPX comes with a default English language file and supports adding new language files.
  
  
• Vault Economy Integration:
  Compatible with Vault-based economy plugins to manage transactions.
  
  
• Citizens NPC Integration:
  Create interactive, clickable NPC shops using the popular Citizens plugin.
  
  
• Enhanced Lore Updates:
  Fast, dynamic lore updates ensure that item names, quantities, and colors are updated in real time across different menus.

Requirements

• Server Version: Compatible with Minecraft versions that support Spigot/Bukkit.
• Dependencies:
  • Vault: Required for economy integration.
  • Citizens: Required for NPC creation and management.
  • Vault-compatible Economy Plugin: (e.g., EssentialsX)
• Java: Ensure your server is running an appropriate version of Java that supports your server’s Bukkit/Spigot version.

Installation Guide

1. Download the Plugin:
   Place the NPCShopHPX-1.0-SNAPSHOT.jar file in your server’s /plugins folder.
   
   
2. Install Required Plugins:
   Ensure that Vault, Citizens, and a compatible economy plugin (such as EssentialsX) are installed on your server.
   
   
3. Start or Restart Your Server:
   Launch your server or restart it to load NPCShopHPX.
   
   
4. Configure the Plugin:
   • Open the generated config.yml file in the /plugins/NPCShopHPX folder.
   • Customize NPC IDs, items, and their buy/sell prices.
   • Important: Item names must be written in ALL CAPITAL LETTERS (e.g., DIAMOND, IRON_INGOT) to preserve their design properties.
5. Reload the Plugin:
   Run the command /reloadnpcshop in-game or restart your server to apply the configuration changes.

Configuration
The config.yml file contains all the settings required to customize NPCShopHPX. Below is an explanation of the main sections:

# Config version and updates
language: "en" # Sets the language used by the plugin. Default is English.

# NPC Shop configuration
enabled-npcs: [0, 1] # Define the NPC IDs that are active.

#
# ITEM NAMES:
# Use names that match the Spigot/Bukkit Material names.
# For example: DIAMOND, EMERALD, IRON_INGOT, etc.
# IMPORTANT: Item names must be in ALL CAPITAL LETTERS.
#

# NPC configuration:
npcs:
0: # NPC ID 0
items:
DIAMOND:
buy: 1000 # Buy price for a diamond
EMERALD:
buy: 800 # Buy price for an emerald
1: # NPC ID 1
items:
IRON_INGOT:
buy: 50 # Buy price for an iron ingot
GOLD_INGOT:
buy: 100 # Buy price for a gold ingot

# Prices for selling items:
prices:
DIAMOND:
sell: 100 # Selling price for a diamond
GOLD_INGOT:
sell: 50 # Selling price for a gold ingot
IRON_INGOT:
sell: 25 # Selling price for an iron ingot

Commands & Permissions
Commands

• /reloadnpcshop
  Reloads the NPCShopHPX plugin configuration.
  Usage:
  bash
  /reloadnpcshop

Permissions

• npcshop.reload
  Allows a user to reload the NPCShopHPX plugin via the /reloadnpcshop command.

How It Works

1. Shop Menu Interaction:
   When a player interacts with an NPC, the shop menu opens displaying available items based on the configured NPC data.
   • Each item shows its name, cost, stock information, and sale options.
   • The plugin saves the original item meta (lore and display names) to enable smooth transitions between different menus (e.g., quantity selection and page changes).
2. Quantity Selection:
   Players can right-click on an item to open a quantity selection menu, which allows them to choose the exact number of items they wish to purchase.
   • The quantity menu updates the lore to reflect the selected quantity.
   • Returning from the quantity selection restores the original lore for consistency.
3. Buyback System:
   After selling items, players can repurchase their most recently sold items via the built-in buyback system.
   • A dedicated slot shows the last sold item for quick repurchase.
4. Dynamic Lore Updates:
   When navigating between shop pages or returning from the quantity menu, the plugin restores and updates the item lore dynamically to reflect the current item count and pricing details.

Troubleshooting

• Items Not Displaying Correctly:
  Ensure that all item names in the config file are in all capital letters and match the Material names exactly.
  
  
• Plugin Not Reloading:
  Verify that you are using the correct command /reloadnpcshop and that you have the proper permissions (npcshop.reload).
  
  
• Economy or NPC Issues:
  Make sure that Vault, Citizens, and your economy plugin are installed and up to date. Check your server logs for any dependency-related errors.

Future Updates
Upcoming updates to NPCShopHPX include:

• Faster and more dynamic lore updates for shop menus.
• Enhanced color and design customization for item lore.
• Further improvements to quantity menu interactions and visual clarity.