> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/plugins/ak47_lib/framework/server.md).

# Server

The `ak47_lib` automatically detects the running framework. You can access these functions by importing the lib export in your script.

```lua
local Lib47 = exports['ak47_lib']:GetLibObject()
```

#### **`Lib47.Framework`**

A built-in variable that stores the active framework detected by the library. This is highly useful for writing dynamic, multi-framework scripts that need to execute different logic depending on the server's core environment.

Expected Values: `'esx'`, `'qb'`, or `'qbx'`.

```lua
--- @type string The name of the currently active framework
local currentFramework = Lib47.Framework

-- Example usage for framework-specific logic
if Lib47.Framework == 'qb' then
    print("Detected Framework: QBCore")
    -- Execute QBCore specific code here
    
elseif Lib47.Framework == 'esx' then
    print("Detected Framework: ESX")
    -- Execute ESX specific code here
    
elseif Lib47.Framework == 'qbx' then
    print("Detected Framework: Qbox")
    -- Execute Qbox specific code here
    
else
    print("No supported framework detected (Standalone)")
end
```

#### **`Lib47.GetCoreConfig`**

Retrieves the main configuration table of the active framework (e.g., `QBCore.Config` or `ESX.GetConfig()`). This is highly useful for fetching default framework settings without needing to directly reference the core objects, keeping your script standalone-friendly.

*Note: When using ESX, you can optionally pass a specific string `key` to return a single value instead of the entire table. In QBCore/Qbox, the `key` parameter is ignored and the full configuration table is always returned.*

```lua
--- @param key string|nil (Optional) Specific config key to fetch (Utilized by ESX)
--- @return table|any The core configuration table, or a specific value (if key is provided in ESX). Returns an empty table {} on failure.

-- Example 1: Fetching the entire config table (Works on all frameworks)
local coreConfig = Lib47.GetCoreConfig()

if coreConfig then
    print("Core configuration loaded successfully.")
    -- You can now access framework settings: e.g., coreConfig.DefaultSpawn
end

-- Example 2: Fetching a specific key (Useful for ESX servers)
if Lib47.Framework == 'esx' then
    local startingAccountMoney = Lib47.GetCoreConfig('StartingAccountMoney')
    print("Default starting money configured in ESX: " .. json.encode(startingAccountMoney))
end
```

### Core Player & Identity

These functions handle identifying players and retrieving their basic information across all frameworks.

#### `Lib47.GetPlayer`

Retrieves the raw framework-specific player object (e.g., `xPlayer` for ESX, `Player` for QBCore).

```lua
--- @param source number The player's server ID
--- @return table|nil The player object
local player = Lib47.GetPlayer(source)
```

#### `Lib47.GetIdentifier`

Returns the unique identifier for the player (CitizenID for QBCore/QBX, Identifier for ESX).

```lua
--- @param source number The player's server ID
--- @return string The unique identifier
local identifier = Lib47.GetIdentifier(source)
```

#### **`Lib47.GetCharacterName`**

Returns the player's full character name directly from the server side. (Note: This function acts as the replacement for `Lib47.GetName`, which is marked for removal.)

```lua
--- @param source number The player's server ID
--- @return string The full name (Firstname Lastname)
local name = Lib47.GetCharacterName(source)
```

#### `Lib47.GetPhoneNumber`

Returns the player's phone number.

```lua
--- @param source number The player's server ID
--- @return string The phone number
local phone = Lib47.GetPhoneNumber(source)
```

#### `Lib47.GetLicense`

Returns the Rockstar license of the player.

```lua
--- @param source number The player's server ID
--- @return string The license
local license = Lib47.GetLicense(source)
```

#### `Lib47.GetSourceFromIdentifier`

Finds a player's server ID based on their identifier.

```lua
--- @param identifier string The unique identifier
--- @return number|nil The source ID (or nil if offline)
local source = Lib47.GetSourceFromIdentifier(identifier)
```

#### **`Lib47.GetCoreConfig`**

Retrieves the active framework's core configuration table on the server.

```lua
--- @param key string|nil (Optional for ESX)
--- @return table
local config = Lib47.GetCoreConfig()
```

#### **`Lib47.GetSource`**

Gets the server ID from a framework player object.

```lua
--- @param Player table The framework player object
--- @return number The source ID
local source = Lib47.GetSource(Player)
```

#### **`Lib47.GetPlayerFromIdentifier`**

Retrieves the framework player object using their identifier.

```lua
--- @param identifier string
--- @return table|nil The player object
local player = Lib47.GetPlayerFromIdentifier(identifier)
```

#### **`Lib47.GetIdentifierByType`**

Fetches a specific type of identifier (e.g., 'steam', 'license', 'discord') from a player.

```lua
--- @param source number The player's server ID
--- @param idtype string The type of identifier to find
--- @return string|nil The identifier string
local discord = Lib47.GetIdentifierByType(source, 'discord')
```

#### **`Lib47.GetNameFromIdentifier`**

Fetches a player's full character name directly from the database using their identifier.

```lua
--- @param identifier string
--- @return string The full name
local name = Lib47.GetNameFromIdentifier(identifier)
```

#### **`Lib47.GetMetaData` / `Lib47.SetMetaData`**

```lua
--- @param source number
--- @param key string
--- @return any
local value = Lib47.GetMetaData(source, 'hunger')

--- @param source number
--- @param key string
--- @param value any
Lib47.SetMetaData(source, 'hunger', 100)
```

#### **`Lib47.HasGroupPermission`**

Checks if a player belongs to a specific permission group.

```lua
--- @param source number
--- @param group string Group name (e.g., 'admin', 'mod')
--- @return boolean
local hasPerm = Lib47.HasGroupPermission(source, 'admin')
```

***

### Jobs, Gangs & Permissions

#### `Lib47.GetJob`

Returns a standardized job table.

```lua
--- @param source number
--- @return table { name, label, payment, isboss, grade = { name, level } }
local job = Lib47.GetJob(source)
print(job.name, job.grade.level)
```

#### `Lib47.SetJob`

Sets the player's job and grade.

```lua
--- @param source number
--- @param jobName string
--- @param grade number
Lib47.SetJob(source, 'police', 2)
```

#### `Lib47.GetGang`

Returns a standardized gang table.

```lua
--- @param source number
--- @return table { name, label, isboss, grade = { name, level } }
local gang = Lib47.GetGang(source)
```

#### `Lib47.SetGang`

Sets the player's gang and grade.

```lua
--- @param source number
--- @param gangName string
--- @param grade number
Lib47.SetGang(source, 'ballas', 1)
```

#### **`Lib47.HasPermission`**

Checks if a player meets any permission criteria (Ace, License, Identifier, or Group) defined in a configuration table. Optionally prints a success notification to the server console.

```lua
--- @param source number
--- @param Admin table { WithAce = boolean, WithLicense = table, WithIdentifier = table, WithGroup = table }
--- @param notify boolean|nil Prints resource and method to console if true
--- @return boolean
local AdminConfig = {
    WithAce = true,
    WithLicense = {
        ['license:yourlicensekeyhere123'] = true
    },
    WithIdentifier = {
        ['YourCitizenIDorESXIdentifier'] = true
    },
    WithGroup = {
        ['admin'] = true,
        ['superadmin'] = true
    }
}

local hasAccess = Lib47.HasPermission(source, AdminConfig, true)

if hasAccess then
    print("Player has required permissions")
end
```

#### `Lib47.IsAdmin`

Checks if the player has admin privileges (checks for 'command' ace permission).

```lua
--- @param source number
--- @return boolean
if Lib47.IsAdmin(source) then
    print("Player is admin")
end
```

***

### Economy

#### `Lib47.GetMoney`

Retrieves the balance of a specific account.

```lua
--- @param source number
--- @param account string 'money' (or 'cash'), 'bank', 'black_money'
--- @return number
local cash = Lib47.GetMoney(source, 'cash')
```

#### `Lib47.AddMoney`

Adds money to a specific account.

```lua
--- @param source number
--- @param account string
--- @param amount number
Lib47.AddMoney(source, 'bank', 5000)
```

#### `Lib47.RemoveMoney`

Removes money from a specific account.

```lua
--- @param source number
--- @param account string
--- @param amount number
Lib47.RemoveMoney(source, 'money', 100)
```

#### `Lib47.GetSocietyMoney`

Gets the money associated with a job/society. Supports `esx_addonaccount`, `qb-management`, `qb-banking`, `okokBanking`, and `Renewed-Banking`.

```lua
--- @param job string The society/job name
--- @param ignoreBankingExport boolean|nil (Optional) Skip external banking exports
--- @return number
local balance = Lib47.GetSocietyMoney('police', false)
```

#### `Lib47.AddSocietyMoney` / `Lib47.RemoveSocietyMoney`

Modifies society funds with optional reason tracking and external export bypassing.

```lua
--- @param job string The society/job name
--- @param money number The amount to add/remove
--- @param reason string|nil (Optional) The reason for the transaction
--- @param ignoreBankingExport boolean|nil (Optional) Skip external banking exports
Lib47.AddSocietyMoney('police', 1000, 'State Grant', false)
Lib47.RemoveSocietyMoney('police', 500, 'Vehicle Repair', false)
```

***

### Basic Vehicle Management

#### `Lib47.GetFrameworkVehicles`

Get all registered framework vehicles.

```lua
local vehicles = Lib47.GetFrameworkVehicles()
local vehicle = vehicles[GetHashKey('adder')]

if vehicle then
    print("Model:" .. vehicle.model, "Name: " .. vehicle.label, "Category: " .. vehicle.category, "Price:" .. vehicle.price)
end
```

#### `Lib47.GetFrameworkVehicleByHash`

Get a specific registered framework vehicle by hash.

```lua
--- @param hash string
local hash = GetHashKey('adder')
local vehicle = Lib47.GetFrameworkVehicleByHash(hash)

if vehicle then
    print("Model:" .. vehicle.model, "Name: " .. vehicle.label, "Category: " .. vehicle.category, "Price:" .. vehicle.
end
```

#### `Lib47.IsVehicleOwner`

Checks if a player owns a vehicle with a specific plate.

```lua
--- @param source number
--- @param plate string
--- @return boolean
local owned = Lib47.IsVehicleOwner(source, 'ABC 123')
```

#### `Lib47.GetVehicleOwner`

Returns the identifier of the owner of a specific plate.

```lua
--- @param plate string
--- @return string|nil Identifier
local owner = Lib47.GetVehicleOwner('ABC 123')
```

#### `Lib47.GeneratePlate`

Generates a unique plate based on a pattern.

```lua
--- @param format string (optional) Default: "AAAA 11A"
--- @param prefix string (optional)
--- @return string
local newPlate = Lib47.GeneratePlate("AA111111")
```

#### `Lib47.GiveVehicle`

Inserts a vehicle into the database (owned\_vehicles / player\_vehicles).

```lua
--- @param source number
--- @param model string|number Model name or hash
Lib47.GiveVehicle(source, 'adder')
```

### Offline Data Management

#### **`Lib47.GetAllOfflinePlayers`**

Fetches all players from the database with their basic character info, money, and job data.

```lua
--- @return table Array of player data tables
local players = Lib47.GetAllOfflinePlayers()
```

#### **`Lib47.GetJobs`**

Retrieves the shared list of all jobs and their grades from the framework.

```lua
--- @return table
local jobs = Lib47.GetJobs()
```

#### **`Lib47.GetOfflineMoney`**

Gets the balance of a specific account for an offline player from the database.

```lua
--- @param identifier string
--- @param account string 'money' (or 'cash'), 'bank'
--- @return number
local offlineBank = Lib47.GetOfflineMoney(identifier, 'bank')
```

#### **`Lib47.AddOfflineMoney` / `Lib47.RemoveOfflineMoney`**

Modifies the money balance of an offline player directly in the database.

```lua
--- @param identifier string
--- @param account string
--- @param amount number
Lib47.AddOfflineMoney(identifier, 'bank', 5000)
Lib47.RemoveOfflineMoney(identifier, 'cash', 500)
```

#### **`Lib47.GetOfflineMetaData` / `Lib47.SetOfflineMetaData`**

Gets or sets metadata for an offline player directly in the database.

```lua
--- @param identifier string
--- @param key string
--- @return any
local jailTime = Lib47.GetOfflineMetaData(identifier, 'injail')

--- @param identifier string
--- @param key string
--- @param value any
Lib47.SetOfflineMetaData(identifier, 'injail', 15)
```

### Inventory

#### **`Lib47.GetInventoryItems`**

Retrieves all items inside a specific inventory or player's inventory.

```lua
--- @param inventoryId string|number The inventory ID or player source
--- @return table List of items
local items = Lib47.GetInventoryItems(source)
```

#### **`Lib47.GetItemsByName`**

Retrieves all instances of a specific item from a player's inventory.

```lua
--- @param source number Player Server ID
--- @param item string Item name
--- @return table List of matched items
local matchedItems = Lib47.GetItemsByName(source, 'water')
```

#### **`Lib47.GetItemAmount`**

An alias/alternative to `Lib47.GetInventoryItem`. Gets the total count of a specific item in the player's inventory.

```lua
--- @param source number Player Server ID
--- @param item string Item name
--- @return number Total amount
local amount = Lib47.GetItemAmount(source, 'phone')
```