JRS API - JRS Core

Warning

This page is for developers making scripts for JRS Core.

Getting the API#

getCoreApi returns one table with every function of the side your code runs on. Call it once at the top of the file.

Note

Shared (server and client have different functions)

getCoreApi#

returntable

The API table. Server side and client side tables are different.

lua

local JRS = exports.jrs_core:getCoreApi()

Characters#

Note

Server Side

GetCharacter#

Returns the loaded character of a player, or nil if the player has not selected a character yet.

sourcenumberrequired

The player source.

returntable | nil

The character table: identifier, charIdentifier, firstname, lastname, job, jobGrade, money, gold, dirtymoney, rol, xp.

lua

local character = JRS.GetCharacter(source)
if character then print(character.firstname, character.money) end

GetCharacterData#

Same as GetCharacter but returns a clean copy that also contains group.

lua

local data = JRS.GetCharacterData(source)

GetCharacterName#

returnstring | nil

firstname lastname, or the Steam name when the character has no name.

lua

local name = JRS.GetCharacterName(source)

IsCharacterReady#

True when the player finished selecting a character. Money, items and XP functions refuse to run before this is true.

lua

if not JRS.IsCharacterReady(source) then return end

GetCharacterById#

Reads any character (online or offline) by its character id.

lua

local character = exports.jrs_core:GetCharacterById(charId)

FindCharactersByName#

lua

local rows = exports.jrs_core:FindCharactersByName('John', 'Marston')

SaveCharacter#

Forces a save of the player character to the database.

lua

exports.jrs_core:SaveCharacter(source)

Money#

Note

Server Side

Currency types: 0 = cash, 1 = gold, 3 = dirty money.

AddMoney / RemoveMoney#

sourcenumberrequired

The player source.

amountnumberrequired

Amount, must be greater than 0.

lua

JRS.AddMoney(source, 25)
JRS.RemoveMoney(source, 10)

AddGold / RemoveGold#

lua

JRS.AddGold(source, 1)
JRS.RemoveGold(source, 1)

AddDirtyMoney / RemoveDirtyMoney / GetDirtyMoney#

lua

JRS.AddDirtyMoney(source, 100)
JRS.RemoveDirtyMoney(source, 25)
local dirty = JRS.GetDirtyMoney(source)

addMoney / removeMoney#

The generic form with a currency type.

sourcenumberrequired

The player source.

currencynumberrequired

0 cash, 1 gold, 3 dirty.

quantitynumberrequired

Amount.

lua

JRS.addMoney(source, 0, 100)
JRS.removeMoney(source, 0, 50)

GetBalance#

lua

local balance = JRS.GetBalance(source)

AddReward#

Pays a gameplay reward. The amount is scaled by Config.Economy (RewardMultiplier, GoldMultiplier, MinReward) and by the player level perks. Use this for jobs and missions instead of AddMoney.

sourcenumberrequired

The player source.

currencynumberrequired

0 cash or 1 gold.

amountnumberrequired

Base amount before scaling.

reasonstring

Reason, used for logs and job pay perks.

lua

JRS.AddReward(source, 0, 2.5, 'hunting_sale')

ScaleReward#

Returns the scaled amount without paying anything.

lua

local pay = JRS.ScaleReward(10, 0)

Jobs and groups#

Note

Server Side

setJob#

sourcenumberrequired

The player source.

jobstringrequired

The job name.

gradenumberrequired

The job grade.

lua

JRS.setJob(source, 'police', 2)

Jobs.Get / Add / Remove / Switch#

Multi-job functions. The maximum number of jobs per player is MaxJobs in jrs_core/config/config.lua.

lua

local jobs = exports.jrs_core:GetJobs(source)
exports.jrs_core:AddJob(source, 'doctor', 0, 'Doctor')
exports.jrs_core:RemoveJob(source, 'doctor')
exports.jrs_core:SwitchJob(source, 'police')

SetDuty / ToggleDuty / GetDutyPlayers#

lua

exports.jrs_core:SetDuty(source, true)
exports.jrs_core:ToggleDuty(source)
local officers = exports.jrs_core:GetDutyPlayers('police')

GetGroup / SetGroup / IsAdmin#

lua

local group = JRS.GetGroup(source)
JRS.SetGroup(source, 'admin')
if exports.jrs_core:IsAdmin(source) then end

XP and levels#

Note

Server Side

Character level goes to 100. XP per level is in config/levels.lua.

AddXP / RemoveXP / SetXP / GetXP#

sourcenumberrequired

The player source.

amountnumberrequired

XP amount.

reasonstring

Reason for logs.

lua

JRS.AddXP(source, 10, 'mission_reward')
local xp = JRS.GetXP(source)

GetLevel / SetLevel / AddLevel / RemoveLevel#

lua

local level = JRS.GetLevel(source)
JRS.SetLevel(source, 25, 'admin')

GetLevelData / GetTotalXpForLevel#

lua

local info = JRS.GetLevelData(totalXp)
local needed = JRS.GetTotalXpForLevel(30)

AddJobXP / GetJobLevel / GetJobXP / GetAllJobLevels#

Every job has its own XP and level.

lua

JRS.AddJobXP(source, 'mining', 15, 'ore')
local level = JRS.GetJobLevel(source, 'mining')
local all = JRS.GetAllJobLevels(source)

Level perks#

Perks give discounts and bonuses by level. Apply them in your payout code:

lua

price = exports.jrs_core:ApplyShopDiscount(source, price)
sell  = exports.jrs_core:ApplySellBonus(source, sell)
tax   = exports.jrs_core:ApplyTaxReduction(source, tax)
local capacity = exports.jrs_core:GetCarryCapacity(source)

Items (through jrs_inventory)#

Note

Server Side

These helpers call jrs_inventory for you and fail safely when it is not started.

AddItem / RemoveItem / GetItemCount / CanCarryItem#

lua

if JRS.CanCarryItem(source, 'bread', 2) then
    JRS.AddItem(source, 'bread', 2, {})
end
local count = JRS.GetItemCount(source, 'bread')
JRS.RemoveItem(source, 'bread', 1)

Inventory.Transaction#

Runs several item operations atomically: all of them succeed or none.

lua

local ok, reason = exports.jrs_inventory:InventoryTransaction(source, {
    { type = 'remove', item = 'wood', amount = 5 },
    { type = 'add', item = 'plank', amount = 2, metadata = {} },
}, { owner = 'sawmill' })
if not ok then print('transaction failed', reason) end

Notifications#

The first argument is the player source.

lua

JRS.NotifyRightTip(source, 'Reward received', 3000)
JRS.NotifyTip(source, 'Tip text', 3000)
JRS.NotifyLeft(source, 'Title', 'Subtitle', 'menu_textures', 'menu_icon_alert', 4000, 'COLOR_WHITE')
JRS.NotifyTop(source, 'Text', 'Location', 4000)
JRS.NotifyObjective(source, 'Objective text', 4000)
JRS.NotifySimpleTop(source, 'Title', 'Subtitle', 4000)
JRS.NotifyCenter(source, 'Text', 4000)
JRS.NotifyBottomRight(source, 'Text', 4000)
JRS.NotifyFail(source, 'Title', 'Subtitle', 4000)
JRS.NotifyUpdate(source, 'Title', 'Message', 4000)
JRS.NotifyWarning(source, 'Title', 'Message', 'Transaction_Feed_Sounds', 'Transaction_Positive', 4000)

lua

JRS.NotifyRightTip('Ready', 3000)
JRS.NotifyTip('Tip text', 3000)
JRS.Notify('Saved', 'success', 3000, 'Title')
JRS.Info('Information', 3000)
JRS.Success('Done', 3000)
JRS.WarningNotify('Careful', 3000)
JRS.ErrorNotify('Failed', 3000)

The server list is also available as exports, e.g. exports.jrs_core:NotifyRightTip(source, text, ms).

Callbacks (RPC)#

Calls are rate limited (30 per second per player), payloads are limited to 64 KB and calls time out after 10 seconds.

RegisterServerCallback#

lua

JRS.RegisterServerCallback('myscript:getPrice', function(source, item)
    return 12.5
end)

TriggerClientCallback#

lua

local result = JRS.TriggerClientCallback(source, 'myscript:getCoords')

Rpc#

lua

JRS.Rpc('myscript:getPrice', function(price)
    print(price)
end, 'bread')

RegisterClientCallback#

lua

JRS.RegisterClientCallback('myscript:getCoords', function()
    return GetEntityCoords(PlayerPedId())
end)

Client helpers#

Note

Client Side

GetPlayerData / WaitForCharacterReady#

lua

JRS.WaitForCharacterReady()
local data = JRS.GetPlayerData()

TeleportToCoords / TeleportToWaypoint#

lua

JRS.TeleportToCoords(x, y, z, heading)
JRS.TeleportToWaypoint()

SetCustomDestination / RemoveCustomDestination#

Sets a 3D waypoint marker.

lua

JRS.SetCustomDestination(vector3(0.0, 0.0, 0.0), 'Destination')

LoadModel / LoadAnimDict / LoadTextureDict#

Safe loaders with a timeout.

lua

JRS.LoadModel(`a_c_horse_arabian_white`)
JRS.LoadAnimDict('amb_camp@world_camp_fire_sit@male_a@base')

GetClosestPlayer / GetNearbyPlayers#

lua

local player, distance = JRS.GetClosestPlayer()

Input / Confirm#

Opens the themed input or confirm dialog.

lua

local amount = JRS.InputAwait('Amount', 'How many?')
local ok = JRS.ConfirmAwait('Are you sure?')