> For the complete documentation index, see [llms.txt](https://hider.somadocs.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hider.somadocs.fr/api-developpeur/cas-concret.md).

# Cas concret

Voici une intégration réelle : un plugin d'événements de faction branche SomaHider sur deux événements, un KoTH et un totem géant. Le schéma est le même à chaque fois. La zone s'ouvre autour de l'arène au démarrage de l'événement, révèle quelques groupes, puis se ferme à l'arrêt.

### Un helper réutilisable

Les deux événements passent par un petit helper, pour que le branchement à l'API tienne à un seul endroit : il récupère l'API, associe chaque joueur à sa faction, applique le déguisement lu dans la config, puis ouvre la zone.

```java
public static HiderZone open(ConfigurationSection hider, Region region, VisibilityRule... reveal) {
    SomaHider somaHider = SomaHiderProvider.getOrNull();
    if (somaHider == null || region == null) {
        return null;
    }
    if (hider != null && !hider.getBoolean("enabled", true)) {
        return null;
    }
    return somaHider.hide(region)
            .groupResolver(Hiders::factionId)   // chaque joueur -> l'id de sa faction
            .disguise(hider)
            .reveal(reveal)
            .open();
}

public static String factionId(Player player) {
    Faction faction = FactionUtils.getFactionByPlayer(player);
    return faction != null && faction.isNormal() ? faction.getId() : null;
}
```

`getOrNull()` et le test qui suit laissent le plugin fonctionner même si SomaHider n'est pas installé (déclaré en `softdepend`). Le resolver renvoie `null` pour un joueur sans faction, et un groupe `null` n'est jamais révélé.

### KoTH : Révéler la faction qui tient le point de capture

Au démarrage, une zone couvre l'arène. Tout le monde est masqué, sauf votre propre faction et celle qui tient le KoTH à cet instant. Le propriétaire est lu en direct, donc la révélation suit la capture. `hider` est la section de config propre à l'événement (activation, rayon, réglages de déguisement), lue par le helper.

```java
// au démarrage de l'événement
ConfigurationSection hider = getConfig().getConfigurationSection("koths." + koth.getName() + ".hider");

zone = Hiders.open(hider, Hiders.around(koth.getArea().getMiddle(), hider),
        Reveal.sameGroup()
            .or(Reveal.group(() -> Hiders.factionId(currentKoth.getOwner()))));

// à l'arrêt
zone.close();
```

`sameGroup()` garde les coéquipiers reconnaissables. `Reveal.group(Supplier)` révèle la faction propriétaire à tout le monde ; comme c'est un `Supplier`, la révélation se déplace vers le nouveau propriétaire dès qu'il change, sans code à écrire. Tant que personne ne tient le point, le propriétaire vaut `null` et seuls les coéquipiers se voient.

### Totem géant : Révéler le haut du classement entre eux

Même forme, autre règle. Autour du totem, on révèle sa propre faction et les trois premières factions du classement. Quand le classement bouge, l'ensemble révélé suit.

```java
ConfigurationSection hider = getConfig().getConfigurationSection("giant-totems." + totem.getName() + ".hider");

zone = Hiders.open(hider, Hiders.around(totem.getLocation(), hider),
        Reveal.sameGroup()
            .or(Reveal.groupsTogether(() -> Hiders.top(standings, 3))));
```

```java
public static List<String> top(List<EventData> standings, int count) {
    List<String> ids = new ArrayList<>();
    for (int i = 0; i < standings.size() && i < count; i++) {
        ids.add(standings.get(i).getId());
    }
    return ids;
}
```

`groupsTogether(Supplier)` révèle entre eux les membres d'un ensemble de groupes : l'observateur et la cible doivent tous deux en faire partie. Ici l'ensemble est celui des factions de tête, recalculé à chaque passage, si bien que le classement s'ouvre à mesure qu'il évolue.

### À retenir

* Un seul helper centralise l'accès à l'API, le resolver de groupe et le déguisement.
* La zone s'ouvre au démarrage et se ferme à l'arrêt avec `zone.close()`.
* Les règles à base de `Supplier` suivent l'état du jeu, sans logique supplémentaire.

Le catalogue complet des fabriques est dans [Règles de révélation](/api-developpeur/regles-de-revelation.md).


---

# 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://hider.somadocs.fr/api-developpeur/cas-concret.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.