NightZoom LogoNightZoom
BJJ Racing Core/BJJ Racing Core v7/Player

Player Server

Server-side player functionality and exports for BJJ Racing Core v7

This page covers server-side player functionality for BJJ Racing Core v7. These functions handle player data management, money operations, permissions, and database interactions.

Core Access

Access the core system and player functions:

local Core = exports.bjj_racingcore:getCore()

Player Management

Core.getPlayer(source)

Retrieve a player object by source ID.

local player = Core.getPlayer(source)

Parameters:

  • source: number - Player's server ID

Returns: table|nil - Player object with methods, or nil if not found

Example:

local player = Core.getPlayer(source)
if player then
    print('Player name:', player.data.name)
    print('Player money:', player.data.money)
end

Core.getPlayerData(source)

Get a copy of player data.

local playerData = Core.getPlayerData(source)

Parameters:

  • source: number - Player's server ID

Returns: table|nil - Copy of player data including source field

Core.getPlayers()

Get all active player objects.

local players = Core.getPlayers()

Returns: table - Array of all loaded player objects

Player Object Methods

Once you have a player object, you can use these methods:

Data Management

player.setData(key, value, autoSave)

Set a specific data field.

local success = player.setData('money', 5000, true)

Parameters:

  • key: string - Data field name
  • value: any - New value
  • autoSave: boolean - Whether to save to database immediately

Returns: boolean - Success status

player.getData(key)

Get a specific data field value.

local money = player.getData('money')
local name = player.getData('name')

Parameters:

  • key: string - Data field name

Returns: any - Field value

Money Operations

player.addMoney(amount, autoSave)

Add money to player's balance.

local success = player.addMoney(1000, true)

Parameters:

  • amount: number - Amount to add
  • autoSave: boolean - Save to database immediately

Returns: boolean - Success status

player.removeMoney(amount, autoSave)

Remove money from player's balance.

local success = player.removeMoney(500, true)

Parameters:

  • amount: number - Amount to remove
  • autoSave: boolean - Save to database immediately

Returns: boolean - Success status (false if insufficient funds)

Crypto Operations

In the next version, crypto support is changing. Instead of a single integer value, players will have multiple cryptocurrency balances, each stored as a float. You can access and modify specific coins using new methods like player.getCrypto(coin), player.addCrypto(coin, amount, autoSave), and player.removeCrypto(coin, amount, autoSave).

player.addCrypto(amount, autoSave)

Add cryptocurrency to player's balance.

local success = player.addCrypto(10, true)

player.removeCrypto(amount, autoSave)

Remove cryptocurrency from player's balance.

local success = player.removeCrypto(5, true)

Metadata Management

player.setMetadata(key, value, autoSave)

Set metadata field.

local success = player.setMetadata('races_won', 15, true)

Parameters:

  • key: string - Metadata key
  • value: any - Value to set
  • autoSave: boolean - Save immediately

player.getMetadata(key, default)

Get metadata field with optional default.

local racesWon = player.getMetadata('races_won', 0)
local lastRace = player.getMetadata('last_race', 'None')

Parameters:

  • key: string - Metadata key
  • default: any - Default value if key doesn't exist

Returns: any - Metadata value or default

player.addMetadata(key, amount, autoSave)

Add numeric value to metadata field.

local success = player.addMetadata('races_won', 1, true)

Group Management

player.hasGroup(group)

Check if player has a specific group.

local isAdmin = player.hasGroup('admin')
local isVip = player.hasGroup('vip')

Parameters:

  • group: string - Group name

Returns: boolean - Has group

player.addGroup(group, autoSave)

Add group to player.

local success = player.addGroup('vip', true)

player.removeGroup(group, autoSave)

Remove group from player.

local success = player.removeGroup('temporary_access', true)

player.getGroups()

Get all player groups.

local groups = player.getGroups()
-- Returns: { admin = true, vip = true }

Database Operations

player.save()

Save player data to database.

player.save()

Returns: boolean - Success status

Player Events

Server Events

EventParametersDescription
bjj:server:playerLoadedplayerData: tablePlayer has loaded and data is ready
bjj:server:playerUnloadedsource: numberPlayer is being unloaded

Event Handlers

-- Player loaded event
AddEventHandler('bjj:server:playerLoaded', function(playerData)
    local source = playerData.source
    print('Player loaded:', playerData.name)
    
    -- Your integration logic here
end)

-- Player dropping
AddEventHandler('playerDropped', function(reason)
    local source = source
    print('Player dropped:', source, reason)
end)

Callbacks

bjj_racingcore:server:updatePlayerData

Update player data from client.

lib.callback.register('myresource:updatePlayerStats', function(source, data)
    local player = Core.getPlayer(source)
    if not player then return false end
    
    -- Update metadata
    for key, value in pairs(data) do
        player.setMetadata(key, value, false)
    end
    
    player.save()
    return true
end)

Integration Example

-- Example: Race completion system
AddEventHandler('myrace:playerFinished', function(source, position, time)
    local player = Core.getPlayer(source)
    if not player then return end
    
    -- Award money based on position
    local prize = position == 1 and 5000 or position <= 3 and 2000 or 500
    player.addMoney(prize, false)
    
    -- Update racing statistics
    player.addMetadata('total_races', 1, false)
    if position == 1 then
        player.addMetadata('races_won', 1, false)
    end
    player.setMetadata('best_time_track_' .. trackId, time, false)
    
    -- Save all changes
    player.save()
    
    -- Notify player
    TriggerClientEvent('bjj_racingcore:client:updatePlayerData', source, {
        money = player.data.money,
        metadata = player.data.metadata
    })
end)

Always use autoSave or call save() manually to persist changes to the database. The system automatically saves all players every 60 seconds.

Player objects are automatically cleaned up when players disconnect. Always check if a player object exists before using it.

Player States

Other player entity states for BJJ Racing Core v7

Vehicle Client

Client-side vehicle functionality and exports for BJJ Racing Core v7