🛍️Shops

Ce document détaille la configuration du système de shop dans le plugin Horizons.

📌 Note: Pour utiliser les boutiques, assurez-vous que le plugin Citizens soit installé sur le serveur. 🛠️

🛒 Configuration des Shops

Cette section concerne les paramètres de configuration dans config.yml

⚙️ Paramètres de Configuration

🕐 Fréquence de mise à jour

Cette option configure l'intervalle à laquelle les prix des articles dans les shops sont automatiquement mis à jour. La valeur par défaut est "15m" (15 minutes).

Le format accepte différentes unités de temps:

• s pour secondes

• m pour minutes

• h pour heures

💡 Exemple d'utilisation

shops:
  # Intervalle de mise à jour des prix (format: 15m, 1h, etc.)
  # Contrôle la fréquence à laquelle les prix de tous les shops sont mis à jour
  price_update_interval: "15m"

À chaque intervalle, le système exécute la méthode pour tous les shops configurés, recalculant les prix selon les paramètres de prix dynamiques définis pour chaque article.

🔊 Sons de l'Interface

sounds:
  # Son joué lors de l'ouverture d'un shop
  open: "block.chest.open"
  # Son joué lors de la fermeture d'un shop
  close: "block.chest.close"
  # Son joué lors d'une vente réussie
  purchase_success: "entity.player.levelup"
  # Son joué lors d'une vente échouée
  purchase_fail: "entity.villager.no"
  # Son joué lors du changement de page
  page_change: "item.book.page_turn"

💬 Messages d'Interaction

  messages:
    # Message lors d'une vente réussie (supporte {points} pour le montant)
    purchase_success: "§aVendu pour §e{points} §apoints!"
    # Message lors d'une vente échouée
    purchase_fail: "§cVous n'avez pas cet objet dans votre inventaire!"

💡 Exemple complet

shops:
  price_update_interval: 15m  # Intervalle de mise à jour des prix (s: secondes, m: minutes, h: heures)
  # Configuration des sons
  sounds:
    open: BLOCK_CHEST_OPEN        # Son d'ouverture du shop
    close: BLOCK_CHEST_CLOSE      # Son de fermeture du shop
    page_change: UI_BUTTON_CLICK  # Son lors du changement de page
    purchase_success: ENTITY_PLAYER_LEVELUP  # Son lors d'une vente réussie
    purchase_fail: ENTITY_VILLAGER_NO       # Son lors d'une vente échouée
    volume: 1.0                   # Volume des sons (entre 0.0 et 1.0)
    pitch: 1.0                    # Tonalité des sons (entre 0.5 et 2.0)
  # Messages personnalisables
  messages:
    purchase_success: "&aVous avez gagné {points} points pour votre équipe!"
    purchase_fail: "&cVous n'avez pas l'item requis!"
  # Mode de stockage des prix
  storage:
    type: "JSON"                  # Type de stockage: "JSON" ou "MYSQL"
    # Configuration MySQL (uniquement si type est "MYSQL")
    mysql:
      host: "localhost"
      port: 3306
      database: "horizons"
      username: "user"
      password: "password"
      table_prefix: "hz_"

💾 Système de Sauvegarde des Prix des shops

Le plugin Horizons propose deux méthodes de stockage pour les prix des shops permettant une persistance des prix après rechargement du plugin.

📄 Stockage JSON

• Les prix sont sauvegardés dans des fichiers JSON dans le dossier plugins/Horizons/data/shop_prices/

• Chaque shop a son propre fichier (ex: example_shop::Forgeron.json)

• Avantages: simple, pas de dépendance externe

• Configuration par défaut, ne nécessite aucune configuration supplémentaire

🗃️ Stockage MySQL (optionnel)

• Les prix sont sauvegardés dans une base de données MySQL

• Idéal pour les serveurs multi-instances ou avec beaucoup de shops

• Nécessite une configuration dans la section shops.storage.mysql

• Les tables sont créées automatiquement lors du premier démarrage

• Permet une synchronisation des prix en temps réel entre plusieurs serveurs

⏱️ Les prix sont automatiquement sauvegardés:

• À intervalles réguliers (configurable via price_update_interval)

• Lors de la désactivation du plugin

• Lors du rechargement des configurations

Pour changer le mode de stockage, modifiez simplement shops.storage.type dans la configuration principale.

🎮 Interactions avec les Shops

Les shop gèrent les interactions suivantes :

• 🖱️ Clic gauche sur un item : Vend une unité de cet item au prix actuel.

• 🖱️ Clic droit sur un item : Vend tous les items du même type dans l'inventaire du joueur.

• 🔄 Clic sur une flèche : Permet de naviguer entre les pages du shop.

  • ⬅️ Flèche gauche (emplacement 45) : Page précédente.

  • ➡️ Flèche droite (emplacement 53) : Page suivante.

💰 Format d'Affichage des Prix

Les prix sont affichés dans l'interface avec une tendance indiquant leur évolution :

• 📈 Augmentation : ↑

• 📉 Diminution : ↓

• ➡️ Stable : →

🏪 Association avec les NPCs

Les shops sont automatiquement associés à des NPCs Citizens par leur ID. Lorsqu'un joueur fait un clic droit sur un NPC :

1. 🎵 Le son configuré est joué.

2. 🛍️ Le shop correspondant s'ouvre automatiquement.

3. 📦 L'interface s'affiche avec les items disponibles.

📝 Structure des Shops

Les shops sont configurés dans des fichiers YAML situés dans le dossier plugins/Horizons/shops/. Chaque fichier représente une ou plusieurs boutiques avec un ou plusieurs NPCs.

🏪 Configuration des NPCs

shop:
  ID_DU_VENDEUR: #Peut être un nombre ou du texte
    display_name: '&6&lNom du vendeur'
    entity_type: VILLAGER
    profession: ARMORER
    villager_type: PLAINS
    Position:
      world: world
      x: 0
      y: 64
      z: 0
    gui_title: '&6Nom du GUI'
    items:
      DIAMOND_SWORD:
        pricing:
          type: STATIC
          base_price: 500
      NETHERITE_CHESTPLATE:
        pricing:
          type: STATIC
          base_price: 2000
      DIAMOND_PICKAXE:
        pricing:
          type: DYNAMIC
          base_price: 300
          min_price: 150
          max_price: 600
          adjustment:
            type: SUPPLY_DEMAND
            demand_multiplier: 0.15
            supply_threshold: 50
            cooldown_rate: 0.03
      GOLDEN_APPLE:
        quantity: 8
        pricing:
          type: DYNAMIC
          base_price: 120
          min_price: 80
          max_price: 250
          adjustment:
            type: FIXED_PERCENTAGE
            change_rate: 0.05
            supply_threshold: 30
      ENCHANTED_GOLDEN_APPLE:
        pricing:
          type: DYNAMIC
          base_price: 1500
          min_price: 1000
          max_price: 3000
          adjustment:
            type: SUPPLY_DEMAND
            demand_multiplier: 0.2
            supply_threshold: 10
            cooldown_rate: 0.02

⚙Configuration des NPCs

Options Disponibles

Paramètre	Description	Obligatoire
display_name	Nom affiché du NPC (supporte les codes couleur)	Oui
entity_type	Type d'entité (VILLAGER, PLAYER, etc.)	Oui
Position	Section contenant les coordonnées	Oui
gui_title	Titre de l'interface du shop	Oui

Types d'Entités Spécifiques

Villageois

shop:
  Forgeron:
    display_name: "&c&lForgeron"
    entity_type: "VILLAGER"
    profession: "WEAPONSMITH"  # Type de métier
    villager_type: "PLAINS"    # Type de biome

Professions disponibles : ARMORER, BUTCHER, CARTOGRAPHER, CLERIC, FARMER, FISHERMAN, FLETCHER, LEATHERWORKER, LIBRARIAN, MASON, NITWIT, NONE, SHEPHERD, TOOLSMITH, WEAPONSMITH

Types de villageois : DESERT, JUNGLE, PLAINS, SAVANNA, SNOW, SWAMP, TAIGA

Joueur avec Skin

shop:
  Trader:
    display_name: "&6&lTrader Elite"
    entity_type: "PLAYER"
    skin_name: "Notch"  # Nom du skin à utiliser

⚙ Configuration des Items

Chaque item du shop est configuré dans la section items avec l'identifiant Minecraft de l'item comme clé.

Système de Prix

Prix Statique

items:
  DIAMOND:
    pricing:
      type: "STATIC"
      base_price: 100          # Prix fixe

Prix Dynamique (Offre et Demande)

items:
  BREAD:
    pricing:
      type: "DYNAMIC"
      base_price: 50           # Prix de base
      min_price: 25            # Prix minimum
      max_price: 100           # Prix maximum
      adjustment:
        type: "SUPPLY_DEMAND"
        demand_multiplier: 0.15  # Multiplicateur de demande
        supply_threshold: 50     # Seuil de fourniture
        cooldown_rate: 0.05      # Taux de récupération

💡Exemple Complet

shop:
  Forgeron:
    display_name: "&c&lForgeron du Village"
    entity_type: "VILLAGER"
    profession: "WEAPONSMITH"
    villager_type: "PLAINS"
    Position:
      world: "world"
      x: 100
      y: 64
      z: 200
    gui_title: "&4Boutique d'Armement"
    items:
      DIAMOND_SWORD:
        pricing:
          type: "DYNAMIC"
          base_price: 1000
          min_price: 750
          max_price: 1500
          adjustment:
            type: "SUPPLY_DEMAND"
            demand_multiplier: 0.2
            supply_threshold: 20
            cooldown_rate: 0.05
      IRON_HELMET:
        pricing:
          type: "STATIC"
          base_price: 350
      BOW:
        pricing:
          type: "DYNAMIC"
          base_price: 250
          min_price: 150
          max_price: 400
          adjustment:
            type: "FIXED_PERCENTAGE"
            supply_threshold: 30
            change_rate: 0.1

Fonctionnement des Prix Dynamiques

Mode SUPPLY_DEMAND (Offre et Demande)

• Les prix diminuent à mesure que les joueurs vendent des items (demande élevée)

• Le calcul des prix est basé sur la formule : priceChange = -demandMultiplier * (salesCount/supplyThreshold)^1.5

• Plus le nombre de ventes (salesCount) s'approche ou dépasse le seuil (supplyThreshold), plus la baisse est importante

• Le taux de baisse dépend du demand_multiplier et du nombre d'achats par rapport au supply_threshold

• Quand aucun achat n'est effectué, les prix remontent lentement selon le cooldown_rate

Mode FIXED_PERCENTAGE (Pourcentage Fixe)

• Les prix augmentent régulièrement selon le change_rate si peu de ventes sont effectués

• Quand les ventes dépassent le supply_threshold, les prix diminuent proportionnellement selon la formule :

• priceChange = -changeRate * (salesCount/supplyThreshold)^1.2

• La diminution s'intensifie de manière exponentielle lorsque le nombre de ventes dépasse largement le seuil

🔢 Système de quantités

⚙Configuration des quantités

Chaque item dans un shop peut avoir une quantité configurée qui détermine combien d'items sont vendus par transaction :

items:
  NETHERITE_INGOT:
    quantity: 5
    pricing:
      type: "STATIC"
      base_price: 1000          

🤖Fonctionnement des quantités

🖱️ Clic gauche (Vente de quantité configurée)

• Vend exactement la quantité configurée d'items

• Le prix affiché est pour la quantité complète

• Exemple : avec quantity: 5 et un prix de vente à 1000, un clic gauche vend 5 items pour 1000 points

🖱️ Clic droit (Vente maximale)

• Vend le maximum possible en multiples de la quantité configurée

• Le prix est multiplié par le nombre de sets vendus

• Exemple : avec 12 items, quantity: 4, et un prix de vente à 1000 → vend 3 sets (12 items) pour 3000 points