# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.r4nkt.com/concepts/achievements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.