> For the complete documentation index, see [llms.txt](https://horizons-cite-plugin.gitbook.io/horizons-cite-plugin/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://horizons-cite-plugin.gitbook.io/horizons-cite-plugin/configurations/items-customs.md).

# Items Customs

## 📝 Introduction

Le système de shops et blackmarkets d'Horizons supporte l'utilisation d'items custom provenant de plugins externes. Cela vous permet d'ajouter des items personnalisés avec leurs propres modèles 3D, textures et comportements dans vos boutiques.

## 🔌 Plugins Supportés

### ✅ ItemsAdder

### ✅ Oraxen

**Statut:** Implémenté et testé

Le plugin **ItemsAdder et Oraxen** sont actuellement les seuls provider d'items custom supporté. D'autres providers peuvent être ajoutés à l'avenir.

## 📋 Format de Configuration

### Format de Clé d'Item Custom

Les items custom sont identifiés par leur format de clé unique. Le format est **obligatoire** et doit contenir exactement 3 parties séparées par `:` :

**Format obligatoire:** `provider:namespace:item_id`

**Exemples:**

* `itemsadder:iaalchemy:demoniac_pickaxe`
* `itemsadder:myitems:ruby_sword`
* `itemsadder:weapons:magic_staff`
* `oraxen:demoniac_sword`

### Identification Automatique

Un item est automatiquement reconnu comme custom si :

* La clé contient **au moins deux** caractères `:` (format `provider:namespace:item_id`)
* OU le flag `custom_item: true` est présent dans la configuration

**⚠️ Important:** Le format `provider:item_id` (2 parties) n'est **PAS** supporté. Vous devez toujours utiliser le format complet avec namespace.

## 🛒 Configuration dans les Shops

### Syntaxe de Base

```yaml
shop:
  Forgeron:
    display_name: "&c&lForgeron"
    entity_type: "VILLAGER"
    profession: "WEAPONSMITH"
    villager_type: "PLAINS"
    Position:
      world: "world"
      x: 100
      y: 64
      z: 200
    gui_title: "&4Boutique d'Armement"
    items:
      # Item vanilla (comme avant)
      DIAMOND_SWORD:
        pricing:
          type: "STATIC"
          base_price: 1000
      
      # Item custom avec prix statique
      "itemsadder:myitems:ruby_sword":
        pricing:
          type: "STATIC"
          base_price: 1500
      
      # Item custom avec prix dynamique (SUPPLY_DEMAND)
      "itemsadder:iaalchemy:demoniac_pickaxe":
        custom_item: true  # Optionnel mais recommandé
        pricing:
          type: "DYNAMIC"
          base_price: 2000
          min_price: 1500
          max_price: 3000
          adjustment:
            type: "SUPPLY_DEMAND"
            demand_multiplier: 0.15
            supply_threshold: 50
            cooldown_rate: 0.03
      
      # Item custom avec prix dynamique (FIXED_PERCENTAGE)
      "itemsadder:weapons:magic_staff":
        pricing:
          type: "DYNAMIC"
          base_price: 3000
          min_price: 2000
          max_price: 5000
          adjustment:
            type: "FIXED_PERCENTAGE"
            change_rate: 0.05
            supply_threshold: 30
```

## 🏴‍☠️ Configuration dans les Marchés Noirs

### Syntaxe de Base

```yaml
blackmarket:
  TraderNoir:
    display_name: "&8&lMarchand Noir"
    entity_type: "VILLAGER"
    profession: "NONE"
    villager_type: "DESERT"
    Position:
      world: "world"
      x: 200
      y: 64
      z: 300
    gui_title: "&8Marché Noir"
    items:
      # Item vanilla
      DIAMOND:
        stock: 5
        price: 1000
      
      # Item custom avec namespace complet
      "itemsadder:darkmagic:necromancer_staff":
        stock: 1
        price: 10000
```

### Format de Clé

* Le format `provider:namespace:item_id` est **obligatoire** pour les items custom (exactement 3 parties)
* Les clés doivent être entre guillemets dans le YAML si elles contiennent des caractères spéciaux
* Le provider doit être installé et chargé pour que les items fonctionnent
* Le format `provider:item_id` (2 parties) n'est **PAS** supporté

### Prix Dynamiques

✅ **Les items custom supportent tous les types de prix** (STATIC, DYNAMIC avec SUPPLY\_DEMAND ou FIXED\_PERCENTAGE), exactement comme les items vanilla.

Les prix dynamiques sont mis à jour automatiquement selon l'offre et la demande, et les tendances de prix (↑↓→) sont affichées dans l'interface du shop, au même titre que pour les items vanilla.

## 🔍 Dépannage

### L'item n'apparaît pas dans le shop

1. **Vérifier que le plugin provider est installé** (ex: ItemsAdder)
2. **Vérifier que l'item existe** dans le provider
3. **Vérifier le format de la clé** : doit être `provider:namespace:item_id` (exactement 3 parties séparées par `:`)
4. **Vérifier les logs** : des messages d'erreur détaillés sont affichés dans la console

### Erreur "Invalid custom item"

Cela signifie que :

* Le provider n'est pas installé
* L'item n'existe pas dans le provider
* Le format de la clé est incorrect

**Solution** : Vérifiez les logs de la console pour le message d'erreur détaillé.

## 🛠️ Commande de Debug

Horizons fournit une commande dédiée pour tester et gérer les items custom : `/customitems`

### Commandes disponibles

* `/customitems providers` - Liste les providers d'items custom chargés
* `/customitems test <provider:namespace:item_id>` - Teste si un item custom existe
* `/customitems give <provider:namespace:item_id> [amount]` - Donne un item custom
* `/customitems identify` - Identifie l'item tenu en main

**Alias:** `/ci`, `/citems`, `/citem`

**Permission:** `horizons.command.customitems`

### Plus de détails disponibles sur la [page de la commande](/horizons-cite-plugin/commandes/customitems.md)

### Cas d'utilisation

**Trouver l'ID d'un item custom :**

1. Tenez l'item en main
2. Exécutez `/customitems identify`
3. Utilisez l'ID complet affiché dans votre configuration

**Tester un item avant de l'ajouter à un shop :**

```
/customitems test itemsadder:namespace:item_name
```

**Vérifier que ItemsAdder est chargé :**

```
/customitems providers
```

Pour plus de détails, consultez la [documentation complète de la commande](broken://pages/e0a90bfd50e8589f7d136d6485282a65193f67b4).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://horizons-cite-plugin.gitbook.io/horizons-cite-plugin/configurations/items-customs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.