⚙️ INSTALLATION

1. Download the latest ItemChestShop-1.0.0-shaded.jar file
2. Place the JAR in your server's plugins/ folder
3. Restart your server
4. The plugin will automatically generate a config.yml in plugins/ItemChestShop/
5. Players can immediately start creating shops!

No configuration needed - it works out of the box!

QUICK START GUIDE

Creating Your First Shop:

1. Place a chest where you want your shop
2. Place a sign on or near the chest (within 2 blocks)
3. Write on the sign:

[SHOP]
YourUsername
Want: 1 Diamond
Give: 64 Bread

1. The sign will automatically format and validate
2. Stock your chest with bread
3. Your shop is ready!

Using Shops:

• Right-click the sign to make a purchase
• Shift + Right-click (or left-click) to view shop information
• You must have the required items to trade
• You cannot buy from your own shops

That's it! No complicated setup, no economy plugin, just simple item trading.

FLEXIBLE SHOP FORMATS

One of the most powerful features - the plugin understands MANY different ways to write the same trade!

All These Formats Work for the Same Trade (64 Bread ↔ 1 Diamond):

Want: 1 Diamond Want: Diamond 1 Want: 1 dia
Give: 64 Bread Give: Bread x64 Give: 64x bread

Want: 1*Diamond Want: Diamond*1 Want: DIAMOND
Give: Bread 64 Give: 64*Bread Give: bread x64

Want: 1 x Diamond Want: Diamond * 1 Want: dia 1
Give: 64 x Bread Give: Bread*64 Give: bread 64
Supported Input Patterns:

• Space-separated: 1 Diamond or Diamond 1
• X-notation: 64x Bread or Bread x64
• Asterisk notation: 5*Iron or Iron*5
• No amount: Diamond (defaults to 1)
• Case insensitive: diamond, DIAMOND, Diamond
• Flexible spacing: Extra spaces are ignored
• Multi-word items: Oak Log, Iron Ingot, Cooked Beef

Mix and Match:

You can use different formats on each line:

[SHOP]
PlayerName
Want: Diamond 1
Give: 64x Bread
SUPPORTED ITEMS

✅ ALL Minecraft Items Supported

The plugin recognizes every vanilla Minecraft item with intelligent parsing:

Full Material Support:

• Blocks: Stone, Cobblestone, Oak_Log, Diamond_Block, Glass, Sand
• Items: Diamond, Iron_Ingot, Stick, String, Leather, Paper
• Ores: Iron_Ore, Gold_Ore, Diamond_Ore, Emerald_Ore, Coal_Ore
• Tools: Diamond_Sword, Iron_Pickaxe, Golden_Axe, Bow, Fishing_Rod
• Weapons: Sword, Bow, Crossbow, Trident, Arrow
• Food: Bread, Apple, Cooked_Beef, Golden_Apple, Cake
• Rails: Rail, Powered_Rail, Detector_Rail, Activator_Rail
• Redstone: Redstone, Repeater, Comparator, Piston, Dispenser

Smart Name Recognition:

The plugin is incredibly flexible with item names:

Exact Names (All Work):

• DIAMOND_SWORD (uppercase)
• diamond_sword (lowercase)
• Diamond Sword (spaces)
• Diamond_Sword (underscores)

Common Aliases (200+ Built-in):

• Wood → Oak_Log
• Stone → Cobblestone
• Iron → Iron_Ingot
• Gold → Gold_Ingot
• Dia → Diamond
• Eme → Emerald
• Cobble → Cobblestone
• Pearl → Ender_Pearl

Partial Matching:

• Diamond finds Diamond
• Dia matches Diamond
• Eme matches Emerald
• Rail finds Rail
• Cart finds Minecart
• Pick matches Iron_Pickaxe
• Sword matches Iron_Sword

Auto-Completion:

• Iron → Iron_Ingot
• Gold → Gold_Ingot
• Oak → Oak_Log
• Cooked → Cooked_Beef

ULTRA-FLEXIBLE FORMATTING

Multiple Amount Formats:

Every format style works:

• 1 Diamond (space before)
• Diamond 1 (space after)
• 64x Bread (x before amount)
• Bread x64 (x after item)
• 5*Iron_Ingot (asterisk before)
• Iron_Ingot*5 (asterisk after)
• 32 Oak Log (multi-word items)
• Oak Log 32 (reversed)
• Diamond (no amount = 1)

Case & Spacing Flexibility:

• Case insensitive: diamond, DIAMOND, Diamond, DiAmOnD
• Space variations: Oak Log, Oak_Log, OakLog, OAKLOG
• Extra spaces ignored: 1 Diamond works fine
• Underscores optional: Iron_Ingot = Iron Ingot

Common Abbreviations Work:

• Dia → Diamond
• Eme → Emerald
• Cobble → Cobblestone
• Pick → Iron_Pickaxe
• Sword → Iron_Sword
• Cart → Minecart
• Pearl → Ender_Pearl
• Wood → Oak_Log

COMMANDS

All basic commands are available to players with the itemchestshop.use permission (default: everyone).

Player Commands:

/itemchestshop help - Display all available commands and usage /itemchestshop info - Show plugin version and information /itemchestshop stats - View your personal shop statistics /itemchestshop list [page] - Browse all shops on the server /itemchestshop find <item> - Search for shops selling a specific item

Admin Commands:

/itemchestshop reload - Reload the plugin configuration

Command Examples:

/itemchestshop find Diamond
Lists all shops selling diamonds

/itemchestshop list 2
Shows page 2 of all active shops

/itemchestshop stats
Shows your trading statistics

/itemchestshop help
Displays command help
Command Aliases:

You can use /ics as a shortcut:

/ics help
/ics find Iron
/ics stats
/ics list
PERMISSIONS

&]dd:bg-bg-500/10">Permission Description Default
&] dd:bg-bg-500/10">itemchestshop.create Allow creating chest shops Everyone
&] dd:bg-bg-500/10">itemchestshop.use Allow using chest shops and commands Everyone
&] dd:bg-bg-500/10">itemchestshop.admin Allow admin commands and breaking others' shops OP only

Setting Up Permissions:

For LuckPerms:

/lp group default permission set itemchestshop.create true
/lp group default permission set itemchestshop.use true
/lp group admin permission set itemchestshop.admin true
For PermissionsEx:

/pex group default add itemchestshop.create
/pex group default add itemchestshop.use
/pex group admin add itemchestshop.admin
SHOP EXAMPLES

Example 1: Basic Food Shop

[SHOP]
PlayerName
Want: 5 Iron
Give: 64 Bread
Trade 5 Iron Ingots for 64 Bread

Example 2: Using Abbreviations

[SHOP]
Steve
Want: 1 dia
Give: 32x cobble
Trade 1 Diamond for 32 Cobblestone

Example 3: Mixed Formats

[SHOP]
Alex
Want: Emerald * 2
Give: Oak Log 128
Trade 2 Emeralds for 128 Oak Logs

Example 4: Tool Trading

[SHOP]
Miner
Want: 10 Diamond
Give: 1 Diamond_Pickaxe
Trade 10 Diamonds for 1 Diamond Pickaxe (enchant it for premium value!)

Example 5: Using Aliases

[SHOP]
Farmer
Want: 16 wheat
Give: 8x bread
Convert raw wheat to processed bread

Example 6: High-Value Rare Items

[SHOP]
Blacksmith
Want: 64 dia
Give: Netherite_Ingot
Premium shop for rare materials

HOW IT WORKS

Shop Creation Process:

1. Player places sign on/near chest with format: [SHOP], username, Want:, Give:
2. Plugin parses item names using intelligent matching (checks aliases, partial names, case variations)
3. Plugin validates amounts and ensures items exist
4. Sign is automatically formatted with colors
5. Shop is registered in database with owner information
6. Shop is ready to use!

Transaction Process:

1. Buyer right-clicks shop sign
2. Plugin checks buyer has required "Want" items in inventory
3. Plugin checks shop chest has "Give" items in stock
4. Plugin verifies buyer has inventory space for items
5. Items are safely exchanged between inventories
6. Shop owner is notified of the sale
7. Transaction is logged for statistics

Safety Features:

• Transaction rollback if any step fails
• Automatic validation before any changes
• Permission checks before modifications
• Stock verification
• Inventory space verification
• Prevents item loss or duplication

Intelligent Parsing:

The plugin uses advanced parsing to understand many formats:

• Tries exact material name match first
• Falls back to alias lookup (200+ aliases)
• Checks partial name matches
• Case-insensitive throughout
• Handles spaces, underscores, and special characters
• Supports amount-first or amount-last formats
• Recognizes x-notation and asterisk notation

⚙️ CONFIGURATION

The plugin creates a config.yml file with customizable options:

yaml
# Maximum shops per player (0 = unlimited)
max_shops_per_player: 10

# Enable debug logging
debug: false

# Message customization
messages:
prefix: "&8[&6ItemChestShop&8]&r "
shop_created: "&aShop created successfully!"
shop_removed: "&cShop removed!"
transaction_success: "&aTransaction complete!"
insufficient_stock: "&cThis shop is out of stock!"
insufficient_funds: "&cYou don't have enough items!"
no_space: "&cNot enough inventory space!"
cannot_buy_own: "&cYou cannot buy from your own shop!"

# Item aliases (add custom shortcuts)
item_aliases:
wood: oak_log
gold: gold_ingot
iron: iron_ingot
dia: diamond
eme: emerald
cobble: cobblestone
Configuration Options:

• max_shops_per_player - Limit shops per player (0 = unlimited)
• debug - Enable detailed console logging
• messages - Customize all player messages
• item_aliases - Add custom item name shortcuts
• Color codes: &a green, &c red, &e yellow, &6 gold

CONFIGURATION TIPS

Limiting Shops Per Player:

yaml
max_shops_per_player: 5
Custom Server Messages:

yaml
messages:
prefix: "&8[&b&lMarket&8]&r "
shop_created: "&a&l✓ &aShop opened!"
transaction_success: "&a&l✓ &aTrade complete!"
Adding Custom Aliases:

yaml
item_aliases:
log: oak_log
plank: oak_planks
pick: diamond_pickaxe
sword: diamond_sword
cart: minecart
Debug Mode for Troubleshooting:

yaml
debug: true
Shows detailed parsing and transaction logs in console.

TROUBLESHOOTING

Shop Not Creating:

• Verify sign format: Line 1 must be [SHOP]
• Check Lines 2-4 have username, Want:, and Give:
• Ensure item names are valid (try abbreviations like dia for diamond)
• Confirm chest is within 2 blocks of sign
• Check player has itemchestshop.create permission

Items Not Recognized:

• Try common aliases: dia, eme, wood, iron, gold
• Use partial names: Diamond works, Dia works, D might not
• Check spelling (case doesn't matter)
• Enable debug mode to see parsing attempts
• Use underscores for multi-word: Oak_Log or Oak Log

Transaction Failing:

• Ensure shop chest has items in stock
• Verify buyer has required payment items
• Check buyer has inventory space
• Make sure chest isn't full (for receiving payment)
• Review console for specific error messages

"No Permission" Errors:

• Verify itemchestshop.use permission is set
• Try giving player OP temporarily to test
• Check permission plugin is loaded
• Reload permissions: /lp reloadconfig or similar

Signs Not Formatting:

• Ensure first line is exactly [SHOP]
• Check Want: and Give: have colons
• Try different item name formats
• Enable debug mode to see parsing errors

DEBUG MODE

Enable detailed logging for troubleshooting:

yaml
debug: true
Debug Output Shows:

• Sign creation attempts and validation
• Item name parsing (tried names, aliases, matches)
• Amount parsing (formats tested)
• Transaction steps and outcomes
• Permission checks
• Stock verification
• Inventory calculations
• Error messages with details

Using Debug Mode:

1. Enable in config.yml
2. Run /itemchestshop reload
3. Try creating a shop
4. Check console for detailed logs
5. Share logs when asking for support

ADVANCED FEATURES

Flexible Amount Parsing:

The plugin accepts amounts in many formats:

• 64 (number only)
• x64 (x-prefix)
• 64x (x-suffix)
• *64 (asterisk-prefix)
• 64* (asterisk-suffix)
• No amount (defaults to 1)

Smart Item Matching:

Priority order for item recognition:

1. Exact material name match (e.g., DIAMOND)
2. Alias lookup (e.g., dia → DIAMOND)
3. Partial name match (e.g., Diam → DIAMOND)
4. Case-insensitive comparison throughout

Shop Discovery:

/itemchestshop find Diamond
Returns all shops selling diamonds with prices and owner names

Statistics Tracking:

/itemchestshop stats
Shows your:

• Total shops owned
• Total sales made
• Total purchases
• Most traded items

️ TECHNICAL DETAILS

Built With:

• Paper API 1.21.4 - Core server framework
• Adventure API - Modern text components (bundled with Paper)
• Gson 2.10.1 - JSON data storage
• Maven - Build automation

Architecture:

• Command system with subcommand routing
• Event-driven shop interaction (sign events, inventory events)
• JSON-based persistent data storage
• Transaction rollback support for safety
• Full Bukkit permission integration
• Intelligent item parsing with multiple fallback strategies

Performance:

• Lightweight event handling (only active when signs are placed/used)
• Efficient shop lookup system
• Minimal memory footprint
• No database required (JSON files)
• Fast item name parsing with caching

Recent Updates:

• ✅ Modernized to Adventure API (no deprecated methods)
• ✅ Enhanced item parsing with 200+ aliases
• ✅ Flexible format support (10+ input patterns)
• ✅ Improved error handling and validation
• ✅ Future-proof for Paper updates
• ✅ Shaded JAR with all dependencies included

SUPPORT

Having issues? Follow these steps:

1. Check the troubleshooting section above
2. Try using item aliases: dia, eme, wood, iron
3. Enable debug mode in config.yml for detailed logs
4. Verify you're running Paper 1.21.4 with Java 17+
5. Check console logs for specific error messages
6. Test with OP permissions first

Common Conflicts:

• Other chest shop plugins (uninstall competing plugins)
• Protection plugins blocking sign placement (add shop regions)
• Economy plugins (not needed, can cause conflicts)