> For the complete documentation index, see [llms.txt](https://mango-5m.gitbook.io/mango5m-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mango-5m.gitbook.io/mango5m-docs/resources/mango-achievements/developer-guide/creating-achievements.md).

# Creating Achievements

Every field an award can have.

Awards live in `config/achievements.lua`.

```lua
{
    id          = 'repeat_offender',
    name        = 'Repeat Offender',
    description = 'Go to prison 50 times.',
    category    = 'prison',
    icon        = 'career_criminal.png',
    goal        = 50,
    points      = 100,
    rarity      = 'rare',
    stat        = 'prison_sentences',
    reward      = { type = 'money', account = 'bank', amount = 5000 },
},
```

## Fields

| Field                 | Type            | Meaning                                                                            |
| --------------------- | --------------- | ---------------------------------------------------------------------------------- |
| `id`                  | string          | **Required.** Unique, lowercase, `a-z 0-9 _`                                       |
| `name`                | string          | Shown on the row and in the popup                                                  |
| `description`         | string          | One line                                                                           |
| `category`            | string          | Must match a configured category                                                   |
| `icon`                | string          | A file in `web/assets/icons/`                                                      |
| `goal`                | number          | Progress needed. Omit for a one-time award                                         |
| `display`             | string          | `hours`, `money` or `distance` — how the bar reads                                 |
| `points`              | number          | Achievement points                                                                 |
| `rarity`              | string          | Must match a configured rarity                                                     |
| `hidden`              | boolean         | Masked until earned                                                                |
| `repeatable`          | boolean         | Can be earned again                                                                |
| `maxCompletions`      | number          | Cap for repeatable awards                                                          |
| `session`             | boolean         | Never saved; resets each session                                                   |
| `stat`                | string          | Shared counter — this is how tiers work                                            |
| `requires`            | string / table  | Award ids that must be completed first                                             |
| `window`              | table           | Only earnable at certain times                                                     |
| `chain` / `tier`      | string / number | Groups awards into a visible ladder                                                |
| `reward`              | table           | See [Rewards](/mango5m-docs/resources/mango-achievements/configuration/rewards.md) |
| `sound` / `animation` | table / false   | Override the defaults for this one                                                 |
| `notify`              | boolean         | `false` unlocks silently                                                           |
| `order`               | number          | Sort order inside its category                                                     |

{% hint style="danger" %}
**Never reuse an `id` for a different award.** Stored progress is keyed on it, so a recycled id inherits the old award's unlock dates, completions and claimed reward. Renaming an award is completely safe; changing what an id *means* is not.
{% endhint %}

## Display units

`goal` is always stored in the smallest unit — minutes, metres — and `display` decides how it reads:

| `display`  | `goal = 600` shows as |
| ---------- | --------------------- |
| `hours`    | 6.9 / 10.0 h          |
| `distance` | 48.2 / 100.0 km       |
| `money`    | $64,200 / $100,000    |

## Icons

Drop a PNG into `web/assets/icons/` and name it in `icon`. A missing file falls back to a generated monogram tile rather than breaking the row.

## Reloading

`/achievementsreload` re-reads the file live, with no restart and no effect on stored progress.