Skip to main content
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 a credit 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.
Returns: 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.
Returns: ok (boolean), balance (number). On insufficient funds, returns false, currentBalance.

GetVice

Read the current VICE balance.
number
required
Player server id.
Returns: number, or nil if no profile could be resolved.

XP and level

Levels are derived from cumulative XP via the curve configured in shared/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.
Returns: 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.
Returns on success: 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.
Returns on failure: 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.
Returns: number, or nil if no profile could be resolved.

GetLevel

Current level.
number
required
Player server id.
Returns: 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.
Returns: a table, or 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. Returns nil if the player has not yet chosen one (the dashboard prompts for an alias on first open).
number
required
Player server id.
Returns: 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.
Returns: boolean.

HasTrainingMinigame

number
required
Player server id.
string
required
Minigame identifier (matches the cc_minigames export name, lowercased — e.g. 'pattern', 'crack', 'lockpick').
Returns: boolean.

UnlockTraining

Idempotent: unlocks the overall training panel for the player.
number
required
Player server id.
Returns: 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).
Returns: 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).