Main Configuration

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:

Operation	Description
`loadItems.loadPlayers`	Time to load player data
`loadItems.loadItemsFromDB`	Time to load items from database
`loadItems.processItems`	Time to process loaded items
`loadItems.total`	Total loading time
`loadItems.rebuildSortedItemsCache`	Time to rebuild sorted cache
`SortedItemsCache.rebuild`	Time to rebuild the sorted items cache
`applyCategories`	Time 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

Value	Description
`auto`	Uses the server's default timezone (default)
`UTC`	Coordinated Universal Time
`Europe/Paris`	Central European Time (UTC+1/UTC+2)
`America/New_York`	Eastern Time (UTC-5/UTC-4)
`Asia/Tokyo`	Japan 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, POSTGRESQL (POSTGRES is also accepted)
storage-type: SQLITE

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

# Database connection settings (MySQL/MariaDB/PostgreSQL only)
database-configuration:
  table-prefix: zauctionhouse_
  host: 192.168.10.10
  port: 3306 # Default port: 3306 for MySQL/MariaDB, 5432 for PostgreSQL
  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 or PostgreSQL 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.

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

Keep it a few minutes below the database wait_timeout (or the equivalent idle timeout on PostgreSQL). 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

Type	Description	Best For
`SQLITE`	Local file-based database	Single server, no setup required
`MYSQL`	MySQL database server	Multi-server, large auction houses
`MARIADB`	MariaDB database server	Multi-server, large auction houses
`POSTGRESQL`	PostgreSQL database server (`POSTGRES` is also accepted)	Multi-server, large auction houses

For multi-server synchronization, use MySQL/MariaDB/PostgreSQL with the Redis addon. SQLITE is refused by the Redis addon. The PostgreSQL driver is downloaded automatically by the server, no extra jar is needed. Remember to use port 5432 (the PostgreSQL default).

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

Time	Seconds
1 hour	3600
1 day	86400
2 days	172800
3 days	259200
1 week	604800
30 days	2592000

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

Placeholder	Description
`%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

  # Preview the content of a listed shulker box (or other container) without buying it
  container-preview:
    enable: true
    click: RIGHT               # RIGHT, LEFT, SHIFT_RIGHT, SHIFT_LEFT, MIDDLE...

  # 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

Container Preview

Players can see what is inside a listed shulker box (or any container supported by the Container Content inventory) by right-clicking it in the auction house, as in V3.

action:
  container-preview:
    enable: true
    click: RIGHT

Option	Default	Description
`enable`	`true`	Enables the preview from the auction house
`click`	`RIGHT`	Click that opens the preview: `RIGHT`, `LEFT`, `SHIFT_RIGHT`, `SHIFT_LEFT`, `MIDDLE`...

The preview opens inventories/shulker-content.yml directly, without the purchase confirmation.
The player's balance is not checked: a player without enough money can still see the content.
The listing is not reserved, other players can still buy it while the preview is open.
Any other click keeps its usual behaviour (purchase, or removal for the seller). Listings without a container are not affected.

With click: LEFT, a left click on a listing that contains a container opens the preview instead of the purchase: players then have to use another click to buy it.

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

Placeholder	Description	Available In
`%seller%`	Name of the seller	Sell & Purchase
`%buyer%`	Name of the buyer	Purchase only
`%items%`	Item display name	Sell & Purchase
`%price%`	Formatted price	Sell & Purchase
`%category%`	Category name	Sell & 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

Main Configuration

Debug & Monitoring

Performance Operations

General Settings

Database Configuration

Connection Lifetime

Storage Types

Message Colors

Command Configuration

Custom Inventory Commands

Price Shortcuts

Decimal Prices

Expiration Settings

Common Time Values

Item Limits

World Restrictions

Item Display Lore

Available Placeholders

Time Format

Action Behavior

Container Preview

Auto-Claim Configuration

Sales Notification

Broadcast

Category Message Overrides

Broadcast Placeholders

Sorting Configuration

Migration Settings

On this page

Documentation in your AI

1. Copy the server URL

2. Choose your tool

3. Ask a question

Debug & MonitoringCopy Anchor Link

Performance OperationsCopy Anchor Link

General SettingsCopy Anchor Link

Database ConfigurationCopy Anchor Link

Connection LifetimeCopy Anchor Link

Storage TypesCopy Anchor Link

Message ColorsCopy Anchor Link

Command ConfigurationCopy Anchor Link

Custom Inventory CommandsCopy Anchor Link

Price ShortcutsCopy Anchor Link

Decimal PricesCopy Anchor Link

Expiration SettingsCopy Anchor Link

Common Time ValuesCopy Anchor Link

Item LimitsCopy Anchor Link

World RestrictionsCopy Anchor Link

Item Display LoreCopy Anchor Link

Available PlaceholdersCopy Anchor Link

Time FormatCopy Anchor Link

Action BehaviorCopy Anchor Link

Container PreviewCopy Anchor Link

Auto-Claim ConfigurationCopy Anchor Link

Sales NotificationCopy Anchor Link

BroadcastCopy Anchor Link

Category Message OverridesCopy Anchor Link

Broadcast PlaceholdersCopy Anchor Link

Sorting ConfigurationCopy Anchor Link

Migration SettingsCopy Anchor Link

On this page

Debug & Monitoring

Performance Operations

General Settings

Database Configuration

Connection Lifetime

Storage Types

Message Colors

Command Configuration

Custom Inventory Commands

Price Shortcuts

Decimal Prices

Expiration Settings

Common Time Values

Item Limits

World Restrictions

Item Display Lore

Available Placeholders

Time Format

Action Behavior

Container Preview

Auto-Claim Configuration

Sales Notification

Broadcast

Category Message Overrides

Broadcast Placeholders

Sorting Configuration

Migration Settings