QCherry: Document skin color and tattoos available from 0.1.3; identity/armor improvements

2026-09-09T02:32:34Z

Document skin color and tattoos available from 0.1.3; identity/armor improvements

New page

{{DISPLAYTITLE:Player customization}}
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
'''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'''.
</div>

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 ==
{| class="wikitable"
! Function !! Purpose
|-
| [[setPlayerSkinColor]](<code>playerId, r, g, b</code>) || Set the skin tint using integer sRGB channels from 0 to 255.
|-
| [[getPlayerSkinColor]](<code>playerId</code>) || Read <code>{r = ..., g = ..., b = ...}</code>, or <code>false</code> when unset or unavailable.
|-
| [[resetPlayerSkinColor]](<code>playerId</code>) || Restore native skin color without changing the tattoo override.
|-
| [[setPlayerTattoo]](<code>playerId, presetKey</code>) || Apply a validated tattoo preset, or <code>"none"</code> to explicitly remove tattoos.
|-
| [[getPlayerTattoo]](<code>playerId</code>) || Read the canonical preset key, or <code>false</code> when unset or unavailable.
|-
| [[resetPlayerTattoo]](<code>playerId</code>) || 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 <code>SetPlayerSkinColor</code> and <code>GetPlayerTattooNames</code>. These aliases are the same APIs, not separate functions in the catalog.

=== Identity: existing API, improved in 0.1.3 ===
* [[setPlayerIdentity]](<code>playerId, "gorn"</code>) selects a named identity. Use <code>"default"</code> to restore the native Nameless Hero identity.
* [[getPlayerIdentity]](<code>playerId</code>) 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.

<syntaxhighlight lang="lua" line>
-- 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)))
</syntaxhighlight>

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 ==
<syntaxhighlight lang="lua">
-- 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")
</syntaxhighlight>

'''Tattoo reset does not necessarily remove tattoos.''' It disables the custom override and restores the native defaults. A color getter returning <code>false</code> 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 <code>true</code> 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 <code>appearance_json</code> 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, <code>admin.players</code>, and <code>RP.Config.testTools.enabled = true</code>. An omitted target means yourself.

{| class="wikitable"
! Command !! Action
|-
| <code>/identity gorn [player name or ID]</code> || Change identity; <code>/identity</code> lists choices.
|-
| <code>/skincolor 180 140 110 [player name or ID]</code> || Set skin color.
|-
| <code>/skincolor reset [player name or ID]</code> || Restore native color.
|-
| <code>/tattoo lester [player name or ID]</code> || Set a tattoo preset.
|-
| <code>/tattoo none [player name or ID]</code> || Remove tattoos explicitly.
|-
| <code>/tattoo reset [player name or ID]</code> || Restore native tattoo defaults.
|}

For optional manual QA, <code>/looktest start</code> or <code>/looktest all</code> saves the cosmetic baseline and starts a sequence; <code>/looktest next</code> advances, and <code>/looktest stop</code> 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. <code>/looktest armor</code> only reads live server equipment and resources.

== Related pages ==
* [[Player tattoo catalog]]
* [[Player identity catalog]]
* [[:Category:Appearance Functions]]
* [[Lua API catalogs]]

[[Category:Lua Tutorials]]
[[Category:Appearance Functions]]

Player customization - Revision history

QCherry: Document skin color and tattoos available from 0.1.3; identity/armor improvements