Inventories

zAuctionHouseStats ships five menus and two patterns, all powered by zMenu. This page explains each menu, the patterns, and every custom button type added by the addon (ZAUCTIONHOUSESTATS_*), with all of their options.

For general zMenu options (items, slots, lore, actions, requirements, etc.), see the zMenu documentation.

Files and FoldersCopy Anchor Link

All menu files are in the addon data folder:

plugins/zAuctionHouseStats/
├── language.yml
├── inventories/
│   ├── stats.yml
│   ├── leaderboard.yml
│   ├── player-stats.yml
│   ├── item-prices.yml
│   └── admin.yml
└── patterns/
    ├── zahstats-back.yml
    └── zahstats-pagination.yml

• Every .yml file in inventories/ (including sub-folders) is loaded as a menu. The menu name is the file name without .yml (for example leaderboard).
• Every .yml file in patterns/ is loaded as a pattern. You can add your own patterns there.
• A missing default file is created again at startup. An existing file is never overwritten, so your changes are kept.
• /zahstats reload reloads all menus and patterns. A pattern you deleted or renamed is removed from zMenu on reload.

LanguageCopy Anchor Link

The default menus are available in four languages. The language is chosen with language.yml:

Any other value falls back to English, with a warning in the console. The four versions of each menu have the same layout, slots and button types: only the texts change. The examples on this page are the English files.

language: auto

Menus OverviewCopy Anchor Link

The permission check is done by a zMenu open-requirement in each file. If the player does not have the permission, the deny message of the file is sent. See Commands & Permissions for the full permission list.

To open an addon menu from another button, use a zMenu INVENTORY button with plugin: zAuctionHouseStats:

open-leaderboard:
  type: INVENTORY
  inventory: leaderboard
  plugin: zAuctionHouseStats
  slot: 38
  item:
    material: GOLD_INGOT
    name: "#2CCED2<bold>ʟᴇᴀᴅᴇʀʙᴏᴀʀᴅs"

Menus are opened with a navigation history, so the BACK button returns to the previous menu.

stats.yml (Hub)Copy Anchor Link

The hub shows live global statistics, the top 3 sellers and buttons to open the other menus. It is opened with /ah stats.

Layout:

The statistic buttons use update: true, so they refresh every update-interval. Values are read from memory caches only: a refresh never waits for a database query (a value not in cache yet is loaded in the background and shows placeholders.loading meanwhile).

┌───┬───┬───┬───┬───┬───┬───┬───┬───┐
│   │   │   │   │ H │   │   │   │   │  H = header
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ L │ S │ E │   │ V │ T │ B │   │  Global statistics
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ 1 │   │   │   │   │  Podium #1
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │ 2 │   │ 3 │   │   │   │  Podium #2 and #3
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │ ↗ │   │ ★ │   │ ↗ │   │   │  Leaderboard / My stats / Prices
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │   │ A │  A = admin
└───┴───┴───┴───┴───┴───┴───┴───┴───┘

leaderboard.ymlCopy Anchor Link

Paginated leaderboards. The player changes the metric, the period and the economy with the three selectors at the bottom. Clicking a player opens their statistics sheet.

Layout:

The default selection of this menu is metric: TOP_SELLERS_MONEY, period: ALL and the default economy.

player-stats.ymlCopy Anchor Link

The statistics sheet of a player: counters summed over all economies, then one entry per economy.

The sheet shows:

• The player clicked in a leaderboard or in the podium of the hub.
• Yourself when opened with the ZAUCTIONHOUSESTATS_MY_STATS button (this clears any player clicked before) or with /ah stats and then "My statistics".

Layout:

item-prices.ymlCopy Anchor Link

The price explorer lists the best-selling materials for the selected economy and period, with the number of sales, the average price and the median price. The list is dynamic: it is computed from the sales, there is no hard-coded list of materials. The icon of each entry is the sold material itself.

It is opened with /zahstats items [economy]. If an economy is given, it is selected when the menu opens.

Layout:

The default selection is period: ALL and the default economy. The number of materials is set by item-prices.top-limit in config.yml (default 100, between 1 and 500).

The median is only computed for the materials of the page you are looking at. Until it is ready, %median% and %format_median% show the placeholders.loading text of config.yml, then the page refreshes on its own.

admin.ymlCopy Anchor Link

The administration panel: live status of the write queue and caches, and shortcuts to maintenance commands.

Layout:

Purge and import are irreversible, so these buttons only show the command. The player has to type it.

PatternsCopy Anchor Link

The addon ships two patterns. Their names start with zahstats- because the zMenu pattern registry is shared by all plugins: keep this prefix if you rename them or add your own, to avoid conflicts.

Both patterns are size: 54 and their buttons use is-permanent: true. They are used by leaderboard.yml, player-stats.yml and item-prices.yml:

patterns:
  - "zahstats-pagination"
  - "zahstats-back"

zahstats-paginationCopy Anchor Link

name: "zahstats-pagination"
size: 54

items:
  previous:
    type: PREVIOUS
    is-permanent: true
    slot: 48
    item:
      url: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjllYTFkODYyNDdmNGFmMzUxZWQxODY2YmNhNmEzMDQwYTA2YzY4MTc3Yzc4ZTQyMzE2YTEwOThlNjBmYjdkMyJ9fX0="
      name: "#2CCED2<bold>ᴘʀᴇᴠɪᴏᴜs ᴘᴀɢᴇ"
      lore:
        - "#92ffffGo to the previous page. #8c8c8c(%page%/%max-page%)"
    else:
      item:
        material: BLACK_STAINED_GLASS_PANE
        name: "<white>"
  next:
    type: NEXT
    is-permanent: true
    slot: 50
    item:
      url: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvODI3MWE0NzEwNDQ5NWUzNTdjM2U4ZTgwZjUxMWE5ZjEwMmIwNzAwY2E5Yjg4ZTg4Yjc5NWQzM2ZmMjAxMDVlYiJ9fX0="
      name: "#2CCED2<bold>ɴᴇxᴛ ᴘᴀɢᴇ"
      lore:
        - "#92ffffGo to the next page. #8c8c8c(%page%/%max-page%)"
    else:
      item:
        material: BLACK_STAINED_GLASS_PANE
        name: "<white>"

zahstats-backCopy Anchor Link

name: "zahstats-back"
size: 54

items:
  back:
    type: BACK
    is-permanent: true
    slot: 49
    item:
      material: DARK_OAK_DOOR
      name: "#2CCED2<bold>ʙᴀᴄᴋ"
      lore:
        - "#92ffffGo to the previous menu."

Button TypesCopy Anchor Link

All these types also accept the standard zMenu options (slot/slots, item, actions, permission, update, etc.).

Common RulesCopy Anchor Link

Loading. Data buttons never query the database while the menu is drawn. When the data is not in cache yet, the button shows its loading-item, loads the data in the background, then refreshes the menu once the data is ready. The cache durations are set in the caches section of config.yml.

Missing items. If a button needs entry-item, loading-item or empty-item and the section is missing, a warning is logged and the button uses its item section instead.

Invalid values. An invalid metric or period value is logged (file and path) and replaced by its default value. A typo never breaks the menu.

%zahstats_*% placeholders. In every ZAUCTIONHOUSESTATS_* button, %zahstats_...% placeholders in the name and lore are resolved by the addon itself, without PlaceholderAPI. Standard zMenu buttons (NONE, INVENTORY, ...) need PlaceholderAPI for that. See Placeholders for the full list.

Default Selection: metric, period, economyCopy Anchor Link

ZAUCTIONHOUSESTATS_LEADERBOARD, ZAUCTIONHOUSESTATS_ITEM_PRICES and ZAUCTIONHOUSESTATS_PODIUM read these options:

Metrics:

Periods:

Periods use the statistics.timezone of config.yml.

When economy is not set:

• Money metrics and prices use the default economy: leaderboards.default-economy in config.yml, or the default economy of zAuctionHouse when it is empty.
• Count metrics (TOP_SELLERS_COUNT, TOP_BUYERS_COUNT) use all economies combined.

Money amounts are never added up across economies.

ZAUCTIONHOUSESTATS_LEADERBOARDCopy Anchor Link

Displays a leaderboard on several slots, with pagination. The metric, period and economy come from the button options, and can be changed by the player with the selectors of the same menu. Clicking an entry opens the statistics sheet (player-stats.yml) of that player.

Configuration:

Entry placeholders (entry-item):

Example:

leaderboard:
  type: ZAUCTIONHOUSESTATS_LEADERBOARD
  slots:
    - "9-17"
    - "18-26"
    - "27-35"
    - "36-44"
  metric: TOP_SELLERS_MONEY
  period: ALL
  # economy: vault
  player-heads: true
  loading-slot: 22
  loading-item:
    material: CLOCK
    name: "#f1c40fLoading the leaderboard..."
  entry-item:
    material: PLAYER_HEAD
    name: "#f1c40f#%rank% #ffffff%name%"
    lore:
      - "#92ffffValue: #2CCED2%format%"
      - ""
      - "#8c8c8c• #2CCED2Click #92ffffto view the player statistics"
  item:
    material: BARRIER
    name: "#ff5555No data for this selection"
    lore:
      - "#92ffffChange the metric, the period or the economy."

SelectorsCopy Anchor Link

The three selector types work the same way:

• Left click: next value.
• Right click: previous value.
• The list loops: after the last value comes the first one.
• After a change, the menu opens again at page 1, and the navigation history is kept.
• The actions, messages and sounds of the button still run on click.

Configuration (all selectors):

Placeholders (item):

A value without a label shows its raw name (for example TOP_TAX_PAID). In metrics and periods, invalid values are logged and skipped, and duplicates are ignored. If the list is empty or only has invalid values, the default list is used. economies is not checked against zAuctionHouse: empty entries and duplicates are removed, the other names are used as they are. If the cycle ends up empty (for example every metric is disabled), a click does nothing.

ZAUCTIONHOUSESTATS_METRIC_SELECTORCopy Anchor Link

Changes the leaderboard metric.

Metrics listed in leaderboards.disabled (config.yml) are removed from the cycle.

Example:

metric-selector:
  type: ZAUCTIONHOUSESTATS_METRIC_SELECTOR
  slot: 45
  # metrics:
  #   - TOP_SELLERS_MONEY
  #   - TOP_BUYERS_MONEY
  labels:
    TOP_SELLERS_MONEY: "Top sellers (money)"
    TOP_BUYERS_MONEY: "Top buyers (money)"
    TOP_SELLERS_COUNT: "Top sellers (sales)"
    TOP_BUYERS_COUNT: "Top buyers (purchases)"
    TOP_TAX_PAID: "Most taxes paid"
    BIGGEST_SALE: "Biggest sale"
  item:
    material: COMPARATOR
    name: "#2CCED2Metric: #ffffff%selected%"
    lore:
      - "#8c8c8c• #2CCED2Left click #92ffff→ %next%"
      - "#8c8c8c• #2CCED2Right click #92ffff→ %previous%"

ZAUCTIONHOUSESTATS_PERIOD_SELECTORCopy Anchor Link

Changes the period.

Example:

period-selector:
  type: ZAUCTIONHOUSESTATS_PERIOD_SELECTOR
  slot: 46
  # periods:
  #   - WEEK
  #   - ALL
  labels:
    DAY: "Today"
    WEEK: "This week"
    MONTH: "This month"
    ALL: "All time"
  item:
    material: CLOCK
    name: "#2CCED2Period: #ffffff%selected%"
    lore:
      - "#8c8c8c• #2CCED2Left click #92ffff→ %next%"
      - "#8c8c8c• #2CCED2Right click #92ffff→ %previous%"

ZAUCTIONHOUSESTATS_ECONOMY_SELECTORCopy Anchor Link

Changes the economy.

The cycle always starts with the default option (label key default): default economy for money and prices, all economies combined for counts. Then come the economies of the list. An economy without a label shows its zAuctionHouse display name. Without a default label, the default option is displayed as default.

Example:

economy-selector:
  type: ZAUCTIONHOUSESTATS_ECONOMY_SELECTOR
  slot: 47
  # economies:
  #   - vault
  #   - playerpoints
  labels:
    default: "Default"
    # vault: "Money"
  item:
    material: GOLD_NUGGET
    name: "#2CCED2Economy: #ffffff%selected%"
    lore:
      - "#8c8c8c• #2CCED2Left click #92ffff→ %next%"
      - "#8c8c8c• #2CCED2Right click #92ffff→ %previous%"

ZAUCTIONHOUSESTATS_PODIUMCopy Anchor Link

Displays one rank of a leaderboard on a single slot, with the player head. Clicking it opens the statistics sheet of that player. The metric, period and economy are fixed by the options: selectors do not change them.

Placeholders:

The skin is applied when leaderboards.player-heads is true (this button has no player-heads option of its own).

Example:

podium-first:
  type: ZAUCTIONHOUSESTATS_PODIUM
  slot: 22
  rank: 1
  metric: TOP_SELLERS_MONEY
  period: ALL
  # economy: vault
  item:
    material: PLAYER_HEAD
    name: "#f1c40f#%rank% #ffffff%name%"
    lore:
      - "#92ffffEarned: #2CCED2%format%"
      - ""
      - "#8c8c8c• #2CCED2Click #92ffffto view the statistics"
  loading-item:
    material: CLOCK
    name: "#f1c40fLoading..."
  empty-item:
    material: SKELETON_SKULL
    name: "#8c8c8cNo seller yet"

ZAUCTIONHOUSESTATS_PLAYER_STATSCopy Anchor Link

Displays the head and the counters of the player shown by the sheet (the player clicked, or yourself). Counters are all-time values summed over all economies.

Placeholders (item):

Dates use placeholders.date-format and statistics.timezone of config.yml. A missing date, or a conversion rate with no listed item, shows placeholders.not-applicable (or placeholders.no-value when placeholders.enable-not-applicable is false).

Example:

player-stats:
  type: ZAUCTIONHOUSESTATS_PLAYER_STATS
  slot: 13
  loading-item:
    material: CLOCK
    name: "#f1c40fLoading the statistics of %target%..."
  item:
    material: PLAYER_HEAD
    name: "#2CCED2<bold>%target%"
    lore:
      - "#92ffffItems listed: #2CCED2%items_listed%"
      - "#92ffffItems sold: #2CCED2%items_sold%"
      - "#92ffffItems bought: #2CCED2%items_bought%"
      - "#92ffffItems expired: #2CCED2%items_expired%"
      - "#92ffffItems removed: #2CCED2%items_removed%"
      - "#92ffffConversion rate: #2CCED2%conversion_rate%%"
      - ""
      - "#92ffffFirst sale: #2CCED2%first_sale%"
      - "#92ffffLast sale: #2CCED2%last_sale%"
      - "#92ffffFirst purchase: #2CCED2%first_purchase%"
      - "#92ffffLast purchase: #2CCED2%last_purchase%"

ZAUCTIONHOUSESTATS_PLAYER_ECONOMIESCopy Anchor Link

Displays one entry per economy used by the player of the sheet, sorted by economy name, with pagination.

Entry placeholders (entry-item):

Example:

economies:
  type: ZAUCTIONHOUSESTATS_PLAYER_ECONOMIES
  slots:
    - "27-35"
    - "36-44"
  loading-slot: 31
  loading-item:
    material: CLOCK
    name: "#f1c40fLoading the economies..."
  entry-item:
    material: GOLD_INGOT
    name: "#2CCED2<bold>%economy_display%"
    lore:
      - "#92ffffEarned: #2CCED2%money_earned%"
      - "#92ffffSpent: #2CCED2%money_spent%"
      - "#92ffffTaxes paid: #2CCED2%tax_paid%"
      - "#92ffffBiggest sale: #2CCED2%biggest_sale%"
      - "#92ffffEarned / spent ratio: #2CCED2%ratio%"
      - ""
      - "#8c8c8c%items_sold% sold, %items_bought% bought"
  item:
    material: BARRIER
    name: "#ff5555No auction activity yet"

ZAUCTIONHOUSESTATS_ITEM_PRICESCopy Anchor Link

Displays the best-selling materials of the selected economy and period, with pagination. Materials are sorted by number of sales (most sold first, then by name). The material of entry-item is replaced by the sold material, but its name, lore and flags are kept (an unknown material keeps the template material). The metric option is not used.

Prices are always computed for one economy: the selected one, otherwise the default economy. If no economy can be found, the item is shown at loading-slot.

The number of materials listed is the smallest of limit and item-prices.top-limit (config.yml).

Entry placeholders (entry-item):

Example:

item-prices:
  type: ZAUCTIONHOUSESTATS_ITEM_PRICES
  slots:
    - "9-17"
    - "18-26"
    - "27-35"
    - "36-44"
  period: ALL
  # economy: vault
  # limit: 50
  loading-slot: 22
  loading-item:
    material: CLOCK
    name: "#f1c40fLoading the prices..."
  entry-item:
    material: PAPER
    name: "#2CCED2<bold>%material_name%"
    lore:
      - "#92ffffSales: #2CCED2%amount%"
      - "#92ffffAverage price: #2CCED2%format_average%"
      - "#92ffffMedian price: #2CCED2%format_median%"
  item:
    material: BARRIER
    name: "#ff5555No sale for this selection"

ZAUCTIONHOUSESTATS_ADMIN_STATUSCopy Anchor Link

Live status panel. It only reads in-memory counters, so it is safe with update: true. It has no specific option.

Placeholders:

Example:

status:
  type: ZAUCTIONHOUSESTATS_ADMIN_STATUS
  slot: 13
  update: true
  item:
    material: COMPARATOR
    name: "#2CCED2<bold>Status"
    lore:
      - "#92ffffDatabase: #2CCED2%storage_type% #8c8c8c(collection: %collection_mode%)"
      - "#92ffffPending events: #2CCED2%queue_pending% #8c8c8c(retry: %pending_retry%)"
      - "#92ffffFlushes: #2CCED2%flush_count% #8c8c8c(failures: %flush_failures%, dropped: %dropped_events%)"
      - ""
      - "#92ffffLeaderboards: #2CCED2%leaderboard_entries% #8c8c8c(hit %leaderboard_hit_ratio%%)"
      - "#92ffffPlayer sheets: #2CCED2%player_entries% #8c8c8c(hit %player_hit_ratio%%)"
      - "#92ffffMaterial prices: #2CCED2%material_entries% #8c8c8c(hit %material_hit_ratio%%)"
      - "#92ffffRows: #2CCED2%sales_count% #92ffffsales, #2CCED2%listings_count% #92fffflistings"
      - "#8c8c8cRead queries: %sql_queries% - head textures: %head_textures%"

ZAUCTIONHOUSESTATS_TEXTCopy Anchor Link

A display button whose name and lore can contain %zahstats_*% placeholders. They are resolved by the addon from its caches, without PlaceholderAPI. It works with update: true. It has no specific option.

Example:

sold:
  type: ZAUCTIONHOUSESTATS_TEXT
  slot: 11
  update: true
  item:
    material: EMERALD
    name: "#2CCED2<bold>Items sold"
    lore:
      - "#92ffffTotal: #2CCED2%zahstats_global_items_sold%"

ZAUCTIONHOUSESTATS_MY_STATSCopy Anchor Link

Opens player-stats.yml on your own statistics. A plain INVENTORY button would show the last player clicked in a leaderboard; this button clears it first. Its name and lore resolve %zahstats_*% placeholders like ZAUCTIONHOUSESTATS_TEXT. It has no specific option.

Example:

my-stats:
  type: ZAUCTIONHOUSESTATS_MY_STATS
  slot: 40
  item:
    material: BOOK
    name: "#2CCED2<bold>ᴍʏ sᴛᴀᴛɪsᴛɪᴄs"
    lore:
      - "#92ffffYour sales, purchases and earnings."
      - ""
      - "#8c8c8c• #2CCED2Click #92ffffto open"

Player HeadsCopy Anchor Link

ZAUCTIONHOUSESTATS_LEADERBOARD, ZAUCTIONHOUSESTATS_PODIUM and ZAUCTIONHOUSESTATS_PLAYER_STATS apply the player skin on their item. The item must be a PLAYER_HEAD; any other material is displayed as it is.

Skins are loaded in the background, a page at a time, and kept in the addon cache for 6 hours (including players without a skin, so they are not requested again). The menu refreshes once the skins of the page are ready. The skin of a player who joins the server is cached right away.

ZAUCTIONHOUSESTATS_LEADERBOARD also has its own player-heads option: skins are applied only if both the option and leaderboards.player-heads are true.

See Configuration for all settings.