SetPlayerIdentity - Revision history

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

2026-09-09T02:32:30Z

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

← Older revision		Revision as of 02:32, 9 September 2026
Line 1:		Line 1:
	= setPlayerIdentity =		= setPlayerIdentity =
	~~Atomically changes~~ a player's ~~complete recognizable appearance without changing~~ armor.		<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
			<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">IMPROVED FROM UPDATE 0.1.3</div>
			<div style="color:#111111; margin-top:0.25rem;">This function is available in earlier releases and has corrected or expanded behavior in G1R:MP 0.1.3 and later. The contract below describes the updated behavior.</div>
			</div>

			Selects a named head/face identity while preserving the player's game body, equipped armor and independent cosmetic overrides.

	== Syntax ==		== Syntax ==
Line 17:		Line 22:

	== Returns ==		== Returns ==
	Returns <code>true</code> when the validated identity ~~is accepted and replicated~~; ~~otherwise~~ returns <code>false</code>.		Returns <code>true</code> when the server accepts the validated identity state; returns <code>false</code> for an unavailable player, invalid key or rejected change. Success is not confirmation that every client has finished rendering it.

	== Examples ==		== Examples ==
	~~Apply~~ Milten's armor~~-free identity~~:		Select Milten's head/face without equipping armor or changing the body:
	<syntaxhighlight lang="lua" line>		<syntaxhighlight lang="lua" line>
	if not setPlayerIdentity(playerId, "milten") then		if not setPlayerIdentity(playerId, "milten") then
Line 29:		Line 34:
	== Notes ==		== Notes ==
	* Available only in server-side resource scripts.		* Available only in server-side resource scripts.
	* ~~In G1R:MP~~ 0.1 ~~this is the only supported setter for~~ a ~~complete player identity. The test command~~ <code>/~~identity <key>~~</code> ~~uses this API~~.		* This existing API has improved behavior in 0.1.3; it was not introduced in that release. Use a key from <code>getPlayerIdentityNames</code>, including <code>default</code> to select the default identity.
	* The face ~~profile~~ and identity ~~surface/hair layer~~ are committed in ~~one authoritative update~~, so ~~clients never observe~~ a ~~half-applied identity~~.		* The client applies a head-only identity layer, including the selected face presentation and supported hair/beard geometry. The current game body and armor remain in place; this does not replace the full body with the named NPC's mesh, texture set, shape or authored skin tone.
	* Equipped armor remains controlled by <code>setPlayerArmor</code>~~; selecting an identity~~ does not equip ~~armor~~.		* The identity layers are committed together in server state. Native asset loading and visual reconstruction are asynchronous, so a successful call does not promise an immediately complete image on every client.
	* ~~Gothic Remake character models and variants are authored with different~~ armor ~~support. Not every identity/armor combination exists or renders correctly~~, ~~so test every combination~~ used by a resource.		* Equipped armor remains controlled independently by <code>setPlayerArmor</code>. This call does not equip or remove items, change HP/progression, or reset <code>setPlayerSkinColor</code>/<code>setPlayerTattoo</code> overrides.
	* ~~The reliable~~ state is replayed ~~during~~ relevance entry and late join.		* Test the identities, armor, exposed skin, materials and LODs used by your resource on local and remote clients; not every authored combination or material permutation is guaranteed to render identically.
	* Accepted changes emit ~~the~~ existing compatibility events for the layers that changed: <code>onPlayerFaceChange</code> and <code>onPlayerBodyChange</code> for the face/body ~~layer~~, and <code>onPlayerHeadChange</code> for the head ~~layer~~.		* Reliable server-owned state is replayed on relevance entry and late join. Resources must perform their own authorization before exposing this setter to player requests.
			* Accepted changes emit existing compatibility events for the layers that changed: <code>onPlayerFaceChange</code> and <code>onPlayerBodyChange</code> for the legacy face/body state, and <code>onPlayerHeadChange</code> for the head state. The legacy body event name does not mean this renderer replaces the player's full body.
			* See [[Player customization]], [[Player identity catalog]] and [[Player tattoo catalog]] for the independent appearance layers and supported catalogs.

	[[Category:Lua Functions]]		[[Category:Lua Functions]]

QCherry: Document 0.1a Lua API, identities, moderation and synchronized spells

2026-08-27T11:36:28Z

Document 0.1a Lua API, identities, moderation and synchronized spells

← Older revision		Revision as of 11:36, 27 August 2026
Line 1:		Line 1:
	~~<!-- This page is generated automatically from the function definition: setPlayerIdentity. -->~~
	= setPlayerIdentity =		= setPlayerIdentity =
	Atomically changes a player's complete recognizable appearance without changing armor.		Atomically changes a player's complete recognizable appearance without changing armor.
Line 30:		Line 29:
	== Notes ==		== Notes ==
	* Available only in server-side resource scripts.		* Available only in server-side resource scripts.
	* ~~This~~ is the ~~recommended appearance~~ setter for ~~normal resources~~.		* In G1R:MP 0.1 this is the only supported setter for a complete player identity. The test command <code>/identity <key></code> uses this API.
	* The face profile and identity surface/hair layer are committed in one authoritative update, so clients never observe a half-applied identity.		* The face profile and identity surface/hair layer are committed in one authoritative update, so clients never observe a half-applied identity.
	* Equipped armor remains controlled ~~exclusively~~ by <code>setPlayerArmor</code>.		* Equipped armor remains controlled by <code>setPlayerArmor</code>; selecting an identity does not equip armor.
	* ~~Some identity profiles still have compatibility issues~~ with ~~specific~~ armor ~~assets~~. ~~Test intended~~ identity ~~and~~ armor ~~combinations before deployment~~.		* Gothic Remake character models and variants are authored with different armor support. Not every identity/armor combination exists or renders correctly, so test every combination used by a resource.
	* The reliable state is replayed during relevance entry and late join.		* The reliable state is replayed during relevance entry and late join.
	* Accepted changes emit the existing <code>onPlayerFaceChange</code>, <code>onPlayerBodyChange</code> and <code>onPlayerHeadChange</code> ~~events~~ for ~~compatibility~~.		* Accepted changes emit the existing compatibility events for the layers that changed: <code>onPlayerFaceChange</code> and <code>onPlayerBodyChange</code> for the face/body layer, and <code>onPlayerHeadChange</code> for the head layer.

	[[Category:Lua Functions]]		[[Category:Lua Functions]]

QCherry: Document Protocol 23 voice and player presentation APIs

2026-08-24T06:13:12Z

Document Protocol 23 voice and player presentation APIs

New page

= setPlayerIdentity =
Atomically changes a player's complete recognizable appearance without changing armor.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerIdentity(int playerId, string identityKey)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>identityKey</code> || <code>string</code> || yes || A stable key returned by <code>getPlayerIdentityNames</code>.
|}

== Returns ==
Returns <code>true</code> when the validated identity is accepted and replicated; otherwise returns <code>false</code>.

== Examples ==
Apply Milten's armor-free identity:
<syntaxhighlight lang="lua" line>
if not setPlayerIdentity(playerId, "milten") then
outputChatBox("The identity could not be applied.", playerId)
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* This is the recommended appearance setter for normal resources.
* The face profile and identity surface/hair layer are committed in one authoritative update, so clients never observe a half-applied identity.
* Equipped armor remains controlled exclusively by <code>setPlayerArmor</code>.
* Some identity profiles still have compatibility issues with specific armor assets. Test intended identity and armor combinations before deployment.
* The reliable state is replayed during relevance entry and late join.
* Accepted changes emit the existing <code>onPlayerFaceChange</code>, <code>onPlayerBodyChange</code> and <code>onPlayerHeadChange</code> events for compatibility.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Player Functions]]
[[Category:Appearance Functions]]