All resources

rsg-character — Server Owner & Developer Docs#

This document explains how rsg-character works under the hood, so you can configure it confidently, troubleshoot problems and build other resources on top of it. For a quick install guide see README.md.

Version: 3.4.0 · Framework: RSG-Core · Lua: 5.4


Contents#

  1. Resource layout
  2. Player flow
  3. Database
  4. Security model
  5. Clothing store & wardrobe
  6. Clothing order
  7. Spawning
  8. Logout
  9. Webhooks
  10. Locales
  11. Developer API
  12. Common tasks (incl. admin commands, slots and names)
  13. Troubleshooting
  14. Configuration reference
  15. Changelog

1. Resource layout#

rsg-character/
├── fxmanifest.lua
├── install.sql           -- manual table install (same schema as sv_database.lua)
├── shared/
│   ├── config.lua        -- all settings (RSG table)
│   └── functions.lua     -- birthdate check, clothing validation, price calculation (shared)
├── client/
│   ├── charselect.lua    -- in-world character select (ped lineup, camera, slot actions)
│   ├── creator.lua       -- character creator, ApplySkin, /loadskin, most exports
│   ├── clothes.lua       -- clothing store, clothing layer order, wardrobe/outfits
│   ├── functions.lua     -- shared client helpers (camera, prompts, components)
│   ├── spawn.lua         -- spawn select screen, ApplySkin event, spawn checks
│   ├── ui.lua            -- NUI bridge (loading screen, menus), NUI focus + push-to-talk whitelist
│   └── hashtocache.lua   -- builds hash lookup caches (loaded as a file)
├── server/
│   ├── sv_charselect.lua -- slots, select, delete, request create
│   ├── sv_appearance.lua -- routing buckets, creator sessions, SaveSkin, createCharacter, appearance callbacks
│   ├── sv_admin.lua      -- /charinfo, /resetskin, /changename
│   ├── sv_clothing.lua   -- buy outfit, wear/delete outfit, outfit callbacks, DB migration
│   ├── sv_delete.lua     -- soft delete, restore, purge, /restorechar, /deletedchars
│   ├── sv_slots.lua      -- database slots (playerslots), /addslot, /setslots, /charslots
│   ├── sv_database.lua   -- builds and upgrades the tables (RSG.AutoDatabase)
│   ├── sv_logout.lua     -- /logout command
│   ├── webhook.lua       -- Discord webhook queue
│   └── versionchecker.lua
├── data/                 -- features, overlays, hair and clothing hash lists
├── html/                 -- NUI (index.html, css, js, spawn images)
├── img/                  -- menu icons and skin tone swatches
└── locales/              -- en, de, el, es, fr, ja, nl, pl, pt-br, ro, ru

Data files in data/ are large hash tables loaded on demand with rsg-core's require (@rsg-core/shared/require.lua).


2. Player flow#

Connect
  └─► client asks server for slots ──► server puts player in a private routing bucket
        └─► Character Select (ped lineup)
              ├─ Play existing ─► server verifies license owns citizenid ─► RSGCore.Player.Login
              │     ├─ has skin ─► ApplySkin ─► reset bucket ─► spawn at last position
              │     │                                        (or spawn select if no valid position)
              │     └─ no skin  ─► Creator opened by server (appearance only)
              ├─ Create (empty slot) ─► server checks slot free ─► Creator session opened
              │     └─ identity form ─► createCharacter (validated) ─► Login + starter items
              │           └─ SaveSkin ─► skin + protected Default outfit saved ─► Spawn Select
              └─ Delete ─► ownership check ─► character, skin and outfits removed

Key points:

  • Character select only works for logged-out players. All charselect server events return early if the source already has a Player object.
  • The creator is server-driven. The client can't open a saving creator session itself; only RSG.OpenCreatorFor(src, data) on the server creates one.
  • New characters always see spawn select. Returning characters with a valid saved position (not 0,0,0) spawn straight there.
  • A new character is given a full heal on first spawn.

3. Database#

The script uses five tables alongside rsg-core's players table.

playerskins#

ColumnTypeNotes
idINT, PK
citizenidVARCHAR(255)Unique key uq_playerskins_citizenid
skinLONGTEXTJSON: body, face features, overlays, hair, sex (1 male, 2 female)
clothesLONGTEXTJSON: clothing per category ({ hats = { model = n, texture = n }, ... })

One row per character (enforced by the unique key; SaveSkin uses ON DUPLICATE KEY UPDATE). Code still reads the newest row (ORDER BY id DESC) in case the key could not be added.

playeroutfit#

ColumnTypeNotes
idINT, PKOutfit id used by wear/delete
citizenidVARCHAR(255)Indexed with is_default (citizen_default)
nameVARCHAR(255)Player-entered (trimmed to 40 chars) or auto-generated
clothesLONGTEXTSame JSON format as playerskins.clothes
is_defaultTINYINT(1)1 = the protected Default outfit

playerslots#

ColumnTypeNotes
licenseVARCHAR(255), PKPlayer license
extra_slotsINTSlots on top of RSG.MaxCharacterSlots
updated_atTIMESTAMPUpdated automatically

rsg_character_names#

One row per character (citizenid, firstname, lastname, indexed on the name pair). Used by the unique-name check so players is never scanned. Filled for existing characters on start and kept up to date by the creator and /changename. If another resource renames a character directly in players.charinfo, call RSG.SetCharacterName or run /changename to refresh the row.

rsg_character_deleted#

Characters hidden by a soft delete: citizenid (PK), license, original_cid (their old slot), deleted_at, purge_at (unix seconds). While a character is listed here its players.cid is moved out of the slot range (cid + 1000), which hides it and frees the slot.

Automatic setup and migration#

On MySQL.ready the script: 0. When RSG.AutoDatabase = true, runs the CREATE TABLE IF NOT EXISTS statements from server/sv_database.lua (printing a green "database tables ready" or a red error). Set it to false and import install.sql to install manually.

  1. Adds is_default to playeroutfit if missing, then the citizen_default index. 1b. Adds the unique key to playerskins (skipped when a unique key on citizenid already exists, as in the txAdmin recipe). Older duplicate rows are removed first when RSG.DedupeSkins = true (only the newest row per character was ever read); otherwise the key is skipped with a console warning. 1c. Fills rsg_character_names for characters that are not in it yet.
  2. Creates a Default outfit for every character that has clothes but no Default yet, and prints how many it created.

This runs on every start and is safe to repeat.

What deleting a character does#

With RSG.Delete.SoftDelete = true (default) the character is only hidden for RSG.Delete.GraceDays days: it gets a row in rsg_character_deleted, its cid is moved out of the slot range, and nothing else is touched. After the grace period (checked at start and every RSG.Delete.PurgeInterval minutes) it is removed for good with RSGCore.Player.ForceDeleteCharacter plus its playerskins, playeroutfit and rsg_character_names rows. /restorechar [citizenid] puts it back into its old slot (or the first free one) before that.

With SoftDelete = false everything is removed at once (RSGCore.Player.DeleteCharacter and the same extra rows).

A hidden character still exists in players: other resources that list characters by license or citizenid (banks, gangs, MDT) can still see it until it is purged.


4. Security model#

rsg-character assumes the client can't be trusted. Server-side protections:

AreaProtection
Character selectOnly for logged-out players. Selecting a citizenid the license doesn't own drops the player (exploit attempt).
Slot creationcid must be a whole number between 1 and MaxCharacterSlots, and free for that license.
CreatorServer-owned CreatorSessions[src]. SaveSkin and createCharacter are ignored without a session; a new character can only be created once per session and must match the session's cid.
IdentityFirst/last name: RSG.IsValidName (shared): RSG.NameRules length, letters incl. accents, apostrophes/hyphens between letters, limited capitals, whole-name and substring blocklists, reserved names. Nationality must match a configured nationality in any locale. Birth date must be inside the range from RSG.GetBirthdateRange() (Min/Max narrowed by MinAge/MaxAge).
GenderTaken from the character record, never from the client.
Skin dataMax 150 keys, string keys ≤ 32 chars, number values (or tables of numbers). Encoded JSON capped at 32 KB.
ClothingValidateClothesData checks every item against the real clothing list for the character's gender. Price is recalculated on the server (CalculatePrice) from what changed.
Store locationBuying and entering the fitting-room bucket require being within 10 m of a store.
WardrobeWearing an outfit requires being near a cloakroom, unless WardrobeTarget.enabled (props can't be checked server-side; outfits are already paid for). Outfits are re-validated before being applied.
CooldownsBuy 2 s, wear/delete 1 s, delete character 3 s, /logout configurable.
Routing bucketsThe script only resets a bucket it assigned, and restores the bucket the player was in before (never blindly bucket 0), so it can't be used to escape jail or other instances.
Double requestsSelecting a character is ignored while a login is running; /logout is ignored while a logout is running. Rejected or failed requests send CharSelectFailed so the client never hangs on the loading screen.
Character slotsSlots are RSG.MaxCharacterSlots + the license's playerslots extra, raised by the best matching RSG.SlotRules ACE rule (the larger value wins), limited by RSG.Slots.Cap. Resolved on the server for every slot list and create request.
Character deleteNeeds RSG.Delete.Enabled, ownership, a 3 s cooldown and (with ConfirmName) the typed first name, re-checked on the server. Soft-deleted characters cannot be selected (RSG.IsPendingDeletion).
Spawn choiceAfter character select the server remembers that a spawn menu was offered and the client asks rsg-character:server:chooseSpawn for the coordinates of its choice; a choice that was not offered, or a second answer, is refused. The client still moves its own ped, so this is a consistency check, not anti-teleport.
Unique namesRSG.NameExists (indexed rsg_character_names table) is checked by the isNameAvailable callback (creator session only) and again in createCharacter.
Outfit sharingServer checks ownership, same body type, distance (re-checked after the prompt), per-player cooldown, one pending offer per receiver and the 30-outfit limit. The receiver must accept (client callback with timeout); the copy is re-validated with ValidateClothesData.
Admin commandsRegistered with rsg-core's permission level (RSG.AdminCommands.Permission); every action can be logged to the admin_action webhook.
Outfit namesHTML/control characters are stripped, max 40 chars; the client also escapes names before showing them.

5. Clothing store & wardrobe#

Outfit sharing: in the wardrobe, pick an outfit and choose Share Outfit. The nearest player (within RSG.OutfitSharing.MaxDistance) gets a confirm dialog; if they accept, a copy is added to their wardrobe. Only same body type, and only if they have room.

Store flow#

  1. Player stands at promtcoords and presses RSG.OpenKey.
  2. Server moves them into a private routing bucket and they're placed at fittingcoords.
  3. Menus are built from RSG.MenuElements; each category label comes from RSG.Label.
  4. On confirm, the client checks cash, asks for an outfit name and sends rsg-character:server:saveOutfit.
  5. The server validates, charges cash, updates playerskins.clothes and inserts a new playeroutfit row (max 30 non-default outfits; past that the purchase still applies but isn't saved as an outfit and the player is told).
  6. Player is placed at quitcoords and returned to bucket 0.

Pricing#

RSG.Price[category] is charged for each category that differs from what the player is currently wearing. Unchanged categories are free. Setting a category to 0 makes it free.

Wardrobe#

  • Cloakrooms: RSG.Cloakroom locations with blips and a prompt.
  • Props: with RSG.WardrobeTarget.enabled = true, every model in models gets an rsg-target option that opens the outfits menu. Add any prop model you like (e.g. MLO furniture).
  • The Default outfit is listed first and can't be deleted (enforced in SQL: AND is_default = 0).

Store doors#

RSG.SetDoorState sets each store door's state on start (0 open, 1 locked). If you use rsg-doorlock for these doors, remove them here to avoid fighting over the state.


Clothing order#

Clothing is applied in a fixed order defined by CLOTHING_ORDER at the top of client/clothes.lua:

  1. Base body parts (upper/lower) for any area not covered by clothing.
  2. Categories in CLOTHING_ORDER order (inner → middle → outer → equipment/accessories).
  3. Any category not listed, alphabetically.

Use the helper anywhere in client code to walk a clothes table in the same order:

for category, data in OrderedClothes(clothes) do
    -- applied in layer order
end

If a new clothing category clips, add it to CLOTHING_ORDER in the right layer.


7. Spawning#

  • RSG.SpawnLocations builds the spawn cards. Card image paths are relative to html/. The client sends the card the player picked (last or preset_<n>) to the server callback rsg-character:server:chooseSpawn, which answers with the coordinates only if that menu was offered.
  • The spawn screen shows for new characters and for characters whose saved position is invalid. With RSG.SpawnMenuWithLastLocation = true it also shows for returning characters, with a Last Location card first.
  • RSG.SpawnChecks is a safety net on RSGCore:Client:OnPlayerLoaded: anyone loading within Radius of a badSpawn point (by default the character select lineup) is moved to moveTo. Add more groups if players end up somewhere they shouldn't:
RSG.SpawnChecks = {
    ["Character Creation"] = {
        badSpawn = { vector3(4234.78, -717.32, 50.12) },
        moveTo   = { vector3(-169.47, 629.38, 113.03) },
        Radius   = 200,
    },
}

If you move RSG.CharSelectLocation, update badSpawn to match.


8. Logout#

/logout (name set by RSG.Logout.Command) is registered through RSGCore.Commands.Add:

  1. Blocked during a creator session, during the cooldown, and (unless forced by the LogoutToCharacterSelect export): when BlockWhenDead and metadata.isdead / inlaststand is set; when BlockWhenCuffed and metadata.ishandcuffed is set; when BlockWhenJailed and metadata.injail is above 0; and for CombatCooldown seconds after the client reported damage or weapon fire (rsg-character:server:combatActivity, sent at most every 4 s). A modified client can skip the report, so treat the combat rule as a fair-play measure, not anti-cheat.
  2. Client fades out (rsg-character:client:BeginLogout).
  3. Player.Functions.Save() then RSGCore.Player.Logout(src).
  4. character_logout webhook is sent and character select opens.

Set RSG.Logout.Enabled = false to remove the command.


9. Webhooks#

RSG.SendWebhook(category, embed) (server) posts a Discord embed if RSG.Webhooks[category].enabled and a real URL is set. Requests are queued one at a time and respect Discord's 429 Retry-After, so a busy server won't get rate-limited.

CategoryFired when
character_createdNew character created (name, citizenid, gender, nationality, birth date)
character_deletedCharacter deleted (or hidden); also used when a hidden character is purged after the grace period
character_restored/restorechar / RestoreCharacter brought a character back
character_selectedCharacter selected at character select
character_logout/logout used
appearance_savedCreator saved
outfit_purchasedClothing bought (price, outfit name)

All categories ship with enabled = false. Every embed also includes the player's identity fields (name and identifiers). Other server files in this resource can call RSG.SendWebhook with their own categories after adding them to RSG.Webhooks.


10. Locales#

  • All text is in locales/<lang>.json, loaded by rsg-core's locale loader.
  • Pick the server language with setr rsg:locale <lang> (ox:locale still works as a fallback).
  • Supported: en, de, el, es, fr, ja, nl, pl, pt-br, ro, ru. When adding a key, add it to every file.
  • Nationality validation accepts the nationality name from any locale file, so a player whose client language differs from the server can still create a character.

11. Developer API#

Everything other resources may rely on is listed here. Anything not listed (the net events in 11.7, RSG.* helpers, global functions) is internal and may change.

11.1 Client exports#

ExportReturnsDescription
ApplySkin()-Reloads the local player's saved skin and clothes from the server. Blocks until done.
ApplySkinMultiChar(skinData, ped, clothesData)-Applies a skin + clothes table to any ped (used for the select lineup).
SetFaceOverlays(ped, data)-Applies overlay data (scars, makeup, etc.).
SetHair(ped, data) / SetBeard(ped, data)-Applies hair / beard.
GetComponentId(name)numberCurrent creator component id by name.
GetBodyComponents()tableBody component table.
GetBodyCurrentComponentHash(name)numberCurrent body component hash.
GetComponentsMax(name)numberMax option count for a component.
GetMaxTexturesForModel(category, model, isClothing)numberTexture count for a model.
GetClothesCache(name)tableCurrent clothing cache (whole cache).
GetClothesComponentId(name)table/nilCurrent clothing cache entry for a category.
GetClothesCurrentComponentHash(name)numberCurrent clothing hash (0 when nothing is worn).
IsCothingActive()booleantrue while the player is in the clothing store. (Spelling kept for compatibility.)
IsInCreator()booleantrue while the character creator is open (new character or appearance-only).
IsInCharacterSelect()booleantrue while the character select lineup is on screen.
OpenWardrobe()booleanOpens the saved-outfits menu. Returns false (and does nothing) in the clothing store or character select.
-- do not open your own UI while the player is in a store, creator or character select
local function playerIsBusy()
    return exports['rsg-character']:IsCothingActive()
        or exports['rsg-character']:IsInCreator()
        or exports['rsg-character']:IsInCharacterSelect()
end
-- reapply appearance after your script changed the ped model (jail, transformation...)
exports['rsg-character']:ApplySkin()
-- add a "Wardrobe" entry to your own menu or command
RegisterCommand('wardrobe', function()
    exports['rsg-character']:OpenWardrobe()
end, false)

11.2 Client events#

You can trigger

EventDescription
rsg-character:client:ApplySkin (skin, clothes)Applies the given skin and clothes to the local player.
rsg-character:client:ApplyClothes (clothes, ped?)Applies a clothes table ({ [category] = { hash = n } }) to ped (default: the local player). Prefer the server export SetClothes, which validates first.
rsg-character:client:outfitsOpens the wardrobe menu (same as OpenWardrobe).
rsg-character:client:OpenCharSelectOpens character select. Only works for logged-out players (see 11.8).
rsg-character:client:OpenSpawnSelect (lastPos, isNew)Opens spawn select, or teleports to lastPos if given (unless RSG.SpawnMenuWithLastLocation).
rsg-character:client:OpenCreatorOpens the creator UI. Saves are only accepted when the server opened the session, so start the flow from the server instead.

You can listen to

EventFired when
rsg-character:client:skinAppliedThe local player's skin and clothes finished applying (after login, /loadskin, ApplySkin()).
RSGCore:Client:OnPlayerLoadedStandard rsg-core event; fired after the spawn select completes.
AddEventHandler('rsg-character:client:skinApplied', function()
    -- re-attach props, re-apply a mask, refresh your HUD...
end)

11.3 Player state (LocalPlayer.state, local only)#

KeyMeaning
inCharacterSelecttrue while the lineup is shown.
inClothingStoretrue while the player is in a fitting room.
isLoadingSkintrue while a skin reload swaps the ped (other resources such as rsg-medic ignore the temporary death state).

11.4 Server exports#

Called from another server script: exports['rsg-character']:Name(...).

ExportReturnsDescription
GetMaxSlots(src)numberSlots this player may use: RSG.MaxCharacterSlots + the license's extra slots, raised by the best matching RSG.SlotRules entry, limited by RSG.Slots.Cap.
GetExtraSlots(license)numberExtra slots stored for a license.
AddExtraSlots(license, amount)extra or nil, reasonAdds (or, with a negative number, removes) extra slots; the result is clamped to 0 .. Cap - MaxCharacterSlots. Reasons: invalid_license, invalid_amount, database.
SetExtraSlots(license, extra)extra or nil, reasonSets the extra slots exactly (same clamping).
GetDeletedCharacters(license?){ citizenid, license, firstname, lastname, deleted_at, purge_at }[]Characters in their deletion grace period (all, or one license).
RestoreCharacter(citizenid)true, cid or false, reasonRestores a hidden character. Reasons: not_found, no_slot.
PurgeDeletedCharacters()numberPermanently removes every hidden character whose grace period is over; returns how many.
IsInCreator(src)booleantrue while the player has a server-opened creator session.
IsNameAvailable(first, last)booleantrue when no character uses that name (always true if RSG.UniqueNames = false).
GetAppearance(citizenid){ skin, clothes } or nilSaved appearance of any character, online or offline.
GetOutfits(citizenid){ id, name, clothes, is_default }[]Saved outfits, Default first.
SetClothes(src, clothes, save?)ok, reasonValidates and wears clothes on an online player. save = true also stores them as the current clothes (free). Reasons: no_player, invalid_clothes, too_large.
AddOutfit(citizenid, name, clothes)id or nil, reasonAdds a wardrobe outfit (online or offline character). Reasons: no_character, invalid_clothes, limit_reached (30 non-default outfits).
ResetAppearance(citizenid)booleanDeletes the saved skin and Default outfit; the creator opens on the next login.
ChangeCharacterName(citizenid, first, last)ok, reasonRenames a character (online or offline) with the creator's name rules and uniqueness check. Reasons: invalid_name, name_taken, not_found.
LogoutToCharacterSelect(src)booleanSaves, logs out and opens character select; ignores the /logout cooldown and dead check. Returns false if the player isn't logged in.

clothes is { [category] = { hash = <number> } } using the hashes from data/clothing.lua / data/hairs_list.lua; every hash is validated against the character's body type.

11.5 Server hook events#

These are local server events (not net events, clients cannot trigger them). Listen with AddEventHandler:

EventArgumentsFired when
rsg-character:server:characterSelectedsrc, citizenidA character was selected and logged in.
rsg-character:server:characterCreatedsrc, citizenid, cidA new character was created (appearance is saved afterwards).
rsg-character:server:characterDeletedsrc, citizenid, pendingA character was deleted from character select. pending = true when it is only hidden and can still be restored.
rsg-character:server:characterRestoredcitizenid, license, cidA hidden character was restored.
rsg-character:server:characterPurgedcitizenid, licenseA hidden character was removed for good after the grace period.
rsg-character:server:slotsChangedlicense, extraThe extra slots of a license changed (/addslot, /setslots, exports).
rsg-character:server:characterLoggedOutsrc, citizenid/logout or LogoutToCharacterSelect finished.
rsg-character:server:appearanceSavedsrc, citizenid, isNewThe creator saved a skin.
rsg-character:server:appearanceResetcitizenidResetAppearance / /resetskin ran.
rsg-character:server:nameChangedcitizenid, first, lastChangeCharacterName / /changename ran.
rsg-character:server:outfitPurchasedsrc, citizenid, price, outfitNameA clothing purchase completed.
rsg-character:server:outfitSharedsrc, targetSrc, outfitIdAn outfit share was accepted and copied.
-- give a welcome item and a bank account to every new character
AddEventHandler('rsg-character:server:characterCreated', function(src, citizenid, cid)
    exports['rsg-inventory']:AddItem(src, 'bread', 1, nil, nil, 'new-character')
end)

11.6 Callbacks (rsg-core)#

NameSideReturns
rsg-character:server:getAppearanceserver{ skin, clothes } for the caller, or nil.
rsg-multicharacter:server:getAppearanceserverSame, { skin = {}, clothes = {} } when none. Legacy name for older resources.
rsg-character:server:getOutfitsserverThe caller's saved outfits (see GetOutfits).
rsg-character:server:LoadClothesserverThe caller's current clothes table.
rsg-character:server:wearOutfit (id)serverClothes of that outfit (re-validated), or nil. Needs a cloakroom nearby unless WardrobeTarget.enabled.
rsg-character:server:isNameAvailable (first, last)serverboolean. Only answers during a new-character creator session.
rsg-character:server:chooseSpawn (value)server{ x, y, z, w, fromMenu } for last or preset_<n>, or nil when no spawn menu was offered / the choice is invalid. One answer per offered menu.
rsg-character:client:confirmShare (fromName, outfitName)clientboolean; asked of the receiver of an outfit share.
-- client of another resource
local appearance = RSGCore.Functions.AwaitCallback('rsg-character:server:getAppearance')
if appearance then print(appearance.skin.sex == 1 and 'male' or 'female') end

11.7 Net events handled by this resource (internal, do not call)#

Listed for auditing and anti-cheat rules. Every one validates source, arguments and state on the server.

EventValidation
rsg-character:server:RequestCharacterSlotsLogged-out players only.
rsg-character:server:SelectCharacterSlot (citizenid)Logged-out, license must own the citizenid (else the player is dropped), one login at a time.
rsg-character:server:DeleteCharacterSlot (citizenid, typedName)Logged-out, RSG.Delete.Enabled, ownership, not already pending, 3 s cooldown, typed first name when ConfirmName.
rsg-character:server:combatActivityLogged-in players only; only refreshes the caller's own combat timestamp for /logout.
rsg-character:server:RequestCreateCharacterSlot (cid, sex)Logged-out, cid within GetMaxSlots, slot free.
rsg-multicharacter:server:createCharacter (data)Needs a server-opened creator session; name, nationality, birth date, uniqueness and cid re-validated. Event name kept for compatibility.
rsg-character:server:SaveSkin (skin, clothes)Needs a creator session; schema, size and clothing hashes validated; gender taken from the character record.
rsg-character:server:SetPlayerBucketMust be logged in and within 10 m of a store; only undoes buckets this resource set.
rsg-character:server:saveOutfit (clothes, _, name)Near a store, 2 s cooldown, clothes validated, price computed server-side.
rsg-character:server:DeleteOutfit (id)Own, non-default outfits only.
rsg-character:server:ShareOutfit (id, targetSrc)Ownership, distance, same body type, cooldown, receiver must accept.

Internal client events (NUI bridge and scene control, not part of the API): rsg-character:client:ReceiveCharacterSlots, CharSelectFailed, BeginLogout, CharInfoPlay, CharInfoDelete, CharInfoGenderChange, CameraMoveStart, CameraMoveStop, CameraReset.

11.8 Examples#

-- send a player back to character select (e.g. from your own admin menu)
exports['rsg-character']:LogoutToCharacterSelect(targetSrc)
-- jail uniform: wear it, but don't overwrite what they own
local ok, reason = exports['rsg-character']:SetClothes(src, {
    shirts_full = { hash = 123456789 }, -- use a real hash from data/clothing.lua
}, false)
if not ok then print('uniform failed: ' .. reason) end
-- registry office: paid name change
RSGCore.Functions.CreateCallback('myres:server:rename', function(src, cb, first, last)
    local Player = RSGCore.Functions.GetPlayer(src)
    if not Player or not Player.Functions.RemoveMoney('cash', 25, 'rename') then return cb(false, 'no_money') end
    local ok, reason = exports['rsg-character']:ChangeCharacterName(Player.PlayerData.citizenid, first, last)
    if not ok then Player.Functions.AddMoney('cash', 25, 'rename-refund') end
    cb(ok, reason)
end)
-- read a character's saved look from another resource (works offline too)
local look = exports['rsg-character']:GetAppearance(citizenid)
if look then print(('sex=%s'):format(look.skin.sex)) end
-- hand out a themed outfit to a character's wardrobe
local id, reason = exports['rsg-character']:AddOutfit(citizenid, 'Sunday Best', clothesTable)

12. Common tasks#

Change slot count — set RSG.MaxCharacterSlots. Characters in slots above the new limit stay in the DB but won't show.

Move the character select scene — change RSG.CharSelectLocation.coords (and the heading). Tune spacing and camera.height / fov; camera.back is a minimum, the script pushes the camera back to fit all slots. Update RSG.SpawnChecks badSpawn too.

Change starting gear — edit RSG.StarterItems. Items must exist in RSGCore.Shared.Items.

Make clothing free — set every RSG.Price value to 0.

Hide a clothing category from stores — remove it from its RSG.MenuElements section (players can still wear it if it's already in an outfit).

Add a nationality — add a key to RSG.Nationalities and a nationalities.<key> entry to every locale file.

Add wardrobe props — add model names to RSG.WardrobeTarget.models.

Turn off a store blip — showblip = false on that RSG.Zones1 entry.


12b. Admin commands, extra slots, deleted characters and unique names#

  • /charinfo [id], /resetskin [id], /changename [id] [first] [last] (names and permission in RSG.AdminCommands). /resetskin deletes playerskins rows and the Default outfit; the player must /logout (or reconnect) so the creator opens.
  • Extra slots from the database: /addslot [id] [amount], /setslots [id] [extra], /charslots [id] (names and permission in RSG.Slots). Stored per license in playerslots, limited by RSG.Slots.Cap. The player sees the new slots the next time character select opens (/logout). From scripts use exports['rsg-character']:AddExtraSlots(license, amount) (for example from a store webhook handler).
  • Extra slots by ACE: RSG.SlotRules = { { slots = 6, ace = 'rsgchar.slots6' } } and add_ace group.vip rsgchar.slots6 allow. The larger of the ACE value and MaxCharacterSlots + extra applies. Characters stored in a slot above the player's current allowance are hidden, not deleted.
  • Deleted characters: /deletedchars [id] lists characters waiting for deletion (days left), /restorechar [citizenid] restores one into its old slot or the first free slot (no_slot if the player has none free; give them a slot first). Both exist only while RSG.Delete.SoftDelete = true.
  • RSG.UniqueNames compares first + last name through the rsg_character_names table (case-insensitive with the default collation).
  • Names: edit RSG.NameRules. BlockedSubstrings match anywhere in a name, so keep entries long and unambiguous; short words belong in ProfanityWords (whole-name match). ReservedNames blocks full first last combinations.

13. Troubleshooting#

ProblemLikely cause / fix
Black screen or stuck on character selectAnother multicharacter/appearance resource is running, or rsg-character starts before rsg-core/oxmysql. Check F8 and server console.
"Table doesn't exist" errorsRSG.AutoDatabase is false or the database user can't create tables — import install.sql manually.
Can't talk while a menu is openCheck RSG.AllowPushToTalkWhileOpen = true and that your push-to-talk control hash is in RSG.PushToTalkControls.
Players naked or wrong body after loginOld/legacy skin row. Ask them to use /loadskin; if still wrong, delete their playerskins row so the creator opens on next select.
Clothing clipsCategory missing from CLOTHING_ORDER or in the wrong layer.
Webhook warning in consoleCategory enabled but URL still the placeholder. Add a URL or set enabled = false.
Can't create a character: "missing info"Name doesn't match RSG.NameRules (capital first, letters/apostrophe/hyphen, 2–20, not blocked or reserved) or the birth date is outside the age range.
Kicked when selecting a characterThe citizenid doesn't belong to that license (exploit protection) — often caused by license changes (e.g. Steam vs Rockstar).
Creator says the name is takenAnother character already uses that first + last name. Set RSG.UniqueNames = false to allow duplicates.
Extra slots not showingThe ACE isn't granted to the player (add_ace ... rsgchar.slotsN allow), RSG.SlotRules has a different ACE name, or the total hits RSG.Slots.Cap. Slots from /addslot show after the next /logout.
Deleted character is gone from select but still existsIt is in its grace period (/deletedchars). Restore it with /restorechar [citizenid] or wait for the purge. Set RSG.Delete.SoftDelete = false for immediate deletion.
/restorechar says no slotThe license has no free slot (a new character took the old one). Raise the player's slots with /addslot, then restore again.
/logout refusesDead, handcuffed, jailed or in a fight within RSG.Logout.CombatCooldown seconds.
Console: playerskins unique key skippedDuplicate rows exist and RSG.DedupeSkins = false. Remove duplicates or set it to true and restart.
Wardrobe prop does nothingrsg-target not started, or WardrobeTarget.enabled = false.
Spawn card image blankImage path wrong or missing from html/img/spawn/.
Spawn at character select sceneAdd/adjust RSG.SpawnChecks.
No rain after selecting a characterFixed: the select scene sets the rain level to 0.0 (_SET_RAIN 0x193DFC0526830FD6); EndScene now resets it to -1.0 so weather controls rain again.

Enable RSG.Debug = true for extra client console output.


Support development: https://buymeacoffee.com/rexshack


14. Configuration reference#

All options live in shared/config.lua (RSG table). Texts come from locales/*.json.

OptionDefaultDescription
DebugfalseExtra client console output.
AutoDatabasetrueCreate and upgrade the five tables on start; false = import install.sql manually.
AllowPushToTalkWhileOpentrueBlock game controls while a NUI is open, except PushToTalkControls.
PushToTalkControls{ 0x4BC9DABB }Control hashes that stay enabled while the NUI has focus.
DedupeSkinstrueRemove older duplicate playerskins rows when adding the unique key.
NameRulestableMinLength, MaxLength, AllowSpaces, MaxCapitals, ProfanityWords, BlockedSubstrings, ReservedNames. RSG.ProfanityWords is kept as an alias of NameRules.ProfanityWords.
MaxCharacterSlots4Base slots per license.
SlotRules{}{ slots = n, ace = 'name' } entries; highest allowed wins; the larger of this and the database slots applies.
SlotstableCap (8), Permission, Add, Set, Info command names.
DeletetableEnabled, ConfirmName, SoftDelete, GraceDays (7), PurgeInterval (60 min), Restore, List, Permission.
UniqueNamestrueOne character per first + last name.
SpawnMenuWithLastLocationfalseShow the spawn menu (with Last Location) for returning characters.
AdminCommandstableEnabled, Permission, CharInfo, ResetSkin, ChangeName.
OutfitSharingtableEnabled, MaxDistance (m), Cooldown (s), AcceptTimeout (s).
BirthdatetableMin, Max, Default (YYYY-MM-DD), GameYear, MinAge, MaxAge.
LogouttableEnabled, Command, Cooldown (s), BlockWhenDead, BlockWhenCuffed, BlockWhenJailed, CombatCooldown (s).
NationalitieslistLocale keys under nationalities.
StarterItemslist{ item, amount } given once to a new character.
CharSelectLocationtablecoords (vector4), spacing, camera = { back, height, fov }.
WebhookstablePer category (character_created, character_deleted, character_restored, character_selected, character_logout, admin_action, appearance_saved, outfit_purchased): enabled, url, name, avatar, color.
SpawnLocationslistlabel, coords (vector4), image (path under html/).
SpawnCheckstablebadSpawn points, moveTo, Radius.
PrompttableControl hashes used by the creator (gender, confirm, camera, rotate, zoom).
OpenKey / Keybindhash / stringKey that opens the clothing store / cloakroom.
BlipSprite, BlipSpriteCloakRoom, BlipScalenumbersMap blip settings.
SetDoorStatelistStore door hashes and state (0 open, 1 locked).
Zones1listStores: location, blipcoords, fittingcoords, quitcoords, promtcoords, epromtcoords?, showblip.
Cloakroomlist of vector3Cloakroom locations.
WardrobeTargettablersg-target wardrobe props: enabled, distance, icon, label, models.
MenuElementstableWhich clothing categories appear in each store menu section.
PricetableCash price per clothing category.
Texts, LabeltablesLocale-driven UI strings (edit locales/*.json, not these).

15. Changelog#

See CHANGELOG.md.

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-character 3.4.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core

Database#

Tables: playerskins, playeroutfit, playerslots, rsg_character_names, rsg_character_deleted.

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

Exports#

Server

ExportArgumentsFile
GetMaxSlotssrcserver/sv_api.lua
GetExtraSlotslicenseserver/sv_slots.lua
SetExtraSlotslicense, extraserver/sv_slots.lua
AddExtraSlotslicense, amountserver/sv_slots.lua
GetDeletedCharacterslicenseserver/sv_delete.lua
RestoreCharactercitizenidserver/sv_delete.lua
PurgeDeletedCharacters``server/sv_delete.lua
IsInCreatorsrcserver/sv_api.lua
IsNameAvailablefirstname, lastnameserver/sv_api.lua
GetAppearancecitizenidserver/sv_api.lua
ResetAppearancecitizenidserver/sv_api.lua
ChangeCharacterNamecitizenid, firstname, lastnameserver/sv_api.lua
LogoutToCharacterSelectsrcserver/sv_api.lua
SetClothessrc, clothes, saveserver/sv_clothing.lua
AddOutfitcitizenid, name, clothesserver/sv_clothing.lua
GetOutfitscitizenidserver/sv_clothing.lua

Client

ExportArgumentsFile
IsInCharacterSelect``client/charselect.lua
IsCothingActive``client/clothes.lua
GetClothesCachenameclient/clothes.lua
GetClothesComponentIdnameclient/clothes.lua
GetClothesCurrentComponentHashnameclient/clothes.lua
OpenWardrobe``client/clothes.lua
ApplySkinMultiChar``client/creator.lua
GetComponentIdnameclient/creator.lua
GetBodyComponents``client/creator.lua
GetBodyCurrentComponentHashnameclient/creator.lua
SetFaceOverlaystarget, dataclient/creator.lua
SetHairtarget, dataclient/creator.lua
SetBeardtarget, dataclient/creator.lua
GetComponentsMaxnameclient/creator.lua
GetMaxTexturesForModelcategory, model, isClothingclient/creator.lua
ApplySkin``client/creator.lua
IsInCreator``client/creator.lua
-- example
local result = exports['rsg-character']:GetMaxSlots(src)

Callbacks#

CallbackSideArgumentsFile
rsg-character:client:confirmShareclientcb, fromName, outfitNameclient/clothes.lua
rsg-character:server:getAppearanceserversrc, cbserver/sv_appearance.lua
rsg-multicharacter:server:getAppearanceserversrc, cbserver/sv_appearance.lua
rsg-character:server:isNameAvailableserversrc, cb, firstname, lastnameserver/sv_appearance.lua
rsg-character:server:chooseSpawnserversrc, cb, valueserver/sv_appearance.lua
rsg-character:server:wearOutfitserversrc, cb, idserver/sv_clothing.lua
rsg-character:server:LoadClothesserversrc, cbserver/sv_clothing.lua
rsg-character:server:getOutfitsserversrc, cbserver/sv_clothing.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-character:client:confirmShare', 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-character:client:ReceiveCharacterSlotsclientslotsclient/charselect.lua
rsg-character:client:CharSelectFailedclient``client/charselect.lua
rsg-character:client:OpenCharSelectclient``client/charselect.lua
rsg-character:client:BeginLogoutclient``client/charselect.lua
rsg-character:client:ApplyClothesclient``client/clothes.lua
rsg-character:client:outfitsclient``client/clothes.lua
rsg-character:client:OpenCreatorclientdata, emptyclient/creator.lua
rsg-character:client:ApplySkinclientskin, clothesclient/spawn.lua
rsg-character:client:OpenSpawnSelectclientlastPos, isNewCharacterclient/spawn.lua
RSGCore:Client:OnPlayerLoadedclient``client/spawn.lua
rsg-character:server:SetPlayerBucketserver_, randomserver/sv_appearance.lua
rsg-character:server:SaveSkinserverskin, clothesserver/sv_appearance.lua
rsg-multicharacter:server:createCharacterservernewDataserver/sv_appearance.lua
rsg-character:server:RequestCharacterSlotsserver``server/sv_charselect.lua
rsg-character:server:SelectCharacterSlotservercitizenidserver/sv_charselect.lua
rsg-character:server:DeleteCharacterSlotservercitizenid, typedNameserver/sv_charselect.lua
rsg-character:server:combatActivityserver``server/sv_logout.lua
rsg-character:server:RequestCreateCharacterSlotservercid, selectedSexserver/sv_charselect.lua
rsg-character:server:saveOutfitservernewClothes, _, outfitNameserver/sv_clothing.lua
rsg-character:server:DeleteOutfitserveridserver/sv_clothing.lua
rsg-character:server:ShareOutfitserveroutfitId, targetSrcserver/sv_clothing.lua
-- from a client script
TriggerServerEvent('rsg-character:server:SetPlayerBucket', _, random)
-- from a server script
TriggerClientEvent('rsg-character:client:ReceiveCharacterSlots', source, slots)

Commands#

CommandNotesFile
/loadskinclient/creator.lua
/restorechar, /deletedcharsadmin; names in RSG.Deleteserver/sv_delete.lua
/addslot, /setslots, /charslotsadmin; names in RSG.Slotsserver/sv_slots.lua

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 -->