GroupeZ Docs
Configuration

Main Configuration

Main configuration options for zAuctionHouse V4

The main configuration file config.yml controls the core behavior of zAuctionHouse V4.

Debug & Monitoring

# Enables detailed logs and error messages in the console
enable-debug: false

# Enables performance monitoring and logging
# Logs execution times for heavy operations
enable-performance-debug: false

# Enables automatic version checking
enable-version-checker: true

# Performance debug filter configuration
performance-debug:
  filter:
    # Filter mode: DISABLED, WHITELIST, BLACKLIST
    mode: DISABLED
    # List of operations to filter (supports wildcards)
    operations:
      - "loadItems.*"
      - "SortedItemsCache.*"

Performance Operations

Available operation names for filtering:

OperationDescription
loadItems.loadPlayersTime to load player data
loadItems.loadItemsFromDBTime to load items from database
loadItems.processItemsTime to process loaded items
loadItems.totalTotal loading time
loadItems.rebuildSortedItemsCacheTime to rebuild sorted cache
SortedItemsCache.rebuildTime to rebuild the sorted items cache
applyCategoriesTime to apply category filters
computeCategoryCount[categoryId]Time to count items per category
openInventory.<file name>Time to open a specific inventory

General Settings

# Date format for timestamps (Java SimpleDateFormat)
# Examples:
#   "dd/MM/yyyy HH:mm:ss" -> "25/12/2024 14:30:45"
#   "MM-dd-yyyy hh:mm a"  -> "12-25-2024 02:30 PM"
date-format: dd/MM/yyyy HH:mm:ss

# Timezone used for displaying dates.
# Set to "auto" to use the server's default timezone.
# Examples: "UTC", "Europe/Paris", "America/New_York", "Asia/Tokyo"
timezone: auto
ValueDescription
autoUses the server's default timezone (default)
UTCCoordinated Universal Time
Europe/ParisCentral European Time (UTC+1/UTC+2)
America/New_YorkEastern Time (UTC-5/UTC-4)
Asia/TokyoJapan Standard Time (UTC+9)

You can use any valid Java TimeZone ID. This setting affects all server-formatted date placeholders: %date%, %formatted-expire-date%, etc. (The Discord webhook %expires_at% placeholder is not affected, as it now uses a Discord dynamic timestamp rendered in each viewer's own local timezone.)

Database Configuration

# Storage type: SQLITE, MYSQL, MARIADB
storage-type: SQLITE

# Server name for multi-server setups
server-name: skyblock

# Database connection settings (MySQL/MariaDB only)
database-configuration:
  table-prefix: zauctionhouse_
  host: 192.168.10.10
  port: 3306
  user: homestead
  password: secret
  database: zauctionhouse
  debug: false
  # Maximum lifetime of a pooled connection, in seconds (default: 1800)
  max-lifetime: 1800

Connection Lifetime

max-lifetime sets how long a MySQL/MariaDB connection stays in the pool before it is retired and replaced. Lower it when your database or a proxy in front of it (firewall, load balancer) closes idle connections sooner than 30 minutes, which shows up as broken-connection errors in the console.

ValueEffect
180030 minutes, same as when the option is missing
0Connections are kept until the pool closes
Less than 30Refused by HikariCP, which falls back to 30 minutes

Keep it a few minutes below the database wait_timeout. The option has no effect with SQLITE. It can also be set in the shared database-configuration.yml file at the server root.

Storage Types

TypeDescriptionBest For
SQLITELocal file-based databaseSingle server, no setup required
MYSQLMySQL database serverMulti-server, large auction houses
MARIADBMariaDB database serverMulti-server, large auction houses

For multi-server synchronization, use MySQL/MariaDB with the Redis addon.

Message Colors

Define custom color shortcuts for use in messages:

message-colors:
  - key: <primary>
    color: '#24d65d'
  - key: <secondary>
    color: '#656665'
  - key: <error>
    color: '#ff0000'
  - key: <success>
    color: '#00ff00'

Use these in any message: <primary>Welcome <secondary>to the auction house!

Command Configuration

A server restart is required after changing command settings!

commands:
  main-command:
    aliases:
      - ah
      - hdv
      - auction
      - zauction

  sell:
    # Open GUI when running /ah sell without arguments
    enable-sell-inventory: false
    aliases:
      - sell
      - s
      - vendre
    arguments:
      - name: price
        display-name: price
        required: true
        auto-completion:
          - 1000
          - 10000
          - 25000
      - name: amount
        display-name: amount
        required: false
        auto-completion:
          - '1'
          - '%max-stack-size%'
      - name: economy
        display-name: economy
        required: false
        auto-completion:
          - vault

  claim:
    aliases:
      - claim
      - c
      - recuperer

  page:
    aliases:
      - page
      - p

Custom Inventory Commands

Create shortcuts to specific inventories:

  inventories:
    - enable: true
      permission: "zauctionhouse.selling"
      description: "Open selling items"
      aliases:
        - 'selling'
      inventory: SELLING_ITEMS

    - enable: true
      permission: "zauctionhouse.expired"
      description: "Open expired items"
      aliases:
        - 'expired'
      inventory: EXPIRED_ITEMS

    - enable: true
      permission: "zauctionhouse.purchased"
      description: "Open purchased items"
      aliases:
        - 'purchased'
      inventory: PURCHASED_ITEMS

    - enable: true
      permission: "zauctionhouse.history"
      description: "Open history"
      aliases:
        - 'history'
      inventory: HISTORY

Price Shortcuts

Allow players to use shorthand notation for large prices:

number-sell-multiplication:
  enable: true
  formats:
    - format: K
      multiplication: 1000
    - format: M
      multiplication: 1000000
    - format: B
      multiplication: 1000000000
    - format: T
      multiplication: 1000000000000
    # ... continues to TR (Tredecillion)

Examples:

  • /ah sell 1K = 1,000
  • /ah sell 2.5M = 2,500,000
  • /ah sell 1B = 1,000,000,000

Decimal Prices

Control whether players can list items for a price that contains decimals (e.g. 10.5):

# Set to false to force whole-number prices only.
allow-decimal-prices: true

When set to false, any listing whose final price has a fractional part is rejected on every sell path (the /ah sell command and the sell inventory), and the player is shown the price-decimal-not-allowed message. Price shortcuts that resolve to a whole number are still allowed (e.g. 2.5K = 2500). Default: true.

Expiration Settings

All times are in seconds.

expiration:
  # Auction listings
  auction:
    default-expiration: 172800  # 2 days
    permission:
      enable: false
      permissions:
        - permission: zauctionhouse.expiration.vip
          expiration: 3600       # 1 hour
        - permission: zauctionhouse.expiration.elite
          expiration: 7200       # 2 hours
        - permission: zauctionhouse.expiration.legend
          expiration: 259200     # 3 days

  # Bid listings (future feature)
  bid:
    default-expiration: 172800

  # Rent listings (future feature)
  rent:
    default-expiration: 172800

  # Expired items cleanup
  expire:
    default-expiration: 604800   # 1 week

  # Purchased items cleanup
  purchase:
    default-expiration: 604800   # 1 week

Common Time Values

TimeSeconds
1 hour3600
1 day86400
2 days172800
3 days259200
1 week604800
30 days2592000

Item Limits

Configure how many items players can list:

permissions:
  auction:
    - permission: zauctionhouse.max.5
      limit: 5
    - permission: zauctionhouse.max.10
      limit: 10
    - permission: zauctionhouse.max.15
      limit: 15

  rent:
    - permission: zauctionhouse.max.5
      limit: 5
    # ...

  bid:
    - permission: zauctionhouse.max.5
      limit: 5
    # ...

World Restrictions

Prevent listing items in specific worlds (players can still browse/buy):

banned-worlds:
  auction:
    - "world_the_end"
  rent:
    - "world_the_end"
  bid:
    - "world_the_end"

Item Display Lore

Customize the lore added to items in the auction house:

item-lore:
  # Forces the displayed item amount to 1 in the auction inventory.
  # The real amount is preserved internally and given to the buyer on purchase.
  # Useful to keep a clean, uniform display.
  force-amount-one: false

  # Items in main auction listing
  listed-auction-item:
    - ""
    - "<white>⌂ #92ffffSeller#8c8c8c: #2CCED2%seller%"
    - "<white>☆ #92ffffPrice#8c8c8c: #2CCED2%price%"
    - "<white>⌚ #92ffffExpire#8c8c8c: #969696%time-remaining%"
    - ""
    - "%status%"

  # Bulk sales (multiple items)
  multiple-listed-auction-item:
    - ""
    - "<white>⌂ #92ffffSeller#8c8c8c: #2CCED2%seller%"
    - "<white>☆ #92ffffPrice#8c8c8c: #2CCED2%price%"
    - "<white>⌚ #92ffffExpire#8c8c8c: #969696%time-remaining%"
    - ""
    - "#8c8c8c• #2CCED2ʟᴇғᴛ ᴄʟɪᴄᴋ #92ffffᴛᴏ sᴇᴇ ᴛʜᴇ ᴄᴏɴᴛᴇɴᴛ"
    - "%status%"

  # Expired items
  expired-item:
    - ""
    - "<white>⌚ #92ffffExpire#8c8c8c: #969696%time-remaining%"
    - ""
    - "#8c8c8c• #2CCED2Click to retrieve this item"

  # Purchased items
  purchased-item:
    - ""
    - "<white>⌚ #92ffffExpire#8c8c8c: #969696%time-remaining%"
    - ""
    - "#8c8c8c• #2CCED2Click to retrieve this item"

  # Your items on sale
  selling-item:
    - ""
    - "<white>⌚ #92ffffExpire#8c8c8c: #969696%time-remaining%"
    - ""
    - "#8c8c8c• #2CCED2Click to retrieve this item"

  # Item being purchased
  being-purchased-item:
    - ""
    - "<white>⌚ #92ffffExpire#8c8c8c: #969696%time-remaining%"
    - ""
    - "#8c8c8c• #ff3535Your item is being purchased, you cannot retrieve it."

  # History items
  history-item:
    - ""
    - "<white>⌂ #92ffffBuyer#8c8c8c: #2CCED2%buyer%"
    - "<white>☆ #92ffffPrice#8c8c8c: #2CCED2%price%"
    - "<white>⌚ #92ffffDate#8c8c8c: #969696%date%"

  # Dynamic status messages
  status:
    seller: "#8c8c8c• #2CCED2ᴄʟɪᴄᴋ #92ffffᴛᴏ ʀᴇᴛʀɪᴇᴠᴇ ᴛʜɪs ɪᴛᴇᴍ"
    buyer: "#8c8c8c• #2CCED2ᴄʟɪᴄᴋ #92ffffᴛᴏ ʙᴜʏ ᴛʜɪs ɪᴛᴇᴍ"
    right-seller: "#8c8c8c• #2CCED2ʀɪɢʜᴛ ᴄʟɪᴄᴋ #92ffffᴛᴏ ʀᴇᴛʀɪᴇᴠᴇ ᴛʜɪs ɪᴛᴇᴍ"
    right-buyer: "#8c8c8c• #2CCED2ʀɪɢʜᴛ ᴄʟɪᴄᴋ #92ffffᴛᴏ ʙᴜʏ ᴛʜɪs ɪᴛᴇᴍ"

  # Log type names
  log-type-names:
    SALE: "Item Listed"
    PURCHASE: "Item Purchased"
    REMOVE_LISTED: "Removed from Listing"
    REMOVE_SELLING: "Retrieved Selling Item"
    REMOVE_EXPIRED: "Retrieved Expired"
    REMOVE_PURCHASED: "Retrieved Purchase"

Available Placeholders

PlaceholderDescription
%seller%Seller's name
%buyer%Buyer's name
%price%Formatted price
%price-price-raw%Raw price value
%price-price-with-decimal-format%Price with decimal formatting (e.g. 10 000)
%price-price-with-reduction%Price with reduction (e.g. 10.0k)
%time-remaining%Time until expiration
%formatted-expire-date%Formatted expiration date
%date%Transaction date
%status%Dynamic action message
%item_count%Total item count in the listing
%economy-name%Economy internal name
%economy-display-name%Economy display name
%items%Item display names
%type%Log entry type
%player%Player involved
%target%Target player (admin)

Performance

Only the placeholders actually used in your lore templates are computed at render time. The plugin pre-detects which placeholders each lore section references when the configuration is loaded. If your expired-item lore only uses %time-remaining%, the plugin won't waste resources computing %price%, %seller%, etc.

Time Format

Configure how time is displayed:

time:
  second: second
  seconds: seconds
  minute: minute
  minutes: minutes
  hour: hour
  hours: hours
  day: day
  days: days

  # Format strings (printf-style)
  time-day: '%02dᴅ %02dʜ %02dᴍ'      # >= 1 day
  time-hour: '%02dʜ %02dᴍ %02ds'     # >= 1 hour
  time-minute: '%02dᴍ %02ds'          # >= 1 minute
  time-second: '%02ds'                # < 1 minute

Action Behavior

action:
  # Auto-refresh inventory after actions
  update-inventory-on-action: true

  # Reset category filter when reopening the auction house
  reset-category-on-open: true

  # Reset search filter when reopening the auction house
  reset-search-on-open: true

  # Removing items from listings
  remove-listed-item:
    give-item: false           # Give to inventory or expired items
    open-inventory: true       # Reopen inventory after
    open-confirm-inventory: true  # Show confirmation

  # Removing expired items
  remove-expired-item:
    open-inventory: true
    player-inventory-must-have-free-space: true

  # Purchasing items
  purchased-item:
    give-item: false           # Give to inventory or purchased items
    # Only used with give-item: true.
    # true: the purchase is refused when the item does not fit in the inventory.
    # false: the purchase goes through and the item is sent to purchased items
    #        (message purchase-inventory-full) when it does not fit.
    player-inventory-must-have-free-space: true
    open-inventory: true
    money-item:
      enable: true
      duration: 60             # Ticks to show error
      item:
        material: BARRIER
        name: "#ff3535✘ You don't have enough money to buy this!"
    money-message: true
    money-sound:
      enable: true
      category: MASTER
      sound: minecraft:entity.villager.no
      volume: 1
      pitch: 1

  # Removing selling items
  selling-item:
    open-inventory: true
    player-inventory-must-have-free-space: true

Auto-Claim Configuration

auto-claim:
  # Auto-deposit pending money on join
  enable: false
  delay-ticks: 20              # Wait before claiming
  notify-player: true          # Message on auto-claim
  notify-pending: true         # Notify about pending money
  notify-delay-ticks: 40
  deposit-reason: "Claimed pending auction money"

Sales Notification

sales-notification:
  # Notify about offline sales on join
  enable: true
  delay-ticks: 60

Broadcast

Send messages to all online players when items are listed or purchased. Players can individually opt out using /ah option.

broadcast:
  sell:
    # If true, a message is sent to all online players when an item is listed
    enable: false

    # If true, the seller will not see the broadcast message
    exclude-seller: true

  purchase:
    # If true, a message is sent to all online players when an item is purchased
    enable: false

    # If true, the buyer will not see the broadcast message
    exclude-buyer: true

  # Per-category message overrides (MiniMessage format).
  # If an item belongs to a category listed here, the custom message is used
  # instead of the default broadcast message from messages.yml.
  # The category key must match a category ID defined in categories.yml.
  # Available placeholders: %seller%, %buyer%, %items%, %price%, %category%
  category-messages:
    sell: {}
    purchase: {}

Category Message Overrides

You can define custom broadcast messages for specific categories. When an item belongs to a configured category, the custom message is used instead of the default one from messages.yml.

broadcast:
  category-messages:
    sell:
      weapons: "<red><bold>WEAPON</bold></red> <white>%seller% <yellow>listed %items% <yellow>for <gold>%price%<yellow>!"
      armor: "<blue><bold>ARMOR</bold></blue> <white>%seller% <yellow>listed %items% <yellow>for <gold>%price%<yellow>!"
      enchanted-books: "<light_purple><bold>ENCHANT</bold></light_purple> <white>%seller% <yellow>listed %items% <yellow>for <gold>%price%<yellow>!"
    purchase:
      weapons: "<red><bold>WEAPON</bold></red> <white>%buyer% <yellow>purchased %items% <yellow>from <white>%seller% <yellow>for <gold>%price%<yellow>!"
      armor: "<blue><bold>ARMOR</bold></blue> <white>%buyer% <yellow>purchased %items% <yellow>from <white>%seller% <yellow>for <gold>%price%<yellow>!"
      enchanted-books: "<light_purple><bold>ENCHANT</bold></light_purple> <white>%buyer% <yellow>purchased %items% <yellow>from <white>%seller% <yellow>for <gold>%price%<yellow>!"

Category keys must match the IDs defined in categories.yml (e.g., weapons, armor, blocks, enchanted-books, misc).

Broadcast Placeholders

PlaceholderDescriptionAvailable In
%seller%Name of the sellerSell & Purchase
%buyer%Name of the buyerPurchase only
%items%Item display nameSell & Purchase
%price%Formatted priceSell & Purchase
%category%Category nameSell & Purchase

Sorting Configuration

sort-items:
  # Default sort: ASCENDING_PRICE, ASCENDING_DATE, DECREASING_DATE, DECREASING_PRICE
  default-sort: DECREASING_DATE

  # Display names for sort types
  translations:
    ASCENDING_PRICE: "ᴀsᴄᴇɴᴅɪɴɢ ᴘʀɪᴄᴇ"
    ASCENDING_DATE: "ᴀsᴄᴇɴᴅɪɴɢ ᴅᴀᴛᴇ"
    DECREASING_DATE: "ᴅᴇᴄʀᴇᴀsɪɴɢ ᴅᴀᴛᴇ"
    DECREASING_PRICE: "ᴅᴇᴄʀᴇᴀsɪɴɢ ᴘʀɪᴄᴇ"

Migration Settings

Migrate data from zAuctionHouse V3:

migration:
  zauctionhouse-v3:
    source-type: SQLITE        # MYSQL, MARIADB, SQLITE, or JSON
    table-prefix: "zauctionhouse_"
    sqlite-path: "plugins/zAuctionHousev3/database.db"

    # MySQL/MariaDB settings
    host: "localhost"
    port: 3306
    database: "zauctionhouse"
    user: "root"
    password: ""

    # JSON settings
    json-folder: "plugins/zAuctionHouseV3"

To migrate, run:

/ah admin migrate zauctionhousev3 confirm

Migration

How to migrate data from other auction plugins to zAuctionHouse V4

Messages

Customize all messages in zAuctionHouse V4

On this page

Debug & MonitoringPerformance OperationsGeneral SettingsDatabase ConfigurationConnection LifetimeStorage TypesMessage ColorsCommand ConfigurationCustom Inventory CommandsPrice ShortcutsDecimal PricesExpiration SettingsCommon Time ValuesItem LimitsWorld RestrictionsItem Display LoreAvailable PlaceholdersTime FormatAction BehaviorAuto-Claim ConfigurationSales NotificationBroadcastCategory Message OverridesBroadcast PlaceholdersSorting ConfigurationMigration Settings
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.