Player API

This page covers how other resources read and change a player through en-core. There are two ways in:

• The player object, fetched with exports['en-core']:GetPlayer(source). It carries the full PlayerData and a Functions table of methods.
• Per-source exports such as GetMoney(source, 'cash') or GetPlayerMetadata(source, 'hunger'). They return just one value and are much cheaper to call often.

Exports for groups, XP, survival and content have their own pages: Groups, XP and levels, Survival system and Content registry.

#The player object

Player = {
    PlayerData = PlayerData, -- see the Player data page
    Offline = false,         -- true for objects from GetOfflinePlayer
    Functions = { ... },
}

Every function that changes state calls UpdatePlayerData(), which sends the full PlayerData to that player's client. Unless the player is offline, it also fires a server event encore:server:<event> with (source, ...) and a client event encore:client:<event> with (...). The event names are listed with each function below and on the Events page.

#Player functions

#Jobs and duty

#Money

See Money and cash for the rules.

#Metadata

#XP

#Survival

For the stat events, the first value is the resulting stat, not the amount that was added.

#Inventory

These pass through to the library's inventory interface, which en-inventory implements. Without an inventory running they return nil, 0 or false.

#Saving and session

When the QB bridge is active, it also adds Functions.SetGang, which does nothing. See Compatibility bridges.

#Server exports

All server exports are called as exports['en-core']:Name(...).

#Players and sessions

Login checks that the character belongs to the connecting license, attaches the player's group, and fires encore:server:onPlayerLoaded(source, playerData) and encore:client:onPlayerLoaded(playerData). Error codes:

CreateCharacter accepts { charinfo = {...} } or a bare charinfo table. It inserts the row but does not put the character in the world; call Login next. Error codes: no_license, no_slots_available, citizenid_generation_failed, insert_failed.

Logout saves the character (unless skipSave is true), removes it from the registry, and fires encore:server:onPlayerUnload(source, playerData) and encore:client:onPlayerUnload.

Offline players. Changes to an object from GetOfflinePlayer are only written when you call player.Functions.Save().

en-multicharacter is the resource that calls Login, CreateCharacter and DeleteCharacter for you.

#Characters

#Lightweight lookups

These touch only the value you ask for, so they are the right choice for polling and hot paths.

SetPlayerMetadata sends only encore:client:onSetMetaData(key, value) to the client and fires encore:server:onSetMetaData(source, key, value). It does not push the whole PlayerData. The value is saved with the character as usual.

#Shared data and config

#Identifiers and logging

#Client exports

The client global ENC (with ENC.PlayerData and helpers) is only visible inside en-core's own client scripts. Other resources should use the exports above.

#Examples

Pay a player for a sale and promote them:

local player = exports['en-core']:GetPlayer(source)
if not player then return end

if player.Functions.AddMoney('cash', 250, 'Sold scrap') then
    player.Functions.SetJob('scavenger', 1)
end

Cheap checks from a loop:

for _, src in ipairs(GetPlayers()) do
    src = tonumber(src)
    if exports['en-core']:IsPlayerLoaded(src) then
        local hunger = exports['en-core']:GetPlayerMetadata(src, 'hunger')
        if hunger and hunger < 10 then
            encore.notify(src, { description = 'Your stomach is cramping.', type = 'warning' })
        end
    end
end

Charge by source without fetching the player object:

if not exports['en-core']:RemoveMoney(source, 'bank', 100, 'Repair fee') then
    encore.notify(source, { description = 'You cannot afford the repair.', type = 'error' })
end

Create a character and log in, as a character screen would:

local created, err = exports['en-core']:CreateCharacter(source, { charinfo = {
    firstname = 'Ada', lastname = 'Reyes', birthdate = '1994-03-02', gender = 1, nationality = 'American',
} })

if not created then
    print('create failed: ' .. err)
    return
end

local player, loginErr = exports['en-core']:Login(source, created.PlayerData.citizenid)

Edit an offline character:

local player = exports['en-core']:GetOfflinePlayer('ENCAB12CD34')
if player then
    player.Functions.SetMetadata('radiation', 0)
    player.Functions.Save()
end

Read data on the client:

local data = exports['en-core']:GetPlayerData()
if data then
    print(data.job.label, data.metadata.radiation)
end

#Related

• Player data
• Events
• Compatibility bridges