rsg-playerinfo — Developer Docs#
Contents#
- Overview
- Files
- Flow
- Data returned by the callback
- Reputation tab
- NUI
- Configuration
- Events, callbacks and commands
- Integrations
- Security
- Locales
- Troubleshooting
Overview#
/info opens a dashboard covering Config.ScreenPercent% (default 80) of the screen. It shows money tiles, identity, employment, a medical check of the player's bones and standing (outlaw status). A second tab, Reputation, shows the player's XP per skill. Every field is toggled in Config.PlayerInfoSetup (shared/config.lua). No database tables or items are added; bone health is stored in player metadata (metadata.bones).
Files#
| File | Purpose |
|---|---|
shared/config.lua | Size, refresh interval, field toggles, push-to-talk |
shared/bones.lua | Tracked bones, UI groups and the bone id / index lookup tables (generated from the rdr3_discoveries boneNames data) |
server/server.lua | /info and /healbones commands, the getPlayerData callback and the bone save event |
client/client.lua | NUI focus (push-to-talk safe), payload builder, live refresh |
client/bones.lua | Bone damage tracker, recovery, medic hooks and exports |
html/index.html, style.css, script.js | Dashboard UI |
locales/*.json | Translations (en, de, el, es, fr, it, ja, nl, pl, pt-br, ro, ru) |
Flow#
/info→ server sendsrsg-playerstats:client:openPlayerStatsto the caller.- Client calls the
rsg-playerstats:server:getPlayerDatacallback. - Server reads
Player.PlayerData(nil-safe) and returns the table below. - Client adds the live bone conditions from the bone tracker, then sends
SendNUIMessage({ action = 'open', ... })with the labels, theshow_*flags, the size percentage and the data. - While open, the client repeats the callback every
Config.RefreshIntervalms and sendsaction = 'update'. The NUI only re-renders when the data changed. - Closing (button, ESC, Backspace) posts the
closeNUI callback, which releases focus.
Data returned by the callback#
{
firstname, lastname, citizenid,
birthdate, gender = 'male' | 'female' | raw, nationality,
bloodtype, fingerprint, walletid, callsign, -- from metadata
job = { label, gradeName, grade, onduty },
gang = 'Label' | nil, -- nil when gang is 'none'
otherJobs = { { label, grade }, ... }, -- rsg-core GetPlayerJobs, active job removed
money = { cash, bloodmoney, gold, bank }, -- bank = rsg-banking GetTotalBalance, else core bank
branches = { rhobank?, valbank?, blkbank?, armbank? }, -- only keys that exist in PlayerData.money
outlaw = { value, text, band = 'good' | 'warn' | 'bad' },
rep = { { name, label?, icon?, value, level, into, need, pct, max }, ... }, -- from metadata.rep, highest XP first (see Reputation tab)
}
Bone conditions are not part of the callback: the client adds its live values (BoneTracker.get()).
The callback returns nil when the player is not loaded or asks again within 750 ms.
Reputation tab#
The tab buttons under the header switch between Overview and Reputation (only shown when Config.PlayerInfoSetup.show_reputation is true and not in a doctor examination). The tab is purely client-side: both views are built from the same callback data, so switching costs no server call and live refresh keeps the selected tab.
Source: PlayerData.metadata.rep, a table of name -> XP that other scripts change with Player.Functions.AddRep(name, amount) / RemoveRep / GetRep. This script only reads it.
Level maths (server, getReputation in server/server.lua, config in Config.Reputation): total XP needed to reach level L is floor(XPPerLevel * L ^ LevelGrowth); the level is the highest L <= MaxLevel whose threshold the XP has reached (level 0 below XPPerLevel). Each entry carries:
| Field | Meaning |
|---|---|
name | rep key as stored in metadata |
label, icon | from Config.Reputation.Categories[name], or nil (the UI prettifies name and uses a star icon) |
value | total XP (floored) |
level | current level (0 - MaxLevel) |
into, need | XP gained inside the current level and XP the level spans (need is 0 at max level) |
pct | 0-100 progress to the next level (100 at max level) |
max | true at MaxLevel |
Entries are sorted by XP (highest first). The header tiles show total XP, number of skills and the top skill. With no rep data the tab shows "No reputation earned yet". Negative XP counts as level 0 with an empty bar.
Naming skills: add entries to Config.Reputation.Categories, e.g. hunting = { label = 'Hunting', icon = 'fa-solid fa-crosshairs' }. Labels in the config are plain text (not translated); skills without one use the prettified key. Tab and card text lives in the locale keys cl_tab_overview, cl_tab_reputation, cl_rep_total_xp, cl_rep_skills, cl_rep_top, cl_rep_level, cl_rep_max, cl_rep_xp, cl_rep_none (all 11 languages).
Medical check (bones)#
Bones: skull, neck, ribcage, lowerspine, pelvis, collarbone_l/_r, upperarm_l/_r, forearm_l/_r, hand_l/_r, thigh_l/_r, shin_l/_r, foot_l/_r. Each has a condition from 100 (healthy) to 0 (broken). _l is the player's left.
Illustration: the skeleton is an original front-view SVG drawn in html/script.js (SKELETON, plus a faint body silhouette). Every bone key is its own <g data-bone="...">; the player's left is on the viewer's right and the _l limbs are mirrored copies of the _r ones. Status classes (st-healthy ... st-broken) in html/style.css colour the bone and show its crack mark.
Status (from Config.Bones.Thresholds): >= 90 healthy, >= 60 bruised, >= 30 cracked, > 0 fractured, 0 broken. The verdict shown is the worst status found; skeletal integrity is the average of all bones.
Detection (client/bones.lua):
- Every
PollIntervalms the client comparesGetEntityHealthwith the previous value. - A loss of at least
MinDamagePercentof max health counts as a hit (smaller losses such as bleeding are ignored). - If the ped was falling in the last 1.5 s (
IsPedFalling), the damage is spread over feet, shins, thighs and pelvis usingConfig.Bones.FallWeights. - Otherwise
GetPedLastDamageBoneis read. The bone id is looked up inBones.ByBoneId(ids are identical on mp_male, mp_female and player_zero). A value below 1000 is treated as a bone index and looked up per skeleton inBones.ByIndex. Unknown bones are ignored. - The bone loses
damage% x DamageScalecondition.
GetPedLastDamageBone is not perfect (it can return the previous hit's bone for non-weapon damage). Set Config.Bones.Debug = true to print the raw bone id of every hit in F8 and check it against shared/bones.lua.
Recovery: bruised bones (condition at or above the bruised threshold) regain RecoveryPerMinute per minute. Cracked, fractured and broken bones only heal through treatment.
Treatment hooks (client events from rsg-medic, when RestoreOnMedic = true): rsg-medic:client:revive and rsg-medic:client:heal with -1 (full heal) restore every bone. A normal bandage heal does not. /healbones [id] (admin) triggers rsg-playerinfo:client:healBones.
Persistence: the client sends its bone table to rsg-playerinfo:server:saveBones (at most every 2 s, only when something changed). The server checks the shape, clamps every value to 0-100, and stores it with Player.Functions.SetMetaData('bones', ...). It is loaded again on RSGCore:Client:OnPlayerLoaded.
Gameplay effects (client/effects.lua)#
Reads BoneTracker.get() and the worst bone of each group in Config.Effects.Legs.Bones / Arms.Bones, converts it to a severity (1 bruised, 2 cracked, 3 fractured, 4 broken, from Config.Bones.Thresholds) and applies:
- Legs:
SetPedMoveRateOverride(cap 1.15),INPUT_SPRINT/INPUT_JUMPdisabled from the configured severity, optional0x8B3CB08158E98481limp flag (LimpNative, undocumented and unverified). Skipped on horseback whenSkipWhenMounted. - Arms: while free aiming, a smooth sine-based offset is added to the gameplay camera heading/pitch (only the per-frame change is applied, so normal aiming still works);
INPUT_RELOADis disabled fromBlockReloadFrom. The loop idles at 500 ms when no effect is active. Everything is reset on heal, unload, death and resource stop. Effects are client-side and cosmetic like the bone state itself.
Treatment, doctors, pain and logging#
- Items (
client/treatment.lua,server/server.lua): usingbone_bandage/bone_splintmakes the server start the action (rsg-playerinfo:client:useTreatment), the client checks there is something to treat and shows the progress bar, thenrsg-playerinfo:server:treatDonemakes the server verify the elapsed time, consume the item and sendrsg-playerinfo:client:applyTreatment. Cancelling keeps the item. - Splints: stored per bone in
metadata.bonesplintsnext tometadata.bones. A splinted bone regainsSplintRecoveryPerMinuteper minute online and is released at the healthy threshold. A new hit removes the splint, a full heal clears all splints. For the gameplay effects a splinted bone counts as at mostTreatment.SplintEffectCap. - Doctors:
/examinebonesand/treatbones(names inConfig.Doctor) check the job (and duty), the distance on the server, then ask the patient's client for fresh bone data (rsg-playerinfo:client:getBonesclient callback). The exam opens the NUI in exam mode (medical card only). Treatment consumes the doctor's items whenUseItemsis true and sendsapplyTreatment('doctor')to the patient. - Pain (
client/pain.lua): reacts to the local eventrsg-playerinfo:client:boneWorsened (key, severity)with an anim post FX flash andPLAY_PAIN(pain id unverified in-game). - Logging: when a saved bone table crosses
Logging.MinSeverity,rsg-log:server:CreateLogis called (only while rsg-log is started). - State for other scripts: client state bags
boneLegs/boneArms(effective severity 0-4, set with replication) and the client eventrsg-playerinfo:client:severityChanged (legs, arms). Server:exports['rsg-playerinfo']:GetSeverity(src, 'legs'|'arms'). Example: block climbing whenexports['rsg-playerinfo']:GetSeverity('legs') >= 3(client) orPlayer(src).state.boneLegs >= 3.
Items to add manually (when RegisterItems = false) in rsg-core/shared/items.lua:
bone_bandage = { name = 'bone_bandage', label = 'Bone Bandage', weight = 100, type = 'item', image = 'bandage.png', unique = false, useable = true, shouldClose = true, description = 'Wraps bruised bones.' },
bone_splint = { name = 'bone_splint', label = 'Splint', weight = 300, type = 'item', image = 'bone_splint.png', unique = false, useable = true, shouldClose = true, description = 'Immobilises a cracked or broken bone so it can heal.' },
Exports (client)#
| Export | Returns / does |
|---|---|
GetBoneHealth() | Table of bone key to condition (0-100) |
GetBoneStatus(key) | 'healthy', 'bruised', 'cracked', 'fractured' or 'broken' (nil for an unknown key) |
HasInjury(what?) | true if any bone, a group ('core', 'arms', 'legs') or a single bone key is below healthy |
GetSeverity(what) | 0-4 for a bone key or 'legs' / 'arms' (0 healthy, 1 bruised, 2 cracked, 3 fractured, 4 broken) |
GetSplints() | Table of splinted bone keys |
BandageBones() / SplintBones() | Apply a bandage / splint to the local player (returns how many bones changed, no item is used) |
HealBones(key?) | Restore one bone, or all when key is nil |
DamageBone(key, amount) | Remove amount condition from a bone |
SetEffectsEnabled(bool) / AreEffectsEnabled() | Turn the gameplay effects on/off at runtime (cutscenes, minigames) |
OpenPlayerInfo() / ClosePlayerInfo() / IsPlayerInfoOpen() | Control the info screen |
Exports (server)#
| Export | Returns / does |
|---|---|
GetBones(src) | Last saved bone table of an online player (can lag ~2 s), or nil |
HealBones(src, key?) | Restore all bones (or one) of an online player; returns true/false |
DamageBone(src, key, amount) | Damage a bone of an online player; returns true/false |
GetSeverity(src, what) | Effective severity 0-4 of 'legs' or 'arms' (from the player's state bag) |
OpenPlayerInfo(src) | Open the info screen for a player |
Example: exports['rsg-playerinfo']:DamageBone(src, 'shin_l', 40) from a trap script, or exports['rsg-playerinfo']:HealBones(src) from a doctor script. The client event rsg-playerinfo:client:damageBone (key, amount) and rsg-playerinfo:client:healBones (key?) are what the server exports trigger. Prefer the server exports from other scripts so the target is validated.
NUI#
- Messages (Lua → NUI):
open,update,close. Callback (NUI → Lua):close. - The panel size is
--size(percent), set fromConfig.ScreenPercent(clamped 50–100). Sizes useremderived from the screen height so it scales with resolution. - All values are HTML-escaped; icon classes are validated before use.
- Style follows the house standard (Roboto, monochrome palette, no vignette, no native form elements).
Configuration#
See the table in README.md.
Push-to-talk: all focus changes go through applyNuiFocus(). While the UI has focus, every control is disabled except Config.PushToTalkControls.
Events, callbacks and commands#
| Name | Side | Description |
|---|---|---|
/info | server | Opens the dashboard (no permission required) |
/healbones [id] | server | Restores all bones of a player (admin) |
rsg-playerinfo:client:healBones | client event | Restores all bones and notifies the player |
rsg-playerinfo:server:saveBones | server event | Stores the client's bone table in metadata (validated, 1 s cooldown) |
rsg-playerstats:client:openPlayerStats | client event | Opens the dashboard for the local player |
rsg-playerstats:server:getPlayerData | callback | Returns the data table above |
The rsg-playerstats prefix is kept from earlier versions so existing triggers (radial menu, keybinds) keep working. To open the dashboard from another resource: TriggerEvent('rsg-playerstats:client:openPlayerStats').
Integrations#
- rsg-banking (optional):
exports['rsg-banking']:GetTotalBalance(citizenid)supplies the bank tile. Without it the coremoney.bankvalue is shown. - rsg-core multi-job:
exports['rsg-core']:GetPlayerJobs(src)supplies "Other Jobs". - rsg-medic: its client events
rsg-medic:client:reviveandrsg-medic:client:heal(-1) restore all bones.
Security#
- The callback only returns the requesting player's own data; the license identifier is never sent.
- Per-player 750 ms cooldown on the callback (it queries
players.outlawstatuswith a?parameter). - The NUI has no actions other than
close. - Bone health is client-reported (cosmetic): a modified client can report healthy bones. The server validates the shape and range only. If you later tie gameplay penalties to bones, apply them with the same trust level or add server checks.
Locales#
Loaded by rsg-core (@rsg-core/shared/locale.lua, locales/*.json, locale('key')). Language comes from the rsg:locale convar. Every file has the same keys as en.json.
Performance notes#
The info callback only queries the database / rsg-banking / multi-job when the matching show_* option is enabled. The effects loop re-reads the bones 4 times a second and only runs per frame while an effect is actually active.
Known limitations#
Bone state is client-reported (the server validates range and shape but cannot tell a legitimate recovery from a spoofed one), so treat it as roleplay state, not as anything that gates money or items. The last 2 seconds of bone changes can be lost on a hard disconnect.
Troubleshooting#
| Problem | Fix |
|---|---|
| Fields show "No data" | The server's PlayerData has no value for it (e.g. blank callsign); hide it with its show_* flag |
| Bank tile shows only the core balance | rsg-banking is not started or GetTotalBalance did not return a number |
| Regional bank card missing | Only shown when PlayerData.money has rhobank / valbank / blkbank / armbank |
| Items are missing / have no image | Items are registered at start (RegisterItems); add bone_splint.png to rsg-inventory's images or point image at an existing one |
/examinebones says not a doctor | Check Config.Doctor.Jobs, that the player is on duty and that the job name matches rsg-medic |
| No limp animation | LimpNative uses an undocumented native; the slowdown and sprint/jump block work without it |
| Bones never change | Set Config.Bones.Debug = true, take a hit and read the F8 console: it prints the raw bone id and the bone it mapped to |
| Wrong bone hit | Add or fix the id in Bones.ByBoneId (shared/bones.lua) |
| Fractures never heal | Only bruises mend on their own; use rsg-medic treatment or /healbones |
| Icons missing | The UI loads Font Awesome and Roboto from a CDN; the player needs internet access |
| Screen too big / small | Change Config.ScreenPercent |
Support: https://rexshack.tebex.store
<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->Technical reference#
Generated from the source of rsg-playerinfo 3.1.1. Names, arguments and defaults below are read straight from the code.
Dependencies#
rsg-core, oxmysql, rsg-inventory
Configuration#
| Option | Default | Notes |
|---|---|---|
Config.ScreenPercent | 80 | Size of the info screen as a percentage of the game screen (50-100). |
Config.RefreshInterval | 5000 | While the screen is open, refresh the data every X milliseconds (0 = off, minimum 1000). |
Config.PlayerInfoSetup | table | Show / hide individual fields and sections. |
Config.Reputation | table | Shown when Config.PlayerInfoSetup.show_reputation is true. Cumulative XP needed to reach level L is floor(XPPe |
Config.XPPerLevel | 100 | |
Config.LevelGrowth | 1.5 | |
Config.MaxLevel | 50 | |
Config.HideZero | false | |
Config.Categories | {} | Categories = { hunting = { label = 'Hunting', icon = 'fa-solid fa-crosshairs' } }, |
Config.Bones | table | Each bone has a condition from 100 (healthy) down to 0 (broken). A hit lowers the condition of the bone that w |
Config.Enabled | true | |
Config.PollInterval | 150 | |
Config.MinDamagePercent | 4 | |
Config.DamageScale | 1.0 | |
Config.RecoveryPerMinute | 2.0 | |
Config.SplintRecoveryPerMinute | 0.5 | |
Config.Thresholds | { healthy = 90, bruised = 60, cracked = 30 } | Condition thresholds: >= healthy = healthy, >= bruised = bruised, >= cracked = cracked, > 0 = fractured, 0 = b |
Config.FallWeights | { foot = 1.0, shin = 0.7, thigh = 0.4, pelvis = 0.2 } | A fall damages the legs instead of the "last damage bone" (share of the damage each bone takes, both sides) |
Config.RestoreOnMedic | true | Doctors / revives restore all bones: rsg-medic:client:revive and rsg-medic:client:heal (-1 = full heal) |
Config.Debug | false | |
Config.Effects | table | Tables are indexed by severity; a missing/0 entry means no effect at that level. The worst bone of each group |
Config.PublishState | true | |
Config.Legs | table | |
Config.Arms | table | |
Config.Treatment | table | A splinted bone loses its splint when it is hit again. Doctors (rsg-medic) can treat others, see Config.Doctor |
Config.RegisterItems | true | |
Config.Bandage | { item = 'bone_bandage', label = 'Bone Bandage', weight = 100, image = | |
Config.Splint | { item = 'bone_splint', label = 'Splint', weight = 300, image = | |
Config.SplintEffectCap | 2 | |
Config.Doctor | table | Doctor tools: /examinebones shows a patient's bone map, /treatbones bandages and splints them. |
Config.Jobs | { 'medic' } | |
Config.RequireDuty | true | |
Config.Distance | 3.0 | |
Config.ExamCommand | 'examinebones' | |
Config.TreatCommand | 'treatbones' | |
Config.UseItems | true | |
Config.Pain | table | Screen flash and pain sound when a bone gets worse. Severity: 1 bruised, 2 cracked, 3 fractured, 4 broken. |
Config.MinSeverity | 2 | |
Config.Cooldown | 4000 | |
Config.Flash | 'MP_HealthDrop' | |
Config.FlashDuration | 1500 | |
Config.Sound | true | |
Config.PainId | 10 | |
Config.Logging | table | Log new fractures/breaks to rsg-log (when running) |
Config.Channel | 'playerinfo' | |
Config.Color | 'orange' | |
Config.AllowPushToTalkWhileOpen | true | While NUI is open, block game controls but allow push-to-talk. |
Config.PushToTalkControls | table |
Exports#
Server
| Export | Arguments | File |
|---|---|---|
GetBones | src | server/server.lua |
HealBones | src, key | server/server.lua |
DamageBone | src, key, amount | server/server.lua |
OpenPlayerInfo | src | server/server.lua |
GetSeverity | src, what | server/server.lua |
Client
| Export | Arguments | File |
|---|---|---|
GetBoneHealth | `` | client/bones.lua |
HealBones | key | client/bones.lua |
DamageBone | key, amount | client/bones.lua |
GetBoneStatus | key | client/bones.lua |
GetSplints | `` | client/bones.lua |
BandageBones | `` | client/bones.lua |
SplintBones | `` | client/bones.lua |
HasInjury | what | client/bones.lua |
OpenPlayerInfo | `` | client/client.lua |
ClosePlayerInfo | `` | client/client.lua |
IsPlayerInfoOpen | `` | client/client.lua |
GetSeverity | what | client/effects.lua |
SetEffectsEnabled | state | client/effects.lua |
AreEffectsEnabled | `` | client/effects.lua |
-- example
local result = exports['rsg-playerinfo']:GetBones(src)
Callbacks#
| Callback | Side | Arguments | File |
|---|---|---|---|
rsg-playerinfo:client:getBones | client | cb | client/bones.lua |
rsg-playerstats:server:getPlayerData | server | source, cb | server/server.lua |
-- client side
RSGCore.Functions.TriggerCallback('rsg-playerinfo:client:getBones', function(result)
-- use result
end)
Events#
Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.
| Event | Side | Arguments | File |
|---|---|---|---|
RSGCore:Client:OnPlayerLoaded | client | `` | client/bones.lua |
RSGCore:Client:OnPlayerUnload | client | `` | client/bones.lua |
rsg-medic:client:revive | client | `` | client/bones.lua |
rsg-medic:client:heal | client | amount | client/bones.lua |
rsg-playerinfo:client:damageBone | client | key, amount | client/bones.lua |
rsg-playerinfo:client:healBones | client | key | client/bones.lua |
rsg-playerstats:client:openPlayerStats | client | `` | client/client.lua |
rsg-playerinfo:client:openExam | client | info | client/client.lua |
rsg-playerinfo:client:useTreatment | client | kind | client/treatment.lua |
rsg-playerinfo:client:applyTreatment | client | kind | client/treatment.lua |
rsg-playerinfo:server:saveBones | server | bones, splints | server/server.lua |
rsg-playerinfo:server:treatCancel | server | `` | server/server.lua |
rsg-playerinfo:server:treatDone | server | kind | server/server.lua |
-- from a client script
TriggerServerEvent('rsg-playerinfo:server:saveBones', bones, splints)
-- from a server script
TriggerClientEvent('RSGCore:Client:OnPlayerLoaded', source)
Commands#
| Command | Notes | File |
|---|---|---|
/info | locale('sv_view_stats') | server/server.lua |
/healbones | locale('sv_healbones_help') | server/server.lua |
Locales#
Language files in locales/: de, el, en, es, fr, it, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".