# Framework Bridge

The Core Bridge module provides a unified API across multiple frameworks for player data, identity, inventory, balances, jobs, and more. The examples below reflect the boii\_core implementation, but the API remains consistent across all supported frameworks.

***

## Accessing the Module

```lua
local CORE <const> = exports.boii_utils:get("bridges.framework")
```

***

## Server

### get\_players()

Returns all players connected to the server.

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| -    | -    | None        |

#### Example

```lua
local players = CORE.get_players()
```

***

### get\_player(source)

Retrieves player data by source ID.

#### Parameters

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| source | `number` | Player source ID |

#### Example

```lua
local player = CORE.get_player(source)
```

***

### get\_id\_params(source)

Generates identifier query and parameters.

#### Parameters

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| source | `number` | Player source ID |

#### Example

```lua
local query, params = CORE.get_id_params(source)
```

***

### get\_player\_id(source)

Returns the player's main identifier.

#### Parameters

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| source | `number` | Player source ID |

#### Example

```lua
local id = CORE.get_player_id(source)
```

***

### get\_identity(source)

Returns a player's identity information.

#### Parameters

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| source | `number` | Player source ID |

#### Example

```lua
local identity = CORE.get_identity(source)
```

***

### get\_inventory(source)

Gets a player's inventory.

#### Parameters

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| source | `number` | Player source ID |

#### Example

```lua
local inventory = CORE.get_inventory(source)
```

***

### get\_item(source, item\_name)

Gets a specific item from the player's inventory.

#### Parameters

| Name       | Type     | Description      |
| ---------- | -------- | ---------------- |
| source     | `number` | Player source ID |
| item\_name | `string` | Name of the item |

#### Example

```lua
local item = CORE.get_item(source, "radio")
```

***

### has\_item(source, item\_name, item\_amount?)

Checks if a player has an item in their inventory.

#### Parameters

| Name          | Type     | Description                    |
| ------------- | -------- | ------------------------------ |
| source        | `number` | Player source ID               |
| item\_name    | `string` | Name of the item               |
| item\_amount? | `number` | Optional quantity (default: 1) |

#### Example

```lua
if CORE.has_item(source, "bandage", 2) then
    -- has at least 2 bandages
end
```

***

### add\_item(source, item\_id, amount, data?)

Adds an item to a player's inventory.

#### Parameters

| Name     | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| source   | `number` | Player source ID              |
| item\_id | `string` | ID of the item                |
| amount   | `number` | Quantity                      |
| data?    | `table`  | Optional metadata (e.g. ammo) |

#### Example

```lua
CORE.add_item(source, "ammo_9mm", 50)
```

***

### remove\_item(source, item\_id, amount)

Removes an item from a player's inventory.

#### Parameters

| Name     | Type     | Description        |
| -------- | -------- | ------------------ |
| source   | `number` | Player source ID   |
| item\_id | `string` | ID of the item     |
| amount   | `number` | Quantity to remove |

#### Example

```lua
CORE.remove_item(source, "radio", 1)
```

***

### update\_item\_data(source, item\_id, updates)

Modifies an item entry (e.g. ammo or durability).

#### Parameters

| Name     | Type     | Description               |
| -------- | -------- | ------------------------- |
| source   | `number` | Player source ID          |
| item\_id | `string` | ID of the item            |
| updates  | `table`  | Data to apply (key/value) |

#### Example

```lua
CORE.update_item_data(source, "weapon_pistol", { durability = 95 })
```

***

### get\_balances(source)

Returns all account balances.

#### Parameters

| Name   | Type     | Description      |
| ------ | -------- | ---------------- |
| source | `number` | Player source ID |

#### Example

```lua
local balances = CORE.get_balances(source)
```

***

### get\_balance\_by\_type(source, balance\_type)

Gets a specific account balance.

#### Parameters

| Name          | Type     | Description          |
| ------------- | -------- | -------------------- |
| source        | `number` | Player source ID     |
| balance\_type | `string` | Type: "cash", "bank" |

#### Example

```lua
local cash = CORE.get_balance_by_type(source, "cash")
```

***

### add\_balance(source, balance\_type, amount, sender?, note?)

Adds money to a player account.

#### Parameters

| Name          | Type     | Description                 |
| ------------- | -------- | --------------------------- |
| source        | `number` | Player source ID            |
| balance\_type | `string` | Account type                |
| amount        | `number` | Amount to add               |
| sender?       | `string` | Optional sender description |
| note?         | `string` | Optional transaction note   |

#### Example

```lua
CORE.add_balance(source, "bank", 1000, "ATM", "Paycheck")
```

***

### remove\_balance(source, balance\_type, amount, recipient?, note?)

Removes money from a player account.

#### Parameters

| Name          | Type     | Description               |
| ------------- | -------- | ------------------------- |
| source        | `number` | Player source ID          |
| balance\_type | `string` | Account type              |
| amount        | `number` | Amount to remove          |
| recipient?    | `string` | Optional recipient name   |
| note?         | `string` | Optional transaction note |

#### Example

```lua
CORE.remove_balance(source, "cash", 250)
```

***

### get\_player\_jobs(source)

Returns a list of jobs the player currently holds.

#### Parameters

| Name   | Type     | Description              |
| ------ | -------- | ------------------------ |
| source | `number` | Player source identifier |

#### Example

```lua
local jobs = CORE.get_player_jobs(source)
for _, job in pairs(jobs) do
    print("Job:", job)
end
```

***

### player\_has\_job(source, job\_names, check\_on\_duty?)

Checks whether a player has one of the specified jobs. Optionally checks if they're on duty.

#### Parameters

| Name            | Type       | Description                       |
| --------------- | ---------- | --------------------------------- |
| source          | `number`   | Player source identifier          |
| job\_names      | `table`    | List of job names to check        |
| check\_on\_duty | `boolean?` | Whether to require on-duty status |

#### Example

```lua
local hasJob = CORE.player_has_job(source, { "police" }, true)
```

***

### get\_player\_job\_grade(source, job\_id)

Returns the player's rank (grade) for the specified job.

#### Parameters

| Name    | Type     | Description              |
| ------- | -------- | ------------------------ |
| source  | `number` | Player source identifier |
| job\_id | `string` | Job ID to check          |

#### Example

```lua
local grade = CORE.get_player_job_grade(source, "police")
```

***

### count\_players\_by\_job(job\_names, check\_on\_duty?)

Counts players with a specific job. Optionally checks duty status.

#### Parameters

| Name            | Type       | Description                       |
| --------------- | ---------- | --------------------------------- |
| job\_names      | `table`    | List of job names to count        |
| check\_on\_duty | `boolean?` | Whether to check for on-duty only |

#### Example

```lua
local total, onduty = CORE.count_players_by_job({ "ambulance" }, true)
```

***

### get\_player\_job\_name(source)

Returns the first job name assigned to a player.

#### Parameters

| Name   | Type     | Description              |
| ------ | -------- | ------------------------ |
| source | `number` | Player source identifier |

#### Example

```lua
local job = CORE.get_player_job_name(source)
```

***

### adjust\_statuses(source, statuses)

Applies status modifications to a player server-side.

#### Parameters

| Name     | Type     | Description              |
| -------- | -------- | ------------------------ |
| source   | `number` | Player source identifier |
| statuses | `table`  | Table of status values   |

#### Example

```lua
CORE.adjust_statuses(source, { hunger = -10, thirst = -5 })
```

***

### register\_item(item, cb)

Registers an item as usable and calls the callback on use.

#### Parameters

| Name | Type       | Description                   |
| ---- | ---------- | ----------------------------- |
| item | `string`   | Name of the usable item       |
| cb   | `function` | Function to run on item usage |

#### Example

```lua
CORE.register_item("joint", function(source)
    print("Joint used by:", source)
end)
```

***

## Client

### get\_data(key?)

Returns the full or partial player data table.

#### Parameters

| Name | Type     | Description                    |
| ---- | -------- | ------------------------------ |
| key  | `string` | (Optional) Specific key to get |

#### Example

```lua
local data = CORE.get_data("identity")
```

***

### get\_identity()

Returns a structured identity object.

#### Example

```lua
local id = CORE.get_identity()
print("Name:", id.first_name, id.last_name)
```

***

### get\_player\_id()

Returns the current player's unique identifier.

#### Example

```lua
local player_id = CORE.get_player_id()
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.boii.dev/old-docs/boii_utils/api/framework-bridge.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.