> For the complete documentation index, see [llms.txt](https://laot7490.gitbook.io/ltbridge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://laot7490.gitbook.io/ltbridge/game-systems/state.md).

# State

## State

Read and write FiveM state bags — persistent key/value data attached to entities or the global scope.

### Functions

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Get</strong></td><td>Get entity state value.</td><td><a href="#get">#get</a></td></tr><tr><td><strong>GetPlayer</strong></td><td>Get local player state value.</td><td><a href="#getplayer">#getplayer</a></td></tr><tr><td><strong>OnChange</strong></td><td>Register a handler for state bag changes across all entities.</td><td><a href="#onchange">#onchange</a></td></tr><tr><td><strong>Set</strong></td><td>Set entity state value.</td><td><a href="#set">#set</a></td></tr><tr><td><strong>SetPlayer</strong></td><td>Set local player state value.</td><td><a href="#setplayer">#setplayer</a></td></tr></tbody></table>

***

## Get

Get entity state value.

{% hint style="info" %}
**Side:** Shared · **Category:** State · **API:** `LT.State.Get`
{% endhint %}

### Example

```lua
local fuel = LT.State.Get(vehicle, 'fuel')
```

### Parameters

| Name     | Required | Description   |
| -------- | -------- | ------------- |
| `entity` | Yes      | Entity handle |
| `key`    | Yes      | State key     |

### Returns

* `any`

***

## GetPlayer

Get a player state bag value.

{% hint style="info" %}
**Side:** Client / Server · **Category:** State · **API:** `LT.State.GetPlayer`
{% endhint %}

### Example

```lua
-- Client
local isWanted = LT.State.GetPlayer('wanted')

-- Server
local isWanted = LT.State.GetPlayer(source, 'wanted')
```

### Parameters

| Name     | Required    | Description      |
| -------- | ----------- | ---------------- |
| `source` | Server only | Player server ID |
| `key`    | Yes         | State key        |

### Returns

* `any`

***

## OnChange

Register a handler for state bag changes across all entities.

{% hint style="info" %}
**Side:** Shared · **Category:** State · **API:** `LT.State.OnChange`
{% endhint %}

### Example

```lua
LT.State.OnChange('fuel', function(value, bagName)
    local entity = GetEntityFromStateBagName(bagName)
    if entity > 0 then
        print(('Entity %s fuel changed to %s'):format(entity, value))
    end
end)
```

### Parameters

| Name      | Required | Description                      |
| --------- | -------- | -------------------------------- |
| `key`     | Yes      | State key to watch               |
| `handler` | Yes      | fun(value: any, bagName: string) |

### Returns

* `number Handler ID (use RemoveStateBagChangeHandler to remove)`

***

## Set

Set entity state value.

{% hint style="info" %}
**Side:** Shared · **Category:** State · **API:** `LT.State.Set`
{% endhint %}

### Example

```lua
LT.State.Set(vehicle, 'fuel', 100.0)
LT.State.Set(ped, 'busy', true, false) -- not replicated
```

### Parameters

| Name         | Required | Description                          |
| ------------ | -------- | ------------------------------------ |
| `entity`     | Yes      | Entity handle                        |
| `key`        | Yes      | State key                            |
| `value`      | Yes      | State value                          |
| `replicated` | No       | Replicate to network (default: true) |

***

## SetPlayer

Set a player state bag value.

{% hint style="info" %}
**Side:** Client / Server · **Category:** State · **API:** `LT.State.SetPlayer`
{% endhint %}

### Example

```lua
-- Client
LT.State.SetPlayer('wanted', true)

-- Server
LT.State.SetPlayer(source, 'wanted', true)
```

### Parameters

| Name         | Required    | Description                         |
| ------------ | ----------- | ----------------------------------- |
| `source`     | Server only | Player server ID                    |
| `key`        | Yes         | State key                           |
| `value`      | Yes         | State value                         |
| `replicated` | No          | Replicate to server (default: true) |