# 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()
```