> 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/commandes/horizons/score/scores-alternatifs.md).

# Scores Alternatifs

Ce document détaille le système de scores alternatifs du plugin Horizons.

## 📝 Introduction

Le système de scores alternatifs permet de créer et gérer des types de scores personnalisés en plus du score global. Chaque type de score peut être utilisé pour compter des points spécifiques (kills, captures, etc.) et peut être lié au score global pour une synchronisation automatique.

## 🔑 Permission

{% hint style="info" %}

* `horizons.score`
  {% endhint %}

## 📋 Gestion des types de scores

{% stepper %}
{% step %}

### ➕ create

**Syntaxe:** `/score alt create <scoreType> [displayName] [--link]`

**Description:** Crée un nouveau type de score alternatif.

**Paramètres:**

* `<scoreType>` : Nom du type de score (lettres, chiffres et underscores uniquement)
* `[displayName]` : Nom d'affichage optionnel (peut contenir des espaces)
* `[--link]` : Option pour lier automatiquement ce score au score global

**Exemples:**

* `/score alt create kills` : Crée un type "kills" avec le nom d'affichage "kills"
* `/score alt create kills "Kills"` : Crée un type "kills" avec le nom d'affichage "Kills"
* `/score alt create kills "Kills" --link` : Crée un type "kills" lié au score global

**Note:** Si un score alternatif est lié au score global, toute modification de ce score alternatif mettra automatiquement à jour le score global.
{% endstep %}

{% step %}

### 🗑️ delete

**Syntaxe:** `/score alt delete <scoreType>`

**Description:** Supprime un type de score alternatif et tous les scores associés.

**Exemples:**

* `/score alt delete kills`

**⚠️ Attention:** Cette action supprime définitivement tous les scores de ce type pour tous les joueurs et équipes.
{% endstep %}

{% step %}

### 📋 list

**Syntaxe:** `/score alt list`

**Description:** Affiche tous les types de scores alternatifs enregistrés avec leur nom d'affichage et leur statut de lien.

**Exemple de sortie:**

```
Alternative Score Types:
- kills (Kills) (Linked to global)
- captures (Captures)
- deaths (Deaths)
```

{% endstep %}

{% step %}

### 🔗 link

**Syntaxe:** `/score alt link <scoreType> [--add|--remove]`

**Description:** Lie ou délie un type de score alternatif au score global.

**Paramètres:**

* `<scoreType>` : Le type de score à lier/délier
* `[--add]` : Force l'ajout du lien
* `[--remove]` : Force la suppression du lien
* Sans argument : Toggle le lien (ajoute si absent, retire si présent)

**Exemples:**

* `/score alt link kills` : Toggle le lien pour "kills"
* `/score alt link kills --add` : Force l'ajout du lien
* `/score alt link kills --remove` : Force la suppression du lien

**Note:** Quand un score est lié, tous les scores existants sont synchronisés avec le score global lors du linking.
{% endstep %}
{% endstepper %}

## 📋 Gestion des scores

### ✏️ set

**Syntaxe:** `/score alt <player/team> set <nom> <scoreType> <points>`

**Description:** Définit le score alternatif d'une équipe ou d'un joueur à une valeur spécifique.

**Exemples:**

* `/score alt team set Rouge kills 100`
* `/score alt player set John kills 50`

### ➕ add

**Syntaxe:** `/score alt <player/team> add <nom> <scoreType> <points>`

**Description:** Ajoute des points au score alternatif actuel d'une équipe ou d'un joueur.

**Exemples:**

* `/score alt team add Bleu kills 25`
* `/score alt player add Alice kills 15`

**Note:** Si le score est lié au score global, les points sont également ajoutés au score global.

### ➖ remove

**Syntaxe:** `/score alt <player/team> remove <nom> <scoreType> <points>`

**Description:** Retire des points au score alternatif actuel d'une équipe ou d'un joueur.

**Exemples:**

* `/score alt team remove Vert kills 10`
* `/score alt player remove Bob kills 5`

**Note:** Si le score est lié au score global, les points sont également retirés du score global.

### 📈 get

**Syntaxe:** `/score alt <player/team> get <nom> <scoreType>`

**Description:** Affiche le score alternatif actuel d'une équipe ou d'un joueur.

**Exemples:**

* `/score alt team get Jaune kills`
* `/score alt player get Emma kills`

## 🎮 Utilisation

### Pour les équipes

```
/score alt team set Rouge kills 100     # Définit le score de kills de l'équipe Rouge à 100
/score alt team add Bleu kills 50       # Ajoute 50 kills à l'équipe Bleu
/score alt team remove Vert kills 25    # Retire 25 kills de l'équipe Vert
/score alt team get Jaune kills         # Affiche le score de kills de l'équipe Jaune
```

### Pour les joueurs

```
/score alt player set John kills 75     # Définit le score de kills de John à 75
/score alt player add Alice kills 30    # Ajoute 30 kills à Alice
/score alt player remove Bob kills 10   # Retire 10 kills de Bob
/score alt player get Emma kills        # Affiche le score de kills d'Emma
```

## 🖼️ Interface Graphique

### Commande GUI

**Syntaxe:** `/score gui [player/team] [name]`

**Description:** Ouvre une interface graphique pour visualiser les scores.

**Exemples:**

* `/score gui` : Ouvre la GUI pour le joueur actuel
* `/score gui player` : Ouvre la liste des joueurs ayant des scores
* `/score gui team` : Ouvre la liste des équipes ayant des scores
* `/score gui player John` : Ouvre la GUI détaillée pour le joueur John
* `/score gui team Rouge` : Ouvre la GUI détaillée pour l'équipe Rouge

**Fonctionnalités:**

* Vue liste : Affiche tous les joueurs/équipes ayant des scores avec leurs têtes/icônes
* Vue détail : Affiche le score global et tous les scores alternatifs d'un joueur/équipe
* Navigation : Permet de switcher entre vue joueur et vue équipe
* Pagination : Automatique si trop de joueurs/équipes

## 🔗 Lien avec le score global

### Fonctionnement

Quand un score alternatif est lié au score global :

* Toute modification (set/add/remove) du score alternatif met automatiquement à jour le score global
* Lors du linking, tous les scores existants sont synchronisés avec le score global
* La différence entre l'ancien et le nouveau score est appliquée au score global

**Exemple:**

```
Score global actuel : 100
Score alternatif "kills" : 50 (lié au score global)

Si on ajoute 10 au score alternatif :
- Score alternatif "kills" : 60
- Score global : 110 (100 + 10)
```

### Synchronisation initiale

Lors du linking d'un score alternatif qui a déjà des points :

* Tous les scores existants des joueurs sont ajoutés à leur score global
* Tous les scores existants des équipes sont ajoutés à leur score global

## 📝 Placeholders

### Placeholders locaux (pour sidebar, etc.)

**Format:** `{alt_<scoreType>_player}` et `{alt_<scoreType>_team}`

**Exemples:**

* `{alt_kills_player}` : Score alternatif "kills" du joueur
* `{alt_kills_team}` : Score alternatif "kills" de l'équipe du joueur

### Placeholders PlaceholderAPI

**Format:** `%horizons_player_alt_score_<scoreType>%`

**Description:** Score alternatif d'un joueur spécifique.

**Exemples:**

* `%horizons_player_alt_score_kills%` : Score "kills" du joueur

**Format:** `%horizons_team_alt_score_<scoreType>%`

**Description:** Score alternatif de l'équipe du joueur.

**Exemples:**

* `%horizons_team_alt_score_kills%` : Score "kills" de l'équipe du joueur

**Format:** `%horizons_<teamName>_alt_score_<scoreType>%`

**Description:** Score alternatif d'une équipe spécifique.

**Exemples:**

* `%horizons_Rouge_alt_score_kills%` : Score "kills" de l'équipe "Rouge"

## 🔧 Skript

### Expression pour les joueurs

**Syntaxe:** `alt score %string% of %player%` ou `%player%'s alt score %string%`

**Description:** Récupère ou modifie le score alternatif d'un joueur.

**Exemples:**

```skript
set {kills} to alt score "kills" of player
set alt score "kills" of player to 100
add 10 to alt score "kills" of player
remove 5 from alt score "kills" of player
```

### Expression pour les équipes

**Syntaxe:** `alt score %string% of team %string%`

**Description:** Récupère ou modifie le score alternatif d'une équipe.

**Exemples:**

```skript
set {team_kills} to alt score "kills" of team "Rouge"
set alt score "kills" of team "Rouge" to 100
add 10 to alt score "kills" of team "Rouge"
remove 5 from alt score "kills" of team "Rouge"
```

## ⚠️ Restrictions

<details>

<summary>Voir les restrictions</summary>

* Les points doivent être des nombres entiers non négatifs
* Le nom du type de score (`scoreType`) ne peut contenir que des lettres, chiffres et underscores
* L'équipe doit exister pour pouvoir modifier son score
* Le joueur doit s'être connecté au moins une fois pour pouvoir modifier son score
* Le type de score doit être créé avant de pouvoir l'utiliser

</details>

## 💾 Stockage

Les scores alternatifs sont stockés dans :

* YAML : Fichier `data/alternative-scores.yml` (si storage YAML)
* MySQL : Tables `hz_alternative_scores_players` et `hz_alternative_scores_teams` (si storage MySQL)

Le type de stockage est configuré dans `config.yml` :

```yaml
alternative_scores:
  storage:
    type: "YAML"  # ou "MYSQL"
```

## 🔄 Commande alternative

Cette commande est également accessible via `/horizons score alt` ou `/hz score alt` avec la même syntaxe.

## 📌 Notes importantes

<details>

<summary>Voir les notes importantes</summary>

* Les scores alternatifs sont indépendants du score global sauf s'ils sont explicitement liés
* Le linking synchronise automatiquement les modifications mais ne fusionne pas les scores existants avant le linking
* La suppression d'un type de score est irréversible et supprime tous les scores associés

</details>


---

# 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/commandes/horizons/score/scores-alternatifs.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.