All resources

rsg-reputation developer and server owner documentation#

Contents#

How it works#

Each character has one honor number and one standing number per region. Both live in an in-memory cache while the player is online, are loaded from the database the first time they are needed and are written back in batches. Only the server changes them. Other scripts report events through server exports; the client holds a read-only mirror that is refreshed after every change.

Regions are plain ids (valentine, new_hanover, ...) chosen by the calling script. The resource does not detect where the player is.

Files#

FilePurpose
shared/config.luaAll settings, tiers, regions and actions.
server/database.luaTable creation, cache, loading, decay, saving.
server/reputation.luaTiers, changing and reading values, exports, panel callback.
server/commands.luaAdmin commands.
client/client.luaRead-only mirror and client exports.
client/ui.luaPanel open/close, NUI focus with push-to-talk.
html/The NUI panel (index.html, style.css, script.js).
locales/*.jsonThe 11 languages.
install.sqlManual install of the tables.

Honor, standing and tiers#

  • Honor: Config.Honor.Min to Max (default -1000 to 1000), starting at Start.
  • Standing: Config.Standing.Min to Max (default -100 to 100). Below 0 is infamy, above 0 is fame.
  • A tier is the entry with the highest min that the value has reached. Fields: min, label (locale key or plain text), and for standing tiers priceModifier (fraction added to prices, 0.10 = 10% dearer) and hostile.
  • Tier tables returned by exports: { index, labelKey, label, min, priceModifier, hostile }. label is already translated.
  • Spill-over: a change in a town also moves its parent state by Standing.ParentSpill of the change, rounded toward zero. Spill-over never chains further. Pass noSpill = true to skip it.
  • Values are always whole numbers and are clamped to the range.

Actions#

Config.Actions maps an action name to { honor = n, standing = n }. ApplyAction(src, name, region) applies the honor part always and the standing part only when a region is given. Add your own entries freely; scripts only need the name.

ActionHonorStanding
theft-8-8
robbery-15-15
murder-40-30
bounty_delivered55
outlaw_killed86
arrest34
helped_lawman54
revive53
donation35
delivery02
gang_territory-3-5

Server exports#

src is the player's server ID. Calls that need the player's data wait (inside a thread or event handler) while it is loaded from the database the first time. They return nil when the player is not online, a value is not a finite number, or a region is unknown.

Changing#

ExportReturnsDescription
AddHonor(src, amount, reason?, quiet?)new honorAdd (or subtract) honor. One call is capped by MaxChangePerCall.
SetHonor(src, value, reason?, quiet?)new honorSet honor to an exact value (clamped).
AddStanding(src, region, amount, reason?, quiet?, noSpill?)new standing of regionAdd standing; spill-over to the parent state unless noSpill.
SetStanding(src, region, value, reason?, quiet?)new standingSet standing exactly. No spill-over.
ApplyAction(src, action, region?)true / falseApply a named action. false for an unknown action.
ResetReputation(src)true / falseHonor and all standing back to the starting values.

reason is passed to the events. quiet = true suppresses the notifications for that call.

Reading#

ExportReturns
GetHonor(src)honor number
GetHonorTier(src)tier table
HasHonor(src, min)true if honor >= min
GetStanding(src, region)standing number
GetStandingTier(src, region)tier table
HasStanding(src, region, min)true if standing >= min
GetPriceModifier(src, region)fraction to add to prices, 0.0 when unknown
IsHostile(src, region)true when the standing tier is hostile
GetHonorByCitizenId(citizenid)honor of an online or offline character
GetRegions()the Config.Regions table

Client exports#

Read-only mirror of the local player. Never use it to decide anything that matters on the server.

ExportReturns
GetHonor()honor number
GetHonorTier()tier table
GetStanding(region)standing number (nil for an unknown region)
GetStandingTier(region)tier table
GetPriceModifier(region)fraction, 0.0 when unknown
IsHostile(region)boolean

Events and callbacks#

NameSideArgumentsPurpose
rsg-reputation:server:readyservernoneDatabase is ready.
rsg-reputation:server:honorChangedserversrc, new, old, reasonHonor changed.
rsg-reputation:server:standingChangedserversrc, region, new, old, reasonStanding changed.
rsg-reputation:server:tierChangedserversrc, kind, region, oldTier, newTierA tier boundary was crossed. kind is 'honor' or 'standing'; region is nil for honor.
rsg-reputation:client:syncclient{ honor, standing }Server pushes the mirror. Used internally.
rsg-reputation:client:changedclienthonorFired locally after a sync so UIs can refresh.
rsg-reputation:client:openclientnoneOpens the panel.
rsg-reputation:server:getReputationcallbacknonePanel data. Read only, throttled to one call per second.
rsg-reputation:server:requestSynccallbacknoneLoads the player and pushes the mirror.

Integration examples#

Report a delivered bounty (e.g. rsg-bountyhunter)#

-- after the server has verified the delivery and paid the reward
exports['rsg-reputation']:ApplyAction(src, 'bounty_delivered', 'valentine')

Charge more to disliked players (any shop script)#

local mod = exports['rsg-reputation']:GetPriceModifier(src, shop.region)
local price = math.floor(basePrice * (1 + mod) + 0.5)

Lawman reactions#

if exports['rsg-reputation']:IsHostile(src, 'blackwater') then
    -- refuse service, alert the law, spawn guards...
end

Gate a job or item by honor#

if not exports['rsg-reputation']:HasHonor(src, 400) then
    return TriggerClientEvent('RSGCore:Client:Notify', src, { title = 'Reputation', description = 'Not trusted enough', type = 'error' })
end

React to tier changes#

AddEventHandler('rsg-reputation:server:tierChanged', function(src, kind, region, oldTier, newTier)
    if kind == 'standing' and newTier.hostile then
        -- the town has turned on this player
    end
end)

Persistence and decay#

  • Changed values are written every SaveInterval seconds, on logout (RSGCore:Server:OnPlayerUnload, playerDropped) and when the resource stops. A failed write is kept and retried on the next save.
  • Each character has a decayed timestamp. For every full day since it, honor and standing move toward 0 by Decay.PerDay (when Decay.Enabled). The timestamp moves forward by whole days only, so partial days are not lost. Decay runs when a player loads and every 30 minutes for online players; it also covers time spent offline.
  • Standing never crosses 0 through decay.

Commands#

See the table in README.md. Admin commands also work from the server console (source 0) and answer in the console. All use Config.AdminPermission.

Security model#

  • Clients cannot change a reputation: there is no client-to-server event that changes values. The only client-callable entries (getReputation, requestSync) are read-only (they load and send the player's own data).
  • Server exports trust their caller. Only call them after your own checks have passed (distance, job, item, cooldown), and never forward client-supplied amounts. Prefer ApplyAction so the numbers come from config.
  • Amounts must be finite numbers; NaN, infinity, strings and unknown regions are rejected. Single calls are capped by MaxChangePerCall.
  • The panel callback is throttled per player.
  • Client exports are for display and convenience only.

Database schema#

Created automatically (Config.AutoDatabase), or import install.sql.

rsg_reputation

ColumnTypeNotes
citizenidVARCHAR(50)Primary key
honorINT
decayedINT UNSIGNEDUnix time of the last decay
updatedTIMESTAMPUpdated automatically

rsg_reputation_standing

ColumnTypeNotes
citizenidVARCHAR(50)Primary key (part 1)
regionVARCHAR(50)Primary key (part 2)
standingINT

Server owner how-tos#

  • Add a region: add an entry to Config.Regions (label, type, parent, order). The panel and commands pick it up. Use the same id in the scripts that report to it.
  • Change a tier: edit the Honor.Tiers or Standing.Tiers list. Keep min values distinct; they are sorted automatically.
  • Make infamy cost more in shops: raise priceModifier on the negative standing tiers.
  • Turn decay on or off: Honor.Decay.Enabled and Standing.Decay.Enabled.
  • Tune an action: edit Config.Actions; scripts that use ApplyAction follow automatically.
  • Wipe a player: /resetreputation [id].

Troubleshooting#

ProblemCheck
"could not create database tables" in the consoleoxmysql is running and the database user may create tables, or set AutoDatabase = false and import install.sql.
Exports return nilThe player is not online, the region id is not in Config.Regions, or the value is not a number.
Panel does not openResource started after rsg-core? Another resource using NUI focus may hold it. Config.Command must not be empty.
Changes do not show in the panelThe panel loads when opened; reopen it.
A locale shows a raw keyThe key is missing from that language file; tier and UI keys must exist in all files.
Push-to-talk does not work with the panel openConfig.AllowPushToTalkWhileOpen and PushToTalkControls.

Support the Project : 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-reputation 3.0.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

oxmysql, rsg-core

Database#

Tables: rsg_reputation, rsg_reputation_standing.

Tables are created automatically on start while Config.AutoDatabase = true (default). Nothing is ever dropped or overwritten. For a manual install set Config.AutoDatabase = false and import install.sql once.

-- shared/config.lua
Config.AutoDatabase = true -- false = import the SQL file yourself

Configuration#

OptionDefaultNotes
Config.AutoDatabasetrueTables are created automatically on start. Set to false to import install.sql manually.
Config.AllowPushToTalkWhileOpentrueWhile the NUI is open, block game controls but allow push-to-talk.
Config.PushToTalkControlstable
Config.Command'reputation'Chat command that opens the reputation panel ('' to disable)
Config.AdminPermission'admin'Permission level needed for the admin commands
Config.NotifyChangestrueSmall "+5 Honor" / "-8 Valentine standing" notifications on every change (a new one replaces the old one)
Config.NotifyTierChangetrueNotification when a player moves into a new honor or standing tier
Config.SaveInterval60Seconds between database saves of changed reputations (also saved on logout)
Config.MaxChangePerCall200Safety cap on the size of a single change made through AddHonor / AddStanding
Config.Honortable
Config.Min-1000
Config.Max1000
Config.Start0
Config.Decay{ Enabled = false, PerDay = 5 }pulls the score back toward 0 by PerDay for every full day (works while the player is offline too)
Config.Tierstable
Config.Standingtable
Config.ParentSpill0.5a change in a town also moves its state by this fraction (0 = never), rounded toward zero
Config.Regionstable
Config.Actionstable

Exports#

Server

ExportArgumentsFile
AddHonor``server/reputation.lua
SetHonor``server/reputation.lua
GetHonor``server/reputation.lua
GetHonorTier``server/reputation.lua
HasHonorsrc, minserver/reputation.lua
AddStanding``server/reputation.lua
SetStanding``server/reputation.lua
GetStanding``server/reputation.lua
GetStandingTier``server/reputation.lua
HasStandingsrc, region, minserver/reputation.lua
GetPriceModifier``server/reputation.lua
IsHostile``server/reputation.lua
ApplyAction``server/reputation.lua
ResetReputation``server/reputation.lua
GetHonorByCitizenId``server/reputation.lua
GetRegions``server/reputation.lua

Client

ExportArgumentsFile
GetHonor``client/client.lua
GetHonorTier``client/client.lua
GetStandingregionclient/client.lua
GetStandingTierregionclient/client.lua
GetPriceModifierregionclient/client.lua
IsHostileregionclient/client.lua
-- example
local result = exports['rsg-reputation']:AddHonor()

Callbacks#

CallbackSideArgumentsFile
rsg-reputation:server:getReputationserversource, cbserver/reputation.lua
rsg-reputation:server:requestSyncserversource, cbserver/reputation.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-reputation:server:getReputation', 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.

EventSideArgumentsFile
rsg-reputation:client:syncclientdataclient/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-reputation:client:openclient``client/ui.lua
-- from a server script
TriggerClientEvent('rsg-reputation:client:sync', source, data)

Locales#

Language files in locales/: de, el, en, es, fr, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->