Player customization

SKIN COLOR AND TATTOOS — AVAILABLE FROM UPDATE 0.1.3

The seven skin-color and tattoo functions below are available in G1R:MP 0.1.3 and later. setPlayerIdentity existed earlier; its head and armor handling is improved from update 0.1.3.

Use these server-side Lua functions to combine a named head, a skin-color override and a tattoo preset. Cosmetic changes are independent of armor and gameplay statistics. They work with an equipped armor or an empty armor slot; clothing naturally covers the skin beneath it.

Function reference

Function	Purpose
setPlayerSkinColor(playerId, r, g, b)	Set the skin tint using integer sRGB channels from 0 to 255.
getPlayerSkinColor(playerId)	Read {r = ..., g = ..., b = ...}, or false when unset or unavailable.
resetPlayerSkinColor(playerId)	Restore native skin color without changing the tattoo override.
setPlayerTattoo(playerId, presetKey)	Apply a validated tattoo preset, or "none" to explicitly remove tattoos.
getPlayerTattoo(playerId)	Read the canonical preset key, or false when unset or unavailable.
resetPlayerTattoo(playerId)	Restore native tattoo defaults without changing the skin-color override.
getPlayerTattooNames()	Enumerate all 12 accepted keys; see Player tattoo catalog.

All seven have equivalent PascalCase aliases, for example SetPlayerSkinColor and GetPlayerTattooNames. These aliases are the same APIs, not separate functions in the catalog.

Identity: existing API, improved in 0.1.3

• setPlayerIdentity(playerId, "gorn") selects a named identity. Use "default" to restore the native Nameless Hero identity.
• getPlayerIdentity(playerId) reads the current key; getPlayerIdentityNames() lists supported identities.
• Identity changes preserve equipped armor and the independent skin-color/tattoo overrides.
• Named identities use a head-only visual layer while retaining the game-owned player body and equipment. This is not an NPC's complete body/outfit replacement and is not a body-shape or morph API.
• Update 0.1.3 corrects head publication and material-mask restoration during identity/armor changes, including meshes with more than 64 material slots. The changes address overlapping heads and missing body parts during visual rebuilds.

See Player identity catalog for accepted names. The deprecated setPlayerBody, setPlayerFace and setPlayerHead are not substitutes for the supported identity API. The older setPlayerSkin channel is separate from these RGB and tattoo overrides.

Example

Run this inside an authorized server handler after the player is connected and ready. The API itself does not grant or check a gamemode-specific administrator permission.

-- playerId is the validated target of your authorized handler.
if not setPlayerIdentity(playerId, "gorn") then
    outputDebugString("Identity was rejected")
    return
end
if not setPlayerSkinColor(playerId, 180, 140, 110) then
    outputDebugString("Skin color was rejected")
    return
end
if not setPlayerTattoo(playerId, "lester") then
    outputDebugString("Tattoo was rejected")
    return
end

local color = getPlayerSkinColor(playerId)
if color then
    outputDebugString("RGB: " .. color.r .. ", " .. color.g .. ", " .. color.b)
end
outputDebugString("Tattoo: " .. tostring(getPlayerTattoo(playerId)))

Each setter is independent; this sequence is not one atomic multi-function transaction. Handle a rejected operation according to the resource's own policy.

Reset versus removal

-- Remove tattoos explicitly, even if the native model normally has them:
setPlayerTattoo(playerId, "none")
-- getPlayerTattoo(playerId) now returns "none".

-- Restore the model's native tattoo defaults instead:
resetPlayerTattoo(playerId)
-- getPlayerTattoo(playerId) now returns false.

-- Reset only skin color; this does not change tattoos or identity:
resetPlayerSkinColor(playerId)

-- Reset only identity; this does not clear color/tattoo overrides:
setPlayerIdentity(playerId, "default")

Tattoo reset does not necessarily remove tattoos. It disables the custom override and restores the native defaults. A color getter returning false is not black RGB; it means there is no active override, or the player is unavailable.

Validation and synchronization

• RGB values must be finite integers in the range 0–255. Invalid values are rejected rather than clamped. They are interpreted as sRGB and converted for the native material; final appearance also depends on skin textures, supported material regions and lighting.
• Tattoo keys are case-insensitive and returned in canonical lowercase. Use the exact catalog key without extra whitespace. Unknown keys and arbitrary texture paths are rejected. There is no custom texture upload API.
• Setters return true when the server accepts the authoritative state, not when every client has finished rendering it. Getters read that authoritative state.
• State is reliably sent to the owner and relevant observers, replayed on late join/relevance entry, and reapplied after supported visual rebuilds. These cosmetic functions do not change armor, inventory, HP, mana or progression statistics.
• Color and tattoos are independent. Their resets do not change the other override. Test the exposed face, neck, arms, hands, torso and legs used by your character/armor combinations, including another client's view.
• A custom resource must implement authorization and persistence. The bundled GothicRP resource persists both overrides in its existing appearance_json data. This persistence is a GothicRP feature, not automatic database storage by each Lua API call.

Bundled GothicRP commands

These are resource commands, not additional core Lua functions. They require authentication, admin.players, and RP.Config.testTools.enabled = true. An omitted target means yourself.

Command	Action
/identity gorn [player name or ID]	Change identity; /identity lists choices.
/skincolor 180 140 110 [player name or ID]	Set skin color.
/skincolor reset [player name or ID]	Restore native color.
/tattoo lester [player name or ID]	Set a tattoo preset.
/tattoo none [player name or ID]	Remove tattoos explicitly.
/tattoo reset [player name or ID]	Restore native tattoo defaults.

For optional manual QA, /looktest start or /looktest all saves the cosmetic baseline and starts a sequence; /looktest next advances, and /looktest stop restores it. End an active test before making normal cosmetic edits. The test never equips armor or changes HP/mana; manual armor changes during it are not undone by stopping. /looktest armor only reads live server equipment and resources.

Related pages

• Player tattoo catalog
• Player identity catalog
• Category:Appearance Functions
• Lua API catalogs