**Language / Langue :** [[fr:yaml:succes|FR]] | **EN**

====== Achievements ======

A scenario can provide its own achievements. They are stored on the player's device independently from game saves: reaching an ending, giving up or starting a new game does not remove them.

The trophy button opens the collection without closing the game. Unlocked and locked achievements are shown separately. A secret one is displayed as “Hidden achievement” until it is earned.

===== Declaration =====

A scenario using achievements needs a stable ''id:'':

<code yaml>
id: my-scenario

achievements:
  first_win:
    title: First victory
    description: Finish the scenario with a victory.
    points: 20
    icon: 🏆

  secret_passage:
    title: Behind the wall
    description: Discover the hidden passage.
    points: 40
    icon: images/achievements/passage.png
    secret: true
</code>

''title'', ''description'' and ''points'' are required. ''icon'' and ''secret'' are optional. JDR-Bot uses a trophy when no icon is provided. An icon may be an emoji, a short piece of text or an image path.

The achievement identifier, such as ''first_win'', is what gets stored on the player's device. Do not change it after publishing the scenario. Titles and descriptions may be rewritten safely.

===== Unlocking an achievement =====

Use the ''achievement:identifier'' action in an event, a custom action or a choice effect:

<code yaml>
events:
  - if: "v_victory_v = 1"
    do: "achievement:first_win"

choices:
  - command: search
    button: Search the wall
    to: passage
    effect: "achievement:secret_passage"
</code>

An achievement already earned is never added twice and its notification does not appear again. It is safe to try unlocking it on every visit without an extra condition.

The linter warns when a declared achievement is never unlocked anywhere in the scenario.

===== Translations =====

French and English versions of the same scenario can share their progress. Give them the same scenario ''id:'' and the same achievement identifiers. Only titles and descriptions need translating.

Points may differ between languages. In that case, the score uses the value from the currently selected language without counting the achievement twice.

===== Displaying a collection inside text =====

These tags work in room text and HUD panels. Their French spelling is kept in both languages:

^ Tag ^ Contents ^
| ''[[SUCCES]]'' | Every available achievement |
| ''[[SUCCES-ACQUIS]]'' | Every unlocked achievement |
| ''[[SUCCES-SCENARIO]]'' | Current scenario achievements |
| ''[[SUCCES-SCENARIO-ACQUIS]]'' | Achievements unlocked in this scenario |
| ''[[SUCCES-GLOBAUX]]'' | Global JDR-Bot achievements |
| ''[[SUCCES-GLOBAUX-ACQUIS]]'' | Unlocked global achievements |
| ''[[SUCCES:identifier]]'' | One specific scenario achievement |

Add ''-ICONE'' to the name to show icons, for example ''[[SUCCES-SCENARIO-ICONE]]'' or ''[[SUCCES-ICONE:first_win]]''.

===== Persistence and reset =====

Achievements are not part of a game save. **Reset** clears the current scenario's achievements and [[en:yaml:variables|persistent ''_p'' variables]], then immediately starts a new game. Global achievements are left untouched.

Web, Android and standalone exports use the browser's local storage. Desktop uses its own local storage. Discord only keeps achievements for the current game.

===== In the editor =====

The [[en:editeur:explorateur|Explorer]] has an **Achievements** tab where achievements can be created and edited. The action builder then offers **Unlock an achievement** and lists their identifiers.

If the scenario has no ID yet, the editor asks for one when the first achievement is added. It can also be edited below the title in the [[en:editeur:globaux|Globals panel]].

===== Standalone and global achievements =====

Scenario achievements are always included in its standalone export. Global JDR-Bot achievements are excluded by default. **Include compatible global achievements** adds only those which can be earned inside a standalone game.

See also [[en:yaml:export|Standalone and PDF export]].