> For the complete documentation index, see [llms.txt](https://docs.fivemstats.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fivemstats.net/tgiann-fivem-stats-script/for-developers/exports.md).

# Exports

Guides with full examples: [Screenshots and Uploads](https://docs.fivemstats.net/tgiann-fivem-stats-script/for-developers/screenshots-and-uploads.md) and [Log API](https://docs.fivemstats.net/tgiann-fivem-stats-script/for-developers/log-api.md).

## Client

### TakeImage

Takes a screenshot of the player's own screen and uploads it straight to the media service. Limited to **Player screenshots** per minute ([Settings > Players and items](https://docs.fivemstats.net/panel/settings.md#players-and-items)); `0` turns it off. Keys starting with `_` in the metadata are dropped.

```lua
local result, reason = exports["tgiann-fivem-stats-script"]:TakeImage({ reason = "bug report" })
```

#### Parameters

* **metadata?**: `table` stored with the file

#### Returns

* `{ id: string, url: string }` or `nil, reason` (`"upload limit reached or media service is down"`)

***

### IsPlayerAFK

Whether the local player is AFK right now.

```lua
local afk = exports["tgiann-fivem-stats-script"]:IsPlayerAFK()
```

#### Returns

* `boolean`

***

### ResetAFKTimer

Counts the player as active again, for example while they use a menu without moving.

```lua
exports["tgiann-fivem-stats-script"]:ResetAFKTimer()
```

## Server

### TakeServerImage

Takes a screenshot of a player's screen. Yields until the upload finishes or the timeout passes. The player becomes the file's player.

```lua
local result, reason = exports["tgiann-fivem-stats-script"]:TakeServerImage(source, { reason = "report" })
```

#### Parameters

* **src**: `number` the player's server id
* **metadata?**: `table` stored with the file
* **timeoutMs?**: `number` defaults to **Screenshot timeout** in [Settings > Players and items](https://docs.fivemstats.net/panel/settings.md#players-and-items)

#### Returns

* `{ id: string, url: string }` or `nil, reason` (`"player not found"`, `"screenshot timed out"`)

***

### UploadBase64

Uploads a file sent as base64 or a data URI: an image, a video, audio, or a JSON file (plain or gzip compressed, up to 50 MB, stored as it is). With a `filename` the file gets a fixed address, `<public address>/f/<path>/<filename>`, and the same folder and name replaces it later.

```lua
local file = exports["tgiann-fivem-stats-script"]:UploadBase64(base64, { filename = "house_12.webp", path = "housing/photos" })
```

#### Parameters

* **base64**: `string` raw base64 or a data URI
* **options?**: `table`
  * **filename?**: `string` the file name; makes the address fixed (images are stored as `.webp`, JSON as `.json`, gzip compressed JSON as `.gz`)
  * **path?**: `string` the folder
  * **metadata?**: `table` `playerSource` / `targetSource` name the players
  * **retentionExempt?**: `boolean` keep forever

#### Returns

* `{ id: string, url: string }` or `nil, error`

***

### RequestPresignedUrl

A single-use upload link for a client or a NUI. The uploader cannot change the folder, the metadata or keep forever, and the file always gets its own id.

```lua
local url = exports["tgiann-fivem-stats-script"]:RequestPresignedUrl("image", { path = "phone/photos", expiresIn = 120 })
```

#### Parameters

* **fileType?**: `string` `"image"`, `"video"`, `"audio"` or `"json"`; images, videos and audio when left out (never JSON)
* **options?**: `table`
  * **path?**: `string` the folder
  * **metadata?**: `table` stored with the file
  * **expiresIn?**: `number` seconds the link works
  * **retentionExempt?**: `boolean` keep forever

#### Returns

* `string` the upload URL (multipart form, field `file`) or `nil, error`

***

### GetFile

Reads a file's record.

```lua
local file = exports["tgiann-fivem-stats-script"]:GetFile("housing/photos/house_12.webp")
```

#### Parameters

* **idOrUrl**: `string` the file id, its URL, or `<path>/<filename>` of a named file

#### Returns

* `{ id, url, originalUrl, filename, type, size, metadata }` or `nil, error`; `type` is `image`, `video`, `audio` or `json`

***

### DeleteFile

Deletes a file; its link stops working.

```lua
local ok = exports["tgiann-fivem-stats-script"]:DeleteFile(url)
```

#### Parameters

* **idOrUrl**: `string` the file id, its URL, or `<path>/<filename>` of a named file

#### Returns

* `boolean` or `false, error`

***

### UploadImage (JavaScript)

Uploads a Buffer from a JavaScript resource. A `fileName` gives the file a fixed address, like `filename` of `UploadBase64`.

```js
const file = await exports["tgiann-fivem-stats-script"].UploadImage(buffer, { fileName: "shot.png", path: "bodycam" });
```

#### Parameters

* **buffer**: `Buffer`
* **options?**: `{ fileName?: string, path?: string, metadata?: object, retentionExempt?: boolean }`

#### Returns

* `Promise<{ id: string, url: string }>`

## Logs

### Log

Writes a log line to the [Server logs](https://docs.fivemstats.net/panel/server-logs.md) page. Never waits: lines are sent in batches. Lines below **Lowest level kept** ([Settings > Logs](https://docs.fivemstats.net/panel/settings.md#logs)) are dropped.

```lua
exports["tgiann-fivem-stats-script"]:Log("bank", "info", "Transfer of $5000", { playerSource = source })
```

#### Parameters

* **dataset?**: `string` `default` when left out
* **level?**: `string` `debug`, `info`, `warn` or `error`, `info` when left out
* **message**: `any` turned into text
* **metadata?**: `table` `playerSource` / `targetSource` name the players

***

### Info, Warn, Error

`Log` with the level in the name.

```lua
exports["tgiann-fivem-stats-script"]:Error("garage", "Vehicle could not be spawned", { playerSource = source, model = model })
```

#### Parameters

* **dataset?**: `string`
* **message**: `any`
* **metadata?**: `table`

***

### LogMessage

Writes to the `default` dataset (fmsdk's name).

```lua
exports["tgiann-fivem-stats-script"]:LogMessage("warn", "Something happened")
```

#### Parameters

* **level**: `string`
* **message**: `any`

## Statistics

### logMoney

Adds a money transaction to the Economy page. ESX `addAccountMoney` / `removeAccountMoney` and QB-Core `OnMoneyChange` are logged on their own; use this for money your scripts move outside the framework.

```lua
exports["tgiann-fivem-stats-script"]:logMoney(citizenid, "add", 2500, "bank", "Lottery win")
```

#### Parameters

* **citizenid**: `string` the character id (QB citizenid, ESX identifier)
* **actionType**: `"add"` or `"remove"`
* **amount**: `number`
* **accountType?**: `string` `cash`, `bank`...
* **description?**: `string`

***

### logKill

Adds a kill to the Combat page. Deaths are logged on their own; use this for kills your scripts handle themselves.

```lua
exports["tgiann-fivem-stats-script"]:logKill(killerCitizenid, victimCitizenid, "WEAPON_PISTOL")
```

#### Parameters

* **killerCitizenid?**: `string` `nil` for deaths without a player killer
* **victimCitizenid**: `string`
* **deathType**: `string` or `number`

***

### logChat

Adds a message to the Chat page. The default `chat` resource and tgiann-chat are logged on their own.

```lua
exports["tgiann-fivem-stats-script"]:logChat(citizenid, "Hello", "ooc")
```

#### Parameters

* **citizenid**: `string`
* **message**: `string`
* **chatType?**: `string` `normal` when left out

***

### IsPlayerAFK

Whether a player is AFK right now. The AFK time is **AFK after** in [Settings > Players and items](https://docs.fivemstats.net/panel/settings.md#players-and-items).

```lua
local afk = exports["tgiann-fivem-stats-script"]:IsPlayerAFK(source)
```

#### Returns

* `boolean`

***

### GetPlayerTotalAFKSeconds

AFK seconds of the player's current session.

```lua
local seconds = exports["tgiann-fivem-stats-script"]:GetPlayerTotalAFKSeconds(source)
```

#### Returns

* `number`

***

### GetAllAFKPlayers

Server ids of every player who is AFK right now.

```lua
local players = exports["tgiann-fivem-stats-script"]:GetAllAFKPlayers()
```

#### Returns

* `number[]`
