# Framework Class

A powerfull library to build a script compatible with all Frameworks. The module architecture is based on a folder structure, with one folder per framework.
With this structure, the data from one framework can't intefere with date from another one. 

::: info
The framework is automatically detected once the module is started based on resource in the server.
:::
::: tip
If you have a custom framework, you can overwrite methods by added the one you want edit inside `_custom/FrameworkClass.lua` file.
:::

:::details List of compatible frameworks
* VORP
* RedEM:RP old
* RedEM:RP 2023 (reboot)
* QBR
* QR
* RSG
* RPX
* TPZ
:::

## Configuration Variables (Convars)

| Convar | Side | Type | Default | Description |
|--------|------|------|---------|-------------|
| `jo_libs:framework` | `[Shared]` | String | `false` | Force the framework |

## jo.framework Methods

### `[Client]` jo.framework:getMyIdentifiers()

A function to get the user identifiers <br>

#### Syntax

```lua
jo.framework:getMyIdentifiers()
```

---

### `[Server]` jo.framework:addItemInInventory()

Adds a specific item to a custom inventory with optional metadata and wait parameter <br>

#### Syntax

```lua
jo.framework:addItemInInventory(source, invId, item, quantity, metadata, needWait)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`invId` : _string_
> The unique ID of the inventory
>

`item` : _string_
> The name of the item
>

`quantity` : _integer_
> The quantity of the item
>

`metadata` : _table_ `[Optional]`

> The metadata of the item
>

`needWait` : _boolean_ `[Optional]`
> If need to wait after the SQL insertion <br> default:`false`
>

---

### `[Server]` jo.framework:addMoney()

A function to give money to a player <br>

#### Syntax

```lua
jo.framework:addMoney(source, amount, moneyType)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`amount` : _number_
> The amount of money to add
>

`moneyType` : _integer_ `[Optional]`
> `0`: dollar, `1`: gold, `2`: rol <br> default:`0`
>

#### Return Value

Type : _boolean_

> Return `true` if the money is successfully added

---

### `[Server]` jo.framework:canUseItem()

Checks if a player has the required quantity of a specific item in their inventory and optionally removes it <br>

#### Syntax

```lua
jo.framework:canUseItem(source, item, amount, meta, remove)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`item` : _string_
> The name of the item need to use
>

`amount` : _integer_
> The quantity of the item
>

`meta` : _table_ `[Optional]`

> The metadata of the item
>

`remove` : _boolean_ `[Optional]`
> If the item has to be removed <br> default:`false`
>

#### Return Value

Type : _boolean_

> Return `true` if the player has enough quantity of the item

---

### `[Server]` jo.framework:canUserBuy()

Checks if a player has sufficient funds of a specified currency type <br>

#### Syntax

```lua
jo.framework:canUserBuy(source, amount, moneyType, removeIfCan)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`amount` : _number_
> The amount of money the player needs to have <br> {money = 10.5, gold = 3, rol = 1.5}
>

`moneyType` : _integer|string_ `[Optional]`
> `0`: dollar, `1`: gold, `2`: rol <br> default:`1`
>

`removeIfCan` : _boolean_ `[Optional]`
> Remove the money if the player has enough <br> default:`false`
>

#### Return Value

Type : _boolean_

> Returns `true` if the player has more money than the amount

---

### `[Server]` jo.framework:canUserPayWith()

A function that checks if a player can pay multiple prices <br>

#### Syntax

```lua
jo.framework:canUserPayWith(source, prices, removeIfCan)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`prices` : _table_

> The prices to check
>

`removeIfCan` : _boolean_ `[Optional]`
> Remove the prices if the player can pay
>

#### Return Value

Type : _boolean,_

---

### `[Server]` jo.framework:createInventory()

Creates a custom inventory with configurable slots, weight limits, and item restrictions <br>

#### Syntax

```lua
jo.framework:createInventory(invName, name, invConfig)
```

#### Parameters

`invName` : _string_
> Unique id of the inventory
>

`name` : _string_
> Label of the inventory
>

`invConfig` : _table_

> Configuration of the inventory
>

> `invConfig.maxSlots` : _integer_ - Max slot of the inventory
> 
> `invConfig.maxWeight` : _float_ - Max weight of the inventory
> 
> `invConfig.acceptWeapons` : _boolean_ - Whether the inventory accepts weapons `[Optional]`
> 
> `invConfig.shared` : _boolean_ - If the inventory is shared between players `[Optional]`
> 
> `invConfig.ignoreStackLimit` : _boolean_ - If the inventory can overcoming stack limits `[Optional]`
> 
> `invConfig.whitelist` : _table_ - Restrict the list of items that can be put in the inventory `[Optional]`
> 
> `invConfig.whitelistˌ_x_ˌitem` : _string_ - Name of the whitelisted item
> 
> `invConfig.whitelistˌ_x_ˌlimit` : _integer_ - Stack limit of this item
> 

---

### `[Server]` jo.framework:get()

Returns the name of the current active framework being used <br>

#### Syntax

```lua
jo.framework:get()
```

#### Return Value

Type : _string_

> Return the name of the current framework : <br> `"VORP"` or `"RedEM"` or `"RedEM2023"` or `"qbr"` or `"rsg"` or `"qr"` or `"rpx"`

---

### `[Server]` jo.framework:getItemCount()

Gets the quantity of a specific item in a player's inventory <br>

#### Syntax

```lua
jo.framework:getItemCount(source, item, meta)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`item` : _string_
> The name of the item
>

`meta` : _table_ `[Optional]`

> The metadata of the item
>

#### Return Value

Type : _integer_

> Return the total quantity of the item in the player's inventory

---

### `[Server]` jo.framework:getItemsFromInventory()

Retrieves all items from a specific inventory with their quantities and metadata <br>

#### Syntax

```lua
jo.framework:getItemsFromInventory(invId)
```

#### Parameters

`invId` : _string_
> The unique ID of the inventory
>

#### Return Value

Type : _table_

> Return the list of items with structure : <br> `item.amount` : *integer* - The amount of the item<br> `item.id` : *integer* - The id of the item<br>`item.item` : *string* - The name of the item<br>`item.metadata` : *table* - The metadata of the item<br>

---

### `[Server]` jo.framework:getJob()

Returns the current job assigned to a player <br>

#### Syntax

```lua
jo.framework:getJob(source)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

#### Return Value

Type : _string_

> Return the job name of the player

---

### `[Server]` jo.framework:getRPName()

Returns the roleplay name (first and last name) of the player <br>

#### Syntax

```lua
jo.framework:getRPName(source)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

#### Return Value

Type : _string_

> Return the formatted first and last name of the player

---

### `[Server]` jo.framework:getSourceFromIdentifiers()

Retrieves the source ID from identifiers <br>

#### Syntax

```lua
jo.framework:getSourceFromIdentifiers(identifier, charid)
```

#### Parameters

`identifier` : _string_
> The identifier to search for
>

`charid` : _string_
> The character ID to search for
>

#### Return Value

Type : _integer|boolean_

> Return the source ID if found, otherwise return false

---

### `[Server]` jo.framework:getUser()

Retrieves a player's full [UserClass](#userclass-methods) object containing all player data and methods <br>

#### Syntax

```lua
jo.framework:getUser(source)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

#### Return Value

Type : _[UserClass](#userclass-methods)_

> Return a User class object containing player data and methods

---

### `[Server]` jo.framework:getUserClothes()

Retrieves a player's clothing data with standardized category names <br>

#### Syntax

```lua
jo.framework:getUserClothes(source)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

#### Return Value

Type : _table_

> Return the list of clothes with standardized categories and properties

---

### `[Server]` jo.framework:getUserIdentifiers()

Retrieves all identifiers associated with a player <br> Shortcut for [jo.framework.UserClass:getIdentifiers()](./user#jo.framework.UserClass-getidentifiers) method <br>

#### Syntax

```lua
jo.framework:getUserIdentifiers(source)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

#### Return Value

Type : _table_

> Return the player's identifiers <br> `identifiers.identifier` - Unique identifier of the player <br> `identifiers.charid` - Unique id of the player

---

### `[Server]` jo.framework:getUserSkin()

Retrieves a player's skin data with standardized properties and formatting <br>

#### Syntax

```lua
jo.framework:getUserSkin(source)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

#### Return Value

Type : _table_

> Return the skin data

---

### `[Server]` jo.framework:giveItem()

Adds an item to a player's inventory with optional metadata <br>

#### Syntax

```lua
jo.framework:giveItem(source, item, quantity, meta)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`item` : _string_
> The name of the item
>

`quantity` : _integer_
> The amount of the item to give
>

`meta` : _table_ `[Optional]`

> The metadata of the item
>

#### Return Value

Type : _boolean_

> Return `true` if the item is successfully given

---

### `[Server]` jo.framework:is()

Compares the current framework with a specified framework name <br>

#### Syntax

```lua
jo.framework:is(name)
```

#### Parameters

`name` : _string_
> The name of the framework to check against <br> Supported frameworks : <br> `"VORP"` or `"RedEM"` or `"RedEM2023"` or `"qbr"` or `"rsg"` or `"qr"` or `"rpx"`
>

#### Return Value

Type : _boolean_

> Return `true` if the current framework matches the name

---

### `[Server]` jo.framework:listenItemRemoved()

Listen when an item is removed of the player inventory <br>

#### Syntax

```lua
jo.framework:listenItemRemoved(...)
```

#### Parameters

`item` : _string|function_
> The name of the item
>

`callback` : _function_
> The function fired after remove the item <br> 1st argument: source <br> 2nd argument: the quantity removed <br> 3rd argument: metadata of the item <br> 4th argument: reason of the removal
>

---

### `[Server]` jo.framework:mergeInventoriesConfiguration()

Merge inventory configuration <br>

#### Syntax

```lua
jo.framework:mergeInventoriesConfiguration(...)
```

#### Parameters

`...` : _table_

> The inventory configurations to merge
>

#### Return Value

Type : _table_

> The merged inventory configuration

---

### `[Server]` jo.framework:onCharacterSelected()

Callback when a character is selected <br>

#### Syntax

```lua
jo.framework:onCharacterSelected(cb)
```

#### Parameters

`cb` : _function_
> The callback function triggered when the character is selected, contains (source:integer, isNew:boolean)
>

---

### `[Server]` jo.framework:openInventory()

Opens a specific inventory <br>

#### Syntax

```lua
jo.framework:openInventory(source, invName)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`invName` : _string_
> The unique ID of the inventory
>

---

### `[Server]` jo.framework:refundUserWith()

A function to refund a player with multiple prices <br>

#### Syntax

```lua
jo.framework:refundUserWith(source, prices)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`prices` : _table_

> The prices to refund
>

#### Return Value

Type : _nil_

---

### `[Server]` jo.framework:registerUseItem()

Registers an item as usable and attaches a callback function that executes when the item is used <br>

#### Syntax

```lua
jo.framework:registerUseItem(item, closeAfterUsed, callback)
```

#### Parameters

`item` : _string_
> The name of the item
>

`closeAfterUsed` : _boolean_ `[Optional]`
> If the inventory needs to be closed after using the item <br> default:`true`
>

`callback` : _function_
> The function fired after use the item <br> 1st argument: source <br> 2nd argument: metadata of the item
>

---

### `[Server]` jo.framework:removeInventory()

Removes an inventory from the *server cache*, useful for reloading inventory data from the database <br>

#### Syntax

```lua
jo.framework:removeInventory(invName)
```

#### Parameters

`invName` : _string_
> Unique id of the inventory
>

---

### `[Server]` jo.framework:removeItem()

A function to remove an item from a player's inventory if they have enough quantity <br>

#### Syntax

```lua
jo.framework:removeItem(source, item, quantity, meta)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`item` : _string_
> The name of the item to remove
>

`quantity` : _integer_
> The quantity of the item to remove
>

`meta` : _table_ `[Optional]`

> The metadata of the item
>

#### Return Value

Type : _boolean_

> Return `true` if the item is successfully removed

---

### `[Server]` jo.framework:removeMoney()

A function to remove money from a player's account <br>

#### Syntax

```lua
jo.framework:removeMoney(source, amount, moneyType)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`amount` : _number_
> The amount of money to remove
>

`moneyType` : _integer_ `[Optional]`
> `0`: dollar, `1`: gold, `2`: rol <br> default:`0`
>

#### Return Value

Type : _boolean_

> Return `true` if the money is successfully removed

---

### `[Server]` jo.framework:revertClothes()

Converts standardized clothing data back to framework-specific format <br>

#### Syntax

```lua
jo.framework:revertClothes(standard)
```

#### Parameters

`standard` : _table_

> The standardized clothes data
>

#### Return Value

Type : _table_

> Return clothes data with framework-specific keys

---

### `[Server]` jo.framework:revertSkin()

Converts standardized skin data back to framework-specific format <br>

#### Syntax

```lua
jo.framework:revertSkin(standard)
```

#### Parameters

`standard` : _table_

> The standardized skin data
>

#### Return Value

Type : _table_

> Return skin data with framework-specific keys

---

### `[Server]` jo.framework:standardizeClothes()

Converts framework-specific clothing data to a standardized format <br>

#### Syntax

```lua
jo.framework:standardizeClothes(clothes)
```

#### Parameters

`clothes` : _table_

> The framework-specific clothes data
>

#### Return Value

Type : _table_

> Return clothes data with standardized keys and structure

---

### `[Server]` jo.framework:standardizeSkin()

Converts framework-specific skin data to a standardized format <br>

#### Syntax

```lua
jo.framework:standardizeSkin(skin)
```

#### Parameters

`skin` : _table_

> The framework-specific skin data
>

#### Return Value

Type : _table_

> Return skin data with standardized keys for components, overlays, and expressions

---

### `[Server]` jo.framework:updateUserClothes()

Save new clothes. <br>
The function has two ways to work: <br>
- With 2 arguments to save multiple clothes <br>
- With 3 arguments to save one piece of clothing <br>

#### Syntax

```lua
jo.framework:updateUserClothes(...)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`clothes` : _table_

> The list of clothes to apply or the category name
>

`value` : _table_ `[Optional]`

> The clothing data if updating a single category
>

`overwrite` : _boolean_ `[Optional]`
> If `true`, the new value overwrites the previous clothes. Else, it's merged
>

---

### `[Server]` jo.framework:updateUserSkin()

Save new skin values. <br>
The function has two ways to work: <br>
- With 3 arguments to save multiple skin data <br>
- With 4 arguments to save only one skin data <br>

#### Syntax

```lua
jo.framework:updateUserSkin(...)
```

#### Parameters

`source` : _integer_
> The source ID of the player
>

`skinData` : _table_

> The list of skin data with category for key and skin data for value
>

`category` : _string_
> The category of the skin data
>

`data` : _table_

> The skin data
>

`overwrite` : _boolean_ `[Optional]`
> If `true`, the new value overwrites the previous skin. Else, it's merged
>

---

### `[Shared]` jo.framework:addItemDataToPrice()

A function to add inventory item data to every item cost inside a price <br>

#### Syntax

```lua
jo.framework:addItemDataToPrice(price)
```

#### Parameters

`price` : _table_

> The price to augment
>

#### Return Value

Type : _table_

> The mutated price

---

### `[Shared]` jo.framework:getItemData()

A function to get an item data <br>

#### Syntax

```lua
jo.framework:getItemData(item)
```

#### Parameters

`item` : _string_
> The name of the item
>

#### Return Value

Type : _table|false_

> The item data or false if not found

---

### `[Shared]` jo.framework:getItems()

A function to get the list of items <br>

#### Syntax

```lua
jo.framework:getItems()
```

#### Return Value

Type : _table_

> The list of items

---

### `[Shared]` jo.framework:loadInventoryFiles()

#### Syntax

```lua
jo.framework:loadInventoryFiles(file)
```

---

# UserClass Methods
Documentation for the [User](./user.md)