cc_heistcontracts keeps every player’s VICE balance, XP, level, alias, and
training progress in a dedicated heist_profiles table, cached in memory
while the player is online and flushed periodically (and on drop) to MySQL.
These exports are the supported way for other resources — admin menus,
reward systems, custom commands — to read or change that state. All exports
are server-side.
Profiles are loaded lazily on first access. The first export call for a
given
src blocks on a one-shot DB read; subsequent calls hit the cache.Currency (VICE)
VICE is the soft currency earned from completing heists and spent in the marketplace. The balance is always a non-negative integer; deltas are floored.AddVice
Credit VICE to the player and append acredit entry to their ledger.
number
required
Player server id.
number
required
Positive integer. Non-integer values are floored; values
≤ 0 are rejected.string
Free-form label written to the ledger. Use a stable identifier (e.g.
'pacific:vault_bonus') so the ledger reads cleanly in the dashboard.ok (boolean), newBalance (number) on success. Returns
false alone if the profile cannot be resolved or the amount is invalid.
RemoveVice
Debit VICE from the player. Fails (without mutating) if the balance is too low.number
required
Player server id.
number
required
Positive integer to debit.
string
Ledger label.
ok (boolean), balance (number). On insufficient funds,
returns false, currentBalance.
GetVice
Read the current VICE balance.number
required
Player server id.
number, or nil if no profile could be resolved.
XP and level
Levels are derived from cumulative XP via the curve configured inshared/config.lua. AddXp rolls the player up as many levels as the new XP
total covers — gaining a huge chunk of XP at once can level the player up
multiple times in a single call.
AddXp
Grant XP to an online player. Level-ups are applied automatically.number
required
Player server id.
number
required
Positive integer. Floored; values
≤ 0 are rejected.ok (boolean), level (number), xp (number) on success.
GrantXpByAlias
Grant XP to a player identified by their dashboard alias. Works whether the player is online (mutates the cached profile and lets the periodic flush persist it) or offline (updates the DB row directly).string
required
Case-insensitive alias lookup.
number
required
Positive integer.
true, info table:
number | nil
Server id if the player is online,
nil if offline.string
Resolved citizenid for the alias.
number
Level prior to the grant.
number
Level after applying the grant.
number
XP total after the grant.
false, errCode where errCode is one of
'invalid_amount', 'not_found', 'db'.
GetXp
Current XP total (cumulative, not level-relative).number
required
Player server id.
number, or nil if no profile could be resolved.
GetLevel
Current level.number
required
Player server id.
number, or nil if no profile could be resolved.
GetLevelProgress
Convenience accessor that returns everything you need to draw a progress ring or “X / Y to next level” label in one call.number
required
Player server id.
nil if no profile could be resolved.
number
Current level.
number
Current cumulative XP.
number
Cumulative XP at the start of the current level.
number
XP accumulated within the current level (
xp - base, clamped).number
XP needed to fill the current level (
nextLevelReq - base).Identity
GetAlias
Read the player’s dashboard alias. Returnsnil if the player has not yet
chosen one (the dashboard prompts for an alias on first open).
number
required
Player server id.
string | nil.
Training
The training side of the dashboard is gated by two flags: an overall unlock, and a per-minigame unlock that controls which games appear in the training list. Both are persisted.IsTrainingUnlocked
number
required
Player server id.
boolean.
HasTrainingMinigame
number
required
Player server id.
string
required
Minigame identifier (matches the
cc_minigames export name, lowercased —
e.g. 'pattern', 'crack', 'lockpick').boolean.
UnlockTraining
Idempotent: unlocks the overall training panel for the player.number
required
Player server id.
boolean — true on success (including when already unlocked).
UnlockTrainingMinigame
Idempotent: unlocks a specific training minigame for the player.number
required
Player server id.
string
required
Minigame identifier (see HasTrainingMinigame).
boolean — true on success (including when already unlocked).
Contract integration exports
Separate from the per-profile API above,cc_heistcontracts also exposes
the integration surface used by heist resources themselves:
Use
FinishContract / FinishHeist for normal heist completion — they
already credit VICE and XP from the contract’s reward table. Reach for
AddVice / AddXp only when you need to grant extra rewards outside the
contract flow (e.g. one-off events, admin tools, side-objectives).