Configuration

zAuctionHouseStats se configure avec trois fichiers, tous situés dans plugins/zAuctionHouseStats/ :

Les menus (inventories/ et patterns/) sont documentés sur la page Inventaires.

config.yml par défautCopier le lien vers ce titre

Voici le config.yml par défaut complet. Les commentaires sont résumés et traduits ici ; les clés et les valeurs par défaut sont exactement celles fournies avec l'addon (le fichier est livré en anglais).

# Logs de debug détaillés (requêtes SQL agrégées, tailles des flush, hits/miss des caches).
debug: false

# Sondes de temps (durées des flush, rafraîchissements des classements...).
debug-performance: false

# Vérifie au démarrage si une nouvelle version de l'addon est disponible.
enable-version-checker: true

# Raccourcis de couleur utilisables dans messages.yml (<primary>, <secondary>, <error>, <success>).
# Même convention que zAuctionHouse V4 (message-colors).
message-colors:
  - key: <primary>
    color: '#24d65d'
  - key: <secondary>
    color: '#656665'
  - key: <error>
    color: '#ff0000'
  - key: <success>
    color: '#00ff00'

#=============================================================================
# STOCKAGE (la base de données PROPRE à l'addon - jamais celle de zAuctionHouse)
#=============================================================================

# SQLITE | MYSQL | MARIADB
# SQLITE : fichier local dans plugins/zAuctionHouseStats/ (serveur unique).
# MYSQL/MARIADB : obligatoire pour un cluster (plusieurs serveurs, une base).
storage-type: SQLITE

# Si un fichier database-configuration.yml existe à la racine du serveur, il
# remplace ce bloc CLÉ PAR CLÉ (même convention que zAuctionHouse V4).
database-configuration:
  # Préfixe de toutes les tables de l'addon.
  # Le modifier sur une base existante crée un nouveau jeu de tables VIDES
  # (les anciennes tables ne sont ni renommées ni migrées).
  table-prefix: "zahstats_"
  host: 192.168.10.10
  port: 3306
  user: homestead
  password: secret
  database: zauctionhouse
  # Taille du pool Hikari (MySQL / MariaDB uniquement).
  max-pool-size: 4
  min-idle: 2
  # Affiche chaque requête SQL dans la console.
  debug: false

#=============================================================================
# COLLECTE (événements de stats de zAuctionHouse, ou lecture de la table des logs)
#=============================================================================

collection:
  # AUTO (par défaut) : utilise les événements de stats de zAuctionHouse s'ils existent ;
  # sinon, se rabat sur la lecture de la table des logs UNIQUEMENT si
  # polling.enabled vaut true (sinon l'addon se désactive).
  # EVENTS | LOGS_POLLING forcent un mode.
  mode: AUTO
  # Paramètres du mode LOGS_POLLING uniquement.
  polling:
    enabled: false
    interval-seconds: 60
    batch-size: 1000
    # true = décode les objets pour obtenir matériau/quantité (coûteux, hors du thread principal).
    decode-itemstacks: false

#=============================================================================
# ÉCRITURE
#=============================================================================

flush:
  # Intervalle entre deux écritures de la file d'événements en base, en secondes.
  interval-seconds: 2
  # Flush anticipé dès que N événements sont en attente (pic d'activité).
  max-pending: 100

#=============================================================================
# CACHES DE LECTURE (utilisés par les commandes, les placeholders ET les menus)
#=============================================================================

caches:
  leaderboard-ttl-seconds: 60
  player-stats-ttl-seconds: 60
  player-stats-offline-ttl-seconds: 60
  material-price-ttl-seconds: 3600
  global-stats-ttl-seconds: 60

#=============================================================================
# CLASSEMENTS
#=============================================================================

leaderboards:
  # Entrées conservées par classement (l'affichage chat de /zahstats top est limité à 10).
  # Borné à [1, 100].
  size: 10
  # Nom affiché lorsqu'un joueur est inconnu.
  unknown-name: "?"
  # Économie utilisée lorsqu'un placeholder/menu monétaire n'en précise pas.
  # Vide = économie par défaut de zAuctionHouse.
  default-economy: ""
  # Clés (métrique, période) calculées en arrière-plan au démarrage.
  # Forme : { metric: <METRIC>, period: DAY|WEEK|MONTH|ALL[, economy: <nom>] }
  preload:
    - { metric: TOP_SELLERS_MONEY, period: ALL }
    - { metric: TOP_SELLERS_MONEY, period: DAY }
    - { metric: TOP_BUYERS_MONEY, period: ALL }
  # Métriques désactivées.
  disabled: []
  # Interrupteur global des têtes de joueurs dans les menus.
  player-heads: true
  # Texture de tête par défaut (base64) lorsqu'un profil joueur est introuvable.
  # Vide = tête par défaut du client.
  default-head-url: ""

#=============================================================================
# STATISTIQUES
#=============================================================================

statistics:
  # Fuseau horaire des agrégats journaliers (périodes DAY/WEEK/MONTH).
  # Vide = fuseau horaire du serveur. Exemple : "Europe/Paris".
  # NE JAMAIS LE MODIFIER après le premier démarrage.
  timezone: ""

  # Stocke l'ItemStack complet (Base64) de chaque vente.
  save-itemstacks: false

  # Statistiques de prix par matériau (/ah price, menu item-prices).
  material-prices:
    max-entries: 1000
    median-sample-limit: 50000

#=============================================================================
# EXPLORATEUR DE PRIX (inventories/item-prices.yml)
#=============================================================================

item-prices:
  # Nombre de matériaux listés par le menu. Borné à [1, 500].
  top-limit: 100

#=============================================================================
# RÉTENTION
#=============================================================================

retention:
  # Purge quotidienne des ventes et mises en vente de plus de N jours. 0 = illimité (par défaut).
  # Les agrégats journaliers et les totaux depuis toujours sont TOUJOURS conservés.
  sales-days: 0

#=============================================================================
# IMPORT / BACKFILL (/zahstats import v1|v4logs)
#=============================================================================

import:
  chunk-size: 500
  pause-between-chunks-ms: 50
  log-every-rows: 10000
  v1:
    server-name: "v1-import"
    listing-outcome-heuristic: true
    # Optionnel : si les tables zah_* sont dans une autre base de données.
    database:
      enabled: false
      type: MYSQL              # MYSQL | MARIADB | SQLITE
      host: localhost
      port: 3306
      user: ""
      password: ""
      database: ""
  v4logs:
    # Ne pas activer si 'import v1' est également utilisé.
    include-migrated-v3: false
    resolve-amounts-from-transactions: true
    server-name-fallback: "v4-import"

#=============================================================================
# PLACEHOLDERS (textes de repli & format)
#=============================================================================

placeholders:
  loading: "Loading..."
  no-name: "✘"
  no-value: "0"
  not-applicable: "N/A"
  enable-not-applicable: true
  date-format: "dd/MM/yyyy HH:mm"
  enable-v1-aliases: true

Gestion des valeurs invalidesCopier le lien vers ce titre

L'addon valide config.yml au démarrage et à chaque /zahstats reload :

• Les valeurs qui corrompraient les données de façon permanente (storage-type, database-configuration.table-prefix, statistics.timezone, collection.mode) sont strictes. Une valeur invalide bloque le démarrage (l'addon se désactive avec une erreur dans la console), ou annule le rechargement (la configuration précédente reste active).
• Les valeurs de réglage inférieures à leur minimum sont remises à leur valeur par défaut avec un avertissement dans la console. Les valeurs avec un intervalle (leaderboards.size, item-prices.top-limit, import.chunk-size) sont ramenées à la borne la plus proche, également avec un avertissement. statistics.material-prices.max-entries est relevé à item-prices.top-limit s'il est inférieur, et un placeholders.date-format invalide revient à dd/MM/yyyy HH:mm (les deux avec un avertissement).
• Deux valeurs d'import sont corrigées silencieusement : un import.pause-between-chunks-ms négatif devient 0, et un import.log-every-rows inférieur à 1 revient à 10000.
• Les entrées invalides de leaderboards.preload et leaderboards.disabled sont ignorées avec un avertissement dans la console.
• Une erreur de syntaxe YAML pendant /zahstats reload annule le rechargement au lieu de revenir silencieusement aux valeurs par défaut.

GénéralCopier le lien vers ce titre

message-colorsCopier le lien vers ce titre

Chaque entrée associe une balise raccourcie à une couleur hexadécimale. Le raccourci peut ensuite être utilisé dans n'importe quel message de messages.yml.

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

• Les quatre raccourcis par défaut ci-dessus sont toujours disponibles : si le bloc est absent, ou si une entrée en est retirée, la couleur par défaut de ce raccourci est quand même utilisée.
• Vous pouvez remplacer un raccourci par défaut ou ajouter le vôtre. La key peut s'écrire avec ou sans chevrons (primary et <primary> sont équivalents).
• color est généralement une couleur hexadécimale ('#24d65d', convertie en <#24d65d>). Une valeur qui commence par < est utilisée telle quelle : vous pouvez donc associer un raccourci à n'importe quelle balise MiniMessage (par exemple '<gradient:#24d65d:#00ff00>').

StockageCopier le lien vers ce titre

• SQLITE stocke les données dans un fichier local, plugins/zAuctionHouseStats/database.db. Il est destiné à un serveur unique. Les clés host, port, user, password, database, max-pool-size et min-idle sont ignorées.
• MYSQL / MARIADB sont obligatoires dans une configuration multi-serveurs (plusieurs serveurs partageant une même base de données). Les compteurs sont écrits sous forme d'incréments atomiques, ce qui permet à plusieurs serveurs d'écrire dans la même base en toute sécurité. Si zAuctionHouseRedis est installé alors que l'addon utilise SQLITE, un avertissement dans la console rappelle que chaque serveur ne verra que ses propres statistiques.

database-configuration.yml partagéCopier le lien vers ce titre

Si un fichier database-configuration.yml existe à la racine du serveur (le répertoire de travail du serveur), il remplace le bloc database-configuration de l'addon clé par clé, de la même manière que zAuctionHouse V4. Une clé absente de ce fichier reprend la valeur du config.yml de l'addon.

Les clés lues depuis ce fichier sont host, port, user, password, database et debug, sous une section database-configuration:.

CollecteCopier le lien vers ce titre

L'addon collecte les statistiques depuis une seule source, choisie une fois au démarrage : les événements de stats de zAuctionHouse, ou la lecture périodique (polling) de la table des logs de zAuctionHouse. Il n'utilise jamais les deux en même temps : une vente n'est donc jamais comptée deux fois.

Résolution du mode :

FlushCopier le lien vers ce titre

Les événements sont mis en file d'attente en mémoire et écrits en base de données par lots.

CachesCopier le lien vers ce titre

Les commandes, les placeholders et les menus lisent depuis des caches en mémoire, jamais directement depuis la base de données. Lorsqu'une entrée expire, elle est rafraîchie de manière asynchrone et les lecteurs conservent la valeur précédente en attendant : un placeholder n'attend jamais une requête en base de données. Toutes les durées sont en secondes (minimum 1).

ClassementsCopier le lien vers ce titre

Métriques disponibles (pour preload, disabled et les commandes) :

Périodes disponibles : DAY (aujourd'hui, depuis minuit), WEEK (depuis lundi), MONTH (depuis le 1er du mois) et ALL (depuis toujours). Les périodes sont des fenêtres calendaires dans le fuseau horaire statistics.timezone.

preloadCopier le lien vers ce titre

Chaque entrée s'écrit { metric: <METRIC>, period: <PERIOD>[, economy: <nom>] } :

leaderboards:
  preload:
    - { metric: TOP_SELLERS_MONEY, period: ALL }
    - { metric: TOP_SELLERS_MONEY, period: DAY }
    - { metric: TOP_BUYERS_MONEY, period: ALL }
    - { metric: TOP_SELLERS_COUNT, period: WEEK, economy: vault }

• period est optionnel et vaut ALL par défaut.
• Sans economy, les métriques monétaires utilisent l'économie par défaut et les métriques de comptage couvrent toutes les économies.
• Le préchargement ne bloque jamais le démarrage du serveur : tant qu'il n'est pas terminé, les placeholders affichent placeholders.loading.
• Une entrée invalide (métrique ou période inconnue) est ignorée avec un avertissement dans la console. Les métriques désactivées ne sont pas préchargées.

disabledCopier le lien vers ce titre

leaderboards:
  disabled:
    - TOP_TAX_PAID
    - BIGGEST_SALE

Une métrique désactivée est retirée du sélecteur de métrique du menu de classement, ses placeholders top renvoient placeholders.not-applicable, /zahstats top répond avec le message top-disabled, et l'API renvoie une liste vide. Les noms de métriques inconnus sont ignorés avec un avertissement dans la console.

StatistiquesCopier le lien vers ce titre

Explorateur de prixCopier le lien vers ce titre

RétentionCopier le lien vers ce titre

• La purge s'exécute de manière asynchrone une fois par jour, en commençant 10 minutes après le démarrage du serveur.
• Les totaux journaliers et les totaux depuis toujours sont toujours conservés : les classements et les périodes survivent donc à la purge.
• Le classement BIGGEST_SALE pour les périodes DAY, WEEK et MONTH est calculé à partir des ventes individuelles. Avec une valeur entre 1 et 34, le classement mensuel devient incomplet et un avertissement s'affiche dans la console. Utilisez 0 ou au moins 35.
• Vous pouvez aussi purger manuellement avec /zahstats purge <days> confirm (voir Commandes & Permissions).

ImportCopier le lien vers ce titre

Ces paramètres sont utilisés par /zahstats import v1 et /zahstats import v4logs. Ils sont relus à chaque rechargement et s'appliquent au prochain import. Voir Migration pour la procédure complète.

PlaceholdersCopier le lien vers ce titre

Ces paramètres contrôlent les textes et le format renvoyés par les placeholders. Certains sont aussi utilisés par les menus et les commandes.

messages.ymlCopier le lien vers ce titre

messages.yml contient tous les messages de chat de l'addon. Il est généré au premier démarrage dans la langue choisie dans language.yml.

FormatCopier le lien vers ce titre

Les messages utilisent le même format que le messages.yml de zAuctionHouse V4 :

• MiniMessage : <red>, <bold>, <gradient:red:blue>, <hover:show_text:'text'>, <click:run_command:'/cmd'>... Voir le format MiniMessage.
• Couleurs hexadécimales : <#RRGGBB>.
• Raccourcis de couleur : <primary>, <secondary>, <error>, <success> et tout raccourci que vous ajoutez dans config.yml (message-colors).
• Codes legacy : &a, &l, §c et &#RRGGBB sont tolérés (convertis en MiniMessage) mais déconseillés.

Règles :

• %prefix% est remplacé par la valeur de la clé prefix. Définissez prefix: "" pour désactiver le préfixe.
• Un message vide ("") n'est pas envoyé.
• price-informations est une liste : chaque ligne est envoyée comme un message séparé.
• Une clé absente de votre fichier (par exemple après une mise à jour) utilise la valeur par défaut fournie avec l'addon, dans la même langue.
• Les valeurs qui proviennent des joueurs (noms de joueurs, économies saisies...) sont toujours affichées en texte brut : les balises MiniMessage ou codes couleur qu'elles contiennent ne sont pas interprétés.
• Une balise MiniMessage invalide ne casse jamais un message : le texte est affiché tel quel.

Clés des messagesCopier le lien vers ce titre

Les libellés metric-name.* et period-name.* sont aussi utilisés pour remplir %metric% et %period% dans les autres messages, ainsi que par les placeholders formatés.

language.ymlCopier le lien vers ce titre

language.yml choisit la langue des fichiers par défaut générés au premier démarrage : messages.yml, le dossier inventories/ et le dossier patterns/. Il fonctionne comme le language.yml de zAuctionHouse V4.

# Options disponibles :
#   - auto : détection à partir du pays/de la locale du serveur
#   - en   : anglais (par défaut)
#   - fr   : français
#   - es   : espagnol
#   - it   : italien
language: auto

Avec auto, l'addon utilise d'abord le pays de la locale du serveur (JVM), puis sa langue :

Une langue explicite qui n'est pas fournie (par exemple de) revient à l'anglais avec un avertissement dans la console.

Changer la langueCopier le lien vers ce titre

La langue ne s'applique qu'aux fichiers qui n'existent pas encore. Vos fichiers existants ne sont jamais écrasés. Pour changer de langue :

1. Modifiez language dans language.yml.
2. Supprimez messages.yml ainsi que les dossiers inventories/ et patterns/ dans plugins/zAuctionHouseStats/ (sauvegardez-les d'abord si vous les avez personnalisés).
3. Redémarrez le serveur. Les fichiers sont régénérés dans la nouvelle langue.

TraduireCopier le lien vers ce titre

Pour traduire ou reformuler les messages, modifiez directement plugins/zAuctionHouseStats/messages.yml puis exécutez /zahstats reload. Vous pouvez partir de n'importe quelle langue fournie (en, fr, es, it) et la traduire dans une autre : chaque clé est disponible dans les quatre langues, et une clé que vous supprimez reprend la valeur par défaut fournie dans la langue sélectionnée.

Ce que recharge /zahstats reloadCopier le lien vers ce titre

/zahstats reload (permission zauctionhouse.stats.reload) applique la plupart des changements sans redémarrage. Il n'exécute jamais de requête en base de données sur le thread de la commande.

Ces paramètres ne sont lus qu'au démarrage. Les modifier nécessite un redémarrage du serveur, et le rechargement affiche un avertissement dans la console lorsqu'ils ont changé :

enable-version-checker n'est lu lui aussi qu'au démarrage, mais sa modification n'affiche aucun avertissement lors du rechargement.