> For the complete documentation index, see [llms.txt](https://godot-essentials.gitbook.io/addons-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://godot-essentials.gitbook.io/addons-documentation/autoload/achievements.md).

# Achievements

Implement achievements in your game in a simple way and with minimal security practices.

## Getting Started

You can access this functionality using the class `GodotEssentialsAchievement` where you can interact with your source file.

Before start you need to set few project settings that will be available after load the plugin:

<figure><img src="https://1059887051-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWThJkY8CZ3qBkgyzYFBw%2Fuploads%2FaaGmYjs18YbKpJPpvL21%2Fimage.png?alt=media&amp;token=0283a2fc-5d74-43d1-8b0d-21a1f3b9adb6" alt="" width="563"><figcaption><p>Achievement settings</p></figcaption></figure>

**Local source** refers to the path of the local file that contains the achievements template. This file is read-only and is used solely to define the structure of the achievements in your game. For example: `res://settings/achievements.json`.

**Remote source**, on the other hand, refers to the path of the remote JSON file that also holds the achievements template. The same rules apply as for the local source, but this information is obtained from a remote URL. For example `https://myserver/achievements.json`

**Save directory** is the location where the encrypted saved file, used to track achievement progress, will be created on the player's machine. By default, it utilizes `OS.get_user_data_dir()/[project_name]`.

**Save file name** is the name of the encrypted file that tracks achievement progress. By default, it is named `achievements.json`.

**Password** is the character set used for encrypting and decrypting the saved achievements file. By default, it generates a random string with a length of 25 characters. This length should be sufficient for most use cases, ensuring that players cannot alter their achievement progress accessing the file.

## Ready

When this node becomes ready, it performs several actions:

1. It connects itself to the `achievement_updated` signal, which updates the encrypted file and checks if all achievements have been unlocked. If all achievements are unlocked, it emits the `all_achievements_unlocked` signal.
2. It creates the save directory using the path defined in **ProjectSettings**.
3. It prepares the achievements within the class by reading from the sources defined in **ProjectSettings**
4. Sync the latest achievements update from the encrypted saved file if it exists

## Achievement structure

The JSON file **must adhere to a specific structure** in order to function correctly. While you can include additional custom properties tailored to your game, there are mandatory ones that must be present:

```json
{
    "achievement-name": {
        "name": "MY achievement",
        "description": "Kill 25 enemies",
        "is_secret": false,
        "count_goal": 25,
        "current_progress": 0.0,
        "icon_path": "res://assets/icon/my-achievement.png",
        "unlocked": false,
        "active": true
    }
}
```

It's important to note that not all achievements will have a `count_goal` requirement for unlocking progress. In cases where this requirement is not applicable, you should leave the `count_goal` value as zero. **The logic and conditions for unlocking achievements are entirely determined by your game project**.&#x20;

This class serves as a helper for updating and unlocking achievements while emitting the appropriate signals for interaction.

## Accessible variables

* current\_achievements: Dictionary = {}
* unlocked\_achievements: Dictionary = {}
* achievements\_keys: PackedStringArray = \[]

## Functions

### get\_achievement(name: String) -> Dictionary

Retrieve the information from the desired achievement, if the name does not exist as key it will return an empty dictionary.

```python
GodotEssentialsAchievements.get_achievement("orcs_party")
```

### update\_achievement(name: String, data: Dictionary)

This function updates the properties of the selected achievement, with values from the `data` dictionary overriding the existing ones. This action also emits the `achievement_updated` signal.

```python
GodotEssentialsAchievements.update_achievement("orcs_party", {"current_progress": 0.55})
```

### unlock\_achievement(name: String)

If the achievement was not previously unlocked, this function changes the `unlocked` variable to `true` and emits the `achievement_unlocked` signal. This action directly unlocks the achievement without further checks.

```
GodotEssentialsAchievements.unlock_achievement("orcs_party")
```

### reset\_achievement(name: String, data: Dictionary = {})

Reset the achievement to a previous state. The current\_progress and unlocked will be set to 0 and false respectively. You can pass as second parameter the data you want to update in this process.

This action also emits the `achievement_reset` and `achievement_updated` signals

```
GodotEssentialsAchievements.reset_achievement("orcs_party", {"description": "An orc party was discovered"})
```

## Signals

* *achievement\_unlocked(name: String, achievement: Dictionary)*
* *achievement\_updated(name: String, achievement: Dictionary)*&#x20;
* *achievement\_reset(name: String, achievement: Dictionary)*
* &#x20;*all\_achievements\_unlocked*