🛍️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 FancyNPCsarrow-up-right 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

Les sons peuvent être configurés à deux niveaux :

  1. Globalement dans config.yml → s'applique à tous les shops

  2. Par shop/NPC dans le fichier de shop → surcharge les sons globaux

Hiérarchie de priorité : Configuration NPC > Configuration globale

Configuration globale (config.yml)

Configuration par shop (fichier de shop)

Vous pouvez surcharger les sons pour un shop spécifique :

💡 Astuce : Les sons par shop sont optionnels. Si non spécifiés, les sons globaux seront utilisés.

💬 Messages d'Interaction

💡 Exemple complet

💾 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 FancyNPCs 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.

🎯 Modes de Trigger

Le plugin propose deux modes pour ouvrir un shop : via NPC ou via commande.

Mode NPC (par défaut)

C'est le comportement classique : un NPC FancyNpcs est créé aux coordonnées spécifiées et le shop s'ouvre au clic.

Mode Command

Ce mode permet d'ouvrir un shop sans créer de NPC. Idéal pour l'intégration avec d'autres plugins de NPC ou autres plugins (menus customs, blocs interactifs, etc.)

Ouverture via Commande

La commande pour ouvrir un shop est réservée à la console ou aux administrateurs (permission horizons.admin).

Exemple :

⚠️ Sécurité : Les joueurs normaux ne peuvent PAS utiliser cette commande, même avec des permissions shop. Cela permet aux autres plugins d'exécuter la commande via console sans risque.

Intégration avec d'autres plugins :

💡 Pour l'API Java complète, voir la documentation APIarrow-up-right.

📝 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

⚙ 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

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

🎨 Configuration de l'Interface (GUI)

Les shops peuvent avoir une interface entièrement personnalisable. Si non spécifié, une configuration par défaut est utilisée.

📊 Hiérarchie de Priorité

La configuration GUI suit une hiérarchie de 3 niveaux. Le système cherche chaque paramètre dans cet ordre :

Priorité
Source
Chemin

1 (Plus haute)

Configuration NPC

shop.NPC_ID.gui.*

2

Defaults du fichier

shop.gui_default.*

3

Defaults globaux

config.ymlshops.gui_defaults.*

4 (Fallback)

Valeurs codées en dur

Voir tableau ci-dessous

💡 Astuce : Vous pouvez définir des defaults dans config.yml pour tous les shops, puis les surcharger au niveau fichier ou NPC.

📦 Valeurs par Défaut (Fallback)

Si aucune configuration n'est trouvée, ces valeurs sont utilisées :

Paramètre
Valeur par défaut

rows

6

layout.items.slots

Slots 10-16, 19-25, 28-34, 37-43 (7 colonnes × 4 lignes au centre)

layout.pagination.previous.slot

45

layout.pagination.next.slot

53

layout.border.item.material

BLACK_STAINED_GLASS_PANE

layout.border.item.name

(espace)

🔧 Structure Complète

📐 Cas de Figures et Exemples

Cas 1: Shop Minimal (utilise tous les defaults)

Résultat : GUI de 6 lignes, bordure noire, items au centre, pagination en bas.


Cas 2: Petit Shop (3 lignes)


Cas 3: Shop avec Layout Custom (style grille espacée)


Cas 4: Defaults au niveau fichier


Cas 5: Configuration globale dans config.yml

Note : Cette configuration s'applique à TOUS les shops du serveur, sauf s'ils ont leur propre configuration.

⚠️ Points Importants

  1. Les slots d'items sont exclusifs : Un slot ne peut pas être à la fois un slot d'item ET un slot de pagination.

  2. Le remplissage de bordure est intelligent : Avec slots: [0, 53], le système remplit tous les slots SAUF ceux définis pour les items et la pagination.

  3. La pagination est optionnelle : Si vous avez peu d'items (tous tiennent sur une page), les flèches n'apparaîtront pas.

🖼️ Format d'Affichage des Items

Vous pouvez personnaliser comment les items sont affichés dans le shop (nom et description).

Placeholders Disponibles :

  • %name% : Nom de l'item

  • %price% : Prix actuel

  • %currency% : Nom de la monnaie (ex: Emeralds)

  • %trend% : Flèche de tendance (↑, ↓, →)

  • %tier% : Numéro du palier actuel (pour les items TIERED)

  • %amount% : Quantité vendue par transaction

  • %amount_click_left% : Quantité vendue au clic gauche

⚙ 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

Le plugin supporte plusieurs modes de tarification définis par le paramètre type dans la section pricing.

1. Prix Statique (STATIC)

Le prix ne change jamais. Il reste fixé au base_price défini.

2. Prix Dynamique (SUPPLY_DEMAND / FIXED_PERCENTAGE)

Utilise le type DYNAMIC et une stratégie d'ajustement.

3. Prix par Paliers (TIERED)

Ce mode permet de définir des prix fixes qui évoluent selon le volume total cumulé des ventes de l'objet.

  • Le prix est déterminé par des paliers (tiers) de ventes cumulées.

  • Le base_price est utilisé tant que le premier palier n'est pas atteint (équivalent à un seuil de 0).

  • Les prix changent immédiatement au franchissement d'un palier (ce mode ignore l'intervalle de rafraîchissement global).

Paramètres spécifiques :

  • tiers: Section contenant la liste des paliers.

    • threshold: Nombre de ventes total requis pour atteindre ce palier.

    • price: Prix appliqué à partir de ce seuil.

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.

🤖 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

🎯 Scope des Prix (GLOBAL / PER_TEAM)

Le plugin permet de configurer si les prix sont partagés globalement ou calculés séparément par équipe.

Modes disponibles

Mode
Description

GLOBAL

Tous les joueurs voient le même prix. Les ventes de tous les joueurs affectent le même pool de prix. (Par défaut)

PER_TEAM

Chaque équipe a son propre marché indépendant. Les ventes d'une équipe n'affectent pas les prix des autres équipes.

Hiérarchie de priorité

Le scope est déterminé selon cette priorité (du plus prioritaire au moins prioritaire) :

  1. Niveau Item → Défini dans la section pricing de l'item

  2. Niveau Shop → Défini dans la configuration du NPC/shop

  3. Niveau Global → Défini dans config.yml sous shops.price_scope

Configuration

Niveau Global (config.yml)

Niveau Shop

Niveau Item

Exemple d'utilisation

Scénario : Compétition entre équipes

Avec price_scope: "PER_TEAM", chaque équipe gère son propre marché :

  • L'équipe Rouge vend beaucoup de diamants → Le prix baisse uniquement pour l'équipe Rouge

  • L'équipe Bleue n'a pas vendu de diamants → Le prix reste élevé pour l'équipe Bleue

Cela permet de créer des stratégies économiques où chaque équipe doit gérer son propre marché !

Mis à jour