Framework Module API Documentation

framework compatibility layer for RedM scripts.

Supported Frameworks

• VORP
• RSG
• CUSTOM

Getting Started

local framework = exports.bln_lib:framework()

Framework API

framework:get()

Returns the current framework name.

local frameworkName = framework:get()
-- "VORP", "RSG", or "CUSTOM"

framework:is(name)

Checks if current framework matches the given name.

Parameters:

• name (string): Framework name

if framework:is('VORP') then
    -- VORP specific logic
end

framework:getUser(source)

Returns a framework user wrapper for a player source.

Parameters:

• source (number): Player server ID

local user = framework:getUser(source)

framework:canUserBuy(source, amount, moneyType, removeIfCan)

Convenience wrapper for checking/removing money from a user.

Parameters:

• source (number): Player server ID
• amount (number): Price to check
• moneyType (number, optional): 0 primary currency, 1 secondary currency, 2 (VORP only) rol
• removeIfCan (boolean, optional): Remove funds if affordable

local ok = framework:canUserBuy(source, 25, 0, true)

User API

user:getMoney(moneyType)

Returns user money by type.

user:addMoney(amount, moneyType)

Adds money by type.

user:removeMoney(amount, moneyType)

Removes money by type.

user:canBuy(price, moneyType, removeIfCan)

Checks affordability and optionally removes money.

Money type notes:

• 0: primary currency (cash/money)
• 1: secondary currency (gold by default)
• 2: VORP rol (where supported)

local cash = user:getMoney(0)
local gold = user:getMoney(1)
local canAfford = user:canBuy(100, 0, true)

user:getIdentifiers()

Returns framework identifiers.

local ids = user:getIdentifiers()
-- { identifier = "...", charid = ... }

user:getJob()

Returns current job name.

user:getJobGrade()

Returns grade summary.

local grade = user:getJobGrade()
-- { level = 1, name = "..." }

user:getJobFullData()

Returns normalized job object.

local job = user:getJobFullData()
-- {
--   name = "...",
--   label = "...",
--   grade = { level = 0, label = "..." }
-- }

user:getRPName()

Returns full RP name.

user:group()

Returns permission group. (e.g. admin)

user:HasPermission(permission)

Checks if user has a permission/group.

if user:HasPermission('admin') then
    -- Admin only here
end

user:getPlayerData(options)

Returns normalized player payload.

Parameters:

• options (table, optional): { permission = "admin" }

local data = user:getPlayerData({ permission = "admin" })
-- {
--   money = ...,
--   gold = ...,
--   job = ...,
--   identifiers = ...,
--   rpName = ...,
--   group = ...,
--   hasPermission = ...
-- }

Inventory API

framework:getInventoryURL()

Returns the inventory image base URL for the active framework.

local baseUrl = framework:getInventoryURL()

framework:canUseItem(source, item, amount, metadata, remove)

Checks item availability and optionally removes it.

Parameters:

• source (number): Player server ID
• item (string): Item name
• amount (number): Quantity to check
• metadata (table, optional): Metadata filter
• remove (boolean, optional): Remove item if available

Returns true if the player has enough, otherwise false.

if framework:canUseItem(source, "bread", 2, nil, true) then
    -- player had 2+ bread and it was removed
end

framework:giveItem(source, item, quantity, metadata)

Gives an item to player.

Parameters:

• source (number): Player server ID
• item (string): Item name
• quantity (number): Amount to give
• metadata (table, optional): Item metadata

Returns true on success, false if the player cannot carry more..

framework:giveItem(source, "water", 1)

framework:canCarryWeapon(source, weaponName)

Checks if a player can carry one more weapon.

Parameters:

• source (number): Player server ID
• weaponName (string): Weapon name (any casing; normalized per framework)

Returns true if the player has capacity, otherwise false.

if framework:canCarryWeapon(source, "weapon_revolver_cattleman") then
    -- player can carry this weapon
end

framework:giveWeapon(source, weaponName)

Checks weapon capacity, then gives one weapon to the player.

Parameters:

• source (number): Player server ID
• weaponName (string): Weapon name (any casing; normalized per framework)

Returns true on success, false if the player cannot carry it or give failed.

framework:giveWeapon(source, "weapon_revolver_cattleman")

framework:has(source, idOrName, type, amount, metadata)

Checks if a player has enough of an item or weapon.

Parameters:

• source (number): Player server ID
• idOrName (string): Item/weapon name, or id:<value> for a specific instance
• type (string, optional): "item" (default) or "weapon"
• amount (number, optional): Quantity to check (default 1)
• metadata (table, optional): Metadata filter for items (VORP, name mode only)

Returns true if the player has enough, otherwise false.

framework:has(source, "bread", "item", 2)
framework:has(source, "weapon_revolver_cattleman", "weapon")
framework:has(source, "id:12345", "item")
framework:has(source, "id:7", "weapon") -- RSG: slot number

idOrName modes:

• Plain name — match by item/weapon name (any matching stacks/instances).
• id:<value> — target one specific instance:
  • VORP: inventory item id or weapon id
  • RSG: inventory slot number

framework:removeIfExists(source, idOrName, type, amount, metadata)

Removes an item or weapon only if the player has enough. All-or-nothing (no partial remove).

Parameters:

• source (number): Player server ID
• idOrName (string): Item/weapon name, or id:<value> for a specific instance
• type (string, optional): "item" (default) or "weapon"
• amount (number, optional): Quantity to remove (default 1)
• metadata (table, optional): Metadata filter for items (VORP, name mode only)

Returns true if removed successfully, otherwise false.

framework:removeIfExists(source, "bread", "item", 2)
framework:removeIfExists(source, "weapon_revolver_cattleman", "weapon", 1)

-- remove a specific entry from getUserInventoryItems
local entry = framework:getUserInventoryItems(source)[1]
framework:removeIfExists(source, "id:" .. entry.id, entry.type, 1)

Notes:

• On RSG, weapons use the same item path in name mode; type mainly affects name normalization.
• Use id:<value> when you need to remove a specific weapon/item, not just any match by name.

framework:registerUseItem(item, closeAfterUse, callback, resourceName)

Registers a usable item callback.

Parameters:

• item (string): Item name
• closeAfterUse (boolean): Close inventory after use (VORP/RSG)
• callback (function): (source, itemData) -> ...
• resourceName (string, optional) for debuging.

framework:registerUseItem("water", true, function(source, itemData)
    print(("Player %s used %s"):format(source, itemData.name or "water"))
end)

framework:createOrUpdateInventory(id, name, options)

Creates or updates a custom inventory/stash.

Common options:

• maxSlots (number)
• maxWeight (number)

framework:createOrUpdateInventory("chest_1", "House Chest", {
    maxSlots = 50,
    maxWeight = 100,
})

framework:openInventory(source, id)

Opens an inventory/stash for a player.

framework:removeInventory(id)

Removes an inventory/stash.

framework:addItemsToInventory(source, id, items)

Adds multiple items to an inventory.

Parameters:

• items (table[]): Array of { name, amount, metadata }

framework:addItemsToInventory(source, "chest_1", {
    { id = 1, name = "water", amount = 2, metadata = {} },
    { id = 2, name = "bread", amount = 1, metadata = {} },
})

framework:getItemsFromInventory(id)

Returns inventory contents.

local items = framework:getItemsFromInventory("chest_1")
-- items are table of: { id, name , amount, metadata}

framework:getUserInventoryItems(source)

Returns player inventory items.

local playerItems = framework:getUserInventoryItems(source)
-- {
--   ...
--   {
--     id = 101,
--     name = "water",
--     label = "Water",
--     type = "item",      -- "item" | "weapon"
--     amount = 5,
--     metadata = {},
--     weight = 100,       -- can be nil
--     image = "water.png",-- can be nil
--     framework = "VORP", -- or "RSG"
--     raw = {...}         -- original framework item object
--   }
--   ...
-- }

Schema fields:

• id (number|string|nil)
• name (string)
• label (string|nil)
• type ("item" | "weapon")
• amount (number)
• metadata (table, defaults to {})
• weight (number|nil)
• image (string|nil)
• framework ("VORP" | "RSG")
• raw (table|nil)

Events

Client Events

-- Money changed
AddEventHandler('bln_lib:c:MoneyChanged', function(data)
    -- Data: { money,gold}
end)

-- Job changed
AddEventHandler('bln_lib:c:JobChanged', function(data)
    -- Data: 
    -- {
    --     name,
    --     label,
    --     grade = {level, label}
    -- }
end)

-- Player loaded (client) — use this in dependent resources
RegisterNetEvent('bln_lib:c:PlayerLoaded', function()
    -- Called when player loads in [any framework]
end)

-- Client response for the `bln_lib:s:GetPlayerData` server event. (server to client)
AddEventHandler('bln_lib:c:GetPlayerDataResponse', function(data)
    -- Data:
    -- {
    --     money = ..,
    --     gold = ..,
    --     job = ..,
    --     identifiers = ..,
    --     rpName = ..,
    --     group = ..,
    --     hasPermission = ..,
    -- }
end)

Server Events

-- Player loaded
AddEventHandler('bln_lib:s:PlayerLoaded', function()
    -- Called when player loads in [any framework]
end)

-- Gets player data
TriggerServerEvent('bln_lib:s:GetPlayerData', options) -- options {permission}

-- Server response for the `bln_lib:s:GetPlayerData` server event. (server to server)
AddEventHandler('bln_lib:s:GetPlayerDataResponse', function(data)
    -- Data:
    -- {
    --     money = ..,
    --     gold = ..,
    --     job = ..,
    --     identifiers = ..,
    --     rpName = ..,
    --     group = ..,
    --     hasPermission = ..,
    -- }
end)

State Bags

iLoggedIn

Checks for player's state if logged in or not

-- Client side
LocalPlayer.state.iLoggedIn

-- Server side
Player(src).state.iLoggedIn

Custom Framework Integration

The framework module already ships with a custom adapter template, So users/devs only need to fill that file with their framework own logic.

1) Enable custom mode in config

In bln_lib/core/config.lua:

Config.framework = "CUSTOM"

2) Fill the custom adapter methods

The custom framework adapter can be found at /bln_lib/modules/framework/api/custom/framework.s.lua

You should implement the User and Custom classes well, just follow the references and docs in the file.

3) Event wiring is critical

Your framework integration must fire BLN events at the correct lifecycle points.
If these are not fired (or fired too early/late), dependent systems may not update correctly.

Required BLN events:

• Server event: bln_lib:s:PlayerLoaded
• Client events: bln_lib:c:PlayerLoaded, bln_lib:c:MoneyChanged, bln_lib:c:JobChanged

Client-side events

-- Fire when your framework says the player/character finished loading
TriggerEvent("bln_lib:c:PlayerLoaded")

-- Fire after your framework updates money
TriggerEvent("bln_lib:c:MoneyChanged", {
    money = money or 0,
    gold = gold or 0
})

-- Fire after your framework updates job
TriggerEvent("bln_lib:c:JobChanged", {
    name = job.name or "unemployed",
    label = job.label or "Unemployed",
    grade = {
        level = (job.grade and job.grade.level) or 0,
        label = (job.grade and job.grade.label) or nil
    }
})

Server-side events

-- Fired by your framework when player is fully loaded
TriggerEvent("bln_lib:s:PlayerLoaded", source)