jobs/*.yml — le cœur du plugin

5. jobs/*.yml — le cœur du plugin

Un fichier = un job. Le nom du fichier n'a pas d'importance (c'est le champ id: à l'intérieur qui compte), mais garder les deux identiques évite la confusion. Déposer un nouveau fichier dans jobs/ puis taper /jobs reload jobs suffit à créer un nouveau job — sans toucher au Java.

Toute la structure ci-dessous part d'un seul fichier, exemple : miner.yml.

5.1 Identité du job

job:
  id: miner
  enabled: true
  display-name: "<gradient:#9827F5:#F179B5>Mineur</gradient>"
  description:
    - "<gray>Mine des minerais"
    - "<gray>pour progresser dans ce job."

• id : identifiant technique (minuscules, sans espace). Utilisé dans les commandes (/jobs join miner), les placeholders (%advancedjobs_miner_...%) et les chemins de menus (jobs/miner/...).
• enabled : mets false pour désactiver le job sans supprimer le fichier (il est ignoré au chargement).
• display-name : nom affiché (MiniMessage, gradients/couleurs acceptés).
• description : lignes de description utilisées par la liste des jobs (gui/main.yml, placeholder %description%).

5.2 Icône et emplacement des menus

  icon:
    provider: VANILLA
    material: DIAMOND_PICKAXE

  gui-folder: miner

• icon : voir le format ItemSpec complet plus bas — utilisé dans la liste des jobs (gui/main.yml).
• gui-folder : nom du sous-dossier utilisé pour résoudre les menus de ce job (gui/jobs/<gui-folder>/...). Par défaut, égal à id. Utile si tu veux que deux jobs différents partagent le même dossier de menus, ou que l'id technique diffère du nom de dossier.

5.3 Accès et adhésion

  # permission: advancedjobs.jobs.miner
  auto-join: false

• permission (optionnel, commenté par défaut) : si présent, seuls les joueurs avec cette permission peuvent rejoindre le job. Absent = accessible à tous.
• auto-join : si true, tout joueur qui se connecte rejoint automatiquement ce job (dans la limite de max-active-jobs).

5.4 Niveaux et progression

  max-level: 100

  progression:
    formula: "floor(100 * pow(level - 1, 1.6))"

  levels:
    1:
      required-xp: 0
    2:
      required-xp: 100
    5:
      required-xp: 900
      rewards: [money_500]
    10:
      required-xp: 3000
      rewards: [money_1000, miner_crate]

• max-level : niveau maximum atteignable pour ce job. Chaque job a sa propre limite, indépendante des autres.
• progression.formula : formule utilisée pour calculer l'XP totale requise de tout niveau non explicitement listé ci-dessous. Variables disponibles : level, max_level. Opérateurs : + - * / % ^, parenthèses, et les fonctions floor, ceil, round, abs, sqrt, log, min(a,b), max(a,b), pow(a,b).
• levels.<N>.required-xp : XP totale (pas incrémentale) nécessaire pour atteindre le niveau N. Un niveau listé ici l'emporte toujours sur la formule — tu peux mélanger les deux (ex. les 10 premiers niveaux écrits à la main pour un contrôle fin, puis la formule prend le relais).
• levels.<N>.rewards : liste d'identifiants de récompenses (voir section 5.6) données à ce palier. Optionnel — un niveau peut n'avoir aucune reward.

Si tu ne définis ni levels ni formula, le job ne peut jamais monter de niveau (erreur de validation affichée au démarrage : fichier, chemin, problème, valeur, attendu).

5.5 Actions et gains

  actions:
    BREAK:
      STONE:
        xp: 2
        money: 0.1
        points: 1
        coins: 1
      DEEPSLATE_DIAMOND_ORE:
        xp: 60
        money: 18
        points: 12
        coins: 12
        cooldown: 250
        multiplier: 1.0
        rewards: [diamond_bonus]
        conditions:
          - "permission advancedjobs.deepslate"

Structure : actions.<TYPE>.<CIBLE>.<gains>.

Types d'action disponibles :

Note sur STRUCTURE : il n'existe pas d'événement Bukkit fiable pour détecter automatiquement "le joueur vient de découvrir un village". Ce type d'action existe et fonctionne, mais doit être déclenché depuis l'extérieur : /jobs admin triggeraction <joueur> <job> STRUCTURE <nom> ou via l'API (AdvancedJobsAPI.triggerAction(...)) — par exemple depuis un datapack ou une commande block.

Clés de gains disponibles pour chaque cible :

• xp, money, points, coins : gains de base (avant multiplicateurs). Toutes optionnelles, défaut 0.
• cooldown : délai en millisecondes avant que cette cible précise (pour ce job) puisse rapporter à nouveau au même joueur. Défaut : pas de cooldown.
• multiplier : multiplicateur propre à cette cible précise, appliqué en plus des multiplicateurs globaux/rank/boosters. Défaut 1.0.
• rewards : liste d'identifiants de récompenses données à chaque déclenchement (pas seulement aux paliers de niveau).
• conditions : liste de conditions (même syntaxe que les menus, voir section 13) qui doivent toutes être vraies pour que l'action rapporte quoi que ce soit. Exemple : restreindre une cible aux joueurs VIP.

Une cible * sert de repli : si le bloc/l'entité cassé(e) n'a pas d'entrée explicite, * est utilisé s'il existe.

5.6 Récompenses locales au job

  rewards:
    miner_crate:
      display-name: "<aqua>Caisse du mineur"
      icon:
        provider: VANILLA
        material: CHEST
      variants:
        premium:
          permission: advancedjobs.reward.premium
          priority: 30
          money: 2000
          points: 200
        vip:
          permission: advancedjobs.reward.vip
          priority: 20
          money: 1000
          points: 100
        default:
          priority: 0
          money: 500
          points: 50

    miner_pickaxe:
      display-name: "<light_purple>Pioche du mineur"
      items:
        pickaxe:
          provider: VANILLA
          material: DIAMOND_PICKAXE
          name: "<light_purple>Pioche du mineur"
          enchantments:
            efficiency: 5
            unbreaking: 3

    miner_booster:
      display-name: "<aqua>Booster XP x2"
      commands:
        - "jobs booster %player% double-xp"

    miner_final:
      display-name: "<gold>Recompense finale"
      money: 50000
      messages:
        - "<gold>Niveau 100 atteint, felicitations !"

Une reward définie ici, dans le fichier du job, est automatiquement préfixée en interne par l'id du job — impossible qu'un autre job y accède par erreur, même en cas de collision de nom avec une reward d'un autre job ou de rewards/global.yml.

Composants de récompense disponibles (combinables librement dans une même reward ou variante) :

Variantes par rank (variants:) : chaque variante a sa propre permission et priority. La variante avec la plus haute priority dont le joueur possède la permission est utilisée. Une variante default sans permission sert de repli pour tout le monde. Sans bloc variants:, les clés de gains peuvent être écrites directement au niveau de la reward (comme miner_final ci-dessus) — c'est un raccourci pour une reward à variante unique.

5.7 Reward Train

  reward-train:
    enabled: true
    claim-mode: MANUAL
    stops:
      5: [money_500]
      10: [money_1000, miner_crate]
      25: [miner_pickaxe]
      50: [miner_booster]
      100: [miner_final]

• claim-mode: MANUAL : le joueur doit cliquer sur le wagon pour récupérer (via l'action [claim] dans un menu).
• claim-mode: AUTO : la récompense est donnée automatiquement dès que le niveau est atteint, sans action du joueur.
• stops : optionnel — si absent, le train utilise automatiquement les rewards: déclarées sous levels: (section 6.4). Si présent, stops prend le dessus et définit sa propre liste de paliers indépendamment de levels.

5.8 Bonus de rank

  rank-bonuses:
    premium:
      permission: advancedjobs.rank.premium
      priority: 30
      xp: 1.5
      money: 1.25
      points: 1.25
      coins: 1.5
    vip:
      permission: advancedjobs.rank.vip
      priority: 20
      xp: 1.25
      money: 1.10
      points: 1.10
      coins: 1.25
    default:
      priority: 0
      xp: 1.0
      money: 1.0
      points: 1.0
      coins: 1.0

Comme les variantes de reward : le bonus avec la plus haute priority dont le joueur a la permission est appliqué, default sert de repli. Les 4 multiplicateurs (xp, money, points, coins) sont indépendants et se combinent avec global-multipliers (section 2) et les boosters actifs (section 8). Aucun rank n'est codé en dur — tout repose sur des permissions, donc compatible LuckPerms ou n'importe quel plugin de permissions.

5.9 Restrictions de monde et région

  restrictions:
    allowed-worlds: []
    denied-worlds: [spawn]
    allowed-regions: []
    denied-regions: [spawn_region]

• allowed-worlds vide = autorisé partout sauf denied-worlds.
• allowed-regions/denied-regions nécessitent WorldGuard installé — sans lui, ces clés sont ignorées silencieusement (pas d'erreur).
• Ces restrictions s'appliquent à toutes les actions de ce job, à l'endroit précis où l'action se produit (pas à la position du joueur au moment de rejoindre le job).

5.10 Affichage : barre de progression, BossBar, ActionBar

  progress-bar:
    symbol: "█"
    length: 10
    filled-color: "<green>"
    empty-color: "<dark_gray>"

Utilisé par le placeholder %advancedjobs_<job>_progress_bar%.

  bossbar:
    enabled: true
    text: "<gradient:#9827F5:#F179B5>Mineur</gradient> <gray>| Niveau <white>%level% <gray>| <white>%progress%%"
    color: PURPLE
    style: SEGMENTED_10
    visible-seconds: 5

Affichée automatiquement à chaque action rapportant quelque chose sur ce job. color et style correspondent aux valeurs de l'enum Bukkit BossBar.Color et BossBar.Overlay (ex. PINK, BLUE, PROGRESS, NOTCHED_10...).

  actionbar:
    enabled: false
    text: "<gray>%job_display% <white>%progress_bar% <gray>%xp%/%required_xp%"

Message affiché au-dessus de la barre d'inventaire à chaque action.

5.11 Montée de niveau

  level-up:
    title:
      main: "<gradient:#9827F5:#F179B5>NIVEAU %level%</gradient>"
      subtitle: "<gray>%job_display%"
    messages:
      - "<green>Tu passes niveau <white>%level% <green>en %job_display%<green> !"

title affiche un titre/sous-titre à l'écran. messages envoie des lignes de chat en plus (ou à la place, si pas de titre configuré).

5.12 Sons et particules

  sounds:
    action: BLOCK_NOTE_BLOCK_HAT
    level-up: ENTITY_PLAYER_LEVELUP
    join: ENTITY_EXPERIENCE_ORB_PICKUP
    leave: BLOCK_NOTE_BLOCK_BASS

  particles:
    action: TOTEM
    level-up: TOTEM

action joue à chaque gain, level-up à la montée de niveau. Format des particules : NOM_PARTICULE ou NOM_PARTICULE:quantité (ex. TOTEM:20). Les noms correspondent à l'enum Bukkit Particle.

Format ItemSpec (icônes)

Utilisé partout où une icône est demandée (icon:, content-item:, items de menu, frames d'animation, items: d'une reward). Toutes les clés sont optionnelles sauf material (ou id selon le provider).

provider: VANILLA          # VANILLA, MODEL_DATA, PLAYER_HEAD, ITEMSADDER, ORAXEN
material: DIAMOND_PICKAXE  # materiau vanilla (ignore si provider != VANILLA/MODEL_DATA/PLAYER_HEAD)
id: "jobs:miner_icon"      # identifiant ItemsAdder/Oraxen (si provider correspondant)
custom-model-data: 10001   # optionnel, compatible avec n'importe quel provider vanilla
name: "<gold>Nom affiche"
lore:
  - "<gray>Ligne 1"
  - "<gray>Ligne 2"
amount: 1
glow: false                 # ajoute un enchant invisible pour l'effet brillant
hide-attributes: true       # cache les attributs/enchants par defaut dans le lore
head-owner: "%player%"      # pour provider: PLAYER_HEAD — nom, %player%, ou UUID
head-texture: "eyJ0ZXh0..."  # texture base64 ou URL directe, alternative a head-owner
item-flags: [HIDE_ATTRIBUTES]
enchantments:
  unbreaking: 3
booster: double-xp           # marque l'item comme item-booster consommable (section 8)

Providers disponibles :

• VANILLA : matériau Minecraft standard.
• MODEL_DATA : matériau vanilla + custom-model-data (pour les resource packs avec des modèles personnalisés).
• PLAYER_HEAD : tête de joueur, via head-owner ou head-texture.
• ITEMSADDER : item custom d'ItemsAdder, via id. Ignoré proprement si ItemsAdder n'est pas installé.
• ORAXEN : item custom d'Oraxen, via id. Idem.