Server

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

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'.

--- @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.

--- @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).

--- @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).

--- @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.)

--- @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.

--- @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.

--- @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.

--- @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.

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

Lib47.GetSource

Gets the server ID from a framework player object.

--- @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.

--- @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.

--- @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.

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

Lib47.GetMetaData / Lib47.SetMetaData

--- @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.

--- @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.

--- @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.

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

Lib47.GetGang

Returns a standardized gang table.

--- @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.

--- @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.

--- @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).

--- @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.

--- @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.

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

Lib47.RemoveMoney

Removes money from a specific account.

--- @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.

--- @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.

--- @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.

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.

--- @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.

--- @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.

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

Lib47.GeneratePlate

Generates a unique plate based on a pattern.

--- @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).

--- @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.

--- @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.

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

Lib47.GetOfflineMoney

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

--- @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.

--- @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.

--- @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.

--- @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.

--- @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.

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