> 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/challenges.md).

# Challenges

{% hint style="danger" %}
Les challenges sont temporairement indisponible suite à la mise à jour incluant les modules le temps de refaire le système et d'optimiser le plus possible le tout.
{% endhint %}

> 💡 **Interface d'Administration** : Les challenges peuvent être configurés directement en jeu via l'interface d'administration accessible avec `/challenges admin` (permission requise : `horizons.challenges.admin`)

## 📑 Table des Matières

1. [🎯 Introduction](#introduction)
2. [🏗️ Structure de Base](#structure-de-base)
3. [🎮 Types de Challenges](#types-de-challenges)
4. [⚡ Triggers Disponibles](#triggers-disponibles)
5. [🔄 Types de Répétition](#types-de-répétition)
6. [🎁 Configuration des Récompenses](#configuration-des-récompenses)
7. [📢 Système de Notifications](#système-de-notifications)
8. [📝 Exemples Complets](#exemples-complets)
9. [✅ Validation et Commandes](#validation-et-commandes)
10. [🔐 Permissions](#permissions)
11. [💡 Conseils et Bonnes Pratiques](#conseils-et-bonnes-pratiques)

***

## 🎯 Introduction

Le système de challenges d'Horizons permet de créer des défis personnalisés pour vos joueurs. Ces challenges peuvent être individuels, d'équipe ou globaux, avec de nombreuses possibilités de configuration.

### Fichier de Configuration

Tous les challenges sont configurés dans le fichier `challenges.yml` situé dans le dossier du plugin.

***

## 🏗️ Structure de Base

Chaque challenge suit cette structure de base :

```yaml
challenges:
  nom_du_challenge:
    name: "&7Nom Affiché du Challenge"
    description:
      - "&7Première ligne de description"
      - "&7Deuxième ligne de description"
    type: "PLAYER"  # PLAYER, TEAM, ou GLOBAL
    trigger: "BLOCK_BREAK"  # Type d'événement
    trigger-data:  # Configuration spécifique au trigger
      material: "STONE"
    target-amount: 100  # Objectif à atteindre
    repeat-type: "DAILY"  # Type de répétition
    display:  # Affichage dans l'interface
      item: "STONE"
      slot: 0
      lore:
        - "&7Progression: &e{progress}/{target}"
    notification:  # Configuration des notifications
      type: "CHAT"
      message: "&aChallenge terminé !"
    rewards:  # Récompenses
      score:
        type: "PLAYER_SCORE"
        amount: 50
```

***

## 🎮 Types de Challenges

### PLAYER

* **Description** : Challenge individuel pour chaque joueur
* **Progression** : Chaque joueur a sa propre progression
* **Utilisation** : Défis personnels, objectifs individuels

### TEAM

* **Description** : Challenge d'équipe où tous les membres contribuent
* **Progression** : Progression partagée entre les membres de l'équipe
* **Utilisation** : Défis collaboratifs, objectifs d'équipe

### GLOBAL

* **Description** : Challenge pour tout le serveur
* **Progression** : Un seul joueur ou une équipe peut le compléter
* **Utilisation** : Événements serveur, premiers à accomplir quelque chose

***

## ⚡ Triggers Disponibles

### 🏗️ Construction et Destruction

* **`BLOCK_BREAK`** : Casser des blocs
* **`BLOCK_PLACE`** : Placer des blocs

### ⚔️ Combat

* **`ENTITY_KILL`** : Tuer des entités (mobs)
* **`PLAYER_KILL`** : Tuer d'autres joueurs
* **`DAMAGE_DEAL`** : Infliger des dégâts
* **`DAMAGE_TAKE`** : Subir des dégâts
* **`DEATH`** : Mourir

### 🎯 Activités

* **`ITEM_CRAFT`** : Crafter des objets
* **`ITEM_CONSUME`** : Consommer des objets
* **`FISH_CATCH`** : Pêcher
* **`ENCHANT_ITEM`** : Enchanter des objets
* **`TRADE_VILLAGER`** : Commercer avec des villageois
* **`POTION_BREW`** : Brasser des potions

### 🐾 Animaux

* **`TAME_ANIMAL`** : Apprivoiser des animaux
* **`BREED_ANIMAL`** : Faire reproduire des animaux

### 🚶 Déplacement et Exploration

* **`DISTANCE_WALK`** : Marcher une certaine distance
* **`DISTANCE_FLY`** : Voler une certaine distance
* **`BIOME_ENTER`** : Entrer dans des biomes
* **`DIMENSION_ENTER`** : Entrer dans des dimensions
* **`WORLD_CHANGE`** : Changer de monde

### 📈 Progression

* **`EXPERIENCE_GAIN`** : Gagner de l'expérience
* **`LEVEL_UP`** : Monter de niveau

### 💬 Social

* **`JOIN_SERVER`** : Se connecter au serveur
* **`CHAT_MESSAGE`** : Envoyer des messages
* **`COMMAND_USE`** : Utiliser des commandes

***

## ⚙️ Configuration des Trigger-Data

### Pour BLOCK\_BREAK et BLOCK\_PLACE

```yaml
trigger-data:
  material: "STONE"  # Un seul matériau
  # OU
  materials:  # Liste de matériaux
    - "STONE"
    - "COBBLESTONE"
    - "GRANITE"
```

### Pour ENTITY\_KILL

```yaml
trigger-data:
  entity: "ZOMBIE"  # Une seule entité
  # OU
  entities:  # Liste d'entités
    - "ZOMBIE"
    - "SKELETON"
    - "CREEPER"
```

### Pour BIOME\_ENTER

```yaml
trigger-data:
  biome: "DESERT"  # Un biome spécifique
  # OU
  biomes:  # Liste de biomes
    - "DESERT"
    - "FOREST"
    - "JUNGLE"
  # OU vide pour tous les biomes
  # trigger-data: {}
```

### Pour DIMENSION\_ENTER

```yaml
trigger-data:
  to_dimension: "NETHER"  # NORMAL, NETHER, THE_END
```

### Pour WORLD\_CHANGE

```yaml
trigger-data:
  to_world: "world_nether"  # Monde de destination
  from_world: "world"      # Monde d'origine (optionnel)
```

***

## 🔄 Types de Répétition

### UNIQUE

* **Description** : Ne peut être complété qu'une seule fois
* **Utilisation** : Achievements permanents, premières fois

### UNLIMITED

* **Description** : Peut être répété indéfiniment
* **Configuration** : Optionnel `cooldown-seconds` pour limiter la fréquence

### DAILY

* **Description** : Se remet à zéro chaque jour
* **Reset** : Minuit (heure du serveur)

### WEEKLY

* **Description** : Se remet à zéro chaque semaine
* **Reset** : Lundi à minuit

### COOLDOWN

* **Description** : Cooldown personnalisé entre les complétions
* **Configuration** : Requis `cooldown-seconds`

### LIMITED\_COUNT

* **Description** : Nombre limité de complétions
* **Configuration** : Requis `max-completions`

```yaml
# Exemple avec cooldown
repeat-type: "COOLDOWN"
cooldown-seconds: 3600  # 1 heure

# Exemple avec limite
repeat-type: "LIMITED_COUNT"
max-completions: 5
```

***

## 🎁 Configuration des Récompenses

### Types de Récompenses

#### PLAYER\_SCORE

```yaml
rewards:
  score:
    type: "PLAYER_SCORE"
    amount: 100
```

#### TEAM\_SCORE

```yaml
rewards:
  team_score:
    type: "TEAM_SCORE"
    amount: 150
```

#### ITEM

```yaml
rewards:
  item:
    type: "ITEM"
    material: "DIAMOND"
    amount: 5
```

#### COMMAND

```yaml
rewards:
  command:
    type: "COMMAND"
    command: "give {player} golden_apple 1"
```

#### EXPERIENCE

```yaml
rewards:
  xp:
    type: "EXPERIENCE"
    amount: 100
```

#### MONEY (si Vault installé)

```yaml
rewards:
  money:
    type: "MONEY"
    amount: 500
```

### Récompenses Multiples

```yaml
rewards:
  score:
    type: "PLAYER_SCORE"
    amount: 100
  item:
    type: "ITEM"
    material: "DIAMOND"
    amount: 1
  command:
    type: "COMMAND"
    command: "effect give {player} speed 60 1"
```

***

## 📢 Système de Notifications

### Types de Notifications

#### CHAT

```yaml
notification:
  type: "CHAT"
  message: "&a✓ Challenge terminé !"
```

#### ACTIONBAR

```yaml
notification:
  type: "ACTIONBAR"
  message: "&e🎯 Objectif atteint !"
```

#### TITLE

```yaml
notification:
  type: "TITLE"
  message: "&b🏆 CHALLENGE TERMINÉ !"
```

#### SUBTITLE

```yaml
notification:
  type: "SUBTITLE"
  message: "&7Félicitations !"
```

#### BOSSBAR

```yaml
notification:
  type: "BOSSBAR"
  message: "&6🎉 Challenge accompli !"
```

### Configuration Audio

```yaml
notification:
  type: "CHAT"
  message: "&aChallenge terminé !"
  sound: "ENTITY_PLAYER_LEVELUP"  # Son Minecraft
  volume: 1.0  # Volume (0.0 à 1.0)
  pitch: 1.0   # Hauteur (0.5 à 2.0)
```

### Variables Disponibles

* `{player}` : Nom du joueur
* `{progress}` : Progression actuelle
* `{target}` : Objectif à atteindre
* `{completions}` : Nombre de complétions
* `{status}` : Statut du challenge

***

## 🖼️ Configuration de l'Affichage

### Interface Graphique

```yaml
display:
  item: "DIAMOND"  # Matériau d'affichage
  slot: 0          # Position dans l'interface (0-53)
  lore:            # Description supplémentaire
    - "&7Progression: &e{progress}/{target}"
    - ""
    - "&7Statut: {status}"
    - "&7Complétions: &e{completions}"
```

***

## 📝 Exemples Complets

### Challenge de Minage Simple

```yaml
mine_diamonds:
  name: "&b💎 Mineur de Diamant"
  description:
    - "&7Minez 10 minerais de diamant"
    - "&7pour devenir un mineur expert"
  type: "PLAYER"
  trigger: "BLOCK_BREAK"
  trigger-data:
    material: "DIAMOND_ORE"
  target-amount: 10
  repeat-type: "WEEKLY"
  display:
    item: "DIAMOND_ORE"
    slot: 1
  notification:
    type: "TITLE"
    message: "&b💎 Mineur de Diamant !"
    sound: "ENTITY_PLAYER_LEVELUP"
  rewards:
    score:
      type: "PLAYER_SCORE"
      amount: 200
```

### Challenge d'Équipe Complexe

```yaml
team_builder:
  name: "&6🏗️ Constructeurs d'Équipe"
  description:
    - "&7Votre équipe doit placer"
    - "&7500 blocs de construction"
  type: "TEAM"
  trigger: "BLOCK_PLACE"
  trigger-data:
    materials:
      - "STONE_BRICKS"
      - "BRICKS"
      - "COBBLESTONE"
      - "WOOD_PLANKS"
  target-amount: 500
  repeat-type: "DAILY"
  display:
    item: "BRICKS"
    slot: 11
  notification:
    type: "BOSSBAR"
    message: "&6🏗️ Équipe de Constructeurs !"
  rewards:
    team_score:
      type: "TEAM_SCORE"
      amount: 300
    command:
      type: "COMMAND"
      command: "effect give @a[team={team}] speed 300 1"
```

### Challenge Global Unique

```yaml
first_nether:
  name: "&c🔥 Pionnier du Nether"
  description:
    - "&7Soyez le premier joueur"
    - "&7à entrer dans le Nether !"
  type: "GLOBAL"
  trigger: "DIMENSION_ENTER"
  trigger-data:
    to_dimension: "NETHER"
  target-amount: 1
  repeat-type: "UNIQUE"
  display:
    item: "OBSIDIAN"
    slot: 20
  notification:
    type: "CHAT"
    message: "&c🔥 {player} est le premier à entrer dans le Nether !"
    sound: "UI_TOAST_CHALLENGE_COMPLETE"
  rewards:
    score:
      type: "PLAYER_SCORE"
      amount: 500
    item:
      type: "ITEM"
      material: "FIRE_RESISTANCE_POTION"
      amount: 3
```

***

## ✅ Validation et Commandes

### Commandes Disponibles

* `/challenges` : Ouvre l'interface des challenges
* `/challenges admin` : Ouvre l'interface d'administration (permission requise)
* `/challenges reload` : Recharge la configuration (permission requise)
* `/challenges reset <player/team/global> [challenge]` : Remet à zéro la progression (permission requise)
* `/challenges info <challenge>` : Informations sur un challenge
* `/challenges progress <player> [challenge]` : Progression d'un joueur

***

## 🔐 Permissions

#### `horizons.challenges.admin`

* **Description** : Accès complet à l'administration des challenges
* **Fonctionnalités** :
  * Interface d'administration (`/challenges admin`)
  * Création, modification et suppression de challenges
  * Gestion des récompenses et paramètres avancés
  * Accès à toutes les fonctionnalités d'édition

#### `horizons.challenges.reload`

* **Description** : Rechargement de la configuration des challenges
* **Fonctionnalités** :
  * Commande `/challenges reload`
  * Rechargement à chaud des challenges depuis les fichiers

#### `horizons.challenges.reset`

* **Description** : Réinitialisation des progressions de challenges
* **Fonctionnalités** :
  * `/challenges reset player <nom>` - Reset d'un joueur spécifique
  * `/challenges reset team <nom>` - Reset d'une équipe complète
  * `/challenges reset global` - Reset de tous les challenges globaux

### Commandes Sans Permission

Ces commandes sont **accessibles à tous les joueurs** :

* `/challenges` - Interface principale des challenges
* `/challenges gui [type]` - Interface par type de challenge
* `/challenges info <id>` - Informations détaillées sur un challenge
* `/challenges progress <id>` - Consultation de sa progression personnelle
* `/challenges help` - Aide et liste des commandes

***

## 💡 Conseils et Bonnes Pratiques

### 🎯 Conception des Challenges

1. **Équilibrage** : Ajustez les objectifs selon la difficulté
2. **Progression** : Créez des challenges de difficulté croissante
3. **Variété** : Utilisez différents triggers pour diversifier
4. **Récompenses** : Équilibrez les récompenses avec l'effort requis

### 🔧 Configuration Technique

1. **Sauvegarde** : Sauvegardez toujours avant modification
2. **Reload** : Utilisez `/challenges reload` pour appliquer les changements
3. **Logs** : Consultez les logs en cas d'erreur

### 📊 Performance

1. **Slots** : Évitez les doublons de slots dans l'interface
2. **Triggers** : Les triggers fréquents (CHAT\_MESSAGE) peuvent impacter les performances
3. **Cooldowns** : Utilisez des cooldowns pour limiter le spam

***

## 🛠️ Support et Dépannage

### Problèmes Courants

**Challenge ne se déclenche pas :**

* Vérifiez le trigger et les trigger-data
* Confirmez que le challenge est actif
* Consultez les logs pour les erreurs

**Erreurs de configuration :**

* Vérifiez la syntaxe YAML
* Consultez les messages d'erreur détaillés

**Récompenses non distribuées :**

* Vérifiez la configuration des rewards
* Confirmez les permissions nécessaires
* Testez avec des récompenses simples

### Logs et Debug

Les logs du plugin fournissent des informations détaillées sur :

* Chargement des challenges
* Erreurs de configuration
* Progression des joueurs
* Distribution des récompenses

***

*Cette documentation couvre toutes les fonctionnalités du système de challenges d'Horizons. Pour des questions spécifiques ou des problèmes, consultez les logs du serveur ou contactez le support.*


---

# 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/challenges.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.