> 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/server-exports.md).

# Server Exports

Feed progress from any resource, in one line.

All server-side. The first argument is always the player's server id.

```lua
-- Advance a single award
exports['mango_achievements']:AddProgress(source, 'repeat_offender', 1)

-- Better: advance a shared counter, and every tier moves at once
exports['mango_achievements']:AddStat(source, 'prison_sentences', 1)
```

## The full list

| Export                            | Returns                                                         |
| --------------------------------- | --------------------------------------------------------------- |
| `AddProgress(src, id, amount)`    | `boolean` — advances an award                                   |
| `SetProgress(src, id, amount)`    | `boolean` — sets an exact value                                 |
| `UnlockAchievement(src, id)`      | `boolean` — completes it and pays the reward                    |
| `ResetAchievement(src, id)`       | `boolean` — clears it so it can be earned again                 |
| `ResetAllAchievements(src)`       | `number` — rows removed                                         |
| `HasAchievement(src, id)`         | `boolean`                                                       |
| `GetProgress(src, id)`            | `number`                                                        |
| `GetAchievement(src, id)`         | `table` — progress, goal, completions, unlock date              |
| `AddStat(src, stat, amount)`      | `number` — awards touched                                       |
| `SetStat(src, stat, value)`       | `number` — absolute version                                     |
| `IsLoaded(src)`                   | `boolean`                                                       |
| `GetPlayerAchievements(src)`      | `table` — everything, for leaderboards                          |
| `GetDefinitions()`                | `table` — the validated award list                              |
| `RefreshVehicleCount(src)`        | Recount owned vehicles now                                      |
| `MarkDiscovered(src, locationId)` | Mark a landmark found                                           |
| `GetLeaderboard(limit)`           | `table` — the server ranking, highest first                     |
| `ClaimReward(src, id)`            | `boolean, string` — hand over a reward held by a full inventory |

## AddStat versus AddProgress

`AddStat` is almost always the one you want. It means your prison script never needs to know how many prison tiers exist, and adding a fourth later is a config edit rather than a code change.

## Leaderboards

The server already keeps a ranked board, cached and summed by MySQL:

```lua
local top10 = exports['mango_achievements']:GetLeaderboard(10)
-- { { rank = 1, identifier = '...', name = 'Tim Maclean', points = 3020, completed = 41 }, ... }
```

Pass `0` or nothing for the whole board. See [Leaderboard](/mango5m-docs/resources/mango-achievements/features/leaderboard.md).

For one player's own totals:

```lua
local data = exports['mango_achievements']:GetPlayerAchievements(source)
-- data.points, data.completed, data.total, data.maxPoints, data.entries[id]
```

## Claiming a held reward

```lua
local ok, reason = exports['mango_achievements']:ClaimReward(source, 'bank_job')
```

Returns `false` and a human-readable reason when the reward is not owed, was already paid, or still will not fit. See [Claiming Rewards](/mango5m-docs/resources/mango-achievements/features/claiming-rewards.md).

## Errors are loud

An unknown award id is logged with the name of the calling resource and ignored:

```
[mango_achievements] unknown achievement id "repeat_offendr" (called from mango_prison)
```

{% hint style="info" %}
Check `IsLoaded(src)` first if you call very early — progress rows load just after the player's character does, and calls before that are ignored.
{% endhint %}