# TItems — PlaceholderAPI & API Développeur / Developer API

#  

## PlaceholderAPI

**FR** — TItems expose des placeholders via PlaceholderAPI (identifiant : `tboss`). Ces placeholders fonctionnent dans un **rayon de 50 blocs** autour d'un boss actif.  
**EN** — TItems exposes placeholders via PlaceholderAPI (identifier: `tboss`). These placeholders work within a **50-block radius** of an active boss.

> ⚠️ Nécessite le plugin **PlaceholderAPI** installé. / Requires **PlaceholderAPI** installed.

### Placeholders disponibles / Available Placeholders

<table id="bkmrk-placeholder-descript"><thead><tr><th>Placeholder</th><th>Description FR</th><th>Description EN</th><th>Valeur si aucun boss</th></tr></thead><tbody><tr><td>`%tboss_near_boss%`</td><td>Boss dans les 50 blocs ?</td><td>Boss within 50 blocks?</td><td>`ERROR`</td></tr><tr><td>`%tboss_health%`</td><td>HP restants du boss proche</td><td>Nearby boss remaining HP</td><td>`ERROR`</td></tr><tr><td>`%tboss_type%`</td><td>Type du boss (`FINAL_DAMAGE`…)</td><td>Boss type</td><td>`ERROR`</td></tr><tr><td>`%tboss_lead_name_1%`</td><td>Nom du joueur #1 au classement dégâts</td><td>Player name at damage rank #1</td><td>`Nobody`</td></tr><tr><td>`%tboss_lead_name_2%`</td><td>Nom du joueur #2 au classement</td><td>Player name at damage rank #2</td><td>`Nobody`</td></tr><tr><td>`%tboss_lead_name_N%`</td><td>Nom du joueur #N</td><td>Player name at rank N</td><td>`Nobody`</td></tr><tr><td>`%tboss_lead_health_1%`</td><td>Dégâts infligés par le joueur #1</td><td>Damage dealt by player #1</td><td>`0`</td></tr><tr><td>`%tboss_lead_health_N%`</td><td>Dégâts infligés par le joueur #N</td><td>Damage dealt by player #N</td><td>`0`</td></tr></tbody></table>

### Usage exemple (scoreboard, HUD…)

```
Boss proche: %tboss_near_boss%
Vie restante: %tboss_health%
#1 - %tboss_lead_name_1% (%tboss_lead_health_1% dmg)
#2 - %tboss_lead_name_2% (%tboss_lead_health_2% dmg)

```

---

## API Développeur / Developer API

Le package d'API est `fr.totallycorp.titems.api.event`. Il expose des **Bukkit events personnalisés** que les plugins tiers peuvent écouter.  
The API package is `fr.totallycorp.titems.api.event`. It exposes **custom Bukkit events** that third-party plugins can listen to.

---

### HarvestEvent

Déclenché lors de la récolte d'une culture via les items TItems (Harvester).  
Fired when a crop is harvested via TItems items (Harvester).

**Méthodes / Methods :**

<table id="bkmrk-m%C3%A9thode-%2F-method-ret"><thead><tr><th>Méthode / Method</th><th>Retour / Return</th><th>Description</th></tr></thead><tbody><tr><td>`getPlayer()`</td><td>`Player`</td><td>Joueur qui récolte / Harvesting player</td></tr><tr><td>`getMaterial()`</td><td>`Material`</td><td>Type de culture récoltée / Harvested crop type</td></tr></tbody></table>

**Exemple / Example :**

```java
@EventHandler
public void onHarvest(HarvestEvent event) {
    Player player = event.getPlayer();
    Material crop = event.getMaterial();
    // votre logique / your logic
}

```

---

### InstantKillEvent *(Cancellable)*

Déclenché quand un monstre est tué en un coup par la Farming Sword. **Annulable.**  
Fired when a mob is one-shot by the Farming Sword. **Cancellable.**

**Méthodes / Methods :**

<table id="bkmrk-m%C3%A9thode-%2F-method-ret-1"><thead><tr><th>Méthode / Method</th><th>Retour / Return</th><th>Description</th></tr></thead><tbody><tr><td>`getKiller()`</td><td>`Player`</td><td>Joueur attaquant / Attacking player</td></tr><tr><td>`getEntity()`</td><td>`LivingEntity`</td><td>Entité tuée / Killed entity</td></tr><tr><td>`setCancelled(true)`</td><td>`void`</td><td>Annule le one-shot / Cancels the one-shot</td></tr></tbody></table>

**Exemple / Example :**

```java
@EventHandler
public void onInstantKill(InstantKillEvent event) {
    if (someCondition) {
        event.setCancelled(true);
    }
}

```

---

### PlayerDropOnDeathEvent

Déclenché à la mort d'un joueur pour gérer les drops d'items TItems. Permet de **forcer la conservation** d'un item spécifique.  
Fired on player death to manage TItems item drops. Allows **forcing item retention**.

**Méthodes / Methods :**

<table id="bkmrk-m%C3%A9thode-%2F-method-ret-2"><thead><tr><th>Méthode / Method</th><th>Retour / Return</th><th>Description</th></tr></thead><tbody><tr><td>`getPlayer()`</td><td>`Player`</td><td>Joueur décédé / Deceased player</td></tr><tr><td>`getDrops()`</td><td>`List<ItemStack>`</td><td>Items normaux droppés / Normal item drops</td></tr><tr><td>`getArmor()`</td><td>`List<ItemStack>`</td><td>Armures droppées / Armor drops</td></tr><tr><td>`getAllDrops()`</td><td>`List<ItemStack>`</td><td>Tous les drops combinés / All drops combined</td></tr><tr><td>`keepItem(ItemStack)`</td><td>`void`</td><td>Force la conservation d'un item / Forces item retention</td></tr><tr><td>`getKeep()`</td><td>`List<ItemStack>`</td><td>Liste des items conservés / Kept items list</td></tr></tbody></table>

**Exemple / Example :**

```java
@EventHandler
public void onDeath(PlayerDropOnDeathEvent event) {
    // Conserver tous les Nether Stars / Keep all Nether Stars
    event.getDrops().stream()
        .filter(item -> item.getType() == Material.NETHER_STAR)
        .forEach(event::keepItem);
}

```

---

### EventStartEvent / EventStopEvent

Événements génériques déclenchés au **démarrage** et à l'**arrêt** d'un event TItems (boss, etc.).  
Generic events fired on TItems event **start** and **stop**.

```java
@EventHandler
public void onEventStart(EventStartEvent event) { /* ... */ }

@EventHandler
public void onEventStop(EventStopEvent event) { /* ... */ }

```

---

## Accès aux Managers / Manager Access

Tous les managers sont accessibles via l'instance principale du plugin.  
All managers are accessible via the plugin's main instance.

<table id="bkmrk-manager-acc%C3%A8s-%2F-acce"><thead><tr><th>Manager</th><th>Accès / Access</th><th>Rôle FR</th><th>Role EN</th></tr></thead><tbody><tr><td>`BossManager`</td><td>`TItems.getInstance().getBossManager()`</td><td>Gère les boss actifs</td><td>Manages active bosses</td></tr><tr><td>`ScepterManager`</td><td>`TItems.getInstance().getScepterManager()`</td><td>Gère les PvP sceptre</td><td>Manages scepter PvP</td></tr><tr><td>`MaskManager`</td><td>`TItems.getInstance().getMaskManager()`</td><td>Gère les masques équipés</td><td>Manages equipped masks</td></tr><tr><td>`SellItemsManager`</td><td>`TItems.getInstance().getSellItemsManager()`</td><td>Gère la vente d'items</td><td>Manages item selling</td></tr></tbody></table>

### Exemple — Vérifier si un boss est à proximité

```java
BossManager bm = TItems.getInstance().getBossManager();

boolean isBossNearby = bm.getBossMap().values().stream()
    .anyMatch(boss -> boss.getLoc().distance(player.getLocation()) <= 50);

```

### Exemple — Récupérer le classement dégâts d'un boss

```java
for (Boss boss : bm.getBossMap().values()) {
    HashMap<UUID, Double> damages = boss.getPlayerDamage();
    // trier et afficher / sort and display
}

```