Installer zAuctionHouseStats

Ce guide couvre l'installation de l'addon zAuctionHouseStats, le choix de son stockage et la vérification de la collecte des statistiques.

PrérequisCopier le lien vers ce titre

Exigences serveurCopier le lien vers ce titre

Plugins requisCopier le lien vers ce titre

Ces plugins sont déclarés dans la liste depend du plugin.yml : l'addon ne se charge pas sans eux.

Plugins optionnelsCopier le lien vers ce titre

BibliothèquesCopier le lien vers ce titre

Les drivers JDBC sont déclarés dans la section libraries du plugin.yml : le serveur les télécharge au premier démarrage. Vous n'avez rien d'autre à installer.

Étapes d'installationCopier le lien vers ce titre

1. Installez le jarCopier le lien vers ce titre

Placez zAuctionHouseStats.jar dans le dossier plugins/ de votre serveur, à côté de zAuctionHouse.jar et zMenu.jar.

2. Démarrez votre serveurCopier le lien vers ce titre

Démarrez le serveur une première fois pour générer les fichiers par défaut. Avec les paramètres par défaut (SQLite), l'addon fonctionne immédiatement.

3. Configurez le stockage et le fuseau horaireCopier le lien vers ce titre

Modifiez plugins/zAuctionHouseStats/config.yml :

• choisissez le type de stockage (SQLite pour un serveur unique, MySQL/MariaDB pour un réseau) ;
• définissez le fuseau horaire avant que la moindre statistique ne soit enregistrée ou importée.

4. Redémarrez votre serveurCopier le lien vers ce titre

Certains paramètres ne sont lus qu'au démarrage : storage-type et database-configuration, collection.*, statistics.timezone, statistics.save-itemstacks, retention.sales-days et language.yml. /zahstats reload ne les applique pas (un avertissement « redémarrage requis » est affiché dans la console). Redémarrez le serveur après les avoir modifiés.

Structure des fichiersCopier le lien vers ce titre

Après le premier démarrage, zAuctionHouseStats crée la structure suivante :

plugins/zAuctionHouseStats/
├── language.yml            # Langue des fichiers générés (auto, en, fr, es, it)
├── config.yml              # Configuration principale
├── messages.yml            # Tous les messages de l'addon
├── inventories/
│   ├── stats.yml           # Hub des statistiques (/ah stats)
│   ├── leaderboard.yml     # Classements
│   ├── player-stats.yml    # Statistiques d'un joueur
│   ├── item-prices.yml     # Explorateur des prix des objets (/zahstats items)
│   └── admin.yml           # Menu d'état administrateur
├── patterns/
│   ├── zahstats-back.yml
│   └── zahstats-pagination.yml
└── database.db             # Base de données SQLite (si SQLite est utilisé)

LangueCopier le lien vers ce titre

language.yml est lu avant la génération de tout autre fichier. Il sélectionne la langue de messages.yml, inventories/ et patterns/.

Toute autre valeur affiche un avertissement et revient à l'anglais. config.yml est toujours généré dans sa version par défaut, quelle que soit la langue.

StockageCopier le lien vers ce titre

zAuctionHouseStats utilise sa propre connexion à la base de données. Il n'écrit jamais dans les tables de zAuctionHouse : toutes ses tables utilisent leur propre préfixe.

# SQLITE | MYSQL | MARIADB
storage-type: SQLITE

database-configuration:
  table-prefix: "zahstats_"
  host: 192.168.10.10
  port: 3306
  user: homestead
  password: secret
  database: zauctionhouse
  max-pool-size: 4
  min-idle: 2
  debug: false

SQLiteCopier le lien vers ce titre

Avec storage-type: SQLITE, les données sont stockées dans plugins/zAuctionHouseStats/database.db. Aucun autre paramètre n'est nécessaire. SQLite est prévu pour un serveur unique.

MySQL / MariaDBCopier le lien vers ce titre

Définissez storage-type sur MYSQL ou MARIADB et renseignez les informations de connexion. Vous pouvez utiliser la même base de données que zAuctionHouse : les tables de l'addon sont séparées grâce à leur préfixe (zahstats_ par défaut).

Avec MySQL/MariaDB, l'addon utilise toujours un pool de connexions HikariCP dimensionné par max-pool-size et min-idle.

Si la connexion ou les migrations échouent (ou ne se terminent pas en moins de 60 secondes), l'addon se désactive et affiche la raison dans la console. Il ne fonctionne jamais en mode dégradé sans stockage.

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

Si un fichier database-configuration.yml existe à la racine du serveur (le même fichier que celui utilisé par zAuctionHouse V4 et d'autres plugins GroupeZ), il est prioritaire sur config.yml clé par clé : chaque clé qu'il définit remplace celle de config.yml, les clés absentes reprennent la valeur de config.yml.

Les clés suivantes sont lues depuis ce fichier, dans la section database-configuration :

Lorsque le fichier est détecté, la console affiche :

Using the server-wide database-configuration.yml for database credentials (table-prefix is still read from config.yml).

Si le fichier existe mais ne peut pas être lu, un avertissement est affiché et les valeurs de config.yml sont utilisées à la place.

Tables crééesCopier le lien vers ce titre

Au démarrage, l'addon exécute ses migrations et crée les tables suivantes (affichées avec le préfixe par défaut zahstats_) :

Le registre des migrations suit le préfixe (<prefix>migrations ; avec un préfixe vide, il s'agit de zahstats_migrations). Ce n'est jamais la table générique migrations ni celle de zAuctionHouse : l'addon peut donc partager une base de données avec zAuctionHouse sans risque. Après les migrations, l'addon vérifie que toutes les tables existent ; si l'une d'elles manque alors que le registre la marque comme créée, l'addon s'arrête et vous indique de supprimer cette table de registre (ou de restaurer les tables manquantes) puis de redémarrer.

Fuseau horaireCopier le lien vers ce titre

Les statistiques des périodes DAY, WEEK et MONTH sont regroupées par jour. Le fuseau horaire utilisé pour découper ces jours se définit dans config.yml :

statistics:
  # Empty = server timezone. Example: "Europe/Paris".
  timezone: ""

Le même fuseau horaire est utilisé pour afficher les dates dans les placeholders de date (placeholders.date-format).

Multi-serveursCopier le lien vers ce titre

Lorsque plusieurs serveurs partagent un même hôtel des ventes (voir l'addon zAuctionHouse Redis) :

• utilisez MYSQL ou MARIADB et faites pointer tous les serveurs vers la même base de données avec le même table-prefix. Les compteurs sont écrits par incréments atomiques, plusieurs serveurs peuvent donc écrire en même temps ;
• n'utilisez pas SQLite : chaque serveur ne verrait que ses propres statistiques. Si l'addon zAuctionHouseRedis est installé alors que l'addon utilise SQLite, un avertissement est affiché au démarrage ;
• chaque vente conserve le nom de serveur configuré dans zAuctionHouse ;
• utilisez le même statistics.timezone sur tous les serveurs ;
• si vous devez utiliser le mode dégradé de lecture des logs (collection.mode: LOGS_POLLING), activez collection.polling.enabled sur un seul serveur. Les serveurs en LOGS_POLLING avec la lecture désactivée ne collectent rien et affichent un avertissement.

Vérifier l'installationCopier le lien vers ce titre

ConsoleCopier le lien vers ce titre

Un démarrage réussi affiche des lignes similaires à :

Storage ready (SQLITE, prefix 'zahstats_').
Statistics collection: zAuctionHouse stats events.
zMenu inventories loaded (language: en).
PlaceholderAPI expansion 'zahstats' registered.
zAuctionHouseStats 2.0.0 enabled.

La ligne PlaceholderAPI n'apparaît que si PlaceholderAPI est installé.

En jeuCopier le lien vers ce titre

Toutes les permissions sont accordées par défaut aux opérateurs. Le menu d'administration (admin.yml, ouvert depuis le hub avec zauctionhouse.stats.admin) affiche le type de stockage, le mode de collecte et l'état de la file d'écriture et des caches.

Les statistiques sont écrites en base de données toutes les quelques secondes (flush.interval-seconds, 2 par défaut, ou plus tôt dès que flush.max-pending événements sont en attente). Sur le serveur où la vente a lieu, les statistiques des joueurs déjà en cache et les statistiques globales sont mises à jour immédiatement. Les classements sont recalculés à l'expiration de leur cache (caches.leaderboard-ttl-seconds, 60 par défaut) et les prix des objets toutes les heures (caches.material-price-ttl-seconds, 3600) : une nouvelle vente peut donc mettre ce temps à y apparaître. Utilisez /zahstats clearcache pour forcer un rafraîchissement immédiat des caches.

Voir Commandes & Permissions pour la référence complète.

Mise à jour depuis la V1Copier le lien vers ce titre

zAuctionHouseStats V2 fonctionne uniquement avec zAuctionHouse V4. Votre historique V1 (tables zah_*) et les logs de zAuctionHouse V4 peuvent être importés dans les nouvelles tables avec /zahstats import v1 et /zahstats import v4logs : sans confirm, la commande affiche seulement un aperçu (nombre de lignes et durée estimés), /zahstats import <v1|v4logs> confirm lance l'import. Les placeholders de la V1 continuent de fonctionner grâce à des alias de compatibilité (placeholders.enable-v1-aliases).

Définissez le fuseau horaire avant l'import, puis suivez le guide de Migration.

Prochaines étapesCopier le lien vers ce titre

• Commandes & Permissions - Référence complète des commandes
• Placeholders - Affichez les statistiques n'importe où
• Configuration - Toutes les options de config.yml
• Inventaires - Personnalisez les menus