Player Module¶

The Player module manages player instances, character data, and account-related operations. It provides both class methods (Player instance methods) and module-level utility functions.

Player Class¶

Instance Properties¶

Property	Type	Description
`source`	number	Player server ID
`accountId`	number	Player account database ID
`charId`	number\|nil	Current character database ID
`citizenId`	string\|nil	Current character citizen ID
`firstname`	string\|nil	Character first name
`lastname`	string\|nil	Character last name
`birthdate`	string\|nil	Character birthdate
`nationality`	string\|nil	Character nationality
`gender`	string\|nil	Character gender model
`height`	number	Character height (default: 175)
`phone`	string\|nil	Character phone number
`email`	string\|nil	Character email address
`faction`	string	Current faction name (default: "unemployed")
`factionRank`	number	Faction rank (0-12)
`money`	number	Character cash money
`bank`	number	Character bank money
`appearance`	string\|nil	Character appearance JSON
`position`	string\|nil	Character last position JSON
`ownedCompany`	string\|nil	Owned company data JSON
`secondCompany`	string\|nil	Second company data JSON
`createdAt`	number	Character creation timestamp
`lastLogin`	number	Last login timestamp
`health`	number	Character health
`armor`	number	Character armor
`hunger`	number	Character hunger level (0-100)
`thirst`	number	Character thirst level (0-100)
`inventory`	table\|nil	Reference to InventoryCache[charId]
`metadata`	string\|nil	Character metadata JSON
`identifiers`	table	Player identifiers (discord, steam, license, ip)
`groups`	table	Player ACE groups

Player Instance Methods¶

Character Data Management¶

`player:loadCharacter(characterData)`¶

Loads character data into player instance from database.

Parameters: - characterData (table): Character data from database

Returns: none

Example:

local player = CVPlayer.GetPlayer(source)
player:loadCharacter(charData)

`player:unloadCharacter()`¶

Unloads current character and resets all character-related data.

Returns: none

Example:

player:unloadCharacter()

`player:saveCharacter()`¶

Saves current character data to database (money, position, health, etc).

Returns: boolean success

Example:

player:saveCharacter()

`player:getName()`¶

Gets player's full name.

Returns: string (format: "FirstName LastName" or "Unknown")

Example:

local name = player:getName()
print(name) -- "John Doe"

`player:getData()`¶

Gets all player data as a table.

Returns: table with all player properties

Example:

local data = player:getData()
print(data.money) -- Current cash

Money Management¶

`player:addMoney(amount, moneyType)`¶

Adds money to player.

Parameters: - amount (number): Amount to add - moneyType (string, optional): "cash", "money", or "bank" (default: "cash")

Returns: boolean success

Example:

player:addMoney(100, "cash")
player:addMoney(500, "bank")

`player:removeMoney(amount, moneyType)`¶

Removes money from player (checks if sufficient funds exist).

Parameters: - amount (number): Amount to remove - moneyType (string, optional): "cash", "money", or "bank" (default: "cash")

Returns: boolean success

Example:

if player:removeMoney(100, "cash") then
    print("Payment successful")
else
    print("Insufficient funds")
end

`player:getMoney(moneyType)`¶

Gets money amount.

Parameters: - moneyType (string, optional): "cash", "money", or "bank" (default: "cash")

Returns: number amount

Example:

local cash = player:getMoney("cash")
local bank = player:getMoney("bank")

`player:setMoney(amount, moneyType)`¶

Sets money amount.

Parameters: - amount (number): Amount to set (negative values clamped to 0) - moneyType (string, optional): "cash", "money", or "bank" (default: "cash")

Returns: boolean success

Example:

player:setMoney(1000, "cash")

`player:saveMoney()`¶

Persists money/bank immediately to database.

Returns: none

Example:

player:saveMoney()

Inventory Management¶

`player:addInventoryItem(itemName, quantity, metadata)`¶

Adds item to player inventory.

Parameters: - itemName (string): Item name - quantity (number): Item quantity - metadata (table, optional): Item metadata

Returns: boolean success

Example:

player:addInventoryItem("water", 1)
player:addInventoryItem("phone", 1, { serial = "ABC123" })

`player:removeInventoryItem(itemName, quantity)`¶

Removes item from player inventory.

Parameters: - itemName (string): Item name - quantity (number): Item quantity

Returns: boolean success

Example:

player:removeInventoryItem("water", 1)

`player:getInventoryItemCount(itemName)`¶

Gets item count in inventory.

Parameters: - itemName (string): Item name

Returns: number count

Example:

local waterCount = player:getInventoryItemCount("water")

`player:getInventoryWeight()`¶

Gets player's inventory weight.

Returns: number weight

Example:

local weight = player:getInventoryWeight()

`player:getInventory()`¶

Gets player's full inventory.

Returns: table inventory

Example:

local inventory = player:getInventory()
for itemName, itemData in pairs(inventory) do
    print(itemName, itemData.quantity)
end

Weapon Management¶

`player:addWeapon(weaponHash, ammo, customName, metadata)`¶

Adds weapon to player.

Parameters: - weaponHash (string): Weapon hash - ammo (number): Ammo count - customName (string, optional): Custom weapon name - metadata (table, optional): Weapon metadata

Returns: boolean success

Example:

player:addWeapon("WEAPON_PISTOL", 100, "My Pistol")

`player:removeWeapon(weaponHash)`¶

Removes weapon from player.

Parameters: - weaponHash (string): Weapon hash

Returns: boolean success

Example:

player:removeWeapon("WEAPON_PISTOL")

`player:getWeapons()`¶

Gets all weapons.

Returns: table weapons

Example:

local weapons = player:getWeapons()
for _, weapon in ipairs(weapons) do
    print(weapon.hash, weapon.ammo)
end

`player:equipWeapon(weaponHash)`¶

Equips weapon.

Parameters: - weaponHash (string): Weapon hash

Returns: boolean success

Example:

player:equipWeapon("WEAPON_PISTOL")

Character State Management¶

`player:setHealth(health)`¶

Updates player health.

Parameters: - health (number): Health value

Returns: none

Example:

player:setHealth(100)

`player:setArmor(armor)`¶

Updates player armor.

Parameters: - armor (number): Armor value

Returns: none

Example:

player:setArmor(50)

`player:setHunger(hunger)`¶

Updates hunger level (clamped 0-100).

Parameters: - hunger (number): Hunger value

Returns: none

Example:

player:setHunger(80)

`player:setThirst(thirst)`¶

Updates thirst level (clamped 0-100).

Parameters: - thirst (number): Thirst value

Returns: none

Example:

player:setThirst(70)

`player:setJob(jobName)`¶

Sets player job.

Parameters: - jobName (string): Job name

Returns: boolean success

Example:

player:setJob("police")

`player:updatePosition(coords, heading)`¶

Updates player position.

Parameters: - coords (table): Player coordinates {x, y, z} - heading (number, optional): Player heading

Returns: none

Example:

player:updatePosition({x = 123.5, y = 456.2, z = 1000.0}, 180.0)

`player:fetchAndUpdatePosition()`¶

Fetches current position from server and updates player data.

Returns: none

Example:

player:fetchAndUpdatePosition()

Group & Permission Management¶

`player:addGroup(groupName)`¶

Adds player to a group and persists to database.

Parameters: - groupName (string): Group name (without 'group.' prefix)

Returns: boolean success

Example:

player:addGroup("admin")

`player:removeGroup(groupName)`¶

Removes player from a group and persists to database.

Parameters: - groupName (string): Group name (without 'group.' prefix)

Returns: boolean success

Example:

player:removeGroup("admin")

`player:hasGroup(groupName)`¶

Checks if player is in a group.

Parameters: - groupName (string): Group name (without 'group.' prefix)

Returns: boolean hasGroup

Example:

if player:hasGroup("admin") then
    print("Player is admin")
end

`player:saveGroups()`¶

Saves groups to database.

Returns: none

Example:

player:saveGroups()

`player:loadGroups(accountData)`¶

Loads player groups from database and applies ACE permissions.

Parameters: - accountData (table): Player account data with groups

Returns: none

Example:

player:loadGroups(accountData)

Utility Methods¶

`player:hasCharacter()`¶

Checks if player has a character loaded.

Returns: boolean

Example:

if player:hasCharacter() then
    print("Character is loaded")
end

`player:kick(reason)`¶

Kicks player from server.

Parameters: - reason (string, optional): Kick reason

Returns: none

Example:

player:kick("You were banned")

`player:remove()`¶

Removes player from active players (called on disconnect).

Returns: none

Example:

player:remove()

Module Functions (cv.player namespace)¶

Player Retrieval¶

`cv.player.getPlayer(source)`¶

Gets player by source.

Parameters: - source (number): Player server ID

Returns: Player|nil

Example:

local player = cv.player.getPlayer(source)
if player and player:hasCharacter() then
    print(player:getName())
end

`cv.player.getPlayerByCharId(charId)`¶

Gets player by character ID.

Parameters: - charId (number): Character database ID

Returns: Player|nil

Example:

local player = cv.player.getPlayerByCharId(123)

`cv.player.getPlayerByIdentifier(identifierType, identifier)`¶

Gets player by identifier.

Parameters: - identifierType (string): Type ("discord", "steam", "license") - identifier (string): Identifier value

Returns: Player|nil

Example:

local player = cv.player.getPlayerByIdentifier("steam", "steam:110000123456789")

`cv.player.getAllPlayers()`¶

Gets all active players.

Returns: table

Example:

local players = cv.player.getAllPlayers()
for source, player in pairs(players) do
    print(source, player:getName())
end

`cv.player.getPlayerCount()`¶

Gets count of active players.

Returns: number

Example:

local count = cv.player.getPlayerCount()
print("Players online:", count)

Player Creation & Management¶

`cv.player.createPlayer(source, accountData)`¶

Creates new player instance (internal use).

Parameters: - source (number): Player server ID - accountData (table): Player account data

Returns: Player

Example:

local player = cv.player.createPlayer(source, accountData)

Money Utility Functions¶

`cv.player.getMoney(source, moneyType)`¶

Gets player money (utility function).

Parameters: - source (number): Player server ID - moneyType (string, optional): "cash" or "bank" (default: "cash")

Returns: number

Example:

local cash = cv.player.getMoney(source, "cash")

`cv.player.addMoney(source, amount, moneyType)`¶

Adds money to player (utility function).

Parameters: - source (number): Player server ID - amount (number): Amount to add - moneyType (string, optional): "cash" or "bank" (default: "cash")

Returns: boolean success

Example:

cv.player.addMoney(source, 100, "cash")

`cv.player.removeMoney(source, amount, moneyType)`¶

Removes money from player (utility function).

Parameters: - source (number): Player server ID - amount (number): Amount to remove - moneyType (string, optional): "cash" or "bank" (default: "cash")

Returns: boolean success

Example:

if cv.player.removeMoney(source, 50, "bank") then
    print("Withdrawal successful")
end

Events¶

`playerDropped`¶

Triggered when a player disconnects.

Example:

AddEventHandler('playerDropped', function(reason)
    local src = source
    local player = cv.player.getPlayer(src)
    if player then
        print(player:getName() .. " disconnected")
    end
end)

`cv_framework:server:Shutdown`¶

Triggered during server shutdown to save all player data.

Auto-Save¶

Players are automatically saved every 5 minutes with position updates, and when the server shuts down or the resource stops.

Usage Example¶

-- Get player
local player = cv.player.getPlayer(source)

if not player or not player:hasCharacter() then
    return print("No character loaded")
end

-- Money operations
print("Cash:", player:getMoney("cash"))
player:addMoney(100, "cash")
player:removeMoney(50, "bank")

-- Inventory operations
player:addInventoryItem("water", 1)
local count = player:getInventoryItemCount("water")
print("Water bottles:", count)

-- Character state
player:setHealth(100)
player:setHunger(80)
player:setThirst(70)

-- Save player data
player:saveCharacter()

Using cvPlayer in external resources¶

This page shows how to get and use the cvPlayer object with:

local cv = exports["cv_framework"]:loadModule()

Get cv object¶

local cv = exports["cv_framework"]:loadModule()

Get cvPlayer object¶

Get by source (most common)¶

local src = source
local player = cv.player.getPlayer(src)

if not player or not player.charId then
    return
end

Get by character id¶

local player = cv.player.getPlayerByCharId(charId)

Get by identifier¶

local player = cv.player.getPlayerByIdentifier("license", licenseIdentifier)
-- supported keys in identifiers table are usually: discord, steam, license, ip

Important check¶

Always validate character context before using character data:

if not player or not player.charId then
    return
end

cvPlayer attributes¶

These are available on player (server-side):

player.source (number) - server id
player.accountId (number) - account row id (players.id)
player.charId (number|nil) - active character id (characters.id)
player.citizenId (string|nil)
player.firstname (string|nil)
player.lastname (string|nil)
player.birthdate (string|nil)
player.nationality (string|nil)
player.gender (string|nil)
player.height (number)
player.phone (string|nil)
player.email (string|nil)
player.faction (string)
player.factionRank (number)
player.money (number) - cash
player.bank (number) - bank balance
player.appearance (string|nil)
player.position (string|nil JSON)
player.ownedCompany (string|nil)
player.secondCompany (string|nil)
player.createdAt (string|nil)
player.lastLogin (string|nil)
player.health (number)
player.armor (number)
player.hunger (number)
player.thirst (number)
player.inventory (table|nil)
player.metadata (string|nil)
player.identifiers (table)
player.groups (table)

cvPlayer methods¶

Identity / state¶

player:getName()
player:hasCharacter()
player:getData()
player:loadCharacter(characterData)
player:unloadCharacter()
player:saveCharacter()

Money (cash/bank)¶

player:getMoney(moneyType) where moneyType is "cash"/"money" or "bank"
player:addMoney(amount, moneyType)
player:removeMoney(amount, moneyType)
player:setMoney(amount, moneyType)
player:saveMoney()

Examples:

local cash = player:getMoney("cash")
local bank = player:getMoney("bank")

player:addMoney(500, "cash")
player:addMoney(1000, "bank")

local ok = player:removeMoney(250, "bank")
if not ok then
    -- not enough bank balance
end

Direct fields are also readable:

print("Cash:", player.money)
print("Bank:", player.bank)

Character vitals¶

player:setHealth(health)
player:setArmor(armor)
player:setHunger(hunger)
player:setThirst(thirst)

Position¶

player:updatePosition(coords, heading)
player:fetchAndUpdatePosition()

Inventory¶

player:addInventoryItem(itemName, quantity, metadata)
player:removeInventoryItem(itemName, quantity)
player:getInventoryItemCount(itemName)
player:getInventoryWeight()
player:getInventory()

Weapons¶

player:addWeapon(weaponHash, ammo, customName, metadata)
player:removeWeapon(weaponHash)
player:getWeapons()
player:equipWeapon(weaponHash)

Groups / permissions¶

player:loadGroups(accountData)
player:addGroup(groupName)
player:removeGroup(groupName)
player:hasGroup(groupName)
player:saveGroups()

Other¶

player:setJob(jobName)
player:kick(reason)
player:remove()

cv.player namespace helpers¶

These are called from cv.player directly:

cv.player.getPlayer(source)
cv.player.getPlayerByCharId(charId)
cv.player.getPlayerByIdentifier(identifierType, identifier)
cv.player.getAllPlayers()
cv.player.getPlayerCount()
cv.player.getMoney(source, moneyType)
cv.player.getMoneyByType(playerOrSource, moneyType)
cv.player.addMoney(source, amount, moneyType)
cv.player.addMoneyByType(playerOrSource, amount, moneyType)
cv.player.removeMoney(source, amount, moneyType)
cv.player.removeMoneyByType(playerOrSource, amount, moneyType)

Example helpers:

local bank = cv.player.getMoney(source, "bank")
local ok = cv.player.removeMoney(source, 500, "cash")

Minimal full example¶

local cv = exports["cv_framework"]:loadModule()

RegisterNetEvent("example:payFee", function(amount)
    local src = source
    local player = cv.player.getPlayer(src)
    if not player or not player.charId then return end

    amount = math.floor(tonumber(amount) or 0)
    if amount <= 0 then return end

    local success = player:removeMoney(amount, "bank")
    if success then
        cv.notify(src, "Bank", ("$%d wurden abgebucht"):format(amount), "success")
    else
        cv.notify(src, "Bank", "Nicht genug Guthaben", "error")
    end
end)

Player Module¶

Player Class¶

Instance Properties¶

Player Instance Methods¶

Character Data Management¶

player:loadCharacter(characterData)¶

player:unloadCharacter()¶

player:saveCharacter()¶

player:getName()¶

player:getData()¶

Money Management¶

player:addMoney(amount, moneyType)¶

player:removeMoney(amount, moneyType)¶

player:getMoney(moneyType)¶

player:setMoney(amount, moneyType)¶

player:saveMoney()¶

Inventory Management¶

player:addInventoryItem(itemName, quantity, metadata)¶

player:removeInventoryItem(itemName, quantity)¶

player:getInventoryItemCount(itemName)¶

player:getInventoryWeight()¶

player:getInventory()¶

Weapon Management¶

player:addWeapon(weaponHash, ammo, customName, metadata)¶

player:removeWeapon(weaponHash)¶

player:getWeapons()¶

player:equipWeapon(weaponHash)¶

Character State Management¶

player:setHealth(health)¶

player:setArmor(armor)¶

player:setHunger(hunger)¶

player:setThirst(thirst)¶

player:setJob(jobName)¶

player:updatePosition(coords, heading)¶

player:fetchAndUpdatePosition()¶

Group & Permission Management¶

player:addGroup(groupName)¶

player:removeGroup(groupName)¶

player:hasGroup(groupName)¶

player:saveGroups()¶

player:loadGroups(accountData)¶

Utility Methods¶

player:hasCharacter()¶

player:kick(reason)¶

player:remove()¶

Module Functions (cv.player namespace)¶

Player Retrieval¶

cv.player.getPlayer(source)¶

cv.player.getPlayerByCharId(charId)¶

cv.player.getPlayerByIdentifier(identifierType, identifier)¶

cv.player.getAllPlayers()¶

cv.player.getPlayerCount()¶

Player Creation & Management¶

cv.player.createPlayer(source, accountData)¶

Money Utility Functions¶

cv.player.getMoney(source, moneyType)¶

cv.player.addMoney(source, amount, moneyType)¶

cv.player.removeMoney(source, amount, moneyType)¶

Events¶

playerDropped¶

cv_framework:server:Shutdown¶

Auto-Save¶

Usage Example¶

Using cvPlayer in external resources¶

Get cv object¶

Get cvPlayer object¶

Get by source (most common)¶

Get by character id¶

Get by identifier¶

Important check¶

cvPlayer attributes¶

cvPlayer methods¶

Identity / state¶

Money (cash/bank)¶

Character vitals¶

Position¶

Inventory¶

Weapons¶

Groups / permissions¶

Other¶

`player:loadCharacter(characterData)`¶

`player:unloadCharacter()`¶

`player:saveCharacter()`¶

`player:getName()`¶

`player:getData()`¶

`player:addMoney(amount, moneyType)`¶

`player:removeMoney(amount, moneyType)`¶

`player:getMoney(moneyType)`¶

`player:setMoney(amount, moneyType)`¶

`player:saveMoney()`¶

`player:addInventoryItem(itemName, quantity, metadata)`¶

`player:removeInventoryItem(itemName, quantity)`¶

`player:getInventoryItemCount(itemName)`¶

`player:getInventoryWeight()`¶

`player:getInventory()`¶

`player:addWeapon(weaponHash, ammo, customName, metadata)`¶

`player:removeWeapon(weaponHash)`¶

`player:getWeapons()`¶

`player:equipWeapon(weaponHash)`¶

`player:setHealth(health)`¶

`player:setArmor(armor)`¶

`player:setHunger(hunger)`¶

`player:setThirst(thirst)`¶

`player:setJob(jobName)`¶

`player:updatePosition(coords, heading)`¶

`player:fetchAndUpdatePosition()`¶

`player:addGroup(groupName)`¶

`player:removeGroup(groupName)`¶

`player:hasGroup(groupName)`¶

`player:saveGroups()`¶

`player:loadGroups(accountData)`¶

`player:hasCharacter()`¶

`player:kick(reason)`¶

`player:remove()`¶

`cv.player.getPlayer(source)`¶

`cv.player.getPlayerByCharId(charId)`¶

`cv.player.getPlayerByIdentifier(identifierType, identifier)`¶

`cv.player.getAllPlayers()`¶

`cv.player.getPlayerCount()`¶

`cv.player.createPlayer(source, accountData)`¶

`cv.player.getMoney(source, moneyType)`¶

`cv.player.addMoney(source, amount, moneyType)`¶

`cv.player.removeMoney(source, amount, moneyType)`¶

`playerDropped`¶

`cv_framework:server:Shutdown`¶