# Custom Data Reference

Custom data references give you much more flexibility and power when it comes to defining your achievements. Using them will allow you to create achievements that:

* are more dynamic
* better reflect the domain knowledge of your game

Custom data references can be used in a handful of [criteria conditions](https://docs.r4nkt.com/concepts/criteria-conditions) and can be used to reference custom data on the following entities:

* action: This refers to the action that is part of the current player activity.
* activity: This refers to the current player activity.
* player: This refers to the player that is part of the current player activity.

This is how it works:

* You report your player activity.
* R4nkt receives the reported player activity and begins to process it. This is what is considered the **current player activity**.
* When applying criteria conditions, any custom data references that are encountered will be replaced with whatever value is found for the **current player activity**, whether that be the player, the action, or the activity itself.

The custom references themselves work in a fairly straightforward manner. They "reach into" the relevant resource's `custom_data` value, with each "dot" (`.`) referring to nested values.

## Example

A simple example would be to define an achievement to be awarded whenever certain actions are performed on your player's birthday. Since you have many players, how do you do this?

You would use custom data references, of course:

* `month:{player.birthdate.month}`
* `dayOfMonth:{player.birthdate.day}`

A full definition would like like so:

```javascript
{
  "groups": [
    {
      "conditions": [
        "month:{player.birthdate.month}",
        "dayOfMonth:{player.birthdate.day}"
      ]
    }
  ]
}
```

And your player's `custom_data` might look like so:

```javascript
{
  "birthdate": {
    "day": 29,
    "month": 5,
    "year": 1970
  }
}
```


---

# 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/custom-data-reference.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.