kMarkets

ABOUT KMARKETS
kMarkets is the ultimate player-owned market solution built for modern Paper servers. It seamlessly bridges the gap between high-performance [Censored] listings and interactive in-world physical chest shops.

With full custom item serialization (preserving NBT, custom lore, and enchantments), an immersive sound engine, packet-level performance isolation, and a beautifully designed customizable GUI, kMarkets elevates economy mechanics to a premium level.

KEY FEATURES

Advanced [Censored]place: Interactive buy/sell orders, direct trade interfaces, and global filter settings.
Dynamic Physical Chest Shops: Bind your virtual shop directly to chest, barrel, shulker box, or ender chest containers in the world.
Stunning 3D Displays: Employs dynamic 3D floating text holograms and rotating item icons that hover above the container.
Custom NBT & Attribute Serialization: Safely sell custom weapons, enchanted armor, items from custom plugins, and special materials without losing NBT tags or attributes.
Packet-Level Glowing Favoriting: Players who favorite a shop will see a custom glowing yellow outline around the chest (configurable distance) without affecting what other players see.
Immersive Sound System: Elevate user experience with responsive high-fidelity sound cues for lists, clicks, purchases, failures, and cancellations.
Smart Icon Height Offset: Uses an origin-relative height setting (FIRST_LINE) ensuring floating icons automatically hover perfectly above descriptions, no matter how many text lines are added.
Rank-Based Shop Limits: Assign shop limits based on ranks or VIP permissions dynamically (kmarkets.limit.<number>).
Heavy Admin Protections: Cancel accidental in-world chest breaks by admins, alerting them to use the safe removal panel.
Safe Admin Deletion & Online/Offline Returns: Safe TNT delete button in Admin Mode returns items directly to the owner's inventory or stashes them offline if the player is disconnected.
Robust Storage Backends: Select between SQLite (flat-file, zero setup), MySQL (with HikariCP pooling for networks), or MongoDB (high-performance NoSQL).

COMMANDS & PERMISSIONS

Player Commands

/markets (Aliases: /market) - Opens the main player market list directory.
Permission:
Code:
```
kmarkets.use
```
(Default: true)
/market <id> - Opens a specific player's store GUI.
Permission:
Code:
```
kmarkets.use
```
(Default: true)
/orders (Aliases: /buyorders, /ordersboard) - Directly access the buy orders board.
Permission:
Code:
```
kmarkets.use
```
(Default: true)

Admin Commands
Permission required for all below:

Code:

kmarkets.admin

(Default: op)

/kmarkets admin - Opens the administrative marketplace dashboard GUI.
/kmarkets create <id> <name...> - Creates an official server-owned admin shop with infinite stock.
/kmarkets reload - Instantly reloads configuration, database cache, and re-initializes valid physical shops.
/kmarkets fix - Scans, repairs broken physical positions, and sweeps orphaned ghost displays.
/kmarkets list - Lists all registered shops in the database.
/kmarkets edit <id> - Remotely opens visual customizer settings for a specific shop.
/kmarkets open <id> / /kmarkets close <id> - Force reopens or temporarily closes and hides a shop.
/kmarkets delete <id> [return_items:true/false] - Force deletes a shop, optionally returning or stashing active sale listings.
/kmarkets version - Displays active plugin version and development details.

CONFIGURABLE PERMISSIONS
You can define exact permission nodes in config.yml for physical shop customizing actions:

Global Shift+Click Editor Access:
Code:
```
kmarkets.physical.edit
```
Change Hologram Custom Text:
Code:
```
kmarkets.physical.edit.text
```
Change Shop Icon Display:
Code:
```
kmarkets.physical.edit.icon
```
Toggle Shop Glowing State:
Code:
```
kmarkets.physical.edit.glowing
```
Select Glow Outline Colors:
Code:
```
kmarkets.physical.edit.glowcolor
```
Swap Physical Container Type:
Code:
```
kmarkets.physical.edit.container
```
Cycle Billboard Rotation Styles:
Code:
```
kmarkets.physical.edit.billboard
```
Formatting Colors in Chat Inputs:
Code:
```
kmarkets.colors
```
Rank shop limits:
Code:
```
kmarkets.limit.<number>
```
(Allows creating <number> of markets)

PLACEHOLDERS
Fully compatible with Kyori MiniMessage formatting, and parses all external placeholders when PlaceholderAPI is present.

Internal Placeholders used in Holograms and Messages:

%name% - Displays the custom formatted shop display name.
%owner% - Displays the name of the shop owner.
%id% - Displays the unique alphanumeric ID of the shop.
%price% - The decimal-formatted unit price of the items.
%stock% - The current stock size of physical chest listings.
%time_left% - The countdown timer before active listings expire.
%expiry% - The formatted date and time of listing expiration.
%limit% - The player's active shop creation limit.
%currency% - The default currency symbol configured in settings.

COMPATIBILITY & DEPENDENCIES

Requirements & Tested Environment:

Minecraft Platform: Paper API / Paper Server Software.
Tested & Supported Version: Paper API 26.1.2 (Optimal compile & target).
Java Environment: Java 21 or higher.

Supported Integrations (Soft Dependencies):

Vault: Required for economy support. Map transactions directly to Vault-compatible economy providers.
PlaceholderAPI: Integrates custom dynamic parsing inside menu names, descriptions, and system messages.

Elevate your Minecraft Server Economy with kMarkets today!

YAML:

# =================================================================================
#                     ✨ kMarkets - Premium Configuration ✨
# =================================================================================
# This is the main configuration file for kMarkets.
# All settings here can be reloaded in-game instantly using: /kmarkets reload
#
# If you make a mistake, don't worry! You can delete this file or specific keys,
# and kMarkets will automatically merge the default values back on startup.
# =================================================================================

# ---------------------------------------------------------------------------------
# 💾 DATABASE STORAGE SETTINGS
# ---------------------------------------------------------------------------------
# Choose how kMarkets saves all data (shops, listings, transactions, reviews, etc.).
# Supported types:
#   - SQLITE  : Fast, local flat-file storage. No setup required! Perfect for most servers.
#   - MYSQL   : External SQL server. Recommended for multi-lobby or BungeeCord networks.
#   - MONGODB : High-performance document-based NoSQL storage.
database:
  # The database engine you want to use. Options: SQLITE, MYSQL, MONGODB
  type: SQLITE
 
  # Configuration for MySQL (only used if type is set to MYSQL)
  mysql:
    host: localhost
    port: 3306
    database: kmarkets
    username: root
    password: password
    # Extra connection properties (HikariCP connection pool settings, encoding, SSL toggles, etc.)
    properties: "?useSSL=false&allowPublicKeyRetrieval=true&useUnicode=true&characterEncoding=UTF-8"
 
  # Configuration for MongoDB (only used if type is set to MONGODB)
  mongodb:
    uri: "mongodb://localhost:27017"
    database: kmarkets
    collection: markets

# ---------------------------------------------------------------------------------
# ⚙️ MAIN PLUGIN SETTINGS
# ---------------------------------------------------------------------------------
settings:

  # 🔊 IMMERSIVE SOUND SYSTEM
  # Enhance player interactions with high-fidelity sound cues on inventory actions.
  # Format: "SOUND_NAME, volume, pitch"
  #   - SOUND_NAME : Must be a valid Bukkit Sound enum (https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html)
  #   - volume     : Decimal value from 0.0 to 1.0 (recommended: 0.5 to 1.0)
  #   - pitch      : Decimal value from 0.5 to 2.0 (higher values = higher pitch sound)
  #
  # Tip: If you want to disable a specific sound, set its value to "NONE".
  sounds:
    # Set to false to globally silence all plugin sound effects
    enabled: true
 
    # Played whenever a player clicks an interactive button inside any custom kMarkets GUI
    menu-click: "UI_BUTTON_CLICK, 0.6, 1.0"
 
    # Played when a player opens any custom plugin inventory/chest layout
    menu-open: "BLOCK_CHEST_OPEN, 0.6, 1.2"
 
    # Played for the buyer (and the seller, if online) upon a successful transaction
    purchase-success: "ENTITY_PLAYER_LEVELUP, 1.0, 1.2"
 
    # Played for the buyer when a transaction fails (e.g., inventory full or insufficient funds)
    purchase-fail: "ENTITY_VILLAGER_NO, 1.0, 1.0"
 
    # Played when a seller successfully lists an item for sale in their shop
    item-listed: "ENTITY_EXPERIENCE_ORB_PICKUP, 0.8, 1.0"
 
    # Played when a seller withdraws an item listing back into their inventory
    item-withdrawn: "BLOCK_CHEST_CLOSE, 0.8, 1.0"
 
    # Played when a seller creates a global or item-specific discount coupon
    coupon-created: "ENTITY_ITEM_PICKUP, 0.8, 1.2"
 
    # Played when a seller removes/deletes an active discount coupon
    coupon-deleted: "BLOCK_GRASS_BREAK, 0.8, 0.8"
 
    # Played to grab attention when a player is prompted to write something in the chat
    chat-input-prompt: "BLOCK_NOTE_BLOCK_PLING, 1.0, 1.5"

  # 💬 CHAT INPUT SETTINGS
  # Keyword players can type in the chat to safely cancel any ongoing text entry prompts
  cancel-keyword: "cancel"
 
  # How long (in seconds) a player has to respond to a chat prompt before it automatically times out
  chat-input-timeout-seconds: 120

  # 🛒 SHOP LIMITS
  # The default number of personal shops a player can create if they have no explicit permission.
  # To give specific ranks or VIPs larger limits, use the permission node: kmarkets.limit.<number>
  # For example, giving a VIP group "kmarkets.limit.5" allows them to create up to 5 shops.
  default-market-limit: 1

  # 💲 ECONOMY & PRICE FORMATTING
  # Symbol to display next to monetary balances and values
  currency-symbol: "$"
 
  # The overall layout format for prices.
  # Use %symbol% for the currency symbol and %price% for the formatted decimal value.
  # Example: "%symbol%%price%" -> $1,500.00 | "%price% %symbol%" -> 1,500.00 USD
  price-format: "%symbol%%price%"
 
  # Decimal pattern used to format numbers (DecimalFormat Java standard).
  # "#,##0.00" will group thousands with commas and enforce exactly two decimal places.
  price-format-pattern: "#,##0.00"

  # ⏰ AUTOMATED ITEM EXPIRATION
  # Keeps your server economy clean by automatically removing stale listings after a set time.
  # Expired items are securely returned directly to online players, or safely stashed in their
  # offline returns chest if they are currently disconnected.
  item-expiration:
    # Set to true to enable automated expiration sweeps
    enabled: true
 
    # The default lifespan of a listing in hours before it is automatically flagged as expired (72 = 3 days)
    default-duration-hours: 72
 
    # The date/time format used to render the expiration date placeholder (%expiry%)
    date-format: "yyyy/MM/dd HH:mm"
 
    # LOCALIZATION STRINGS FOR EXPIRED ITEMS
    # These values customize the item descriptions and countdown timers.
 
    # Returned by the %time_left% placeholder if an item is set to never expire (e.g. Server Admin Shops)
    text-never: "Never"
 
    # Returned by the %time_left% placeholder if the item has already reached its expiration timestamp
    text-expired: "Expired"
 
    # Template prepended to remaining time (e.g., "Expires in 3d 12h")
    # %time% will be replaced dynamically by the formatted countdown string.
    text-expires-in: "Expires in %time%"
 
    # Individual suffixes for duration intervals
    text-days-suffix: "d"
    text-hours-suffix: "h"
    text-minutes-suffix: "m"
    text-seconds-suffix: "s"

# ---------------------------------------------------------------------------------
# 🛡️ SERVER OFFICIAL ADMIN SHIPS
# ---------------------------------------------------------------------------------
# Configurations for server-official administrative shops (/kmarkets create <id> <name>).
# Admin shops have infinite stock, don't expire, and their transactions are mapped
# to this virtual profile.
admin-shop:
  owner-uuid: "00000000-0000-0000-0000-000000000000"
  owner-name: "AdminShop"

# ---------------------------------------------------------------------------------
# 📦 PHYSICAL CHEST & BARREL SHOPS
# ---------------------------------------------------------------------------------
# Let players link virtual shops to physical chest/barrel containers in the world.
# When linked, floating 3D/2D miniature display holograms will float above the container.
physical-shops:
  # The text required in the top line of a sign to trigger shop binding.
  # Case-insensitive. Example: "[Market]"
  sign-trigger: "[Market]"

  # Configuration for floating holograms above chest shops.
  hologram:
    # 📝 TEXT HOLOGRAM SETTINGS
    # Set to false to completely disable the floating text hologram.
    text-enabled: true
 
    # Text lines displayed above the physical container. Supports multi-line lists!
    # Supports Kyori MiniMessage formatting, and placeholders:
    #   - %name%  : The display name of the shop (MiniMessage formatted).
    #   - %owner% : The username of the shop owner.
    #   - %id%    : The unique alphanumeric ID of the shop.
    text-format:
      - "<gradient:#ffae19:#ff5e62><bold>%name%</bold></gradient>"
      - "<gray>Owner: %owner%</gray>"

    # Height offset relative to the bottom center of the chest block (default: 1.1)
    text-offset: 1.1
 
    # 📦 ICON HOLOGRAM SETTINGS
    # Set to false to completely disable the floating shop icon.
    icon-enabled: true

    # Determines which icon to display above the shop container.
    #   - "DEFAULT" : Displays the shop's custom branding icon.
    #   - "MATERIAL_NAME" : Displays a fixed item/block (e.g., "CHEST", "GOLD_INGOT", "BARREL").
    icon-type: "DEFAULT"

    # Height offset relative to the bottom center of the chest block for the floating icon.
    # Set to "AUTO" to calculate it dynamically so it always floats perfectly above the text.
    # Or set to a decimal value (e.g. 1.45) to lock it to a static height.
    icon-offset: "1.7"

    # Determines where the icon height offset is measured from when text is enabled.
    #   - "FIRST_LINE" : Measures from the first (top) line of the hologram. Recommended!
    #                    This guarantees that the icon will hover perfectly above the top line,
    #                    regardless of how many lines are in the hologram.
    #   - "CENTER"     : Measures from the vertical center of the text display.
    icon-offset-origin: "FIRST_LINE"
 
    # icon-scale is the miniature scaling factor for the floating shop item (default: 0.35)
    icon-scale: 0.35

    # 🔄 ROTATION / BILLBOARD SETTINGS
    # Billboard rotation mode for both the text and the icon display.
    # Options:
    #   - FIXED      : Completely static, does not rotate (aligns perfectly with the chest's facing!).
    #   - CENTER     : Rotates fully (horizontally & vertically) to face the player.
    #   - HORIZONTAL : Rotates horizontally (left/right) to face the player.
    #   - VERTICAL   : Rotates vertically (up/down) to face the player.
    billboard: "CENTER"

  # ⚙️ PHYSICAL SHOP EDITING SETTINGS
  # Settings for in-game editing of physical chest shops (via Shift + Right-Click).
  edit-settings:
    # Set to false to completely disable the settings editing menu globally.
    enabled: true

    # Permission node required to Shift + Right-Click and open the settings editing menu.
    permission: "kmarkets.physical.edit"

    # Toggle individual options that can be configured in the editing GUI along with their distinct permission nodes:
    change-icon:
      enabled: true
      permission: "kmarkets.physical.edit.icon"

    change-text:
      enabled: true
      permission: "kmarkets.physical.edit.text"

    toggle-glowing:
      enabled: true
      permission: "kmarkets.physical.edit.glowing"

    glowing-color:
      permission: "kmarkets.physical.edit.glowcolor"

    change-container:
      enabled: true
      permission: "kmarkets.physical.edit.container"

    change-billboard:
      enabled: true
      permission: "kmarkets.physical.edit.billboard"

    # Distance configuration for chest glowing outlines (in blocks)
    glowing:
      enabled: true
      distance: 5.0

  # 🌟 FAVORITE SHOP OUTLINE GLOWING
  # If a player has a shop in their favorites, they will see a glowing outline
  # regardless of whether the owner has glowing enabled or disabled.
  favorites-glowing:
    # Set to false to disable this feature globally
    enabled: true
    # The default glowing color for favorited shops (Bukkit color string)
    color: "YELLOW"
    # Distance configuration in blocks for favorited shop glowing outline
    distance: 5.0

kMarkets v1.0.3

Overview Dependencies Updates (3) History