> For the complete documentation index, see [llms.txt](https://dirkscripts.gitbook.io/dirkscripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dirkscripts.gitbook.io/dirkscripts-documentation/resources/dirk-lib/cache.md).

# Cache

`dirk_lib` keeps a client-side cache for frequently accessed values and emits change events when values update.

## Accessing Cache

### `cache.<key>`

```lua
local ped = cache.ped
local vehicle = cache.vehicle
local loaded = cache.playerLoaded
```

### `lib.cache(key)`

```lua
local job = lib.cache('job')
```

### `lib.onCache(key, cb)`

Registers a change listener and immediately invokes the callback with the current value.

```lua
lib.onCache('cuffed', function(isCuffed, oldValue)
  print(('Now cuffed: %s (was %s)'):format(isCuffed, oldValue))
end)
```

Equivalent low-level event:

```lua
AddEventHandler('dirk_lib:cache:cuffed', function(newValue, oldValue)
  -- ...
end)
```

## Cache Keys (Client)

| Key            | Type            | Description                                        |
| -------------- | --------------- | -------------------------------------------------- |
| `resource`     | string          | Current resource name                              |
| `game`         | string          | Game name (`fivem` / `redm`)                       |
| `playerId`     | number          | Result of `PlayerId()`                             |
| `serverId`     | number          | Current player server ID                           |
| `ped`          | number          | Current player ped entity                          |
| `vehicle`      | number \| false | Vehicle entity if in vehicle; otherwise `false`    |
| `seat`         | number \| false | Current seat index; otherwise `false`              |
| `driver`       | boolean         | `true` when seat is `-1`                           |
| `weapon`       | number \| false | Current weapon hash when armed; otherwise `false`  |
| `mount`        | number \| false | RedM only: current mount entity or `false`         |
| `dead`         | boolean         | Framework/game state death flag                    |
| `cuffed`       | boolean \| nil  | Framework-specific cuff state                      |
| `job`          | table           | Parsed framework job object (see formats below)    |
| `gang`         | table \| nil    | QB/QBX gang payload                                |
| `citizenId`    | string \| nil   | Character identifier (`citizenid` or `identifier`) |
| `charName`     | string \| nil   | Character full name                                |
| `playerLoaded` | boolean         | Whether character/player has loaded                |

{% hint style="warning" %}
`cache.playerData` is **not** a cache key in current `dirk_lib` source.
{% endhint %}

## Job Object Format

The `job` cache shape is built in framework cache adapters (not from `dirk_lib/types/job`).

### QB / QBX job shape

```lua
{
  name = string,
  type = string,
  label = string,
  grade = number,       -- job.grade.level
  isBoss = boolean,
  bankAuth = any,
  gradeLabel = string,  -- job.grade.name
  duty = boolean,       -- job.onduty
}
```

### ESX job shape

```lua
{
  name = string,
  type = string,
  label = string,
  grade = number,       -- job.grade
  isBoss = boolean,
  bankAuth = any,
  gradeLabel = string,  -- job.grade_label
  duty = boolean,       -- job.onduty
}
```

### Logged-out QB/QBX fallback

On player unload, `job` is set to:

```lua
{
  name = 'logged_off',
  grade = 2,
  onduty = false
}
```

## Framework-Dependent Notes

* `dead`, `cuffed`, `job`, `citizenId`, `charName`, and `playerLoaded` are framework-populated.
* `gang` is currently populated in QB/QBX adapters.
* `mount` is populated only on RedM.

## Change Semantics

Cache writes use deep comparison for tables and emit `dirk_lib:cache:<key>` only when values actually change.