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.

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

Gives an item to player.

framework:registerUseItem(item, closeAfterUse, callback)

Registers a usable item callback.

framework:registerUseItem("water", true, function(source, itemData)
    print(("Player %s used water"):format(source))
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
AddEventHandler('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)