> For the complete documentation index, see [llms.txt](https://docs.r4nkt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.r4nkt.com/concepts/achievements.md).

# Achievements

## Description

Achievements in r4nkt are like goals that you can create and define. They provide ways to measure a player's activities, to incentivize certain behavior, or to provide goals. Your players, through the actions they take, can meet these goals and earn an achievement.  When this is done, they will be awarded a [badge](/concepts/badges.md) to represent the earned achievement.

You must assign criteria to your achievements. These criteria must be met in order to earn the achievement and receive a related badge. You may assign points to achievements, which are then awarded to your players once they are earned. Finally, you may attach [rewards](/concepts/rewards.md) to your achievements and then distribute them once they are earned.

{% hint style="warning" %}
Keep in mind that new or modified achievements are not evaluated to see whether or not players have met the criteria. Rather, achievements are only evaluated when related [player activities](/concepts/activities.md) have been reported.
{% endhint %}

## Properties

Achievements have the following properties:

| Name                        |    Type    | Default |
| --------------------------- | :--------: | :-----: |
| custom\_id                  |   string   |    -    |
| name                        |   string   |    -    |
| description                 |   string   | *empty* |
| custom\_data                |    json    | *empty* |
| is\_secret                  |   boolean  |  false  |
| custom\_criteria\_group\_id |   string   | *empty* |
| points                      |   integer  |    1    |
| rewards                     | collection | *empty* |

{% hint style="info" %}
Click [here](/concepts/overview.md#common-properties) for information about common properties.
{% endhint %}

### Is secret

An achievement's `is_secret` property determines whether or not it is returned to the calling application for normal requests. It is boolean and must therefore be equal to one of the following values:

* true
* false

{% hint style="info" %}
By default, "secret" achievements will not be returned by "list" or "get" calls to the API.
{% endhint %}

An achievement with an `is_secret` value of `true` is intended to be kept hidden from the player. It is recommended to make an achievement "secret" if it contains a spoiler you don't want to reveal too early, eg. "Discover that you were a ghost all along!".

Finally, an achievement that is "known" (`is_secret` is `false`) is one where the player can know about the achievement prior to having earned it.

### Criteria group

An achievement can have a single [criteria group](/concepts/criteria-groups.md), which is identified by the criteria group's `custom_id` and asigned to its `custom_criteria_group_id` property. This is where you begin to define the different criteria that must be met in order for the player to earn the achievement and be awarded a [badge](/concepts/badges.md).

### Points

An achievement can be given points. Whenever a player earns an achievement, any associated points are automatically added to the points for any other achievements they have earned and your game's standard and session-based [leaderboards](/concepts/leaderboards.md#type) will be updated automatically.

### Rewards

An achievement can have multiple [rewards](/concepts/rewards.md). They are associated with achievements so that, when a player earns an achievement, any associated rewards can be distributed.