Wiki G1R-MP G1 Remake Multiplayer - User contributions [en]

Main Page

2026-10-20T13:30:30Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

__NOTOC__

<div style="background:#111611; color:#eee7d5; border:1px solid #8f7338; border-top:4px solid #c6a251; padding:1.6rem 1.8rem; margin-bottom:1.25rem;">
<div style="color:#c6a251; font-size:0.78rem; font-weight:bold; letter-spacing:0.08em; text-transform:uppercase;">Gothic 1 Remake Multiplayer</div>
<div style="font-size:2.25rem; font-weight:bold; line-height:1.1; margin:0.25rem 0 0.55rem;">G1R:MP Scripting Wiki</div>
<div style="max-width:58rem; color:#cfc8b8; font-size:1.02rem; line-height:1.55;">Build multiplayer resources and gamemodes with Lua 5.1. This wiki documents the server, client, networking, gameplay, database, and RmlUi APIs exposed by G1R:MP.</div>
<div style="margin-top:1rem; color:#e1c36d; font-size:0.9rem;">Lua 5.1 • server and client resources • authoritative gameplay • RmlUi</div>
</div>

<div style="border:1px solid #b28a3d; border-left:4px solid #b28a3d; background:#faf9f5; padding:0.9rem 1rem; margin:0 0 1.2rem;">
'''Current public release: G1R:MP 0.1.9 / BUILD264 / Protocol 42.''' Windows client and Windows/Linux dedicated servers are available on the [https://g1r-mp.com/download/ Download page]. Update both client and server; Protocol 41 and older cannot join. See [[Update 0.1.9]] for changes and compatibility notes.
</div>


<div style="border:1px solid #6f8461; background:#f5f8f2; padding:0.9rem 1rem; margin-bottom:1.2rem;">
'''New in [[Update 0.1.9|0.1.9]].''' See the guides below for APIs, examples and scope.
* [[Item type stats|Server-controlled item statistics]], jewelry/consumables/rune settings and positive-mana casting recovery.
* [[Armor upgrades|Armor bases, upgrade pieces and full sets]]; [[Female identities|corrected female identities]].
* [[Activity animations|844 added activity aliases and fishing]] (962 total), with the [[Activity animation catalog|complete list]].
* [[Interactive map objects|94 editor prefabs]], [[World model removal|original-world inspection/removal]], shared placed doors and [[Custom keys|custom native keys with server APIs/callbacks]].
* [[Native crafting UI|Crafting-window visibility]] and [[Weather|extended weather]] with the [[Weather catalog|43-setting catalog]].
* [[Discord Rich Presence|Optional Discord Rich Presence]]: eight server Lua functions, status callback and [[Discord Presence configuration|server-owner configuration]], from 0.1.9.
See each guide for availability, current limits and remaining visual qualification.
</div>

[[Armor upgrades|Also available from 0.1.9: armor upgrade slots and full sets]], with the [[Armor catalog|26-base catalog]], [[Armor upgrade catalog|84-part catalog]] and eight server Lua functions.


<div style="border:1px solid #6f8461; background:#f5f8f2; padding:0.9rem 1rem; margin-bottom:1.2rem;">
'''Also available since [[Update 0.1.8|0.1.8]].''' [[Character dimensions]] for players, NPCs and monsters: six server-side Lua functions, three events and private character-creator examples. Also includes UI rendering fixes and automatic completion of multiplayer loading screens when loading is finished.
</div>



<div style="border:1px solid #b89a50; padding:0.85rem 1rem; margin:1rem 0;">
'''Also available (since [[Update 0.1.7|0.1.7]]).''' [[Native HUD and menus]]: 5 client Lua functions and a result event, resource-owned HUD/menu control and multiplayer save/load protection. [[Game audio|Built-in game audio]]: 11 client functions and a result event. [[Server TTS|Optional server TTS]]: 33 server functions and 4 events, reusable recordings and remote 3D/NPC speech. English guides: [[TTS configuration|Windows/Linux setup]] and [[TTS voices|own/downloaded voice samples and presets]]. Also: NPC crowd optimizations, melee skill tiers, remote acrobatics, climbing/ladder transitions, torch synchronization, identity accessory and gate-streaming fixes.
</div>



<div style="border:1px solid #6f8461; background:#f5f8f2; padding:0.9rem 1rem; margin-bottom:1.2rem;">
'''Also included (since [[Update 0.1.6|0.1.6]]).''' Four new server-side functions: [[Area notifications|custom area notifications]] and [[Mounts|player-owned rideable scavengers]]. Also includes mounted nameplate/recovery fixes, smoother ordinary doors and pickup performance/animation improvements. See the guides for remaining in-game validation.
</div>


<div style="border:1px solid #6f8461; background:#f5f8f2; padding:0.9rem 1rem; margin-bottom:1.2rem;">
'''Also included (since [[Update 0.1.5|0.1.5]]).''' [[NPC scripting|NPC combat and scripting]], walk/run pursuit, identity, skin colour, tattoos, player weapon modes and events. Also includes crouch synchronization, melee presentation and knockdown recovery improvements.
</div>

<div style="border:1px solid #6f8461; background:#f5f8f2; padding:0.9rem 1rem; margin-bottom:1.2rem;">
'''Also included (since [[Update 0.1.4|0.1.4]]).''' See [[MySQL connection recovery]], [[Weapon control]], [[Mouse capture]], [[UpdateCameraPose]], [[Map editor]], [[World objects]] and [[Player animation catalog|118 player animations]] for released tools and scripting APIs. Also see [[RmlUi images|WebP images]], [[os.time]] and [[getEventClient|remote event security]].
</div>

<div style="display:flex; flex-wrap:wrap; gap:1rem; margin-bottom:1rem;">
<div style="flex:1 1 22rem; border:1px solid #c9c2b2; border-left:4px solid #b28a3d; padding:1rem 1.15rem; background:#faf9f5;">
<div style="font-size:1.35rem; font-weight:bold; margin-bottom:0.45rem;">Start here</div>
<div style="color:#555; margin-bottom:0.6rem;">Find the right entry point for your first resource.</div>
<ul style="margin:0.35rem 0 0 1.25rem; line-height:1.75;">
<li>[[:Category:Lua API|Lua API overview]]</li>
<li>[[:Category:Lua Functions|Complete function catalog]]</li>
<li>[[Lua events|Complete event and callback catalog]]</li>
<li>[[Scripting limits|Lua, resource and API limits]]</li>
<li>[[Lua API catalogs|Validated skin, monster, equipment, and gameplay keys]]</li>
<li>[[NPC and monster navigation collision|NPC and monster navigation collision]]</li>
<li>[[Client audio|Client audio and synchronized 3D playback]]</li>
<li>[[Game audio|Built-in game audio (since 0.1.7)]]</li>
<li>[[Game dialogue catalog|Complete dialogue catalog (since 0.1.7)]]</li>
<li>[[Server TTS|Server TTS (since 0.1.7)]] — [[TTS configuration|setup]] · [[TTS voices|voice samples and presets]]</li>
<li>[[Native HUD and menus|Native HUD/menu control and custom key bindings]]</li>
<li>[[Scripted camera|Scripted camera and moving login backgrounds]]</li>
<li>[[Map editor|Map editor: controls, save and reopen (0.1.4)]]</li>
<li>[[Interactive map objects|Interactive seats and lights (since 0.1.9)]]</li>
<li>[[Item type stats|Item statistics and armor protection (since 0.1.9)]]</li>
<li>[[Map scene deployment|Load exported objects for players (0.1.4)]]</li>
<li>[[Player animation catalog|Player animations: work, sitting, sleep and gestures (expanded in 0.1.4)]]</li>
<li>[[Player customization|Identity, skin color and tattoos]]</li>
<li>[[Character dimensions|Character dimensions and private creators (since 0.1.8)]]</li>
<li>[[Chapter screens|Custom chapter title cards]]</li>
<li>[[Area notifications|Custom area notifications (since 0.1.6)]]</li>
<li>[[Mounts|Rideable scavengers and ownership (since 0.1.6)]]</li>
<li>[[Observer nameplates|Observer-specific labels and acquaintance presentation]]</li>
<li>[[:Category:Resource Functions|Resource lifecycle functions]]</li>
<li>[[:Category:Lua Examples|Lua examples]]</li>
<li>[[Hosting a G1R:MP dedicated server|Hosting a dedicated server]]</li>
<li>[[Known issues|Known issues and GPU crash workarounds]]</li>
<li>[[:Category:Experimental Lua API|Experimental API status]]</li>
</ul>
</div>

<div style="flex:1 1 22rem; border:1px solid #c9c2b2; border-left:4px solid #6f8461; padding:1rem 1.15rem; background:#faf9f5;">
<div style="font-size:1.35rem; font-weight:bold; margin-bottom:0.45rem;">Reference by execution side</div>
<div style="color:#555; margin-bottom:0.6rem;">Check where a function is available before using it.</div>
<ul style="margin:0.35rem 0 0 1.25rem; line-height:1.75;">
<li>[[:Category:Server Functions|Server-side functions]]</li>
<li>[[:Category:Client Functions|Client-side functions]]</li>
<li>[[:Category:Audio Functions|Audio functions (client / server)]]</li>
<li>[[:Category:Shared Functions|Shared functions]]</li>
<li>[[:Category:Server Events|Server-side events]]</li>
<li>[[:Category:Client Events|Client-side events]]</li>
<li>[[:Category:Event Functions|Event functions]]</li>
<li>[[:Category:Network Functions|Network functions]]</li>
</ul>
</div>
</div>

<div style="display:flex; flex-wrap:wrap; gap:1rem; margin-bottom:1rem;">
<div style="flex:1 1 22rem; border:1px solid #c9c2b2; padding:1rem 1.15rem; background:#fff;">
<div style="font-size:1.25rem; font-weight:bold; border-bottom:1px solid #ded8ca; padding-bottom:0.45rem; margin-bottom:0.6rem;">Gameplay</div>
<div style="display:grid; grid-template-columns:repeat(auto-fit,minmax(10rem,1fr)); gap:0.4rem 1rem; line-height:1.65;">
<div>[[:Category:Player Functions|Players]]</div>
<div>[[:Category:Spatial Functions|Position and spawn]]</div>
<div>[[:Category:Progression Functions|Progression]]</div>
<div>[[:Category:Inventory Functions|Inventory]]</div>
<div>[[:Category:Equipment Functions|Equipment]]</div>
<div>[[:Category:Magic Functions|Magic]]</div>
<div>[[:Category:Life State Functions|Health and life state]]</div>
<div>[[:Category:World Functions|World time and weather]]</div>
<div>[[:Category:Monster Functions|Monsters]]</div>
<div>[[:Category:Navigation Functions|AI navigation]]</div>
<div>[[:Category:Interaction Functions|Interactions]]</div>
</div>
</div>

<div style="flex:1 1 22rem; border:1px solid #c9c2b2; padding:1rem 1.15rem; background:#fff;">
<div style="font-size:1.25rem; font-weight:bold; border-bottom:1px solid #ded8ca; padding-bottom:0.45rem; margin-bottom:0.6rem;">Scripting systems</div>
<div style="display:grid; grid-template-columns:repeat(auto-fit,minmax(10rem,1fr)); gap:0.4rem 1rem; line-height:1.65;">
<div>[[:Category:GUI Functions|RmlUi and GUI]]</div>
<div>[[:Category:Database Functions|Database]]</div>
<div>[[MySQL connection recovery|Connection recovery (0.1.4)]]</div>
<div>[[:Category:Timer Functions|Timers]]</div>
<div>[[:Category:Command Functions|Commands]]</div>
<div>[[:Category:Chat Functions|Chat]]</div>
<div>[[:Category:Animation Functions|Animations]]</div>
<div>[[Client audio|Client audio and OGG playback]]</div>
<div>[[:Category:Camera Functions|Camera]]</div>
<div>[[Lua events|Events and callbacks]]</div>
</div>
</div>
</div>

== Your first server script ==

The following example welcomes a joining player and places them at an authoritative spawn point:

<syntaxhighlight lang="lua" line>
addEventHandler("onPlayerJoin", root, function(playerId)
setPlayerName(playerId, "Newcomer")
spawnPlayer(playerId, 12.0, 24.0, 2.0, 90)
outputChatBox("Welcome to G1R:MP!", playerId, 225, 195, 110)
end)
</syntaxhighlight>

See [[onPlayerJoin]], [[AddEventHandler|addEventHandler]], [[SetPlayerName|setPlayerName]], [[SpawnPlayer|spawnPlayer]], and [[OutputChatBox|outputChatBox]] for parameter details and additional examples.

<div style="display:flex; flex-wrap:wrap; gap:1rem; margin-top:1.25rem;">
<div style="flex:1 1 22rem; border-top:3px solid #b28a3d; background:#f5f2e9; padding:1rem 1.15rem;">
<div style="font-size:1.2rem; font-weight:bold; margin-bottom:0.4rem;">Community</div>
<ul style="margin:0.35rem 0 0 1.25rem; line-height:1.7;">
<li>[https://g1r-mp.com/ G1R:MP website]</li>
<li>[https://g1r-mp.com/forum/ Community forum]</li>
<li>[https://g1r-mp.com/forum/member.php?action=profile&uid=1 Project lead: QCherry]</li>
</ul>
</div>

<div style="flex:1 1 22rem; border-top:3px solid #6f8461; background:#f5f2e9; padding:1rem 1.15rem;">
<div style="font-size:1.2rem; font-weight:bold; margin-bottom:0.4rem;">Documentation status</div>
<div style="line-height:1.6;">Browse functions and events by topic above. Each API page identifies its version and execution side. See [[Update 0.1.9]] for the current release and [[Update 0.1.8]] for the previous release. APIs marked [[:Category:Experimental Lua API|experimental]] may change. Historical release notices remain on their dedicated reference pages.</div>
</div>
</div>

[[Category:Lua API]]

WorldObjects.request

2026-10-20T13:30:23Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= WorldObjects.request =
'''Since 0.1.4.'''

'''Client Functions.'''

<syntaxhighlight lang="lua">
requestIdOrFalse = WorldObjects.request(command)
</syntaxhighlight>

Submits a validated command table. Returns a numeric request ID or false; a request ID is not completion. See the full command schemas, result JSON, limits and lifecycle below.

See [[World objects]] for parameters, examples, failure handling and limits.
[[Category:Lua API]]
[[Category:Client Functions]]
[[Category:Lua Functions]]


== Original world model operations from 0.1.9 ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[World model removal#Developer API and diagnostics|World model removal]] documents world_pick, world_nearby, world_select, world_set and world_restore_all, layer ownership and result handling. Existing create/delete operations still concern the caller's own static objects. Original-world hiding is reversible and does not edit terrain or NPC obstacle maps. A native live layer is not server authorization/replication: use trusted server state and the supplied editor/deployment workflow. Shared placed doors instead use server [[setWorldDoors]].

World objects

2026-10-20T13:30:20Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= World objects =
'''Client-side; since 0.1.4.'''

[[WorldObjects.request]] submits asynchronous commands for resource-owned static meshes. It is generic gameplay-resource API, not restricted to the map editor. There is no engine global named CreateModel or MapEditor.CreateObject; [[MapEditor helpers|MapEditor helpers]] are Lua functions inside the editor resource only.

== Function and events ==
<syntaxhighlight lang="lua">
requestIdOrFalse = WorldObjects.request(command)
-- Events on the calling resource:
-- onClientWorldObjectResult(requestId, ok, reason, json)
-- onClientWorldObjectsReset()
</syntaxhighlight>

Supply a table. A numeric request ID means '''queued''', not spawned/applied. <code>false</code> means immediate validation/readiness/capacity/IPC rejection. Match the ID in [[onClientWorldObjectResult]] before committing Lua state. The result's JSON argument is a '''string'''; decode it with <code>fromJSON</code>. Never expose native pointers to Lua.

== Commands ==
{| class="wikitable"
! op !! Required fields and effect
|-
| create || <code>id, mesh, x,y,z, pitch,yaw,roll, sx,sy,sz, hidden,collision,selected</code>. Creates a new instance; an existing ID fails with id-already-exists.
|-
| update || <code>id</code>, all nine transform numbers and all three booleans. Updates an existing instance. '''Full state, not a partial patch.''' Does not replace the mesh: delete/create to change the asset.
|-
| delete || <code>id</code>. Removes the caller's instance; an absent ID also succeeds.
|-
| clear || Only <code>op</code>. Removes the caller's created instances; from 0.1.9 also releases its original-world removal claims. It never destroys original world actors or releases another resource's claims.
|-
| pick || <code>op</code>. Traces from the native player-controller view through the OS cursor, up to 1000 m. Requires usable game focus/viewport.
|-
| raycast || <code>x,y,z,tx,ty,tz</code>, start and end in metres, length at most 1000 m.
|-
| lease || Only <code>op</code>. Registers/renews ownership without creating a mesh; the host also renews ownership automatically.
|}

Object IDs: 1-64 ASCII letters, digits, underscores or hyphens, scoped to the calling resource. Mesh must be a valid installed static-mesh object path like <code>/Game/Directory/Asset.Asset</code>, at most 512 characters, not an OBJ filename or filesystem path. The editor additionally restricts choices to its shipped catalog. A syntactically valid path can still fail to load.

Position: metres, each coordinate +/-100000. Rotation: pitch/yaw/roll in degrees, each +/-36000. Scale: sx/sy/sz in [0.01,100]. All numbers must be finite. The three booleans are required even when false. <code>selected</code> requests custom-depth selection presentation; it does not guarantee an outline without matching post-processing. Names and editor locks belong to the Lua document, not the native command schema.

== Result contract ==
Successful mutations return JSON containing their <code>id</code>; clear/lease return an empty JSON object. Successful traces return <code>{"hit":false}</code> or a hit containing <code>hit,x,y,z,nx,ny,nz,id</code>. The coordinates are metres, normals unitless. A hit ID is populated only for a recognized object owned by the caller; it is empty for ordinary world surfaces or unrecognized/foreign instances. Do not access hit coordinates when hit=false. Traces depend on collision; use the editor hierarchy to select non-colliding objects.

Typical failure reasons include <code>world-not-ready</code>, <code>native-dependencies-pending</code>, <code>mesh-load-or-spawn-failed</code>, <code>id-already-exists</code>, <code>owner-limit</code>, <code>object-invalid-or-transform-failed</code> and <code>raycast-unavailable</code>. The former fixed-count <code>object-limit</code> failure is removed in BUILD124. An unanswered host request reports <code>native-timeout</code> after 10 seconds. A timeout does not prove a mutation was never applied: do not blindly retry it. Reconcile/reload the owned scene.

== Example: complete create command ==
<syntaxhighlight lang="lua">
function requestMesh(meshPath, x, y, z)
return WorldObjects.request({
op="create", id="example_rock", mesh=meshPath,
x=x, y=y, z=z, pitch=0, yaw=0, roll=0,
sx=1, sy=1, sz=1,
hidden=false, collision=true, selected=false
})
end
-- Supply an actual installed mesh path and your desired coordinates.
-- Call after gameplay readiness; wait for onClientWorldObjectResult.
-- Reusing example_rock while it exists fails: assign unique IDs per instance.
</syntaxhighlight>

== Example: asynchronous deletion ==
<syntaxhighlight lang="lua">
local pending = {}
addEventHandler("onClientWorldObjectResult", resourceRoot,
function(requestId, ok, reason, json)
local id = pending[requestId]
if not id then return end
pending[requestId] = nil
if ok then
outputDebugString("Deleted owned object: " .. id)
else
outputDebugString("Delete not confirmed: " .. tostring(reason), 1)
end
end)

function deleteOwnedObject(id)
local requestId = WorldObjects.request({op="delete", id=id})
if not requestId then return false end
pending[requestId] = id
return true -- accepted only; completion is handled above
end
</syntaxhighlight>

For full scene creation, use the supplied <code>map_scene/client.lua</code> loader and [[Map scene deployment]]. It includes startup readiness retries and reconstruction, which a one-shot on-start create call would miss.

== Lifetime, limits and multiplayer ==
'''No fixed instance-count, pending-request-count or requests/second cap in this API since BUILD124 (0.1.4).''' The former 512 instances, 32 pending requests and 80 requests/second checks have been removed, not replaced with higher count caps. The editor and map_scene loader likewise no longer impose 500 objects.

Commands still encode to at most 4096 bytes and at most 16 owning resources are supported. Shared IPC transport queues remain bounded (256 frames per queue); a full queue can cause immediate request rejection even though the WorldObjects-specific pending-count ceiling is gone. Check false returns, pace submissions and await completion. Do not submit an entire huge scene in a tight loop: native mesh loading/creation runs on the game thread. The supplied loader continues to load sequentially. RAM/VRAM/CPU, asset complexity, Lua/resource memory and JSON document limits remain practical bounds, not a guarantee of unlimited performance.

The native ownership lease is 15 seconds and the host sends renewals every second. Stop/disconnect/world changes clear owned instances. Handle [[onClientWorldObjectsReset]] to discard stale IDs/pending state and reconstruct deliberately; the event has no arguments. Readiness, ownership, duplicate-ID checks, validation and timeout/cleanup safety have not been removed.

This API creates client-local static actors, not synchronized interactive doors, inventory items, server collision geometry or networked physics. Sending the same trusted static map resource to every player, as map_scene does, reconstructs the same layout for late joiners. Dynamic multiplayer edits require their own server-authorized state distribution.
[[Category:Lua API]]


== Original world model operations from 0.1.9 ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[World model removal#Developer API and diagnostics|World model removal]] documents world_pick, world_nearby, world_select, world_set and world_restore_all, layer ownership and result handling. Existing create/delete operations still concern the caller's own static objects. Original-world hiding is reversible and does not edit terrain or NPC obstacle maps. A native live layer is not server authorization/replication: use trusted server state and the supplied editor/deployment workflow. Shared placed doors instead use server [[setWorldDoors]].

World model removal

2026-10-20T13:30:18Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= World model removal =
'''Available from 0.1.9.''' The [[Map editor]] can inspect and reversibly hide supported original world objects, then publish a saved removal set to players. This does not destructively edit the installed map.

== Inspect and select ==
# Open your authorized editor session and scroll to '''Original world objects'''. Click '''Inspect world / edit objects''', then click the model in the viewport.
# The inspector shows the object/component class, model, position/transform when available, provenance, selection status and persistent placement ID. The ID field can be selected/copied.
# If several models overlap, select the exact candidate from the list. Use '''Nearby (50 m)''' for loaded models that cannot be reached by a collision trace, including some bushes/decorations. Allow the initial bounded scan to finish, then refresh if needed.
# Click '''Hide model (preview)''' and confirm. It affects your local preview only. Use Undo/Redo or the removed-model list to restore it.

Supported adapters cover eligible standalone environment models, individual grouped decoration/foliage instances, authored doors, lights, interactive objects and ladders. A ladder is selected as one whole object, not separate rungs. A successful group selection does not authorize hiding all its neighbours. Group highlighting is deliberately limited to avoid highlighting unrelated models.

Characters, terrain, world controllers and baked distant HLOD aggregates remain protected. An unresolved/ambiguous target must be inspected or selected more precisely; the editor does not guess a nearby replacement. This is not a promise that every engine object can safely be deleted.

== Preview, save and apply ==
{| class="wikitable"
! Action !! Effect
|-
| Hide/restore preview || Only this editor's local presentation changes; other players keep their current live state.
|-
| Save / Open || Stores/loads the draft and removal IDs. Save alone does not publish anything.
|-
| Apply removals + doors LIVE || Replaces the editor resource's entire saved live removal list and placed-door set for everyone, then closes the local editor. Static additions are not deployed by this button.
|-
| Clear live removals + doors || Releases this resource's live removals '''and removes its placed doors'''. Other resources' objects/claims are not cleared.
|-
| Export Lua / map_scene || Deploys supported saved data using the complete updated [[Map scene deployment|map_scene]] resource. Do not run the same map through both live editor deployment and map_scene.
|}

Save first and wait for acknowledgement before Apply LIVE. Applying another saved map replaces the current editor-owned live set rather than merging it. Concurrent stale revisions are rejected; refresh and deliberately reconfirm. A map containing non-door interactive prefabs cannot be deployed through this live door path: seats, lights and placed ladders still have local native tests only.

Closing the editor releases preview, not the saved live set. If an object remains hidden after local restoration, another preview/live owner may still request its removal. Owners combine; releasing one does not override another.

== Identity, restart and streaming ==
Placement IDs are derived from the authored world placement and validated model/layout, not a transient runtime index. Generated world-cell names displayed in the inspector are not names you should invent or rename. IDs are intended to survive unload/reload and restart with the '''same supported game data'''.

Version-3 documents store <code>catalog</code> and <code>removals</code> separately from newly placed objects. Catalog/layout mismatches after game-data changes are rejected rather than silently hiding a different model. Reinspect and migrate deliberately after such an update; persistence is not a guarantee across arbitrary game versions.

Server storage under <code>resources/map_editor/.storage</code> includes <code>data-map_NAME.json</code> for drafts and <code>data-world_applied.json</code> for the saved live removal/door set. Atomic writes retain a previous backup generation. Back up this directory before replacing resources. Starting the editor resource again reapplies its saved live set. Door placements return, but door open/closed state starts closed after resource/server restart; that transient state is not a durable door-state journal.

Only matching loaded world cells are altered. The system does not force distant cells to load or keep the whole world resident. The desired removal remains recorded and is applied when the placement is encountered again; joining clients receive the live list. This still requires representative streaming/late-join tests on your map.

== Collision, interactions and performance ==
Removal hides the selected object's supported visuals and its own collision. Authored interactive adapters also suppress the associated interaction and relevant light/fire/audio presentation. Busy interactions wait for native release and a short exit-settle period rather than interrupting an occupied object. Restoration respects previously disabled states and current synchronized fire state.

Grouped models may require rebuilding their shared render/collision component when the removal set changes. This is not a rebuild every frame, but a large group can still hitch. First-use asset loading and bounded nearby scanning also have costs. Check adjacent models, collision and restoration when using a new group type.

'''The server NPC/monster obstacle map is intentionally not changed.''' Server authors must update their own obstacle/navigation data if their layout needs it. Baked lighting/shadows and distant HLOD representations are not regenerated, so a distant baked representation can remain visible. No map-file deletion, mesh-wide replacement or arbitrary runtime-object destruction API is provided.

== Developer API and diagnostics ==
The editor uses the existing client [[WorldObjects.request]] channel with these additional commands:
{| class="wikitable"
! op !! Additional fields / behavior
|-
| <code>world_pick</code> || None; inspect the original world under the cursor.
|-
| <code>world_nearby</code> || <code>x,y,z,offset</code>; finite metre coordinates in +/-100000 and integer pagination offset 0..1000000. Lists loaded nearby candidates.
|-
| <code>world_select</code> || <code>id</code>; approved placement ID, or empty string to deselect.
|-
| <code>world_set</code> || <code>id,catalog,layer,hidden</code>; exact compatible catalog, approved placement ID, layer <code>preview</code> or <code>live</code>, boolean hidden. No transform or arbitrary class/path is accepted.
|-
| <code>world_restore_all</code> || <code>layer</code>; release the calling resource's claims in that layer only.
|}
The layer name <code>live</code> is local native bookkeeping, '''not server permission or automatic replication'''. Use the supplied trusted server/resource workflow for global changes. Do not accept arbitrary client-provided removal sets, identities or permission claims.

Request IDs mean queued. Match [[onClientWorldObjectResult]]; its JSON can describe accepted/pending reconciliation, not necessarily already invisible geometry. Handle [[onClientWorldObjectsReset]] and reapply authoritative state. Missing, unsafe or changed native contracts fail instead of reporting completed removal.

Repeated selected grouped-object hide/restore has been confirmed in game; all object classes, occupied cases, collision, streaming and two-client combinations have not been individually certified. Test your actual map, save/restart, restore and a late join before production use.

[[Category:Lua API]]
[[Category:Lua Tutorials]]

World door prefab catalog

2026-10-20T13:30:17Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

'''Available from 0.1.9. Use matching updated server and clients.'''

7 approved door aliases for [[setWorldDoors]]. Query [[getWorldDoorPrefabs]] for the running server. Each uses original native scale and collision; this is not the static mesh catalog. Not every alias has individual in-game visual qualification.

* <code>io_oc_room_door</code>
* <code>io_mf_room_door</code>
* <code>io_nc_mages_door</code>
* <code>io_merchant_door</code>
* <code>io_prison_door</code>
* <code>io_prison_door_02</code>
* <code>io_xt_door</code>

[[Category:Lua catalogs]]

Weather catalog

2026-10-20T13:30:16Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= Weather catalog =
'''Available from 0.1.9. Use matching updated clients and server.'''

All 43 canonical settings exposed by [[getWeatherTypes]] in 0.1.9: five original biome-aware modes and 38 explicit game presets. See [[Weather]] for Lua, configuration, synchronization and qualification. A catalog entry is not individual in-game visual certification.

{| class="wikitable sortable"
! Canonical name !! Family
|-
| <code>sunny</code> || Native biome
|-
| <code>rain1</code> || Native biome
|-
| <code>rain2</code> || Native biome
|-
| <code>rain3</code> || Native biome
|-
| <code>cloudy</code> || Native biome
|-
| <code>snow1</code> || Snow
|-
| <code>snow2</code> || Snow
|-
| <code>snow3</code> || Snow
|-
| <code>foggy</code> || Sky / fog / rain
|-
| <code>partly_cloudy</code> || Sky / fog / rain
|-
| <code>overcast</code> || Sky / fog / rain
|-
| <code>clear_skies</code> || Sky / fog / rain
|-
| <code>cloudy_global</code> || Sky / fog / rain
|-
| <code>rain_light_global</code> || Sky / fog / rain
|-
| <code>rain_global</code> || Sky / fog / rain
|-
| <code>thunderstorm</code> || Sky / fog / rain
|-
| <code>sandstorm1</code> || Sand / dust
|-
| <code>sandstorm2</code> || Sand / dust
|-
| <code>sandstorm3</code> || Sand / dust
|-
| <code>desert_sunny</code> || Desert
|-
| <code>desert_cloudy</code> || Desert
|-
| <code>forest_sunny</code> || Forest
|-
| <code>forest_cloudy</code> || Forest
|-
| <code>forest_rain1</code> || Forest
|-
| <code>forest_rain2</code> || Forest
|-
| <code>forest_rain3</code> || Forest
|-
| <code>upland_sunny</code> || Upland
|-
| <code>upland_cloudy</code> || Upland
|-
| <code>upland_rain1</code> || Upland
|-
| <code>upland_rain2</code> || Upland
|-
| <code>upland_rain3</code> || Upland
|-
| <code>wetland_sunny</code> || Wetland
|-
| <code>wetland_cloudy</code> || Wetland
|-
| <code>wetland_rain1</code> || Wetland
|-
| <code>wetland_rain2</code> || Wetland
|-
| <code>wetland_rain3</code> || Wetland
|-
| <code>tundra_sunny</code> || Tundra
|-
| <code>tundra_cloudy</code> || Tundra
|-
| <code>tundra_snow1</code> || Tundra
|-
| <code>tundra_snow2</code> || Tundra
|-
| <code>tundra_snow3</code> || Tundra
|-
| <code>orccity_dust2</code> || Orccity
|-
| <code>orccity_dust3</code> || Orccity
|}

== Aliases ==
Names are case-insensitive. [[getWeather]] and callbacks return the canonical name, not the alias supplied by the caller.
{| class="wikitable"
! Alias !! Canonical name
|-
| clear || sunny
|-
| clouds || cloudy
|-
| light_rain || rain1
|-
| rain || rain2
|-
| storm || rain3
|-
| snow, snow_normal || snow2
|-
| snow_light || snow1
|-
| blizzard, snow_blizzard || snow3
|-
| fog || foggy
|-
| sandstorm, dust || sandstorm2
|}
The original aliases keep their biome-dependent meaning. Use <code>thunderstorm</code> for the explicit global preset, not <code>storm</code>. These are names, not raw asset paths or stable numeric indices. Snow coverage depends on compatible world materials.
[[Category:Lua catalogs]]

Weather

2026-10-20T13:30:14Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= Weather =
'''Extended presets and getWeatherTypes are available from 0.1.9.''' Existing weather/time functions remain available in earlier releases with their earlier catalog. Use matching updated server and clients.

== Available weather ==
[[Weather catalog]] lists '''43 canonical settings''': the original five biome-aware modes and 38 explicit presets provided by the game. These include light/normal snow, blizzard, fog, clouds, rain/thunderstorm, sand/dust storms and regional variations. They are not 43 different precipitation effects.

<code>sunny</code>, <code>cloudy</code>, <code>rain1</code>, <code>rain2</code> and <code>rain3</code> keep the native biome-dependent behavior. Explicit presets select their settings independently of that automatic biome choice. Returning to a legacy name releases the explicit override. No game assets or map files are edited.

== Server Lua ==
{| class="wikitable"
! Function !! Purpose
|-
| [[getWeatherTypes]] || New in 0.1.9: fresh array of supported canonical names.
|-
| [[setWeather]] || Select server weather, optionally with transition milliseconds.
|-
| [[getWeather]] || Read the canonical server target, not the client's rendered image.
|-
| [[getWeatherRevision]] / [[getWeatherTransitionDuration]] || Inspect authoritative revision and requested transition duration.
|-
| [[getPlayerWeatherSync]] || Inspect one client's latest acknowledgement and freshness.
|}

Run these calls in trusted server resource code, after applying your own administration/gameplay permissions:
<syntaxhighlight lang="lua">
local modes = getWeatherTypes()
for _, name in ipairs(modes) do
outputDebugString(name)
end

-- Choose one when your gameplay requires it:
local accepted = setWeather("snow2", 5000)
if not accepted then
outputDebugString("Weather change rejected")
end
-- Later: setWeather("foggy", 3000)
-- Later: setWeather("sandstorm3", 3000)
-- Restore biome weather: setWeather("sunny", 0)
</syntaxhighlight>

The optional transition is an integer from 0 to 300000 milliseconds, default 3000; zero requests immediate application. Names are case-insensitive and aliases normalize to canonical names. Unknown names and arbitrary asset paths are rejected. A true return means server acceptance, not completed client rendering. Avoid competing weather timers in different resources: there is one global server weather target, not separate player/dimension weather.

== Callback ==
The existing [[onWeatherChange]] event includes the new canonical names without a new signature:
<syntaxhighlight lang="lua">
addEventHandler("onWeatherChange", root,
function(previousWeather, currentWeather, transitionMs, sourceName)
outputDebugString(previousWeather .. " -> " .. currentWeather)
end)
</syntaxhighlight>
This is a server notification after acceptance, not a client transition-completion event. Lua changes identify their resource; administrative changes use their administrative source.

== Configuration and console ==
In the server configuration:
<syntaxhighlight lang="ini">
[world]
weather=snow2
weatherTransitionMs=5000
</syntaxhighlight>
Use the same canonical names or aliases in the existing server console/RCON command:
<pre>weather list
weather snow3 5000
weather sunny 0</pre>
These are administrative console commands, not automatically installed player chat commands. Examples do not grant players permission to change the weather.

== Synchronization and transitions ==
The existing reliable world-environment synchronization is retained. Connected clients receive the target; joining clients apply the current target directly instead of replaying an obsolete transition. Explicit-preset transitions blend cloud, precipitation, lightning, wind, fog, dust and supported surface-coverage settings. Changing to a different preset mid-transition starts from the current blend; repeated snapshots of the same target do not restart it. Returning to a legacy mode uses the existing native weather path.

The same server target does not mean identical particles or lightning timing on all machines. Regional legacy modes and local indoor/weather occlusion can also affect appearance. Snow and sand presets do not start the multiplayer rain-audio loop. The update does not add a separately synchronized snow-sound or sandstorm-sound API.

== Verification and limits ==
The preset catalog, validation, state replay and transition logic have automated coverage. '''The new presets still require visual qualification in the running game''', including another player, late join, indoor areas and returning to ordinary weather. A client ACK or status <code>ok</code> confirms command/override acceptance, not proof that snow, fog or dust rendered correctly.

Snow coverage affects only compatible game materials; it does not convert the whole world into a winter map. Terrain, navigation and collision are unchanged. This is a preset API, not arbitrary particle spawning, numeric weather-field editing, seasonal simulation or per-player weather. Test the presets your server intends to use before enabling them in gameplay.

[[Category:Lua API]]
[[Category:World Functions]]

ValidateWorldDoors

2026-10-20T13:30:13Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= validateWorldDoors =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server Lua. Part of [[Custom keys|custom keys and shared placed doors]].

== Syntax ==
<syntaxhighlight lang="lua">
ok, error = validateWorldDoors(doors)
</syntaxhighlight>
== Parameters and behavior ==
Same complete array, limits and compatibility checks as [[setWorldDoors]], without applying placements, locks or state. A later state change can invalidate an earlier successful check.
== Returns ==
true, empty error when valid now; false, error string otherwise. No objects are created.
== Examples and security ==
See [[Custom keys]] for complete registration, copy issuance, placement, persistence and callback examples. These are server functions, not client RPC endpoints. Do not forward untrusted client arguments without gameplay authorization.
[[Category:Lua Functions]]

UpdatePlayerDiscordPresence

2026-10-20T13:30:11Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= updatePlayerDiscordPresence =
'''Available from 0.1.9. Use matching updated clients and server.'''

'''Server-side only.''' Part of [[Discord Rich Presence]]. See [[Discord Presence configuration]] for the optional server-owner resource.
== Syntax ==
<syntaxhighlight lang="lua">
local ok, reason = updatePlayerDiscordPresence(playerId, {state="At the Old Camp", smallImage=false, smallText=false})
</syntaxhighlight>
== Parameters and behavior ==
Connected numeric game player ID and a flat patch table. Requires an existing profile owned by this resource. Unspecified fields stay unchanged; false removes a field, while nil is absent and cannot remove it. The merged profile is validated atomically, including paired link/party/timestamp constraints. Uses this resource's currently configured Application ID.
== Returns ==
Boolean success and empty reason, or false with an error string (including presence-not-set or presence-owned-by-another-resource). True means queued, not publicly visible. No partial changes on rejection.
== Examples, lifecycle and safety ==
See [[Discord Rich Presence]] for complete initialization, location/job updates, field removal, timestamps, counts, buttons and callback examples. Player launcher opt-in is off by default and cannot be overridden. No bot or token is needed; no Discord account identity is returned. Do not forward arbitrary client input to this server API.
[[Category:Lua Functions]]
[[Category:Server Functions]]

Update 0.1.9

2026-10-20T13:30:10Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= Update 0.1.9 =
'''Released: G1R:MP 0.1.9 / BUILD264 / Protocol 42.''' The Windows client and Windows/Linux dedicated servers are available on the [https://g1r-mp.com/download/ Download page]. Update both client and server. Experimental features and remaining qualification limits are identified below.

== Server-controlled item statistics ==
[[Item type stats]] introduces eight server Lua functions:
* [[getItemTypes]], [[getItemStats]], [[getItemStatDefinitions]]
* [[setItemStats]], [[setItemStatsBatch]], [[resetItemStats]]
* [[getItemStatsProfile]], [[replaceItemStatsProfile]]

One profile changes every copy of the same item type on that server, not individual inventory instances. Supported fields cover weapon and ammunition damage, seven damage/protection channels, armor and jewelry bonuses, equipment requirements, consumable restoration/regeneration, appropriate rune settings, and available common metadata such as value and stack size. See [[Item stat properties]] for exact support and ranges.

Changes are validated atomically, resource-owned, reversible and replayed to compatible joining clients. Profiles can be saved/restored by Lua. [[onPlayerItemStatsReport]] reports client application diagnostics; it is not authoritative proof of damage, inventory or gameplay success.

The bundled GothicRP generated native-item metadata follows configured value/weight/stack-size values; separately authored gamemode item/shop definitions remain the gamemode's responsibility. Changing stack size does not delete or rearrange existing quantities.

== Armor, jewelry and NPCs ==
Ordinary armor defense values can be configured directly, independently for cutting, blunt, piercing, fire, wind, ice and energy damage. Armor/player bases and bonuses are kept separate. Raising maxima does not heal/refill; lowering them clamps current values when needed.

Explicit armor HP/mana/strength/dexterity bonuses also affect equipped scripted NPCs. NPC maximum setters use base values; getters return effective values. Combat-config dexterity remains a base value, and [[getNpcData]] exposes the new breakdown. Profile refresh does not intentionally reload ammunition or restart accepted attacks/casts. See [[NPC scripting]] and [[Item type stats]].

Numeric ring/amulet overrides support the normal inventory equip/remove workflow and two owned identical rings. Reset-while-worn and multi-client lifecycle cases remain under qualification; NPC jewelry is not introduced.

== Rune settings and mana recovery ==
Appropriate implemented runes support damage, range, duration and magic-circle requirements. A custom <code>manaCost</code> is a fixed cost per accepted release; zero means free and resetting restores original cost rules. It preserves other spell eligibility checks. '''Custom paid/free/reset casting still requires final in-game qualification.'''

The client also corrects a stale out-of-mana state after a successful positive mana assignment. This addresses cases where mana was visible in the HUD but casting remained blocked until restarting the game. The baseline Fire Bolt/Light and empty/refill sequence has been confirmed in game without restarting. The fix does not grant spells or bypass circle, ownership or equipment requirements. Scroll support is not added.

== Interactive map-editor objects ==
The experimental [[Interactive map objects]] extension adds a searchable catalogue of '''94 entries: 18 seats, 48 lights/flames, 7 doors and 21 ladder sizes''', editor placement/transforms, duplicate/history, prefab-aware save/open/export, initial light state and local native testing. [[Interactive prefab catalog]] lists all entries.

[[MapEditor.CreateInteractiveObject]] is a new editor-resource client helper. Preview/local-test transform alignment and deferred seat cleanup were corrected; cleanup waits for native release and a 1-metre clearance. These additions are distinct from the existing static-object API.

'''Approved doors now have shared server-owned deployment''', through Apply removals + doors LIVE or the complete updated [[Map scene deployment|map_scene]] loader. Test native remains local; seats, lights and placed ladders are not yet shared deployed interactions. Beds, workshops and quest mechanisms are not enabled by this feature. The updated loader accepts formats 1/2/3 for supported static objects, doors and original-world removals.

== Scope and release status ==
Ordinary armor protection and [[Armor upgrades|armor-upgrade-slot effects]] are implemented; see the armor guide for catalog coverage and remaining visual qualification. Special haste/orc-spore/joint effects, critical-hit multipliers, stagger damage and NPC toughness are not advertised as writable. Consult [[getItemStatDefinitions]] rather than assuming all engine fields are supported.

In-game tests have confirmed selected potion and life-jewelry scenarios, not every item, tooltip, equipped-reset case or remote/late-join lifecycle. Experimental features remain marked as such until qualification is complete. The release is BUILD264 / Protocol 42. Use matching 0.1.9 client/server packages; publication does not remove the qualification limits above.

[[Category:Lua API]]


== Armor bases and upgrade pieces (from 0.1.9) ==
Available from 0.1.9. [[Armor catalog]] lists all 26 bases (24 existing plus Royal Guard and Judge additions); [[Armor upgrade catalog]] lists all 84 authored parts and exact family presets. [[Armor upgrades]] explains ownership, full sets, individual slots, players/NPCs, numeric protection and persistence.

Eight new server functions: [[getArmorUpgrades]], [[getArmorUpgradePresets]], [[getPlayerArmorUpgrades]], [[setPlayerArmorUpgrades]], [[setPlayerArmorPreset]], [[getNpcArmorUpgrades]], [[setNpcArmorUpgrades]], [[setNpcArmorPreset]]. Local-player and NPC checks are reported working; remote-human/late-join visual qualification remains pending.



== Female identity presentation ==
The existing <code>syra</code>, <code>velaya</code>, <code>seraphia</code>, <code>chani</code> and <code>natalia</code> identities receive corrected facial proportions, addressing stretched faces on female characters, including while wearing armor. The correction covers local players, remote human players and scripted human NPCs.

A matching identity without armor displays its full authored female body/outfit; an equipped armor keeps its original shape and selected pieces with the corrected female head. Facial expression is currently neutral. Existing [[setPlayerIdentity]] and [[setNpcIdentity]] APIs are used; no separate female API is introduced. See [[Female identities]] for usage, skin/tattoo limits and synchronization expectations. This is included from 0.1.9.



== Expanded activity animations and fishing ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
'''844 additional aliases; 962 total.''' The existing 118 remain available. New entries include gathering, rice/herb processing, crafting/work variations, sitting/rest, daily activities, carrying, poses and gestures. Many entries address sections/variants of the same animation rather than separate full animations.

Fishing adds idle, reeling and four held direction poses, with corrected rod size, hand attachment and orientation. Cosmetic props cover local players, relevant observers and scripted human NPCs; they are not inventory grants. There is no verified casting animation or complete fishing minigame.

Existing [[startAnim]], [[stopAnim]], [[startNpcAnim]] and [[stopNpcAnim]] calls are retained. [[getPlayerAnimationInfo]] adds catalogIndex, assetKind, since and verifiedInGame; [[getPlayerAnimationNames]] enumerates the expanded catalog. See [[Activity animations]] for Lua examples and limits, and [[Activity animation catalog]] for every new alias. New aliases are asset-audited, not all visually confirmed; local corrected fishing appearance was reported working, while complete observer/late-join visual qualification remains pending.



'''Available from 0.1.9. Use matching updated server and clients.'''

== Custom native keys and shared placed doors ==
[[Custom keys]] adds independent native key types, names/descriptions, approved model/icon reuse, multiple copies and normal authoritative drop/pickup. Server-owned door rules check canonical key quantities; wrong/local-only keys do not authorize shared operations. Includes definition/query/placement/lock APIs and lifecycle callbacks. [[World door prefab catalog]] lists the supported door aliases. Persistence/economy remain gamemode responsibilities.



== Extended weather ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[Weather]] adds 38 explicit game presets alongside five legacy biome-aware modes: 43 names including snow/blizzard, fog, sky/rain and sand/dust/regional variants. [[Weather catalog]] lists every name and alias. New [[getWeatherTypes]] plus the existing set/get/revision/sync functions and [[onWeatherChange]]; shared snapshots and late join are retained. New preset rendering still requires in-game qualification; an ACK is not visual proof, and snow coverage depends on map materials.



== Native crafting-window visibility ==
[[Native crafting UI]] adds the crafting key to [[setNativeHudComponentVisible]] and includes it in [[showNativeHud]]. Recipe/progress windows can be hidden while station interaction and normal exit remain. Hidden new recipe starts are guarded; running crafts are not deliberately cancelled. This is client presentation control, not a recipe API or server authorization. New getNativeUiState diagnostics and existing asynchronous result event are documented. Available from 0.1.9; full station qualification remains pending.



== Original-world inspection and reversible removal ==
[[World model removal]] adds object/model inspection, candidate/Nearby selection, original-world hide/restore with collision/interaction handling, undo/redo, persistent placement identities, format-3 save/export and server-guarded live publication/replay. Supported adapters include standalone and grouped models, foliage, authored doors, lights and whole ladders. Busy interactions wait for native release. Terrain, characters, world controllers and baked distant HLOD remain protected; NPC obstacle data is intentionally unchanged. Matching game/catalog data is required after restart/update.

[[Interactive prefab catalog]] also includes 21 native ladder lengths (7..25, 28 and 30 steps) and all seven approved door prefabs. Local preview/native alignment and moving-door initialization were corrected. Shared doors use the original mechanism synchronization path, server interaction ownership, streamed construction and late-join state. See [[Interactive map objects]] for limits and production checks.



== Optional Discord Rich Presence ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[Discord Rich Presence]] adds eight server Lua functions and [[onPlayerDiscordPresenceStatus]] for public server/location/job text, artwork, timers, displayed counts and two HTTPS buttons. [[Discord Presence configuration]] includes the complete optional Windows/Linux server resource and application setup. Player launcher opt-in is off by default. Resource ownership, coalescing and automatic cleanup are built in; no bot/token/account linking or automatic Join/Spectate. Real Discord visibility still requires owner-application acceptance testing.

== Installation and compatibility ==
* Install the matching '''0.1.9 / BUILD264 / Protocol 42''' client and dedicated server. Protocol 41 and older clients/servers are incompatible.
* Windows and Linux each have two dedicated-server downloads: '''with TTS''' includes the CPU speech runtime/models; '''without TTS''' is smaller. TTS is optional and disabled by default in both variants. See [[TTS configuration]] before enabling it.
* Distribution configurations contain no operator passwords or private state. Back up and preserve your own serverconf.cfg, database credentials, keys, maps and resource .storage when upgrading; merge new settings and updated bundled resources instead of overwriting your data.
* Optional [[Discord Rich Presence]] requires server-owner configuration and a separate player opt-in. It is disabled by default.
* Back up single-player saves before using the mod; multiplayer use may remove save files.

== Remote head and upper-body look direction ==
Native look direction is forwarded for remote head/neck/upper-body presentation. No new Lua command is required. Missing native look data falls back to neutral, and interaction/combat/climbing and other full-body activities take priority. This does not change gameplay aiming or damage. Full multi-player visual qualification remains pending.

StopNpcAnim

2026-10-20T13:30:06Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= stopNpcAnim =
<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;">AVAILABLE FROM UPDATE 0.1.5</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.5 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Stops the NPC scripted animation.

== Syntax ==
<syntaxhighlight lang="lua">
stopNpcAnim(npcId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || Server-assigned NPC ID returned by spawnNpc; not a player ID.
|}

== Returns ==
Returns true when accepted, false for a rejected request. Acceptance is not proof of a rendered animation, projectile release or hit.

== Examples ==
<syntaxhighlight lang="lua" line>
stopNpcAnim(npcId)
</syntaxhighlight>

== Notes ==
* Server-side only. Mutations require the NPC to belong to the calling resource; getters do not grant control.
* The function was introduced in 0.1.5. Use matching supported client/server versions; new 0.1.9 aliases require that update on both.
* Use matching updated client and server. See [[NPC scripting]] for lifecycle, defaults, combat examples and collision limitations.
* Idempotent stop; original route/goal can resume without catching up suspended wait time.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:NPC Functions]]


== Activity cleanup from 0.1.9 ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
Use <code>stopNpcAnim(npcId)</code> for the new work/fishing/rest loops and held poses. It cleans up their animation-owned props without deleting NPC equipment or scenery. Resource ownership and route-resumption behavior remain unchanged. See [[Activity animations]].

StopAnim

2026-10-20T13:30:05Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= stopAnim =
<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.2</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.2 and later. The contract below describes the updated behavior.</div>
</div>

Stops the tracked scripted visual animation for a connected player and synchronizes the stop with relevant clients.

== Syntax ==
<syntaxhighlight lang="lua">
bool stopAnim(int playerId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|}

== Returns ==
Returns <code>true</code> when the server records or retransmits the authoritative stopped state and attempts reliable delivery. This is not a client or transport acknowledgement. Returns <code>false</code> for an invalid player or inactive player session.

== Examples ==
Stop a scripted animation:
<syntaxhighlight lang="lua" line>
stopAnim(playerId)
</syntaxhighlight>

== Notes ==
* Since 0.1.4 BUILD127, this also stops the new entries in the [[Player animation catalog]] and retires their owned cosmetic props. It does not delete equipped weapons, inventory items or unrelated world objects.
* Available only in server-side resource scripts.
* This stops only the scripted animation tracked by <code>startAnim</code>; it does not issue a global montage stop and does not cancel normal replicated locomotion, combat, interaction, hit, or death state.
* Calling <code>stopAnim</code> after an accepted start also supersedes any still-pending client asset load for that older animation state.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Animation Functions]]


== Activity cleanup from 0.1.9 ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
Also ends the new [[Activity animations|activity animations and held fishing poses]] and retires their animation-owned cosmetic props. Use <code>stopAnim(playerId)</code>; no new argument is required. It does not remove inventory rods/weapons, furniture or unrelated world objects.

StartNpcAnim

2026-10-20T13:30:02Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= startNpcAnim =
<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;">AVAILABLE FROM UPDATE 0.1.5</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.5 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Starts a catalog animation on an NPC.

== Syntax ==
<syntaxhighlight lang="lua">
startNpcAnim(npcId, alias, looped=false, blendSeconds=0.15)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || Server-assigned NPC ID returned by spawnNpc; not a player ID.
|-
| <code>alias</code> || <code>string</code> || yes || Supported alias from [[Player animation catalog]], not an asset path.
|-
| <code>looped</code> || <code>bool</code> || no || Optional; default false.
|-
| <code>blendSeconds</code> || <code>number</code> || no || Optional blend-out time in seconds, 0..2; default 0.15.
|}

== Returns ==
Returns true when accepted, false for a rejected request. Acceptance is not proof of a rendered animation, projectile release or hit.

== Examples ==
<syntaxhighlight lang="lua" line>
setNpcWeaponMode(npcId, "none")
startNpcAnim(npcId, "pray", true, 0.15)
</syntaxhighlight>

== Notes ==
* Server-side only. Mutations require the NPC to belong to the calling resource; getters do not grant control.
* The function was introduced in 0.1.5. Use matching supported client/server versions; new 0.1.9 aliases require that update on both.
* Use matching updated client and server. See [[NPC scripting]] for lifecycle, defaults, combat examples and collision limitations.
* Requires living NPC with holstered weapon. Suspends route/goal/wait progress. One-shot ends on its timeline; a loop requires stopNpcAnim. Does not replace the original route.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:NPC Functions]]


== Activity aliases from 0.1.9 ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
Uses the same expanded catalog as [[startAnim]]: 962 aliases, including 844 additions. Example: <code>startNpcAnim(npcId, "pickrice_loop02", true, 0.15)</code>. Fishing includes the cosmetic rod. Existing resource ownership, living-NPC and holstered-weapon requirements remain. See [[Activity animations]] for examples and [[Activity animation catalog]] for modes and visual-qualification status.

StartAnim

2026-10-20T13:30:00Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= startAnim =
<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.2</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.2 and later. The contract below describes the updated behavior.</div>
</div>

Starts an allowlisted scripted visual animation for a connected player and synchronizes it with relevant clients.

== Syntax ==
<syntaxhighlight lang="lua">
bool startAnim(int playerId, string animation [, bool looped = false, number blendSeconds = 0.15])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>animation</code> || <code>string</code> || yes || A case-insensitive alias from the [[Player animation catalog]]. Raw Unreal asset paths are not accepted.
|-
| <code>looped</code> || <code>bool</code> || no || Whether to hold and replay the animation from its catalog loop point. The compatible default remains false, even for aliases whose authored mode is <code>hold</code>.
|-
| <code>blendSeconds</code> || <code>number</code> || no || Requested owning-player native montage transition/stop duration from 0 to 2 seconds; defaults to 0.15. When this request replaces an existing scripted animation, it controls that outgoing montage and is then retained for a later stop of the new animation.
|}

== Returns ==
Returns <code>true</code> when the server validates the request, records the authoritative animation state, and attempts reliable delivery. This is not a client playback or transport acknowledgement. Returns <code>false</code> for an invalid player, alias, argument, or inactive player session.

== Examples ==
Hold the allowlisted prayer animation until it is stopped:
<syntaxhighlight lang="lua" line>
if not startAnim(playerId, "pray", true, 0.2) then
outputDebugString("Prayer animation request was rejected")
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* [[Player animation catalog]] documents the earlier 118 aliases. From 0.1.9, [[Activity animation catalog]] adds 844 entries (962 total), including route/gesture variants; these additions are not all individually visually confirmed. Use [[getPlayerAnimationNames]] and [[getPlayerAnimationInfo]] to enumerate the running server catalog and recommended modes. Selected introduction/loop/exit playback retains the existing signature and default looped=false.
* The optional <code>looped</code> argument explicitly controls the request. Omitting it always requests a one-shot animation; the catalog mode is an authored recommendation, not an implicit override.
* Starting another scripted animation replaces the player's current scripted animation. Normal replicated gameplay actions retain their own presentation rules.
* Use <code>stopAnim</code> to end the tracked scripted animation. Clients use bounded loading and presentation retries for the newest accepted revision; a terminal miss is written to the animation diagnostic log instead of retrying forever.
* The requested blend is applied to the owning player's exact native montage. Remote proxy handoff is immediate and does not guarantee an interpolated blend.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Animation Functions]]


== Activity aliases from 0.1.9 ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
Use the existing call, for example <code>startAnim(playerId, "fishing", true, 0.15)</code> or <code>startAnim(playerId, "pickcrouch", false, 0.15)</code>. See [[Activity animations]] and the full [[Activity animation catalog]]. Animation-owned rods/tools are cosmetic, not inventory grants; rewards and interaction validation belong to your server script. Acceptance is not a visual acknowledgement.

SpawnItem

2026-10-20T13:29:58Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

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

Spawns an allowlisted, server-authoritative synchronized pickup near a player or at an exact world position.

== Syntax ==
<syntaxhighlight lang="lua">
bool spawnItem(int playerId, string itemKey [, number heightOffset])
bool spawnItem(int playerId, string itemKey, number x, number y, number z [, number yaw [, bool snapToGround]])
bool spawnItem(string itemKey, number x, number y, number z [, number yaw [, bool snapToGround]])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || no || Required by the near-player and player-attributed exact-position overloads. Omit it only for a purely server-owned exact-position spawn.
|-
| <code>itemKey</code> || <code>string</code> || yes || A verified public world-item key or inventory key from the server catalog allowlist, for example <code>apple</code> or <code>itfo_apple</code>.
|-
| <code>heightOffset</code> || <code>number</code> || no || Optional finite vertical offset in metres from -100 through 100. Values outside this range are rejected. Omit it to request ground snapping; an explicit 0 keeps the player's snapshot height without ground snapping.
|-
| <code>x</code> || <code>number</code> || no || Exact world X coordinate in metres. The exact-position overload requires <code>x</code>, <code>y</code>, and <code>z</code> together.
|-
| <code>y</code> || <code>number</code> || no || Exact world Y coordinate in metres. The exact-position overload requires <code>x</code>, <code>y</code>, and <code>z</code> together.
|-
| <code>z</code> || <code>number</code> || no || Exact world Z coordinate in metres. The exact-position overload requires <code>x</code>, <code>y</code>, and <code>z</code> together.
|-
| <code>yaw</code> || <code>number</code> || no || Optional finite world yaw in degrees for an exact-position spawn. Defaults to 0 and is normalized by the authoritative world-item system.
|-
| <code>snapToGround</code> || <code>bool</code> || no || Whether an exact-position spawn requests ground snapping. Defaults to <code>false</code>.
|}

== Returns ==
Returns <code>true</code> after the server accepts and creates the item; otherwise returns <code>false</code>.

== Examples ==
=== Example 1 ===
Spawn an allowlisted apple near the invoking player:
<syntaxhighlight lang="lua" line>
addCommandHandler("spawnitem", function(playerId)
if not spawnItem(playerId, "itfo_apple") then
outputChatBox("The item could not be spawned.", playerId)
end
end)
</syntaxhighlight>
=== Example 2 ===
Spawn other verified food, weapon, and rune entries:
<syntaxhighlight lang="lua" line>
spawnItem(playerId, "ItFo_Loaf")
spawnItem(playerId, "ItMw_1H_Axe_01")
spawnItem(playerId, "ItAr_Rune_FireBolt")
</syntaxhighlight>
=== Example 3 ===
Spawn at exact positions, either attributed to a connected player or owned only by the server:
<syntaxhighlight lang="lua" line>
spawnItem(playerId, "itfo_loaf", 125.5, -42.0, 18.25, 90, true)
spawnItem("itfo_apple", 125.5, -42.0, 18.25)
</syntaxhighlight>
=== Example 4 ===
Observe only pickups that the server has accepted and already granted:
<syntaxhighlight lang="lua" line>
addEventHandler("onWorldItemPickup", root, function(objectId, playerId, itemKey, quantity, serverTimeMs)
outputDebugString(getPlayerName(playerId) .. " picked up " .. quantity .. "x " .. itemKey)
end)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* This function was introduced in update 0.1.2. Update 0.1.3 adds the two exact-position overloads without changing the original near-player signature.
* The legacy overload spawns exactly one item 0.7 metres in front of the connected player's latest replicated position and facing direction.
* Exact-position <code>x</code>, <code>y</code>, and <code>z</code> inputs use metres. [[onWorldItemSpawn]] exposes the published packet coordinates in Unreal centimetres.
* The player-attributed exact overload reports that connected player as <code>sourcePlayerId</code>. The server-owned exact overload reports <code>sourcePlayerId = 0</code> and does not require a player snapshot.
* The update 0.1.2 catalog contains 681 structurally verified world-item entries. Item codes are case-insensitive; the server canonicalizes every accepted value before replication.
* The [https://www.nexusmods.com/gothic1remake/articles/8 Gothic Remake item-code reference] is useful when looking up candidate codes. A code is spawnable only when it also exists in the current server catalog; unsupported codes return <code>false</code>.
* The server owns the item identity, revision, visibility, pickup validation, inventory award, and late-join state.
* [[onWorldItemPickup]] runs only after an authoritative pickup is accepted, the inventory grant is applied, and the reliable picked-up tombstone removes the item from active late-join state. It is an observation event; do not grant the same item again in its handler.
* Only entries mapped by the verified world-item catalog may be spawned; arbitrary asset names and paths are rejected.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:World Functions]]
[[Category:Inventory Functions]]


'''Available from 0.1.9. Use matching updated server and clients.'''

== Registered custom keys ==
This existing API also accepts the canonical item string from [[registerKeyDefinition]] in 0.1.9. Server registration, active definition and appropriate presentation readiness are required for mutations; use [[isPlayerKeyDefinitionReady]]. Do not pass the donor model alias as the custom item identity. Existing call shapes and limits remain; [[spawnItem]] creates one world item per call, whereas give/remove counts can manage copies. See [[Custom keys]] for safe server-side issuance, drop, pickup and persistence.

ShowNativeHud

2026-10-20T13:29:55Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= showNativeHud =
<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;">AVAILABLE FROM UPDATE 0.1.7</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.7 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Set this client resource's visibility policy for the six original native HUD groups; from 0.1.9 also crafting presentation. It does not disable the four native management menus.

== Syntax ==
<syntaxhighlight lang="lua">
requestId = showNativeHud(visible)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>visible</code> || <code>boolean</code> || yes || false hides all HUD groups; true releases this resource's HUD restrictions.
|}

== Returns ==
Positive numeric request ID if queued, or <code>false</code> if rejected. This is not an application acknowledgement.

== Examples ==
<syntaxhighlight lang="lua" line>
local requestId = showNativeHud(false)
-- Later, restore only this resource's HUD policy:
showNativeHud(true)
</syntaxhighlight>

== Notes ==
* Client-side only; the original API exists since 0.1.7. Crafting extensions require 0.1.9; use matching updated client/server versions.
* See [[Native HUD and menus]] for asynchronous acknowledgements, resource ownership, input and restoration.
* A positive request ID means queued, not applied. Listen for [[onClientNativeUiResult]] and inspect [[getNativeUiState]].
* Register the handler before submitting. Rapid changes coalesce: track the latest request ID, not every intermediate ID.
* false restricts; true releases only the calling resource's restriction. Other resources remain respected.
* This does not change inventory data, player attributes or custom RmlUi documents. Native save/load cannot be re-enabled.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:GUI Functions]]


== Crafting presentation from 0.1.9 ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[Native crafting UI]] documents the new crafting component, recipe/progress windows, preserved station entry/exit and prevention of invisible recipe starts. It is not a setNativeMenuEnabled key or a custom recipe API. getNativeUiState gains components.crafting, craftingReady, craftingGuardReady, craftingWidgets and craftingObserved; HUD bit 64 is appended, older bits unchanged. Existing resource ownership, asynchronous result handling and restoration still apply. Full station-by-station in-game qualification remains pending.

SetWorldDoors

2026-10-20T13:29:49Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setWorldDoors =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server Lua. Part of [[Custom keys|custom keys and shared placed doors]].

== Syntax ==
<syntaxhighlight lang="lua">
ok, error = setWorldDoors(doors)
</syntaxhighlight>
== Parameters and behavior ==
doors is the complete 1-based array for the calling resource. Each row has exactly id, prefab, x, y, z, yaw; coordinates are metres, yaw degrees. Empty table removes all owned doors. Omitted rows are removed. Does not change another resource's set. See [[Custom keys#Shared door placement and access|replacement and key-binding lifecycle]].
== Returns ==
true, empty error on acceptance; false, error string on validation/compatibility/limit failure. Acceptance is not a visual acknowledgement. Requires updated connected clients.
== Examples and security ==
See [[Custom keys]] for complete registration, copy issuance, placement, persistence and callback examples. These are server functions, not client RPC endpoints. Do not forward untrusted client arguments without gameplay authorization.
[[Category:Lua Functions]]

SetWorldDoorLocked

2026-10-20T13:29:47Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setWorldDoorLocked =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server Lua. Part of [[Custom keys|custom keys and shared placed doors]].

== Syntax ==
<syntaxhighlight lang="lua">
ok, error = setWorldDoorLocked(id, locked)
</syntaxhighlight>
== Parameters and behavior ==
id identifies an owned placed door with an assigned key; locked is a boolean. false disables the requirement while retaining the assignment; true enables it again. No binding means failure.
== Returns ==
true, empty error on success; false, error string otherwise. Idempotent setters do not emit duplicate lock-change events.
== Examples and security ==
See [[Custom keys]] for complete registration, copy issuance, placement, persistence and callback examples. These are server functions, not client RPC endpoints. Do not forward untrusted client arguments without gameplay authorization.
[[Category:Lua Functions]]

SetWorldDoorKey

2026-10-20T13:29:46Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setWorldDoorKey =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server Lua. Part of [[Custom keys|custom keys and shared placed doors]].

== Syntax ==
<syntaxhighlight lang="lua">
ok, error = setWorldDoorKey(id, item)
</syntaxhighlight>
== Parameters and behavior ==
id identifies an owned placed door. item is an active canonical custom key from this or another resource. Assigns the key and enables its lock. One key type can open multiple doors; at least one authoritative copy is required and is not consumed.
== Returns ==
true, empty error on success; false, error string otherwise. Locking does not close an open door. An actual rule change queues [[onWorldDoorLockChange]].
== Examples and security ==
See [[Custom keys]] for complete registration, copy issuance, placement, persistence and callback examples. These are server functions, not client RPC endpoints. Do not forward untrusted client arguments without gameplay authorization.
[[Category:Lua Functions]]

SetWeather

2026-10-20T13:29:44Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setWeather =
Changes the authoritative weather and replicates it to every connected player.

== Syntax ==
<syntaxhighlight lang="lua">
bool setWeather(string weather [, int transitionMs = 3000])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>weather</code> || <code>string</code> || yes || Earlier releases: sunny, cloudy, rain1, rain2 or rain3. From 0.1.9: any canonical name or alias in [[Weather catalog]], including snow, fog and sandstorms; query [[getWeatherTypes]].
|-
| <code>transitionMs</code> || <code>int</code> || no || Transition duration from 0 to 300000 milliseconds. Defaults to 3000; 0 applies an immediate transition.
|}

== Returns ==
Returns <code>true</code> when the weather name and transition are accepted; otherwise returns <code>false</code>.

== Examples ==
=== Example 1 ===
Create a five-second transition into a storm:
<syntaxhighlight lang="lua" line>
if not setWeather("rain3", 5000) then
outputDebugString("The server rejected the weather change")
end
</syntaxhighlight>
=== Example 2 ===
Register a simple sunny-weather command:
<syntaxhighlight lang="lua" line>
addCommandHandler("sunny", function(playerId)
if setWeather("sunny", 3000) then
outputChatBox("Clear weather enabled.", playerId)
end
end)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The new state is retained for late joiners.
* A successful change increments the weather revision and triggers <code>onWeatherChange</code>.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:World Functions]]


== Extended weather from 0.1.9 ==
'''Available from 0.1.9. Use matching updated clients and server.'''

This existing API retains its call shape; the catalog is extended, not restricted to five names. See [[Weather]] and [[Weather catalog]]. Server target/revision and client acknowledgement are not proof of the final rendered image. The new presets still require in-game visual qualification; use compatible clients and test late join, indoor areas and returning to ordinary weather.

SetPlayerMana

2026-10-20T13:29:43Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setPlayerMana =
Sets a player's authoritative current mana value.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerMana(int playerId, number value)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player to update.
|-
| <code>value</code> || <code>number</code> || yes || The new current mana value.
|}

== Returns ==
Returns <code>true</code> when the value is accepted; otherwise returns <code>false</code>.

== Examples ==
Set a player's current mana:
<syntaxhighlight lang="lua" line>
setPlayerMana(playerId, 50)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* This is a convenience wrapper around <code>setPlayerStat(playerId, "mana", value)</code>.

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


== Mana-state correction (from 0.1.9) ==
The 0.1.9 client clears a stale out-of-mana condition after a successful, verified positive mana assignment. This addresses casting remaining blocked despite the updated mana display, without requiring a game restart. Zero/insufficient mana still blocks ordinary paid casts; rune ownership, equipment, circle and other eligibility checks remain. This improves the existing mana setter; it is not a new Lua function. Separate custom rune manaCost profiles are described in [[Item type stats]] and remain under in-game qualification.

SetPlayerIdentity

2026-10-20T13:29:41Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setPlayerIdentity =
<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 identity while preserving equipped armor and independent cosmetic overrides. See [[Female identities]] for the expanded female body/outfit presentation from 0.1.9.

== 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 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 ==
Select Milten's head/face without equipping armor or changing the body:
<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 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.
* In 0.1.8, the client applies a head-only identity layer with supported face/hair/beard geometry. From 0.1.9, the five [[Female identities|supported female identities]] also display their full authored outfit when no armor is equipped and body/head selections match. With armor equipped, the corrected female head is shown with the native armor. This is not a general body-shape or arbitrary model replacement API.
* 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.
* 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.
* 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.
* 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. These are state-change events, not notifications that visual reconstruction has finished; the female outfit presentation from 0.1.9 does not add a new event.
* See [[Player customization]], [[Player identity catalog]] and [[Player tattoo catalog]] for the independent appearance layers and supported catalogs.

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


== Female presentation improved from 0.1.9 ==
'''Improved from 0.1.9.'''
<code>setPlayerIdentity(playerId, "syra")</code> selects the matched identity; the same applies to <code>velaya</code>, <code>seraphia</code>, <code>chani</code> and <code>natalia</code>. Identity selection remains an existing API. See [[Female identities]] for full-outfit/armor behavior, neutral facial expression and supported customization. The call does not remove armor, change protection or clear tint/tattoos.

SetPlayerDiscordPresence

2026-10-20T13:29:40Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setPlayerDiscordPresence =
'''Available from 0.1.9. Use matching updated clients and server.'''

'''Server-side only.''' Part of [[Discord Rich Presence]]. See [[Discord Presence configuration]] for the optional server-owner resource.
== Syntax ==
<syntaxhighlight lang="lua">
local ok, reason = setPlayerDiscordPresence(playerId, {details="My Gothic RP", state="Exploring the Colony"})
</syntaxhighlight>
== Parameters and behavior ==
playerId: a connected game player ID, numeric integer 1..4294967295. Second argument: the complete flat profile table described in [[Discord Rich Presence#Profile fields|profile fields]]. First configure the calling resource's Application ID. Replaces all previous fields and claims ownership when unowned; another resource's ownership is rejected. An empty table is a basic Playing activity, not clear.
== Returns ==
Boolean success and empty reason, or false and an error string. True means queued on the server, not visible on Discord. Invalid input/ownership leaves the previous profile unchanged.
== Examples, lifecycle and safety ==
See [[Discord Rich Presence]] for complete initialization, location/job updates, field removal, timestamps, counts, buttons and callback examples. Player launcher opt-in is off by default and cannot be overridden. No bot or token is needed; no Discord account identity is returned. Do not forward arbitrary client input to this server API.
[[Category:Lua Functions]]
[[Category:Server Functions]]

SetPlayerArmorUpgrades

2026-10-20T13:29:38Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setPlayerArmorUpgrades =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9.</div>
</div>

Replaces all three selected armor-upgrade slots for a player.

== Syntax ==
<syntaxhighlight lang="lua">
accepted = setPlayerArmorUpgrades(playerId, parts)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>number</code> || yes || Existing connected player ID: finite integer 1..4294967295, not a numeric string.
|-
| <code>parts</code> || <code>table</code> || yes || String keys top/mid/bottom only, with compatible part-key string values. Omitted slots, empty strings or none clear a slot. {} clears all parts.
|}

== Returns ==
Boolean: true when accepted; false for invalid arguments/selection, unavailable character, wrong family/slot, or failed ownership/requirements. Invalid selections are rejected before equipment mutation.

== Examples ==
<syntaxhighlight lang="lua" line>
local presets = getArmorUpgradePresets("mercenary")
if presets and presets.heavy_2 then
-- Player already wears mercenary and owns these parts.
assert(setPlayerArmorUpgrades(playerId, presets.heavy_2))
end
</syntaxhighlight>

== Notes ==
* Server-side only; available from 0.1.9.
* See [[Armor upgrades]], [[Armor catalog]] and [[Armor upgrade catalog]].
* The player must own the equipped base and every selected part, and satisfy the server equipment requirements. No items or attributes are granted.
* Uses the already equipped base; never selects a different base. The part must match its family and slot.
* true confirms server acceptance, not completed native rendering. No automatic healing/refill or database save.
* Treat remote requests as untrusted; authorize the action in your server resource.
* This is replacement, NOT a partial patch. Read the current table and modify one field to preserve the other slots. Values are keys, not item IDs; unknown table fields and non-string values reject the request.
* Equivalent alias: SetPlayerArmorUpgrades.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Equipment Functions]]
[[Category:Inventory Functions]]

SetPlayerArmorPreset

2026-10-20T13:29:37Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setPlayerArmorPreset =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9.</div>
</div>

Selects an authored armor preset for the currently equipped base.

== Syntax ==
<syntaxhighlight lang="lua">
accepted = setPlayerArmorPreset(playerId, preset)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>number</code> || yes || Existing connected player ID: finite integer 1..4294967295, not a numeric string.
|-
| <code>preset</code> || <code>string</code> || yes || light_1, light_2, medium_1, medium_2, heavy_1, heavy_2, or none to clear selected parts.
|}

== Returns ==
Boolean: true when accepted; false for invalid/unavailable ID, unknown/inapplicable preset, or failed validation/ownership/requirements. none clears parts without removing the base.

== Examples ==
<syntaxhighlight lang="lua" line>
-- Player already wears mercenary and owns the heavy_2 parts.
assert(setPlayerArmorPreset(playerId, "heavy_2"))
-- Keep the base, remove all selected parts:
assert(setPlayerArmorPreset(playerId, "none"))
</syntaxhighlight>

== Notes ==
* Server-side only; available from 0.1.9.
* See [[Armor upgrades]], [[Armor catalog]] and [[Armor upgrade catalog]].
* The player must own the equipped base and every selected part, and satisfy the server equipment requirements. No items or attributes are granted.
* Uses the already equipped base; never selects a different base. The part must match its family and slot.
* true confirms server acceptance, not completed native rendering. No automatic healing/refill or database save.
* Treat remote requests as untrusted; authorize the action in your server resource.
* Sparse families use only existing parts up to the requested tier, so different presets may select the same pieces. Query getArmorUpgradePresets first.
* Equivalent alias: SetPlayerArmorPreset.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Equipment Functions]]
[[Category:Inventory Functions]]

SetPlayerArmor

2026-10-20T13:29:35Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setPlayerArmor =
Equips or clears a player's authoritative armor slot.

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

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>itemKey</code> || <code>string</code> || yes || A key returned by <code>getPlayerArmorNames</code>, or <code>"none"</code> to clear the slot.
|}

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

== Examples ==
=== Example 1 ===
Give an item and equip it in the armor slot:
<syntaxhighlight lang="lua" line>
local itemKey = "water_robe"
if givePlayerItem(playerId, itemKey) then
setPlayerArmor(playerId, itemKey)
end
</syntaxhighlight>
=== Example 2 ===
Clear the armor slot:
<syntaxhighlight lang="lua" line>
setPlayerArmor(playerId, "none")
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The player must own at least one copy of a non-empty item before it can be equipped.
* The selected appearance is reliably synchronized and included in late-join state.
* Gothic Remake character variants have identity-specific armor support. Not every identity/armor combination exists or renders correctly; test every combination exposed by a resource.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Player Functions]]
[[Category:Inventory Functions]]
[[Category:Equipment Functions]]


== Armor parts (from 0.1.9) ==
Available from 0.1.9. [[Armor catalog]] lists the 26 bases; [[Armor upgrade catalog]] lists all 84 pieces. This existing function/guide is not newly introduced in 0.1.9. The new [[Armor upgrades|upgrade system]] adds per-character top/mid/bottom selections, full presets and separate player/NPC setters. A different base clears the old parts; choosing the same base keeps compatible selections. Identity, skin tint and tattoos remain separate. See the guide for requirements, safe replacement and synchronization validation.

SetNpcMaxMana

2026-10-20T13:29:30Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcMaxMana =
<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;">AVAILABLE FROM UPDATE 0.1.5</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.5 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Sets NPC maximum mana.

== Syntax ==
<syntaxhighlight lang="lua">
setNpcMaxMana(npcId, maxMana)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || Server-assigned NPC ID returned by spawnNpc; not a player ID.
|-
| <code>maxMana</code> || <code>number</code> || yes || Finite 0..100000; clamps current mana, does not refill it.
|}

== Returns ==
Returns true when accepted, false for a rejected request. Acceptance is not proof of a rendered animation, projectile release or hit.

== Examples ==
<syntaxhighlight lang="lua" line>
setNpcMaxMana(npcId, 100)
</syntaxhighlight>

== Notes ==
* Server-side only. Mutations require the NPC to belong to the calling resource; getters do not grant control.
* Since 0.1.5. Use the matching 0.1.5 client and server (Protocol 37).
* Use matching updated client and server. See [[NPC scripting]] for lifecycle, defaults, combat examples and collision limitations.
* May cancel pending preparation; increasing maximum does not refill current mana.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:NPC Functions]]


== Item-type armor bonuses (from 0.1.9) ==
[[Item type stats]] adds explicit armor bonusHealth/bonusMana/bonusStrength/bonusDexterity contributions for equipped scripted NPCs, plus the armor protection profile. Unconfigured native bonuses do not silently change existing NPC balance. Base stats and bonuses are separate; raising maxima does not heal/refill and lowering maxima clamps current values without reviving dead NPCs.

setNpcMaxHealth/setNpcMaxMana set BASE maxima; getNpcMaxHealth/getNpcMaxMana return EFFECTIVE maxima. setNpcCombatConfig/getNpcCombatConfig dexterity is BASE dexterity. getNpcData adds baseMaxHealth, baseMaxMana, baseDexterity, mana, maxMana, dexterity, armorHealthBonus, armorManaBonus, armorStrengthBonus and armorDexterityBonus.

NPC melee includes explicit armor strength and ranged combat uses effective dexterity. Numeric refresh preserves accepted attack/projectile snapshots; it does not reload ammo or restart prepared casts. NPC toughness and NPC jewelry are not implemented by this addition. These are extensions to existing APIs, not new names or a replacement for their earlier contracts.

SetNpcMaxHealth

2026-10-20T13:29:28Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcMaxHealth =
<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;">AVAILABLE FROM UPDATE 0.1.5</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.5 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Sets NPC maximum health.

== Syntax ==
<syntaxhighlight lang="lua">
setNpcMaxHealth(npcId, maxHealth)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || Server-assigned NPC ID returned by spawnNpc; not a player ID.
|-
| <code>maxHealth</code> || <code>number</code> || yes || Finite 1..100000; lowering clamps current HP, raising does not heal.
|}

== Returns ==
Returns true when accepted, false for a rejected request. Acceptance is not proof of a rendered animation, projectile release or hit.

== Examples ==
<syntaxhighlight lang="lua" line>
setNpcMaxHealth(npcId, 100)
</syntaxhighlight>

== Notes ==
* Server-side only. Mutations require the NPC to belong to the calling resource; getters do not grant control.
* Since 0.1.5. Use the matching 0.1.5 client and server (Protocol 37).
* Use matching updated client and server. See [[NPC scripting]] for lifecycle, defaults, combat examples and collision limitations.
* Changing maxHP does not automatically heal. Script HP is separate from armor protection.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:NPC Functions]]


== Item-type armor bonuses (from 0.1.9) ==
[[Item type stats]] adds explicit armor bonusHealth/bonusMana/bonusStrength/bonusDexterity contributions for equipped scripted NPCs, plus the armor protection profile. Unconfigured native bonuses do not silently change existing NPC balance. Base stats and bonuses are separate; raising maxima does not heal/refill and lowering maxima clamps current values without reviving dead NPCs.

setNpcMaxHealth/setNpcMaxMana set BASE maxima; getNpcMaxHealth/getNpcMaxMana return EFFECTIVE maxima. setNpcCombatConfig/getNpcCombatConfig dexterity is BASE dexterity. getNpcData adds baseMaxHealth, baseMaxMana, baseDexterity, mana, maxMana, dexterity, armorHealthBonus, armorManaBonus, armorStrengthBonus and armorDexterityBonus.

NPC melee includes explicit armor strength and ranged combat uses effective dexterity. Numeric refresh preserves accepted attack/projectile snapshots; it does not reload ammo or restart prepared casts. NPC toughness and NPC jewelry are not implemented by this addition. These are extensions to existing APIs, not new names or a replacement for their earlier contracts.

SetNpcIdentity

2026-10-20T13:29:26Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcIdentity =
<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;">AVAILABLE FROM UPDATE 0.1.5</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.5 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Selects the matched head/identity profile of an NPC.

== Syntax ==
<syntaxhighlight lang="lua">
setNpcIdentity(npcId, identity)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || NPC ID returned by spawnNpc; not a player ID.
|-
| <code>identity</code> || <code>string</code> || yes || Named identity from getNpcIdentityNames, or default. ASCII case-insensitive, at most 48 bytes; not an asset path.
|}

== Returns ==
true when accepted, false when invalid, unavailable or owned by another resource.

== Examples ==
<syntaxhighlight lang="lua" line>
setNpcIdentity(npcId, "milten")
</syntaxhighlight>

== Notes ==
* Server-side only. Mutations require the resource that owns this NPC; getters do not grant control.
* Available from update 0.1.5. See [[NPC scripting#NPC appearance since 0.1.5]].
* The authoritative state is replayed for relevance entry/late join. Rendering is asynchronous; acceptance does not mean the mesh has finished rebuilding.
* Does not change authoritative HP, weapons, armor, routes or combat configuration. No automatic persistent database storage.
* Upper-initial alias SetNpcIdentity is also supported.
* Use default to explicitly restore the Nameless Hero identity. Preserves armor, skin-color and tattoo overrides. In 0.1.8 it does not replace the whole NPC outfit. From 0.1.9, the five supported female identities can show their full authored outfit without armor; see [[Female identities]]. Existing setNpcSkin remains a separate legacy preset.

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


== Female presentation improved from 0.1.9 ==
'''Improved from 0.1.9.'''
<code>setNpcIdentity(npcId, "syra")</code> selects a matching female identity for a resource-owned human NPC. The same correction covers <code>velaya</code>, <code>seraphia</code>, <code>chani</code> and <code>natalia</code>. Without armor the matching identity shows its authored female outfit; with armor it retains the native armor and corrected head. Face expression remains neutral. See [[Female identities]] for examples and material limits. This improves the existing API, available since 0.1.5; it does not introduce a new NPC setter.

SetNpcCombatConfig

2026-10-20T13:29:24Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcCombatConfig =
<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;">AVAILABLE FROM UPDATE 0.1.5</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.5 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Updates NPC projectile combat configuration atomically.

== Syntax ==
<syntaxhighlight lang="lua">
setNpcCombatConfig(npcId, settings)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || Server-assigned NPC ID returned by spawnNpc; not a player ID.
|-
| <code>settings</code> || <code>table</code> || yes || Partial configuration table; unknown fields and invalid values reject the whole change. See details below.
|}

== Returns ==
Returns true when accepted, false for a rejected request. Acceptance is not proof of a rendered animation, projectile release or hit.

== Examples ==
<syntaxhighlight lang="lua" line>
setNpcCombatConfig(npcId, {range=3, aimTimeMs=600, consumeMana=true})
</syntaxhighlight>

== Notes ==
* Server-side only. Mutations require the NPC to belong to the calling resource; getters do not grant control.
* Introduced in 0.1.5. Use matching client/server versions; the meleeSkillTier extension below requires 0.1.7.
* Use matching updated client and server. See [[NPC scripting]] for lifecycle, defaults, combat examples and collision limitations.
* Fields: range (metres 1..40, default 15), dexterity (0..100000, default 10), skillTier (integer 0..2, default 0), aimTimeMs (integer 150..30000, default 600), cooldownMs (integer 360..60000, default 1000), consumeAmmo/consumeMana (booleans, default true). Spell range/cooldown still apply. Configuration changes interrupt pending preparation. Disabling consumption still requires sufficient initial resources.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:NPC Functions]]


== NPC melee skill tiers (since 0.1.7) ==
The functions themselves remain available since 0.1.5. '''Only the additions below are new in 0.1.7'''; they require matching 0.1.7 client/server support.

* [[setNpcCombatConfig]] accepts optional <code>meleeSkillTier</code>: integer 0 (untrained, default), 1 (trained) or 2 (master). [[getNpcCombatConfig]] includes this field in its result table.
* <code>skillTier</code> remains the separate ranged-combat tier. Changing the melee tier does not overwrite ranged settings. Omitted fields keep their existing values; invalid/unknown fields reject the entire change.
* This selects ordinary melee presentation/timing for the NPC's equipped family, not its weapon or damage. It does not enable combat, select a target or increase strength/damage. Existing resource ownership and combat controls still apply.
* A strike already admitted keeps its captured animation/impact deadline. A melee-only or unchanged update does not restart unrelated projectile preparation; changing ranged settings still affects that separate configuration.
* Use matching updated client/server support to see the new tier presentation, including observers and late join. Players continue using the existing [[setPlayerSkill]] API; no new setPlayerCombatStyle function was added.

<syntaxhighlight lang="lua">
-- npcId is an existing NPC owned by this server resource.
local ok = setNpcCombatConfig(npcId, {meleeSkillTier=2})
if ok then
local config = getNpcCombatConfig(npcId)
if config then outputDebugString("NPC melee tier: " .. config.meleeSkillTier) end
end
</syntaxhighlight>




== Item-type armor bonuses (from 0.1.9) ==
[[Item type stats]] adds explicit armor bonusHealth/bonusMana/bonusStrength/bonusDexterity contributions for equipped scripted NPCs, plus the armor protection profile. Unconfigured native bonuses do not silently change existing NPC balance. Base stats and bonuses are separate; raising maxima does not heal/refill and lowering maxima clamps current values without reviving dead NPCs.

setNpcMaxHealth/setNpcMaxMana set BASE maxima; getNpcMaxHealth/getNpcMaxMana return EFFECTIVE maxima. setNpcCombatConfig/getNpcCombatConfig dexterity is BASE dexterity. getNpcData adds baseMaxHealth, baseMaxMana, baseDexterity, mana, maxMana, dexterity, armorHealthBonus, armorManaBonus, armorStrengthBonus and armorDexterityBonus.

NPC melee includes explicit armor strength and ranged combat uses effective dexterity. Numeric refresh preserves accepted attack/projectile snapshots; it does not reload ammo or restart prepared casts. NPC toughness and NPC jewelry are not implemented by this addition. These are extensions to existing APIs, not new names or a replacement for their earlier contracts.

SetNpcArmorUpgrades

2026-10-20T13:29:22Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcArmorUpgrades =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9.</div>
</div>

Replaces all three selected armor-upgrade slots for a resource-owned NPC.

== Syntax ==
<syntaxhighlight lang="lua">
accepted = setNpcArmorUpgrades(npcId, parts)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>number</code> || yes || Existing scripted human NPC ID: finite integer 1..4294967295, not a numeric string.
|-
| <code>parts</code> || <code>table</code> || yes || String keys top/mid/bottom only, with compatible part-key string values. Omitted slots, empty strings or none clear a slot. {} clears all parts.
|}

== Returns ==
Boolean: true when accepted; false for invalid arguments/selection, unavailable character, wrong family/slot, or failed ownership/requirements. Invalid selections are rejected before equipment mutation.

== Examples ==
<syntaxhighlight lang="lua" line>
-- NPC already wears mercenary and belongs to this resource.
local presets = getArmorUpgradePresets("mercenary")
if presets and presets.heavy_2 then
assert(setNpcArmorUpgrades(npcId, presets.heavy_2))
end
</syntaxhighlight>

== Notes ==
* Server-side only; available from 0.1.9.
* See [[Armor upgrades]], [[Armor catalog]] and [[Armor upgrade catalog]].
* Only the resource owning the NPC may change its parts. No player-inventory or player-requirement check is applied to NPCs.
* Uses the already equipped base; never selects a different base. The part must match its family and slot.
* true confirms server acceptance, not completed native rendering. No automatic healing/refill or database save.
* Treat remote requests as untrusted; authorize the action in your server resource.
* This is replacement, NOT a partial patch. Read the current table and modify one field to preserve the other slots. Values are keys, not item IDs; unknown table fields and non-string values reject the request.
* Equivalent alias: SetNpcArmorUpgrades.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Equipment Functions]]
[[Category:NPC Functions]]

SetNpcArmorPreset

2026-10-20T13:29:21Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcArmorPreset =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9.</div>
</div>

Selects an authored armor preset for the currently equipped base.

== Syntax ==
<syntaxhighlight lang="lua">
accepted = setNpcArmorPreset(npcId, preset)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>number</code> || yes || Existing scripted human NPC ID: finite integer 1..4294967295, not a numeric string.
|-
| <code>preset</code> || <code>string</code> || yes || light_1, light_2, medium_1, medium_2, heavy_1, heavy_2, or none to clear selected parts.
|}

== Returns ==
Boolean: true when accepted; false for invalid/unavailable ID, unknown/inapplicable preset, or failed validation/ownership/requirements. none clears parts without removing the base.

== Examples ==
<syntaxhighlight lang="lua" line>
-- npcId is an existing human NPC created by this resource.
assert(setNpcArmor(npcId, "mercenary"))
assert(setNpcArmorPreset(npcId, "heavy_2"))
local parts = getNpcArmorUpgrades(npcId)
if parts then outputDebugString(parts.top) end
</syntaxhighlight>

== Notes ==
* Server-side only; available from 0.1.9.
* See [[Armor upgrades]], [[Armor catalog]] and [[Armor upgrade catalog]].
* Only the resource owning the NPC may change its parts. No player-inventory or player-requirement check is applied to NPCs.
* Uses the already equipped base; never selects a different base. The part must match its family and slot.
* true confirms server acceptance, not completed native rendering. No automatic healing/refill or database save.
* Treat remote requests as untrusted; authorize the action in your server resource.
* Sparse families use only existing parts up to the requested tier, so different presets may select the same pieces. Query getArmorUpgradePresets first.
* Equivalent alias: SetNpcArmorPreset.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Equipment Functions]]
[[Category:NPC Functions]]

SetNpcArmor

2026-10-20T13:29:19Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNpcArmor =
Changes the authoritative armor of a resource-owned scripted NPC.

== Syntax ==
<syntaxhighlight lang="lua">
bool setNpcArmor(int npcId, string itemKey)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>npcId</code> || <code>int</code> || yes || The server-assigned NPC identifier returned by <code>spawnNpc</code> or <code>getNpcs</code>.
|-
| <code>itemKey</code> || <code>string</code> || yes || A validated key returned by <code>getPlayerArmorNames</code>; armor and weapon accept <code>none</code> to clear the slot.
|}

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

== Examples ==
Change an NPC's armor:
<syntaxhighlight lang="lua" line>
setNpcArmor(npcId, "none")
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The state is sent reliably to current viewers and replayed on relevance entry and late join.
* Raw Unreal object paths are never accepted from Lua.
* Use <code>getPlayerArmorNames</code> to enumerate supported keys.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:World Functions]]
[[Category:NPC Functions]]
[[Category:Equipment Functions]]


== Appearance API since 0.1.5 ==
From 0.1.5 [[setNpcIdentity]], [[setNpcSkinColor]] and [[setNpcTattoo]] remain independent of armor. Changing or removing armor does not clear these values. Covered skin/tattoo regions naturally remain hidden by garments.



== Armor parts (from 0.1.9) ==
Available from 0.1.9. [[Armor catalog]] lists the 26 bases; [[Armor upgrade catalog]] lists all 84 pieces. This existing function/guide is not newly introduced in 0.1.9. The new [[Armor upgrades|upgrade system]] adds per-character top/mid/bottom selections, full presets and separate player/NPC setters. A different base clears the old parts; choosing the same base keeps compatible selections. Identity, skin tint and tattoos remain separate. See the guide for requirements, safe replacement and synchronization validation.

SetNativeHudComponentVisible

2026-10-20T13:29:17Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setNativeHudComponentVisible =
<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;">AVAILABLE FROM UPDATE 0.1.7</div>
<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.7 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Hide or release one native HUD group without removing the native UI root.

== Syntax ==
<syntaxhighlight lang="lua">
requestId = setNativeHudComponentVisible(component, visible)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>component</code> || <code>string</code> || yes || bars, crosshair, interaction, hotbar, notifications, combat_markers, or all (case-sensitive). From 0.1.9: also crafting; all includes it.
|-
| <code>visible</code> || <code>boolean</code> || yes || false hides the group; true releases this resource's restriction.
|}

== Returns ==
Positive numeric request ID if queued, or <code>false</code> if rejected. This is not an application acknowledgement. Unknown component keys return <code>false</code>.

== Examples ==
<syntaxhighlight lang="lua" line>
setNativeHudComponentVisible("bars", false)
setNativeHudComponentVisible("interaction", false)
</syntaxhighlight>

== Notes ==
* Client-side only; the original API exists since 0.1.7. Crafting extensions require 0.1.9; use matching updated client/server versions.
* See [[Native HUD and menus]] for asynchronous acknowledgements, resource ownership, input and restoration.
* A positive request ID means queued, not applied. Listen for [[onClientNativeUiResult]] and inspect [[getNativeUiState]].
* Register the handler before submitting. Rapid changes coalesce: track the latest request ID, not every intermediate ID.
* false restricts; true releases only the calling resource's restriction. Other resources remain respected.
* This does not change inventory data, player attributes or custom RmlUi documents. Native save/load cannot be re-enabled.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:GUI Functions]]


== Crafting presentation from 0.1.9 ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[Native crafting UI]] documents the new crafting component, recipe/progress windows, preserved station entry/exit and prevention of invisible recipe starts. It is not a setNativeMenuEnabled key or a custom recipe API. getNativeUiState gains components.crafting, craftingReady, craftingGuardReady, craftingWidgets and craftingObserved; HUD bit 64 is appended, older bits unchanged. Existing resource ownership, asynchronous result handling and restoration still apply. Full station-by-station in-game qualification remains pending.

SetItemStatsBatch

2026-10-20T13:29:14Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setItemStatsBatch =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9. See the scope and validation notes below.</div>
</div>

Patches several item types in one validated transaction.

== Syntax ==
<syntaxhighlight lang="lua">
accepted, error, revision = setItemStatsBatch(items)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>items</code> || <code>table</code> || yes || Map of item keys to property/value tables, not an array of item records.
|}

== Returns ==
Three values: accepted (boolean), error (string; empty on success), revision (decimal string). Check accepted before using the revision. Success means server acceptance, not visual/client completion. A no-op may return the unchanged revision.

== Examples ==
<syntaxhighlight lang="lua" line>
local ok, why = setItemStatsBatch({
["1h_sword_short_02"]={damage=60},
mercenary={resistanceEdge=80},
itfo_potion_mana_03={mana=31}
})
assert(ok, why)
</syntaxhighlight>

== Notes ==
* Available from G1R:MP 0.1.9. This documents the implemented API and its current limits. See [[Item type stats]] for scope and remaining in-game validation.
* Server-side only. Profiles affect every copy of the same type on this server, across dimensions; not individual item instances.
* Use matching supported client and server builds. Server acceptance and a client application report do not prove the native gameplay effect.
* Active overrides are owned per item type by the calling resource. Another resource cannot change that owned type. Resource stop removes its overrides.
* Validation is atomic for the submitted transaction. Unsupported fields, wrong families, invalid/non-finite values, duplicate item/property aliases or ownership conflicts reject it.
* A numeric 0 is an explicit value where allowed, not reset. Use resetItemStats to remove an override. Profiles are not automatically persisted.
* Do not expose this setter directly to untrusted remote events. See [[getItemStatDefinitions]] and [[Item stat properties]].
* This merges fields. Types/fields omitted from the batch retain their previous overrides; use replaceItemStatsProfile for full replacement.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Inventory Functions]]
[[Category:Equipment Functions]]
[[Category:Experimental Lua API]]

SetItemStats

2026-10-20T13:29:12Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setItemStats =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9. See the scope and validation notes below.</div>
</div>

Changes selected numeric properties of one item type.

== Syntax ==
<syntaxhighlight lang="lua">
accepted, error, revision = setItemStats(item, fields)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>item</code> || <code>string</code> || yes || Known canonical item key or recognized alias; this is not an inventory-instance ID.
|-
| <code>fields</code> || <code>table</code> || yes || Property-name to numeric value map. Omitted fields are preserved; check per-item support and ranges.
|}

== Returns ==
Three values: accepted (boolean), error (string; empty on success), revision (decimal string). Check accepted before using the revision. Success means server acceptance, not visual/client completion. A no-op may return the unchanged revision.

== Examples ==
<syntaxhighlight lang="lua" line>
local ok, why = setItemStats("mercenary", {
resistanceEdge=80, resistanceBlunt=60, resistancePoint=50,
resistanceFire=30, bonusHealth=25
})
assert(ok, why)
</syntaxhighlight>

== Notes ==
* Available from G1R:MP 0.1.9. This documents the implemented API and its current limits. See [[Item type stats]] for scope and remaining in-game validation.
* Server-side only. Profiles affect every copy of the same type on this server, across dimensions; not individual item instances.
* Use matching supported client and server builds. Server acceptance and a client application report do not prove the native gameplay effect.
* Active overrides are owned per item type by the calling resource. Another resource cannot change that owned type. Resource stop removes its overrides.
* Validation is atomic for the submitted transaction. Unsupported fields, wrong families, invalid/non-finite values, duplicate item/property aliases or ownership conflicts reject it.
* A numeric 0 is an explicit value where allowed, not reset. Use resetItemStats to remove an override. Profiles are not automatically persisted.
* Do not expose this setter directly to untrusted remote events. See [[getItemStatDefinitions]] and [[Item stat properties]].

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Inventory Functions]]
[[Category:Equipment Functions]]
[[Category:Experimental Lua API]]

SetDiscordApplicationId

2026-10-20T13:29:11Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= setDiscordApplicationId =
'''Available from 0.1.9. Use matching updated clients and server.'''

'''Server-side only.''' Part of [[Discord Rich Presence]]. See [[Discord Presence configuration]] for the optional server-owner resource.
== Syntax ==
<syntaxhighlight lang="lua">
local ok, reason = setDiscordApplicationId("YOUR_PUBLIC_APPLICATION_ID")
</syntaxhighlight>
== Parameters and behavior ==
One public Discord Application ID as a decimal string, 17..20 digits, nonzero with no leading zero and within unsigned 64-bit range. Do not use a Lua number, guild/user ID, Client Secret or bot token. This setting belongs to the calling resource. It affects subsequent set/update calls; already queued profiles retain their previous ID until updated.
== Returns ==
Boolean success plus an empty string, or false plus application-id-must-be-a-decimal-string. Rejection preserves the previous configured ID.
== Examples, lifecycle and safety ==
See [[Discord Rich Presence]] for complete initialization, location/job updates, field removal, timestamps, counts, buttons and callback examples. Player launcher opt-in is off by default and cannot be overridden. No bot or token is needed; no Discord account identity is returned. Do not forward arbitrary client input to this server API.
[[Category:Lua Functions]]
[[Category:Server Functions]]

Server configuration limits

2026-10-20T13:29:10Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

{{DISPLAYTITLE:Server configuration limits}}
<div style="border-left:4px solid #c33;padding:0.7em 1em;background:#fff5f5">'''CURRENT IN UPDATE 0.1.3 — expanded-budget BUILD81 (2026-09-12).'''</div>
All numeric ranges below are extracted from the production configuration parser, not guessed from a running server. Defaults are the compiled defaults; an explicit setting in your existing configuration overrides them. Invalid out-of-range values fail configuration loading instead of being silently clamped. Restart with the new server executable/configuration to apply changes. Do not overwrite your passwords, keys or other custom settings with a sample configuration.

See [[Scripting limits]] for fixed API capacities and client limits. Server <code>[lua]</code> settings do not propagate to the client VM.

== Complete numeric configuration table ==
{| class="wikitable sortable"
! Setting !! Compiled default !! Minimum !! Maximum !! Unit
|-
| <code>server.port</code> || 7777 || 1 || 65535 || TCP/UDP port
|-
| <code>server.maxPlayers</code> || 500 || 1 || 5000 || count / integer
|-
| <code>server.tickrate</code> || 30 || 1 || 240 || ticks/s
|-
| <code>server.syncDistance</code> || 15000 || 500 || 200000 || cm (100 cm = 1 m)
|-
| <code>server.peerTimeoutMinimumMs</code> || 20000 || 5000 || 60000 || ms
|-
| <code>server.peerTimeoutMaximumMs</code> || 40000 || 5000 || 120000 || ms
|-
| <code>server.peerTimeoutLimit</code> || 32 || 4 || 64 || count / integer
|-
| <code>http.port</code> || 7780 || 1 || 65535 || TCP/UDP port
|-
| <code>http.workerThreads</code> || 8 || 1 || 64 || count / integer
|-
| <code>http.maxQueuedRequests</code> || 1024 || 8 || 16384 || count / integer
|-
| <code>http.requestsPerMinutePerIp</code> || 1200 || 60 || 100000 || per minute
|-
| <code>http.maxTrackedAddresses</code> || 8192 || 256 || 1000000 || count / integer
|-
| <code>http.readTimeoutMs</code> || 5000 || 500 || 120000 || ms
|-
| <code>http.writeTimeoutMs</code> || 30000 || 1000 || 600000 || ms
|-
| <code>nameplates.maxPairs</code> || 250000 || 1 || 1000000 || count / integer
|-
| <code>nameplates.maxPairsPerResource</code> || 250000 || 1 || 1000000 || count / integer
|-
| <code>nameplates.mutationsPerSecond</code> || 4096 || 1 || 250000 || per second
|-
| <code>nameplates.mutationBurst</code> || 8192 || 1 || 250000 || count / integer
|-
| <code>voice.port</code> || 7778 || 1 || 65535 || TCP/UDP port
|-
| <code>voice.ticketTtlMs</code> || 15000 || 1000 || 120000 || ms
|-
| <code>voice.idleTimeoutMs</code> || 5000 || 2000 || 120000 || ms
|-
| <code>voice.heartbeatIntervalMs</code> || 1000 || 250 || 10000 || ms
|-
| <code>voice.maxFramesPerSecond</code> || 55 || 10 || 200 || per second
|-
| <code>voice.maxBytesPerSecond</code> || 65536 || 8192 || 1048576 || bytes/s
|-
| <code>voice.maxPendingHandshakes</code> || 128 || 1 || 4096 || count / integer
|-
| <code>voice.maxConnectionsPerIp</code> || 32 || 1 || 1000 || count / integer
|-
| <code>voice.maxTrackedAddresses</code> || 16384 || 256 || 1000000 || count / integer
|-
| <code>voice.whisperRange</code> || 500 || 50 || 200000 || cm (100 cm = 1 m)
|-
| <code>voice.defaultRange</code> || 1800 || 50 || 200000 || cm (100 cm = 1 m)
|-
| <code>voice.shoutRange</code> || 3500 || 50 || 200000 || cm (100 cm = 1 m)
|-
| <code>voice.maxRange</code> || 10000 || 50 || 200000 || cm (100 cm = 1 m)
|-
| <code>lua.memoryLimitMB</code> || 1024 || 4 || 4096 || MiB
|-
| <code>lua.instructionLimit</code> || 10000000 || 10000 || 1000000000 || count / integer
|-
| <code>lua.timeoutMs</code> || 5000 || 10 || 60000 || ms
|-
| <code>lua.hookInstructionInterval</code> || 10000 || 100 || 1000000 || count / integer
|-
| <code>magic.projectileTickrate</code> || 30 || 10 || 120 || ticks/s
|-
| <code>magic.maxCastsPerSecond</code> || 6 || 1 || 30 || per second
|-
| <code>magic.maxSnapshotAgeMs</code> || 1000 || 100 || 10000 || ms
|-
| <code>magic.playerCapsuleRadius</code> || 45 || 10 || 500 || cm (100 cm = 1 m)
|-
| <code>magic.playerCapsuleHalfHeight</code> || 90 || 20 || 1000 || cm (100 cm = 1 m)
|-
| <code>ranged.projectileTickrate</code> || 30 || 10 || 120 || ticks/s
|-
| <code>ranged.maxShotsPerSecond</code> || 8 || 1 || 30 || per second
|-
| <code>ranged.maxSnapshotAgeMs</code> || 1000 || 100 || 10000 || ms
|-
| <code>ranged.developmentArrowCount</code> || 0 || 0 || 65535 || count / integer
|-
| <code>ranged.developmentBoltCount</code> || 0 || 0 || 65535 || count / integer
|-
| <code>ranged.playerCapsuleRadius</code> || 45 || 10 || 500 || cm (100 cm = 1 m)
|-
| <code>ranged.playerCapsuleHalfHeight</code> || 90 || 20 || 1000 || cm (100 cm = 1 m)
|-
| <code>rcon.port</code> || 7781 || 1 || 65535 || TCP/UDP port
|-
| <code>rcon.timestampWindowSeconds</code> || 30 || 5 || 300 || s
|-
| <code>rcon.requestsPerMinute</code> || 60 || 1 || 600 || per minute
|-
| <code>security.handshakeTimeoutMs</code> || 5000 || 1000 || 30000 || ms
|-
| <code>security.maxConnectionsPerIp</code> || 32 || 1 || 1000 || count / integer
|-
| <code>security.maxPendingHandshakes</code> || 128 || 1 || 2048 || count / integer
|-
| <code>security.connectionAttemptsPerMinute</code> || 120 || 1 || 100000 || per minute
|-
| <code>security.preAuthPacketsPerSecond</code> || 12 || 1 || 1000 || per second
|-
| <code>security.authenticatedPacketsPerSecond</code> || 240 || 30 || 10000 || per second
|-
| <code>security.authenticatedBytesPerSecond</code> || 524288 || 65536 || 67108864 || bytes/s
|-
| <code>security.invalidPacketsPerMinute</code> || 16 || 1 || 10000 || per minute
|-
| <code>security.temporaryBlockSeconds</code> || 120 || 10 || 86400 || s
|-
| <code>security.maxTrackedAddresses</code> || 16384 || 256 || 1000000 || count / integer
|-
| <code>security.maxPacketBytes</code> || 65536 || 16384 || 1048576 || bytes
|-
| <code>security.maxWaitingDataPerPeerBytes</code> || 524288 || 65536 || 16777216 || bytes
|-
| <code>world.day</code> || 0 || 0 || 1000000 || count / integer
|-
| <code>world.hour</code> || 8 || 0 || 23 || count / integer
|-
| <code>world.minute</code> || 0 || 0 || 59 || count / integer
|-
| <code>world.minuteDurationMs</code> || 1000 || 0 || 3600000 || ms
|-
| <code>world.weatherTransitionMs</code> || 3000 || 0 || 300000 || ms
|-
| <code>world.syncIntervalMs</code> || 5000 || 500 || 60000 || ms
|-
| <code>database.workerThreads</code> || 8 || 1 || 64 || count / integer
|-
| <code>database.maxConnectionsPerResource</code> || 16 || 1 || 128 || count / integer
|-
| <code>database.maxPendingQueriesPerResource</code> || 1024 || 1 || 100000 || count / integer
|-
| <code>database.maxQueryBytes</code> || 4194304 || 1024 || 67108864 || bytes
|-
| <code>database.maxResultRows</code> || 50000 || 1 || 1000000 || count / integer
|-
| <code>database.maxResultBytes</code> || 67108864 || 1024 || 536870912 || bytes
|-
| <code>database.connectTimeoutMs</code> || 5000 || 100 || 120000 || ms
|-
| <code>database.readTimeoutMs</code> || 15000 || 100 || 300000 || ms
|-
| <code>database.writeTimeoutMs</code> || 15000 || 100 || 300000 || ms
|-
| <code>database.maxBlockingPollMs</code> || 100 || 0 || 5000 || ms
|-
| <code>security.passwordWorkerThreads</code> || 4 || 1 || 8 || count / integer
|-
| <code>security.passwordQueueCapacity</code> || 1024 || 8 || 4096 || count / integer
|-
| <code>security.passwordPendingPerResource</code> || 256 || 1 || 512 || count / integer
|-
| <code>security.passwordMemoryKiB</code> || 65536 || 8192 || 1048576 || KiB
|-
| <code>security.passwordIterations</code> || 3 || 1 || 10 || count / integer
|-
| <code>security.passwordParallelism</code> || 1 || 1 || 4 || count / integer
|}

== Additional validation and units ==
* Peer timeout maximum must be at least the minimum. Voice idle timeout must be at least twice its heartbeat interval.
* Voice ranges must satisfy whisper <= default <= shout <= max. These configuration values and <code>server.syncDistance</code> are '''centimetres''', not the metre units used by camera, NPC route and 3D-text Lua functions.
* <code>world.minuteDurationMs=0</code> pauses time. Day 0..1000000, hour 0..23 and minute 0..59 are separate limits.
* Enabled voice must use a different port from gameplay, resource HTTP and enabled RCON.
* At least one autostart resource and a nonempty navigation map filename are required. Navigation geometry settings are not exposed as numeric serverconf settings; see [[Scripting limits#Navigation]].
* Listing/name text: server name at most 96 UTF-8 bytes and 48 codepoints; description at most 320 bytes and 160 codepoints. Game mode is an ASCII token up to 24 bytes, region 12, version 24; at most 8 tags of 16 bytes each. Join password is at most 128 bytes.
* Production master-list heartbeat is fixed at 20 seconds and authorization maximum staleness at 300 seconds. These are not operator-adjustable Lua limits. Device identity verification remains mandatory.
* Rate controls are shared traffic budgets, not one independent allowance per Lua event. Increasing Lua storage does not disable anti-abuse controls.

== Source audit ==
The numeric table above records the configuration/parser audit for 0.1.3 dated 2026-09-12; it is not a new complete configuration audit for 0.1.9. Later scoped additions are documented separately below and in their feature guides.

[[Category:Lua API]]


== Extended weather configuration (from 0.1.9) ==
'''Available from 0.1.9. Use matching updated clients and server.'''

The world weather setting accepts the canonical names and aliases in [[Weather catalog]]. Weather transition remains 0..300000 milliseconds. Existing modes remain biome-dependent; explicit presets add snow, fog, dust and regional variations. See [[Weather]] for examples. This does not change current public-release configuration support.



== Optional Discord presence (from 0.1.9) ==
'''Available from 0.1.9. Use matching updated clients and server.'''

[[Discord Presence configuration]] provides the complete server-only resource. Configure its public Application ID and presentation fields in config.lua, then append its name to your existing resources autostart list. No new [discord] INI section, bot token, Client Secret, Discord installation, Python or SDK is needed on either Windows or Linux dedicated servers. Players opt in separately in launcher Settings and rejoin. Keep existing gamemode/server settings; do not enable development QA commands publicly.

Scripting limits

2026-10-20T13:29:08Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

{{DISPLAYTITLE:Scripting limits}}
<div style="border-left:4px solid #c33;padding:0.7em 1em;background:#fff5f5">'''BASELINE: UPDATE 0.1.3 — expanded-budget BUILD81 (2026-09-12).''' Earlier 0.1.3 binaries have smaller capacities. Update the server and the complete client/launcher package before relying on the expanded limits.</div>

'''0.1.4 additions are explicitly marked below:''' [[os.time]] and resource-file/GUI security in BUILD126; static [[RmlUi images|WebP images]] in BUILD125; map-editor capacities in BUILD124. The current public release is 0.1.9 / BUILD264 / Protocol 42. Historical baseline values and version-specific additions are distinguished below.

This reference lists the current developer-facing Lua, resource, API, queue and configuration limits audited in source. It distinguishes '''fixed capacities''', '''compiled defaults''' and '''operator-configurable bounds'''. It does not treat every internal rendering/physics constant as a scripting limit or guarantee that the maximum workload will run smoothly on every machine.

* [[Server configuration limits|All 84 numeric server settings: default, minimum, maximum and units]]
* [[Player statistic limits|All 59 player statistic ranges]]
* [[Lua API catalogs|Allowed appearance, equipment, monster and other catalog keys]]

'''Units:''' KiB = 1024 bytes; MiB = 1024 KiB; GiB = 1024 MiB. String limits count bytes unless a separate Unicode-codepoint limit is stated. Most position-based Lua functions use metres; '''server sync-distance configuration and voice range use centimetres'''. Times are milliseconds unless stated otherwise. Coordinates must be finite; numeric validity is not a promise that playable terrain exists at that position.

== Lua VM and execution ==
{| class="wikitable"
! Limit !! Client !! Server !! Scope / behaviour
|-
| Lua VM allocation budget || 1024 MiB || 1024 MiB default; configurable 4..4096 MiB || Per resource/VM. Allocated on demand, not reserved on resource startup. This is not a cap on total process/native allocations, textures, audio or database buffers.
|-
| Instruction budget || 10000000 || 10000000 default; configurable 10000..1000000000 || Reset on each protected script chunk/callback invocation. Exceeding it raises a Lua error.
|-
| Execution timeout || 5000 ms || 5000 ms default; configurable 10..60000 ms || Cooperative Lua-hook check, not an OS watchdog and not preemption of a blocking native API call.
|-
| Hook interval || 10000 instructions || 10000 default; configurable 100..1000000 || Budgets are checked in samples; execution can pass a nominal boundary before the next check.
|}

Server settings are <code>lua.memoryLimitMB</code>, <code>lua.instructionLimit</code>, <code>lua.timeoutMs</code>, <code>lua.hookInstructionInterval</code>. They '''do not propagate to the client'''. An existing configuration retaining older values overrides the new server defaults. The production and bundled GothicRP-test configuration templates now use the expanded Lua/DB defaults.

Lua is the sandboxed LuaJIT/Lua 5.1 environment with JIT disabled. Base, table, string and math libraries are exposed; general filesystem/OS/module-loading access is not. <code>dofile</code>, <code>load</code>, <code>loadfile</code>, <code>loadstring</code>, <code>getfenv</code>, <code>setfenv</code>, <code>collectgarbage</code>, <code>newproxy</code>, <code>coroutine</code>, <code>io</code>, <code>package</code>, <code>debug</code>, <code>jit</code>, <code>ffi</code> and <code>string.dump</code> are unavailable. Lua bytecode is rejected. Increasing capacity does not weaken sandbox, hash, ownership, path or network validation.

=== Safe wall-clock time (since 0.1.4 BUILD126) ===
The <code>os</code> table remains unavailable in 0.1.3. Since '''0.1.4 BUILD126''', client and server resources receive a restricted table containing only [[os.time|os.time()]]. It returns Unix seconds from the local host clock and accepts no arguments (not even a date table or explicit nil). The full OS library is never opened: <code>os.execute</code>, <code>os.exit</code>, filesystem operations, environment access and all other OS-library members remain unavailable.
<syntaxhighlight lang="lua">
-- Seed once at resource startup, not before every draw.
math.randomseed(os.time())
local roll = math.random(1, 100)
</syntaxhighlight>
This is ordinary, non-cryptographic randomness. Use [[getTickCount]] for elapsed time; wall-clock time can change and client clocks are not authoritative. See [[os.time]] for the complete contract.

== Timers, handlers and commands ==
{| class="wikitable"
! Capacity !! Client, per resource !! Server
|-
| Timers || 8192 (previously 256) || No additional fixed timer-count cap in the server Lua API; still subject to memory and execution cost.
|-
| Timer callbacks selected per tick || 256 (previously 32), oldest deadline first || No matching fixed per-tick callback-count cap. Due timers are processed by the server runtime.
|-
| Event handlers, total || 8192 (previously 256) || No additional fixed count cap in the registration API.
|-
| Handlers for one event || 512 (previously 32) || No matching fixed per-event count cap.
|-
| Declared remote event names || 4096 (previously 256) || No additional fixed registration-count cap.
|-
| Key bindings || 1024 (previously 128) || Client-only feature.
|}

Both timer APIs require an interval of at least '''10 ms'''; interval and repeat-count parameters are unsigned 32-bit values. Repeat count <code>0</code> means repeat indefinitely. This is not a precision guarantee: timer dispatch follows runtime ticks, and missed intervals are not replayed in an unlimited catch-up loop. Client timers and key bindings accept at most '''32 callback arguments'''. Cancelled client timers leave their storage slots when the tick removes cancelled entries. Client <code>setTimer</code> returns <code>0</code> on rejection; handler/key-binding registration returns <code>false</code>. Check return values.

Client selection is deadline-ordered and snapshots timer IDs before callbacks. Large batches of fast repeating timers therefore do not permanently starve later timers; callbacks may still be delayed by load. Do not use thousands of 10-ms timers as a substitute for batching work.

Server local event dispatch has a recursion-depth limit of '''32'''; nested command execution has a depth limit of '''16'''. Command names are nonempty and at most '''64 bytes'''. <code>executeCommandHandler</code> accepts at most '''32 arguments''' with at most '''2048 bytes''' of converted argument text in total. These recursion guards are not capacities for how many independent events/commands a gamemode can declare.

== Network events and IPC ==
{| class="wikitable"
! Field !! Fixed limit
|-
| Resource name in an event envelope || 96 bytes
|-
| Event name || 128 bytes
|-
| Arguments per serialized resource event || 32
|-
| One event string || 32 KiB
|-
| Complete serialized resource event || 64 KiB, including headers, names and all arguments
|-
| Client IPC payload || 64 KiB
|-
| IPC buffered bytes / queued frames || 256 KiB / 256 frames; separate guards
|}

Values transported directly are nil, boolean, integer/number and string, '''not Lua tables, functions or userdata'''. Client local event argument conversion also uses the 32-argument/32-KiB-string guards. Server-local callbacks should not be confused with serialized network messages. Lua numbers do not represent every 64-bit integer exactly: keep large opaque identifiers as strings where the API specifies strings.

'''A 1-MiB JSON document cannot be sent as one event string.''' The expanded JSON limit is for local serialization/storage; the event envelope is unchanged. For bulk application data, use bounded application-level chunks or appropriate resource/HTTP/database facilities. Validate sender permissions, payloads and request rates. Packet/IP budgets in [[Server configuration limits]] still apply to the connection as a whole.

== Resource files and downloads ==
{| class="wikitable"
! Capacity !! BUILD81 value !! Previous value
|-
| One Lua source file || 128 MiB || 64 MiB
|-
| One resource file || 256 MiB || 64 MiB
|-
| All files in the client download catalog || 32 GiB || 8 GiB
|-
| Catalog file count || 262144 || 65536
|-
| Serialized catalog document || 128 MiB || 64 MiB
|}

The download totals cover client/shared scripts and declared files, not server-only scripts. Server-only Lua files still have their individual Lua source-file cap. Server, launcher and client share these constants. A resource exceeding the old client limits will not work with old launchers simply because the server was updated.

Client catalog relative paths are at most '''512 bytes''', with at most '''128 bytes per segment'''; file URLs are at most '''2048 bytes'''. Resource names used across the whole scripting/network stack should fit the stricter '''96-byte event-name envelope field''' even though filesystem-side validators allow longer names. Paths must stay inside the resource, use the accepted relative-path syntax and refer to declared files; absolute paths and traversal are not enabled by larger file budgets.

=== Download and GUI security (since 0.1.4 BUILD126) ===
These 0.1.4 changes enforce a shared file policy in the server manifest/catalog and client catalog/download path. They do not increase the size budgets above.
* Allowed extensions (case-insensitive): <code>.lua .json .xml .txt .csv .rml .html .rcss .css .png .webp .tga .jpg .jpeg .bmp .svg .ttf .otf .woff .woff2 .ogg .wav .mp3 .flac</code>.
* This is a '''transport allowlist, not a decoder capability list'''. It does not enable JavaScript, arbitrary HTML-browser features, additional audio codecs or every listed image format. Existing Lua audio remains declared join-time Ogg; supported GUI image behaviour is documented in [[RmlUi images]].
* Executables and native modules such as <code>.exe .dll .asi .com .scr</code>, installers, shell scripts and shortcuts are not allowed. Recognized native executable headers (MZ/PE, ELF and Mach-O) are rejected even when renamed to an allowed suffix; cached files are checked too. This is defence in depth, '''not an antivirus or a guarantee that arbitrary content is harmless'''. Historical cache files are not automatically erased.
* Relative path segments use ASCII letters/digits, spaces, <code>_</code>, <code>-</code> and <code>.</code>; empty/dot/traversal segments, absolute paths, backslashes, alternate data streams, Windows reserved device names and trailing dots/spaces are rejected. Case-insensitive catalog collisions are rejected. The 512-byte path and 128-byte segment limits remain.
* The catalog's canonical SHA-256 must match the revision obtained from the official HTTPS server listing. Launcher/supervisor and client runtime enforce this pin before accepting resource payloads. An absent or stale listing is rejected, not replaced with an untrusted HTTP fallback. After changing resources, allow the official listing to refresh before rejoining. HTTP asset transfer remains unencrypted: integrity verification is not confidentiality.
* RmlUi reads verified, declared GUI assets owned by the requesting resource. Arbitrary local files, other resources, scripts and undeclared files are not available through GUI references. Resource file size/hash and final resolved paths are checked, including rejection of reparse/junction redirection. The host's explicitly approved system-font fallback is separate from resource access.
See [[Update 0.1.4]]; use the updated server and complete client/launcher package for these protections. The complete public 0.1.4 release uses Protocol 36; update both client and server.

== JSON ==
<code>toJSON</code>/<code>fromJSON</code> now allow '''1 MiB''', nesting depth '''64''' and '''65536 cumulative entries''' across the document (previously 32 KiB / 16 / 2048). Object keys remain at most '''256 bytes'''. Arrays must use contiguous positive indices; mixed array/object key tables, cyclic references and non-finite numbers are rejected. Failure returns <code>false</code> plus an error description. The byte cap applies to the serialized document, not to the full native/Lua memory consumed while processing it.

== Database and password work ==
{| class="wikitable"
! Compiled default !! BUILD81 value !! Configuration / scope
|-
| DB workers || 8 || Global worker pool
|-
| DB connections || 16 || Per resource
|-
| Pending DB queries || 1024 || Per resource
|-
| SQL statement || 4 MiB || Per query
|-
| DB result || 50000 rows and 64 MiB || Per result, both guards apply
|-
| DB timeouts || connect 5000 / read 15000 / write 15000 ms || Connection options may reduce, but not exceed, configured timeouts; minimum 100 ms
|-
| Blocking dbPoll || 100 ms maximum || Configurable; negative timeout becomes non-blocking and excessive timeout is clamped
|-
| Password workers / queue / pending per resource || 4 / 1024 / 256 || Password hashing/verifying service
|}

All configurable ranges are listed in [[Server configuration limits]]. Result overflow is reported as a database error (client result-limit error '''90001'''), not a successful partial result. Free/poll results and avoid unbounded result retention; use SQL pagination. MariaDB/MySQL can impose additional server-side limits, including its packet and connection settings, which this application does not automatically change.

Passwords for hash/verify are at most '''256 bytes'''; encoded hashes at most '''512 bytes'''. Default Argon2id parameters remain '''65536 KiB memory, 3 iterations, parallelism 1'''; larger queue capacity does not weaken hash security. DB multi-statements, multi-queries, local infile and automatic reconnect are not enabled as a side effect of the 0.1.3 capacity update. Separately, 0.1.4 adds explicit opt-in recovery; see [[MySQL connection recovery]].

== requestRemote ==
{| class="wikitable"
! Limit !! Value
|-
| Workers / queued work / pending per resource || 8 / 256 / 32 (compiled defaults)
|-
| URL || 2048 bytes
|-
| Request body / response body || 4 MiB / 8 MiB
|-
| Request headers / response headers || 128 / 256
|-
| Aggregate header bytes || 64 KiB
|-
| Header name / username / password || 128 / 512 / 512 bytes
|-
| Connection attempts || 1..3; default 1
|-
| Connect timeout || 500..10000 ms; default 5000
|-
| Total timeout || 1000..30000 ms; default 15000
|-
| Redirect count || 0..3; default 2
|}

Allowed methods are GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. Only the supported HTTP/HTTPS destinations are accepted. Loopback/private-address restrictions, DNS and redirect validation stay enabled in production. Capacity or validation rejection returns an error; asynchronous transfers also report completion errors. Keep callbacks short. The larger download-catalog file limit is '''not''' the requestRemote response limit.

== World entities and text ==
{| class="wikitable"
! Feature !! Fixed capacity / range
|-
| Active world items || 16384 globally (previously 4096); quantity 1..1000 per spawn
|-
| Active NPCs || 8192 globally (previously 2048)
|-
| Active monsters || 4096 globally (previously 1024)
|-
| NPC route || 1..1024 points (previously 256); each wait 0..3600000 ms; speed 0.1..12 m/s
|-
| NPC scripted movement arrival radius || 0.01..5 m
|-
| Monster scripted movement || speedScale >0 and <=1; Lua arrivalRadius 0.01..5 m
|-
| Monster max health / attack damage || max health >0 and <=1000000; damage 0..100000
|-
| NPC name || 3..16 bytes, without control characters
|-
| Monster/nameplate display text || At most 96 UTF-8 bytes and 48 codepoints
|-
| 3D text objects || 1024 per resource / 8192 globally (previously 256 / 2048)
|-
| 3D text content || Nonempty, at most 256 bytes AND 128 Unicode codepoints; no control characters/newlines
|-
| 3D text draw distance / scale || 1..1000 m / 0.25..5
|-
| Scripted world positions || Finite coordinates within +/-1000000 m per axis where the Lua position validator is used
|}

Global capacities are shared across resources. Creation above a capacity is rejected; it does not expand the cap or authorize mutation of another resource's entities. More accepted entities do not mean that placing all of them in one visible area is performant. Navigation, authoritative sync distance, client streaming and actual hardware still matter.

== Navigation ==
The compiled custom-collision capacities are '''16384 blockers globally / 4096 per owner''' (previously 4096 / 1024). The internal settings validator permits global capacity up to '''65536''', with owner capacity positive and no greater than global capacity. These are not extra numeric <code>serverconf.cfg</code> options.

* Lua custom blocker coordinates: +/-100000 m; size/height dimensions 0.01..10000 m; polygons 3..16 vertices and must pass geometry validation.
* Navigation artifact: at most 256 MiB and 200000 baked blockers (previously 64 MiB / 50000); polygon cap 16 vertices.
* Compiled search defaults remain grid cell 50 cm, detour margin 1200 cm, maximum slope 45 degrees, maximum path distance 30000 cm (300 m), maximum search nodes 120000.
* Internal settings bounds: grid cell 5..1000 cm; detour margin 0..50000 cm; slope >=0 and <89 degrees; path distance >=grid cell and <=1000000 cm; search nodes 64..1000000.
* Navigation failure/search exhaustion is not permission to cross blockers. See [[NPC and monster navigation collision]].

== Player state, appearance and nameplates ==
* Player names: 3..16 bytes, accepted player-name character set. Appearance, armor, weapons, spells, skills and tattoo selection use validated catalogs, not arbitrary game asset paths; see [[Lua API catalogs]].
* Skin RGB and display RGBA components: integers 0..255. Tattoo catalog: 12 presets. These are valid value ranges, not gamemode capacity budgets, and were not expanded.
* Inventory give/remove amount: 1..1000 per call. Server-controlled cumulative count: ammunition at most 65535, other supported items at most 100000. Ownership and item-specific rules still apply.
* Consumable grant count: 1..100; persistent consumable commit keys at most 96 bytes. This does not authorize trusting client-submitted permanent stats.
* All 59 stat ranges: [[Player statistic limits]]. Common HP/STR/DEX values cap at 100000; max-health minimum is 1. Level caps at 1000, magician level at 6; other stats have their own bounds.
* Scripted player damage amount: positive, at most 100000. Unconscious duration: 0 or 250..3600000 ms; configured health arguments must fit the relevant player-health range. Life-state checks still apply.
* Player/nameplate text: at most 96 UTF-8 bytes and 48 codepoints. Nameplate height offset is within +/-100 m.
* Observer-specific nameplates: defaults 250000 pairs globally and per resource; per-resource mutation budget 4096/s with burst 8192. Configurable ranges: [[Server configuration limits]]. These are directed observer/target overrides, not persistent database rows. Throttle bulk restore operations and handle rejected mutations.
* Nearby-player radius: 0..100000 m. Focus-query maximum distance: 0.1..1000 m; field of view: 1..180 degrees.
* Lua chat output: nonempty and at most 2048 bytes; chat RGB values are clamped to 0..255. Administrative <code>say</code> has its separate 512-byte message cap.
* Animation API catalog: 27 original aliases, 118 from 0.1.4, and 962 from 0.1.9 (844 additions). See [[Player animation catalog]] and [[Activity animation catalog]]. The blend argument range remains 0..2 seconds, default 0.15. Catalog keys are not raw asset paths; catalog size is not a simultaneous-animation capacity guarantee.
* Account binding key: 3..24 bytes with its validated identifier syntax; serial: 32 hexadecimal characters. Kick/ban reason: nonempty, at most 160 bytes, valid text without controls. Ban duration: 0 (permanent) or at most 5256000 minutes.

== Camera ==
Camera safety/representation ranges were not changed by this capacity update. '''There is no 100-metre distance-from-player restriction.''' Keep engine streaming and server relevance in mind; coordinate acceptance alone cannot guarantee valid/rendered terrain everywhere. See [[Scripted camera]].

{| class="wikitable"
! Parameter !! Limit
|-
| Camera command document || 24 KiB
|-
| Position/focus/path/orbit envelope || Finite coordinates within +/-1000000 m per axis
|-
| Path points || 1..32
|-
| FOV || 15..150 degrees
|-
| Rotation / orbit starting angle || Absolute value <=360000 degrees
|-
| Orbit sweep || Absolute value <=3600 degrees
|-
| Orbit radius / height offset || 0.1..50 m / absolute value <=50 m
|-
| Command duration || At most 600000 ms
|-
| Each path point || Duration 1..600000 ms; hold 0..600000 ms; sum of all durations and holds <=600000 ms per cycle
|-
| Orbit duration || 100..600000 ms
|-
| Reset blend || 0..10000 ms
|-
| Camera state document || At most 4096 bytes
|}

Looped paths/orbits can repeat; the per-cycle duration bound is not a total lifetime cap. Invalid commands are rejected, not silently replaced by a different camera path. Resource ownership and cleanup still apply.

== Client audio and UI ==
* Audio: '''128 sound handles per resource / 512 globally''' (previously 32 / 128). Declared join-time <code>.ogg</code> resource files only. Stop unused handles; an accepted handle is not a promise that hundreds of simultaneously mixed sounds are cheap.
* Sound volume 0..1; finite 3D coordinates +/-1000000 m; minimum distance >=0.01 m, maximum distance greater than minimum and <=10000 m. Audio paths must also satisfy the catalog's stricter relative-path bounds.
* UI texture files: at most '''256 MiB''' encoded (previously 64 MiB); decoded width and height remain at most '''8192 pixels each'''. This is not a VRAM allocation guarantee.
* '''Since 0.1.4 BUILD125:''' static lossy/lossless WebP with alpha works in RML images and RCSS image decorators; PNG support is retained. Animated WebP is rejected. No new Lua image function is required. See [[RmlUi images]] for manifest/RML examples and format restrictions. BUILD126 also hardens uncompressed 24/32-bit TGA validation and resource GUI reads.
* UI attribute name: 1..64 bytes with safe-name validation; attribute value at most '''16384 bytes''' (previously 4096). Event-handler attribute injection remains prohibited.
* GUI append-text retains at most '''1000 child lines''' per target element (previously 200), removing older children. This is not a cap on all elements in an RML document.
* No separate fixed document-count or general <code>setInnerRML</code> byte cap was found in the exposed UI API. Resource ownership, file limits, Lua/native memory and rendering cost still apply; this does not mean unlimited capacity.

== Voice ==
Voice remains a separate real-time stream: 48000 Hz, 960 samples/20-ms frame, two channels; encoded frame at most 512 bytes and voice datagram at most 768 bytes. Default sender budgets are 55 frames/s and 65536 bytes/s; see [[Server configuration limits]] for ranges.

'''Voice range values use centimetres''', including <code>setPlayerVoiceRange</code>/<code>getPlayerVoiceRange</code>. A positive finite custom range is normalized to 50 cm..configured <code>voice.maxRange</code>; defaults are whisper 500 cm (5 m), normal 1800 cm (18 m), shout 3500 cm (35 m), maximum 10000 cm (100 m). Voice volume is 0..2; channel ID 0..4294967295. Increasing Lua capacity does not alter voice gain, codec timing or anti-abuse limits.

== Validation and practical use ==
Focused follow-up: '''2026-09-20''', development '''0.1.4 BUILD125/126''', protocol '''35''': WebP, restricted [[os.time]], resource file policy and GUI loading. This is not a new audit of every historical numeric limit below. Earlier audit baseline follows.

Audit date: '''2026-09-12'''; expanded-budget '''0.1.3 BUILD81''', protocol '''34'''. Changes increase capacities, not packet layouts.

The test suite executes the real Lua runtimes with 8192 client timers / 8193 server timers, expanded handler/remote-event/key-binding capacities, JSON boundary and overflow cases, client timer fairness and restart/cleanup. Capacity boundaries are not a full in-game performance benchmark. Use staged loading, staggered timers, asynchronous DB/HTTP, pagination and explicit cleanup even on fast computers. Always check API results and the runtime logs.

[[Category:Lua API]]


== Map editor and world objects (since 0.1.4) ==
* BUILD124 and updated scripts remove the fixed editor/legacy/map_scene object-count caps. Remaining document bounds: 1000000-byte transfers, shared JSON codec 1 MiB and 65536 entries (including nested fields); 200 undo commands; map names up to 48 ASCII letters/digits/_/-.
* WorldObjects since BUILD124: no fixed instance-count, pending-request-count or requests/second cap (former 512/32/80 removed). Still 16 owning resources, command JSON up to 4096 bytes and a 10-second result timeout. Shared IPC queues remain bounded at 256 frames each: check rejection and pace submissions. Memory/CPU/GPU limits still apply; the scene loader remains sequential.
* Coordinates +/-100000 metres; rotations +/-36000 degrees; scale 0.01-100 per axis; ray length up to 1000 m; object IDs up to 64 characters and asset paths up to 512.
* Resource storage: 1 MiB/file and 64-character keys. Pre-write admission rejects an existing directory over 64 MiB or over 512 regular files (including backups); these are not post-write hard quotas.
See [[Map editor]], [[World objects]], [[Resource data storage]]. Other limits documented on this page remain unchanged unless explicitly marked otherwise.



== NPC control API since 0.1.5 ==
See [[NPC scripting]] for the new functions. Health/damage/mana: 0..100000 (maxHP at least 1); ammo: integer 0..65535; perception: distance >0..1000 metres, FOV >0..360 degrees; projectile range 1..40 m; aim 150..30000 ms; cooldown 360..60000 ms; skillTier 0..2; animation blend-out 0..2 s. Combat walk 0.1..2.5 m/s, run 2.6..8 m/s; chase is independently configurable. These validations do not replace earlier server resource/capacity limits. Defaults and lifecycle caveats are documented on the linked function pages.



== NPC appearance validation since 0.1.5 ==
RGB: integer sRGB channels 0..255. Identity/tattoo keys: at most 48 bytes, ASCII case-insensitive closed catalogs; no arbitrary asset paths. IDs must identify a live server NPC record and mutation requires its owning resource. See [[NPC scripting#NPC appearance since 0.1.5]].



== Area notifications (since 0.1.6) ==
Server-side [[ShowAreaNotification]] / [[HideAreaNotification]] and lower-camel aliases. Available since 0.1.6.
* Connected numeric player ID: finite integer 1..4294967295.
* Heading: 0..256 UTF-8 bytes; title: 1..512 UTF-8 bytes. Literal text only; malformed UTF-8, NUL, controls and line breaks are rejected.
* Duration: finite integer 1000..30000 ms, default 5000 ms; includes fades. Omit the optional argument rather than passing nil.
* One custom banner per player; latest show replaces the previous owner/timer. At most 8192 distinct tracked player IDs per resource; explicit hide/resource cleanup releases tracking.
* Native pending queue: 32 commands; excess commands may be discarded. Three bounded creation attempts, 500 ms apart. Server acceptance is not a visual acknowledgement.
See [[Area notifications]] for cleanup, per-resource ownership, Unicode and the separate automatic discovery-banner suppression. Other limits are unchanged by this addition.



== Mounts (since 0.1.6) ==
Server-side [[createPlayerMount]] and [[destroyPlayerMount]]; available since 0.1.6. See [[Mounts]] for ownership, native eligibility and verification status.
* One active mount per player. No separate global mount-count cap in this subsystem; ordinary player/resource limits still apply.
* No fixed ride lifetime or two-minute age-based despawn. Disconnect, resource stop, ineligibility and explicit removal still clean up the session.
* Initial server observation readiness: 15 seconds; an established session is revoked after more than 20 seconds without accepted observations. These are health timeouts, not maximum riding duration.
* Native spawn requests have a 10-second cooldown and bounded readiness checks. Avoid repeated creation/removal loops; return values acknowledge requests, not native completion.
* Initial boarding/incomplete native transitions use a 6000 ms recovery grace. A lost previously confirmed seat outside a native transition uses a 500 ms debounce. A transition grace is latched for its continuous unhealthy episode; repeated phase reports do not renew it. Healthy riding has no recovery timer running.
* Snapshot observation is approximately 10 Hz. Server ownership/sequence/finite-value, movement and collision-registry validation remain enforced. This is not full native-world collision replication.
* Petting observations are bounded to 4 metres, idle gait and at most 8 seconds of montage position; native eligibility still applies. Petting availability needs final in-game confirmation.
* Ownership is tied to the creating resource and current connection player ID; no database persistence or ownership-transfer API.
The server/client safety bounds above are separate from the existing nameplate range and do not increase it.



== Game audio (since 0.1.7) ==
'''Available since update 0.1.7.''' These limits apply to [[Game audio]], not existing resource-file audio or voice chat.

{| class="wikitable"
! Item !! Limit / behavior
|-
| Sound key || Exact entry in the built-in catalog. No arbitrary files, URLs or native audio paths.
|-
| Volume || Finite number 0..1; default 1.
|-
| Coordinates || Each axis -200000..200000 metres; finite numbers only.
|-
| Attenuation || minDistance >= 0; maxDistance >= 0.01; minDistance < maxDistance <= 200000 metres. Defaults 1 and 30.
|-
| Options || Only volume, minDistance and maxDistance. Unknown keys are rejected.
|-
| Catalog search || Query at most 160 bytes; categories empty, sfx, music or dialogue.
|-
| Catalog pagination || Zero-based nonnegative integer offset; integer limit 1..200, default 50.
|-
| Active sounds || 128 per client, shared across resources, including pending/starting playbacks.
|-
| Audio resource owners || 16 per client. Resource/lifecycle cleanup releases ownership; stopping the last sound alone does not release the owner or its cache.
|-
| Prepared native cache || 64 entries per owner. Dialogue 2D and 3D variants use separate entries. Cache is released by resource/lifecycle cleanup, not by stopping one sound.
|-
| Pending requests / native work queue || 256 each per client. Rejected work must not be retried in a tight loop.
|-
| Retained sound records || Up to 512 across resources; older terminal records are evicted as new handles are created.
|-
| Loading timeout || 12 seconds for queued native preparation; 15 seconds for runtime request completion. A timed-out play request is cancelled.
|-
| Owner heartbeat || Once per second, with a 5-second native lease. Expiry cleans up owned audio.
|-
| Playback-state observation || Approximately every 50 ms while the game is ticking; not a real-time timing guarantee.
|}

Handles/request IDs are positive runtime-assigned numbers, not engine pointers or persistent IDs. Playback and controls are asynchronous. [[onClientGameSoundResult]] supplies results; [[getGameSoundState]] supplies the latest accumulated state, not a guaranteed full property snapshot.

Voice preload is reported as requested, with <code>voicePreloadConfirmed=false</code>; loaded event samples and a resolved recording do not independently confirm voice PCM loading. There is no automatic broadcast, late-join replay or precise cross-client audio clock. Cold loading is paced but is not guaranteed hitch-free.



== Server TTS (since 0.1.7) ==
'''Available since 0.1.7.''' See [[Server TTS]], [[TTS configuration]] and [[TTS voices]]. TTS is default-off and starts no Python/models when disabled.
* Text: 4000 Unicode characters and 12000 UTF-8 bytes. Output: at most 180 seconds and 8 MiB per clip.
* Private reference audio: WAV/OGG/FLAC, 1–30 seconds, 1–2 channels, 8–96 kHz, at most 8 MiB; relative ASCII path and lowercase SHA-256 required. Ukrainian requires a reference. No client uploads, URLs or arbitrary checkpoints.
* Default pending queue: 128 globally, 16 per resource (configurable); at most 2048 retained job handles. Release completed handles; this does not delete recordings.
* Per resource: up to 256 voices and 256 presets. Profile/named-recording identifiers: 1–64 ASCII letters/digits/underscores/hyphens.
* Active playback/preload handles: 128 server-side; 32 client-side. Recipient list at most 5000 entries, connected IDs only. Empty recipients reject the request.
* Playback volume 0..1. Spatial distances: 0.1 <= min <= max <= 1000 metres, defaults 1 and 30. Position is {x,y,z} metres with finite absolute components <= 1000000.
* Readiness deadline: 500..30000 ms, default 10000. A ready listener is required; slow clients do not block everyone indefinitely. Common start is normally scheduled 500 ms ahead.
* Default compressed server memory cache 256 MiB; persistent disk budget 2048 MiB; client decoded cache 256 MiB. These are not inference-model RAM limits.
* Persistent client download cache: 512 MiB / 8192 files, LRU. Deletion, eviction, corruption or unwritable storage can require another download; fresh session signatures remain mandatory.
* A stable saveAs name cannot silently overwrite different audio. Server disk exhaustion/corruption is an explicit error; stored recordings are not automatically erased to satisfy a new request.
* Generation is asynchronous but still consumes host CPU/RAM when used. Pre-render frequent dialogue and enforce permissions/quotas on player-driven requests.




== Native HUD and menus (since 0.1.7) ==
* Client-side, resource-owned policy; 6 original HUD groups and 4 native menus. From 0.1.9, crafting becomes a seventh HUD group; the menu count stays four. Exact keys and bit masks: [[Native HUD and menus]] / [[getNativeUiState]].
* Up to 256 owner records per client session, including released records retained for safe ordering. Excess new owners can be rejected; reset is not a way to allocate unlimited new owner identities.
* Mutators return a positive request ID or false. Consecutive requests can coalesce into the latest complete policy; intermediate IDs are not guaranteed individual acknowledgements.
* Acknowledged native state is fresh for less than 6000 ms while connected. Unrenewed policies expire after 6000 ms; ordinary heartbeats renew them every 1000 ms.
* Native result JSON is bounded to 8192 bytes. Read the returned table or decode the result string; do not infer success merely from pending=false.
* false adds a restriction; true/reset releases only the caller's restriction. Stopping a resource releases ownership. Native quicksave/quickload and pause save/load restrictions cannot be re-enabled by Lua.
See [[onClientNativeUiResult]] and [[Native HUD and menus]] for the public contract.



== Character dimensions (since 0.1.8) ==
* Server-controlled integer dimension numbers: 0..2147483647. Default 0. Invalid/fractional/non-finite/string values fail.
* No independent dimension-creation pool: entity/player capacity and existing streaming distances still apply.
* NPC/monster setters require the owning resource. Player dimensions are gamemode-managed and are not automatically restored when the resource stops.
* One player transition at a time. Pending transitions/position changes, active interactions/climbing and owned mount leases can reject a change. An unchanged dimension is a no-op success.
* [[spawnNpc]] / [[spawnMonster]] accept <code>options.dimension</code>. Omission preserves dimension 0; normal spawn validation still applies.
* This isolates characters, combat and proximity voice, not world items, doors/gates, static/custom blockers, global events or arbitrary script audio. See [[Character dimensions]] for exact scope and examples.
* Requires matching 0.1.8 / Protocol 40 peers.



== Item profiles and interactive editor objects (from 0.1.9) ==
Available from 0.1.9.
* [[Item type stats]] affects every copy of one known item type across this server, not per-instance/per-dimension variants. Item types are resource-owned while overridden. No arbitrary engine field writes or new item definitions.
* [[getItemStatDefinitions]] supplies exact finite-number ranges, integer rules and per-item support. See [[Item stat properties]]. Invalid/unsupported inputs and ownership conflicts reject the transaction. Resource stop resets owned overrides; persistence is explicit.
* Joining clients need support for active profiles. A setter/report is not proof of completed native gameplay. Revisions are strings; missing defaults are not zero.
* [[Interactive map objects]] provides 94 editor prefabs: 18 seats, 48 lights, seven doors and 21 ladder sizes. Test native remains local; shared placed-door deployment is separate. One native test at a time; position/yaw only, original scale/collision. Seat cleanup waits for release/exit and 1-metre clearance.
* The updated map_scene loader accepts formats 1/2/3 for supported static objects, server-owned doors and original-world removals. Shared seats/lights/placed ladders are still unsupported; these categories are rejected, not silently made static. Original NPC obstacle data is unchanged.



== Armor-upgrade API (from 0.1.9) ==
Available from 0.1.9. See [[Armor upgrades]] and the complete [[Armor catalog]] / [[Armor upgrade catalog]].
* Server-side, known keys only: 26 bases, 84 parts, three slots top/mid/bottom. The part setter replaces all three slots; omitted slots clear. Empty strings or none clear a slot; {} clears all parts.
* Exact lowercase base keys and preset names. Part values are recognized catalog strings (maximum 64 bytes); non-string values/unknown fields reject the request. Character IDs must be finite integer numbers 1..4294967295. Player/NPC getters take one argument; setters take exactly two.
* Players need owned base/parts and must meet server requirements. NPC mutation requires the owning resource. Setters never grant items, equip a different base, raise attributes or heal/refill.
* Six tier presets choose only existing compatible parts; none clears. A known base without upgrades returns empty catalog/preset tables, not fabricated pieces.
* Selection is per character; [[Item type stats|numeric type profiles]] are server-wide. Persistence in custom gamemodes is explicit. Existing dimension/visibility rules remain.



== Female identity presentation (from 0.1.9) ==
'''Improved from 0.1.9.'''
* Supported keys for the correction: <code>syra</code>, <code>velaya</code>, <code>seraphia</code>, <code>chani</code>, <code>natalia</code>; existing catalog and permission checks remain.
* Full authored female outfit requires matching identity body/head selections and no equipped armor. Separate head selection does not replace a separately selected body.
* Armor retains its native shape and protection; no automatically generated female armor variants.
* Neutral facial expression only; this does not introduce facial animation or lip synchronization. Skin/tattoo display remains limited to supported exposed material regions.
* Existing server-side setters and authoritative state are reused. Success means acceptance, not completed rendering. All viewing clients need the update. See [[Female identities]].



== Activity animation scope (from 0.1.9) ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
* Existing player/NPC start/stop APIs and validation remain. Aliases must be in the running server's catalog; arbitrary asset paths are not accepted.
* Looping remains explicit: omitted looped means false. Use the mode returned by [[getPlayerAnimationInfo]] when appropriate.
* Cosmetic rods/tools do not grant items or rewards; furniture/workstation placement and gameplay checks remain the gamemode's responsibility.
* First-use loading can occur. Server acceptance is not client-render confirmation, and catalog qualification is not a live acknowledgement. See [[Activity animations]] for visual-test status and boundaries.



'''Available from 0.1.9. Use matching updated server and clients.'''

== Custom keys and placed doors ==
See [[Custom keys#Limits, restart and qualification|complete limits]]. Keys: 64 distinct types/resource, 256/process including inactive registrations; immutable recipes, approved donor only. Doors: 1024/resource, 4096 total, six placement fields and original native scale. Deferred notifications: 4096 queued, 64/tick; one key-denial notification/player/second. Resource stop drops its queued events. No automatic database persistence or arbitrary custom weapon/armor definitions.



== Weather, crafting and original-world editing from 0.1.9 ==
'''Available from 0.1.9. Use matching updated clients and server.'''
* [[Weather]] exposes a closed 43-name catalog, not arbitrary particle/asset paths. Transition range remains 0..300000 ms, default 3000. Weather is global server state, not per-player/dimension. Render/ACK limitations remain explicit.
* [[Native crafting UI]] is a seventh HUD component, not a fifth management menu, recipe executor or server authorization system. Existing resource ownership/expiry and async result contracts apply.
* [[Interactive map objects]] exposes 94 editor prefabs with original scale/collision and yaw rotation. Only the seven doors have shared placed-interaction authority; seats/lights/ladders remain local tests.
* [[World model removal]] retains command-size, owner, catalog, exact-identity and protected-object guards. It does not alter terrain, baked HLOD or NPC navigation data. Group changes and first loading can hitch; bounded work is not a zero-cost promise.
* Editor live application replaces its whole saved removal/door set, not a merge or arbitrary client request. Map formats 1/2/3 require the matching supplied loaders. In-game verification is still needed for each deployed scene.



== Discord Rich Presence (from 0.1.9) ==
'''Available from 0.1.9. Use matching updated clients and server.'''

One owning resource/profile per player; 15-second latest-value coalescing and reconnect spacing, 45-second client lease fallback. Text/asset keys at most 128 bytes; button labels 32 bytes, HTTPS URLs 512 bytes, at most two links. Unix timestamp seconds 0..4102444800; displayed counts 0..1000000 with size <= max and paired party fields. Application ID is a 17..20-digit unsigned-64 decimal string, never a Lua number. [[Discord Rich Presence#Profile fields|Complete fields, validation and lifecycle]]. Local opt-in cannot be overridden; reports cannot authorize gameplay.

ResetItemStats

2026-10-20T13:29:07Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= resetItemStats =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9. See the scope and validation notes below.</div>
</div>

Removes one property override or all overrides of one item type owned by this resource.

== Syntax ==
<syntaxhighlight lang="lua">
accepted, error, revision = resetItemStats(item [, property])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>item</code> || <code>string</code> || yes || Known canonical item key or recognized alias; this is not an inventory-instance ID.
|-
| <code>property</code> || <code>string</code> || no || Exact property name to reset. Omit to reset the whole type.
|}

== Returns ==
Three values: accepted (boolean), error (string; empty on success), revision (decimal string). Check accepted before using the revision. Success means server acceptance, not visual/client completion. A no-op may return the unchanged revision.

== Examples ==
<syntaxhighlight lang="lua" line>
local ok, why = resetItemStats("mercenary", "resistanceEdge")
assert(ok, why)
-- To reset every override of this armor instead:
-- local ok, why = resetItemStats("mercenary")
</syntaxhighlight>

== Notes ==
* Available from G1R:MP 0.1.9. This documents the implemented API and its current limits. See [[Item type stats]] for scope and remaining in-game validation.
* Server-side only. Profiles affect every copy of the same type on this server, across dimensions; not individual item instances.
* Use matching supported client and server builds. Server acceptance and a client application report do not prove the native gameplay effect.
* Active overrides are owned per item type by the calling resource. Another resource cannot change that owned type. Resource stop removes its overrides.
* Validation is atomic for the submitted transaction. Unsupported fields, wrong families, invalid/non-finite values, duplicate item/property aliases or ownership conflicts reject it.
* A numeric 0 is an explicit value where allowed, not reset. Use resetItemStats to remove an override. Profiles are not automatically persisted.
* Do not expose this setter directly to untrusted remote events. See [[getItemStatDefinitions]] and [[Item stat properties]].
* Restores the multiplayer baseline for server-controlled values and the captured originals for applicable native edits. It does not heal, revive or erase equipment.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Inventory Functions]]
[[Category:Equipment Functions]]
[[Category:Experimental Lua API]]

ReplaceItemStatsProfile

2026-10-20T13:29:05Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= replaceItemStatsProfile =
<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;">AVAILABLE FROM UPDATE 0.1.9</div>
<div style="color:#111111; margin-top:0.25rem;">Available from 0.1.9. See the scope and validation notes below.</div>
</div>

Replaces the complete item profile owned by this resource.

== Syntax ==
<syntaxhighlight lang="lua">
accepted, error, revision = replaceItemStatsProfile(profile)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>profile</code> || <code>table</code> || yes || Map of item keys to property/value tables, such as getItemStatsProfile() returns.
|}

== Returns ==
Three values: accepted (boolean), error (string; empty on success), revision (decimal string). Check accepted before using the revision. Success means server acceptance, not visual/client completion. A no-op may return the unchanged revision.

== Examples ==
<syntaxhighlight lang="lua" line>
local saved = readResourceData("item_balance")
if saved then
local profile = fromJSON(saved)
assert(type(profile) == "table", "Invalid item profile")
local ok, why = replaceItemStatsProfile(profile)
assert(ok, why)
end
</syntaxhighlight>

== Notes ==
* Available from G1R:MP 0.1.9. This documents the implemented API and its current limits. See [[Item type stats]] for scope and remaining in-game validation.
* Server-side only. Profiles affect every copy of the same type on this server, across dimensions; not individual item instances.
* Use matching supported client and server builds. Server acceptance and a client application report do not prove the native gameplay effect.
* Active overrides are owned per item type by the calling resource. Another resource cannot change that owned type. Resource stop removes its overrides.
* Validation is atomic for the submitted transaction. Unsupported fields, wrong families, invalid/non-finite values, duplicate item/property aliases or ownership conflicts reject it.
* A numeric 0 is an explicit value where allowed, not reset. Use resetItemStats to remove an override. Profiles are not automatically persisted.
* Do not expose this setter directly to untrusted remote events. See [[getItemStatDefinitions]] and [[Item stat properties]].
* Omitted old fields/types owned by this resource are reset in the same transaction as new values. Other resources are untouched. An empty table resets all of your resource's overrides.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Inventory Functions]]
[[Category:Equipment Functions]]
[[Category:Experimental Lua API]]

RemovePlayerItem

2026-10-20T13:29:04Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= removePlayerItem =
Removes a known item from a player's authoritative inventory.

== Syntax ==
<syntaxhighlight lang="lua">
bool removePlayerItem(int playerId, string itemKey [, int quantity = 1])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>itemKey</code> || <code>string</code> || yes || A rune, armor, or melee weapon key from the server catalog.
|-
| <code>quantity</code> || <code>int</code> || no || Number of items to remove, from 1 to 1000; defaults to 1.
|}

== Returns ==
Returns <code>true</code> when the complete quantity can be removed and the change is replicated; otherwise returns <code>false</code>.

== Examples ==
Consume one item only when the player owns it:
<syntaxhighlight lang="lua" line>
if hasPlayerItem(playerId, "light") then
removePlayerItem(playerId, "light", 1)
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The operation is rejected rather than allowing the inventory quantity to become negative.

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


'''Available from 0.1.9. Use matching updated server and clients.'''

== Registered custom keys ==
This existing API also accepts the canonical item string from [[registerKeyDefinition]] in 0.1.9. Server registration, active definition and appropriate presentation readiness are required for mutations; use [[isPlayerKeyDefinitionReady]]. Do not pass the donor model alias as the custom item identity. Existing call shapes and limits remain; [[spawnItem]] creates one world item per call, whereas give/remove counts can manage copies. See [[Custom keys]] for safe server-side issuance, drop, pickup and persistence.

RegisterKeyDefinition

2026-10-20T13:29:02Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= registerKeyDefinition =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server Lua. Part of [[Custom keys|custom keys and shared placed doors]].

== Syntax ==
<syntaxhighlight lang="lua">
item, error = registerKeyDefinition(id, options)
</syntaxhighlight>
== Parameters and behavior ==
id is a resource-local string; options is a table with required name and optional description, model, value, weight, maxStack. See [[Custom keys#Limits, restart and qualification|exact limits/defaults]]. Ownership comes from the calling resource, never an options field. Identical registration is idempotent; conflicting metadata is rejected.
== Returns ==
Canonical item string and empty error on success; nil and an error string on failure. No inventory is granted.
== Examples and security ==
See [[Custom keys]] for complete registration, copy issuance, placement, persistence and callback examples. These are server functions, not client RPC endpoints. Do not forward untrusted client arguments without gameplay authorization.
[[Category:Lua Functions]]

Player identity catalog

2026-10-20T13:29:01Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

{{DISPLAYTITLE:Player identity catalog}}
The '''player identity catalog''' lists named player identities accepted by [[setPlayerIdentity]]. The server commits matching identity keys together. In 0.1.8, named identities use head-only presentation while retaining the game-owned body and equipped armor. From 0.1.9, the five [[Female identities|supported female identities]] can also show their full authored outfit when no armor is equipped and body/head selections match. Selecting an identity does not equip or remove armor.

<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
'''IMPROVED FROM UPDATE 0.1.3'''

Identity selection existed in earlier releases. Update 0.1.3 corrects head publication and material-mask restoration during identity/armor rebuilds, addressing overlapping heads and missing body parts. Independent skin-color and tattoo functions are new in 0.1.3; see [[Player customization]].
</div>

== Usage ==
<syntaxhighlight lang="lua">
if not setPlayerIdentity(playerId, "milten") then
outputChatBox("The identity could not be applied.", playerId)
end
</syntaxhighlight>

In G1R:MP 0.1 this is the only supported setter for a complete player identity. The test command <code>/identity <key></code> uses the same API. The state is server-authoritative and replayed during relevance entry and late join. Raw Unreal paths are never accepted.

Equipment remains independent of the selected identity. The full female outfit exception from 0.1.9 is described in [[Female identities]]. Identity changes preserve the [[setPlayerSkinColor|skin-color]] and [[setPlayerTattoo|tattoo]] overrides, including when no armor is equipped. A successful setter confirms authoritative state acceptance, not completion of rendering. Validate the character/armor combinations and viewing distances used by your resource on both local and observing clients.

== Available identities ==
{| class="wikitable sortable"
! Key !! Composition
|-
| <code>default</code> || Native Nameless Hero identity
|-
| <code>baloro</code> || GTO <code>FM_SLD_Baloro_753</code> profile plus validated character materials and hair
|-
| <code>homer</code> || GTO <code>NC_BAU_Homer_935</code> profile plus validated character materials and hair
|-
| <code>horatio</code> || GTO <code>NC_BAU_Horatio_901</code> profile plus validated character materials and hair
|-
| <code>jan</code> || GTO <code>NC_BAU_Jan_942</code> profile plus validated character materials and hair
|-
| <code>rice_lord</code> || GTO <code>NC_BAU_RiceLord_900</code> profile plus validated character materials and hair
|-
| <code>cronos</code> || GTO <code>NC_KDW_Cronos_604</code> profile plus validated character materials and hair
|-
| <code>merdarion</code> || GTO <code>NC_KDW_Merdarion_602</code> profile plus validated character materials and hair
|-
| <code>myxir</code> || GTO <code>NC_KDW_Myxir_601</code> profile plus validated character materials and hair
|-
| <code>nefarius</code> || GTO <code>NC_KDW_Nefarius_603</code> profile plus validated character materials and hair
|-
| <code>riordian</code> || GTO <code>NC_KDW_Riordian_605</code> profile plus validated character materials and hair
|-
| <code>saturas</code> || GTO <code>NC_KDW_Saturas_600</code> profile plus validated character materials and hair
|-
| <code>baal_isidro</code> || GTO <code>NC_NOV_BaalIsidro_1333</code> profile plus validated character materials and hair
|-
| <code>baal_kagan</code> || GTO <code>NC_NOV_BaalKagan_1332</code> profile plus validated character materials and hair
|-
| <code>buster</code> || GTO <code>NC_ORG_Buster_833</code> profile plus validated character materials and hair
|-
| <code>cipher</code> || GTO <code>NC_ORG_Cipher_873</code> profile plus validated character materials and hair
|-
| <code>drax</code> || GTO <code>NC_ORG_Drax_819</code> profile plus validated character materials and hair
|-
| <code>lares</code> || GTO <code>NC_ORG_Lares_801</code> profile plus validated character materials and hair
|-
| <code>lefty</code> || GTO <code>NC_ORG_Lefty_844</code> profile plus validated character materials and hair
|-
| <code>ratford</code> || GTO <code>NC_ORG_Ratford_818</code> profile plus validated character materials and hair
|-
| <code>wolf</code> || GTO <code>NC_ORG_Wolf_855</code> profile plus validated character materials and hair
|-
| <code>cord</code> || GTO <code>NC_SLD_Cord_709</code> profile plus validated character materials and hair
|-
| <code>gorn</code> || GTO <code>NC_SLD_Gorn_699</code> profile plus validated character materials and hair
|-
| <code>haenno</code> || GTO <code>NC_SLD_Haenno_741</code> profile plus validated character materials and hair
|-
| <code>jarvis</code> || GTO <code>NC_SLD_Jarvis_728</code> profile plus validated character materials and hair
|-
| <code>lee</code> || GTO <code>NC_SLD_Lee_700</code> profile plus validated character materials and hair
|-
| <code>gomez</code> || GTO <code>OC_EBR_Gomez_100</code> profile plus validated character materials and hair
|-
| <code>raven</code> || GTO <code>OC_EBR_Raven_105</code> profile plus validated character materials and hair
|-
| <code>fletcher</code> || GTO <code>OC_GRD_Fletcher_255</code> profile plus validated character materials and hair
|-
| <code>kirgo</code> || GTO <code>OC_GRD_Kirgo_251</code> profile plus validated character materials and hair
|-
| <code>orry</code> || GTO <code>OC_GRD_Orry_254</code> profile plus validated character materials and hair
|-
| <code>thorus</code> || GTO <code>OC_GRD_Thorus_200</code> profile plus validated character materials and hair
|-
| <code>flex</code> || GTO <code>OC_IE_Flex</code> profile plus validated character materials and hair
|-
| <code>lutter</code> || GTO <code>OC_IE_Lutter</code> profile plus validated character materials and hair
|-
| <code>unicorn</code> || GTO <code>OC_IE_Unicorn</code> profile plus validated character materials and hair
|-
| <code>corristo</code> || GTO <code>OC_KDF_Corristo_402</code> profile plus validated character materials and hair
|-
| <code>milten</code> || GTO <code>OC_KDF_Milten</code> profile plus validated character materials and hair
|-
| <code>baal_parvez</code> || GTO <code>OC_NOV_BaalParvez_1330</code> profile plus validated character materials and hair
|-
| <code>mordrag</code> || GTO <code>OC_ORG_Mordrag_826</code> profile plus validated character materials and hair
|-
| <code>dexter</code> || GTO <code>OC_STT_Dexter_329</code> profile plus validated character materials and hair
|-
| <code>diego</code> || GTO <code>OC_STT_Diego</code> profile plus validated character materials and hair
|-
| <code>fingers</code> || GTO <code>OC_STT_Fingers_331</code> profile plus validated character materials and hair
|-
| <code>fisk</code> || GTO <code>OC_STT_Fisk_311</code> profile plus validated character materials and hair
|-
| <code>whistler</code> || GTO <code>OC_STT_Whistler_309</code> profile plus validated character materials and hair
|-
| <code>dusty</code> || GTO <code>OC_VLK_Dusty_524</code> profile plus validated character materials and hair
|-
| <code>huno</code> || GTO <code>OC_VLK_Huno_538</code> profile plus validated character materials and hair
|-
| <code>mud</code> || GTO <code>OC_VLK_Mud_574</code> profile plus validated character materials and hair
|-
| <code>snaf</code> || GTO <code>OC_VLK_Snaf_581</code> profile plus validated character materials and hair
|-
| <code>seraphia</code> || GTO <code>OC_WOC_Seraphia_110</code> profile plus validated character materials and hair
|-
| <code>syra</code> || GTO <code>OC_WOC_Syra_109</code> profile plus validated character materials and hair
|-
| <code>velaya</code> || GTO <code>OC_WOC_Velaya_108</code> profile plus validated character materials and hair
|-
| <code>bloodwyn</code> || GTO <code>OCR_GRD_Bloodwyn_233</code> profile plus validated character materials and hair
|-
| <code>scatty</code> || GTO <code>OCR_GRD_Scatty_210</code> profile plus validated character materials and hair
|-
| <code>skip</code> || GTO <code>OCR_GRD_Skip_211</code> profile plus validated character materials and hair
|-
| <code>baal_lukor</code> || GTO <code>OG_GUR_BaalLukor_1211</code> profile plus validated character materials and hair
|-
| <code>ulbert</code> || GTO <code>OM_GRD_Ulbert_271</code> profile plus validated character materials and hair
|-
| <code>ian</code> || GTO <code>OM_STT_Ian_301</code> profile plus validated character materials and hair
|-
| <code>aleph</code> || GTO <code>OM_VLK_Aleph_585</code> profile plus validated character materials and hair
|-
| <code>baal_cadar</code> || GTO <code>SC_GUR_BaalCadar_1208</code> profile plus validated character materials and hair
|-
| <code>baal_namib</code> || GTO <code>SC_GUR_BaalNamib_1204</code> profile plus validated character materials and hair
|-
| <code>baal_orun</code> || GTO <code>SC_GUR_BaalOrun_1209</code> profile plus validated character materials and hair
|-
| <code>baal_tondral</code> || GTO <code>SC_GUR_BaalTondral_1203</code> profile plus validated character materials and hair
|-
| <code>baal_tyon</code> || GTO <code>SC_GUR_BaalTyon_1210</code> profile plus validated character materials and hair
|-
| <code>cor_angar</code> || GTO <code>SC_GUR_CorAngar_1202</code> profile plus validated character materials and hair
|-
| <code>cor_kalom</code> || GTO <code>SC_GUR_CorKalom_1201</code> profile plus validated character materials and hair
|-
| <code>yberion</code> || GTO <code>SC_GUR_YBerion_1200</code> profile plus validated character materials and hair
|-
| <code>balor</code> || GTO <code>SC_NOV_Balor_1304</code> profile plus validated character materials and hair
|-
| <code>fortuno</code> || GTO <code>SC_NOV_Fortuno_1357</code> profile plus validated character materials and hair
|-
| <code>lester</code> || GTO <code>SC_NOV_Lester</code> profile plus validated character materials and hair
|-
| <code>nyras</code> || GTO <code>SC_NOV_Nyras_1303</code> profile plus validated character materials and hair
|-
| <code>chani</code> || GTO <code>SC_WSC_Chani_1205</code> profile plus validated character materials and hair
|-
| <code>natalia</code> || GTO <code>SC_WSC_Natalia_1207</code> profile plus validated character materials and hair
|-
| <code>cavalorn</code> || GTO <code>UL_STT_Cavalorn_336</code> profile plus validated character materials and hair
|-
| <code>cohsel</code> || GTO <code>UL_STT_Cohsel_337</code> profile plus validated character materials and hair
|-
| <code>xardas</code> || GTO <code>XT_DMB_Xardas_404</code> profile plus validated character materials and hair
|}

== Related functions ==
* [[getPlayerIdentityNames]]
* [[getPlayerIdentity]]
* [[setPlayerIdentity]]
* [[setPlayerArmor]]

[[Category:Lua API]]
[[Category:Lua Catalogs]]
[[Category:Appearance Functions]]


== Female identities (from 0.1.9) ==
'''Improved from 0.1.9.'''
The existing keys <code>syra</code>, <code>velaya</code>, <code>seraphia</code>, <code>chani</code> and <code>natalia</code> receive corrected facial proportions and matching female-body presentation. Without armor, a complete matching identity shows its authored outfit; with armor, the native armor remains visible with the corrected head. Facial expression is currently neutral. See [[Female identities]] for player/NPC examples, mixed head/body selections and limits.

Player customization

2026-10-20T13:28:59Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

{{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.
* 0.1.8 uses head-only identity presentation. From 0.1.9, [[Female identities|five supported female identities]] additionally show their full authored body/outfit without armor when body/head selections match. Equipped armor is preserved. This 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]]


== Armor parts (from 0.1.9) ==
Available from 0.1.9. [[Armor catalog]] lists the 26 bases; [[Armor upgrade catalog]] lists all 84 pieces. This existing function/guide is not newly introduced in 0.1.9. The new [[Armor upgrades|upgrade system]] adds per-character top/mid/bottom selections, full presets and separate player/NPC setters. A different base clears the old parts; choosing the same base keeps compatible selections. Identity, skin tint and tattoos remain separate. See the guide for requirements, safe replacement and synchronization validation.



== Female characters (from 0.1.9) ==
'''Improved from 0.1.9.'''
Use [[setPlayerIdentity]] with <code>syra</code>, <code>velaya</code>, <code>seraphia</code>, <code>chani</code> or <code>natalia</code>. The update corrects stretched female faces, including armored characters. Complete matching identities show their female outfit without armor; equipped armor retains its original shape and takes priority. Skin tint and tattoo overrides remain independent, subject to exposed/supported skin regions. See [[Female identities]] for examples and the neutral-expression limitation. No new customization function is required.

Player animation catalog

2026-10-20T13:28:58Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

{{DISPLAYTITLE:Player animation catalog}}
<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;">AVAILABLE FROM UPDATE 0.1.2</div>
<div style="color:#111111; margin-top:0.25rem;">The original 27-entry player-animation catalog and the synchronized [[startAnim]] and [[stopAnim]] behavior are available from G1R:MP 0.1.2.</div>
</div>

The '''player animation catalog''' lists the stable, server-validated aliases accepted by [[startAnim]]. Aliases are case-insensitive. Lua passes an alias from this table; raw Unreal asset paths are neither accepted nor exposed as API inputs.

'''0.1.8 includes the 118-alias catalog expanded in 0.1.4.''' These earlier entries have been confirmed working in-game; see the tables below and [[Update 0.1.4]].

'''From 0.1.9: 962 aliases in total, including 844 additions.''' See the complete [[Activity animation catalog]] and [[Activity animations|usage guide]]. The new entries include route/gesture variants and are not all individually visually confirmed. Both client and server need the matching update.

== Request modes ==
The '''authored mode''' documents the safe, recommended presentation for each animation. It does not change the compatible Lua signature:

* Omitting <code>looped</code> from [[startAnim]] always means <code>false</code>, including for entries whose authored mode is <code>hold</code>.
* With <code>looped = false</code>, the animation plays once from its beginning and ends naturally. Use this for every <code>once</code> entry.
* With <code>looped = true</code>, a <code>hold</code> entry plays its introduction, then repeats from the catalogued loop-start time until [[stopAnim]] or a newer scripted animation supersedes it. Higher-priority gameplay presentation temporarily takes precedence; the same active scripted revision may resume afterward.
* The optional blend duration controls the owning player's native montage transition when the request replaces an existing scripted animation, then remains the stop blend for the new animation. Remote proxy handoff is immediate and does not guarantee an interpolated blend.
* A loop-start value is native catalog metadata. It is not an additional Lua argument.

== Original aliases (since 0.1.2) ==
{| class="wikitable sortable"
! Key !! Description !! Authored mode !! Loop start !! Notes
|-
| <code>crossarms</code> || Stand with arms crossed. || <code>hold</code> || <code>3.47 s</code> ||
|-
| <code>pray</code> || Pray while standing. || <code>hold</code> || <code>6.83 s</code> ||
|-
| <code>meditate</code> || Perform a standing meditation pose. || <code>hold</code> || <code>11.5 s</code> ||
|-
| <code>warmhands</code> || Warm the hands in a cold or rainy standing pose. || <code>hold</code> || <code>0.93 s</code> || Uses the stable Rain Pose 04 replacement; the unsafe original Warm Hands montage is not exposed.
|-
| <code>exhausted</code> || Show an exhausted standing pose. || <code>hold</code> || <code>9.47 s</code> ||
|-
| <code>dance</code> || Perform a standing dance. || <code>hold</code> || <code>1.97 s</code> ||
|-
| <code>smalltalk</code> || Gesture while speaking to an audience. || <code>hold</code> || <code>4.5 s</code> || Uses the visible Speaks Audience replacement; the original non-rendering Small Talk montage is not exposed.
|-
| <code>guard</code> || Hold a watchful guard pose with crossed arms. || <code>hold</code> || <code>3.47 s</code> ||
|-
| <code>sitground</code> || Sit on the ground. || <code>hold</code> || <code>5.03 s</code> ||
|-
| <code>sleepground</code> || Lie down and sleep on the ground. || <code>once</code> || — ||
|-
| <code>sleepstand</code> || Doze while standing. || <code>hold</code> || <code>4.17 s</code> ||
|-
| <code>leanwall</code> || Lean against a wall. || <code>hold</code> || <code>3 s</code> ||
|-
| <code>listen</code> || Adopt a listening pose. || <code>hold</code> || <code>2.57 s</code> ||
|-
| <code>waterpipe</code> || Use a water pipe. || <code>hold</code> || <code>8.67 s</code> ||
|-
| <code>smoke</code> || Perform the standing smoking pose. || <code>hold</code> || <code>1.47 s</code> ||
|-
| <code>campfire</code> || Warm up in front of a campfire. || <code>hold</code> || <code>4.73 s</code> ||
|-
| <code>puke</code> || Perform the vomiting animation. || <code>once</code> || — ||
|-
| <code>angrydrunk</code> || Act like an angry drunk. || <code>hold</code> || <code>3.67 s</code> ||
|-
| <code>airguitar</code> || Perform the concert air-guitar pose. || <code>hold</code> || <code>0.03 s</code> ||
|-
| <code>headbang</code> || Perform the concert headbang pose. || <code>hold</code> || <code>0.03 s</code> ||
|-
| <code>fistpump</code> || Perform the concert fist-pump pose. || <code>hold</code> || <code>0.03 s</code> ||
|-
| <code>pogo</code> || Perform the concert pogo pose. || <code>hold</code> || <code>0.03 s</code> ||
|-
| <code>stomp</code> || Perform the concert stomp pose. || <code>hold</code> || <code>0.03 s</code> ||
|-
| <code>sway</code> || Perform the concert sway pose. || <code>hold</code> || <code>0.03 s</code> ||
|-
| <code>work</code> || Perform a smithing work animation. || <code>hold</code> || <code>50.7667 s</code> || Compatibility alias used by the bundled GothicRP activities; the authored montage presents visible smithing and its prop.
|-
| <code>mine</code> || Perform the pickaxe mining animation. || <code>hold</code> || <code>1.97333 s</code> || Compatibility alias used by the bundled GothicRP mining activities.
|-
| <code>pickup</code> || Pick up an item from the ground with the left hand. || <code>once</code> || — || Compatibility alias used by the bundled GothicRP gathering activities; authored as a one-shot.
|}

== Additional animations since 0.1.4 BUILD127 ==
'''The 0.1.4 expansion added 91 entries, bringing that release's total to 118. These earlier entries were confirmed working in-game by the project owner.''' The separate [[Activity animation catalog|0.1.9 expansion]] adds another 844 aliases.
The original 27 IDs and aliases are unchanged. Use the updated '''client and server'''. These additions are part of [[Update 0.1.4]], not the public 0.1.3 catalog.

New playback follows the selected introduction, loop and exit rather than unrelated alternate montage sections. The introduction duration below is elapsed time; loop start is a native montage position, not a Lua argument. With looped=false, a new hold animation follows its introduction, one loop and exit. With looped=true it repeats the selected loop until stopped or superseded.

=== Work and training (35) ===
{| class="wikitable sortable"
! Alias !! Activity !! Recommended mode !! Introduction !! Native loop start
|-
| <code>alchemy</code> || Work at an alchemy lab || <code>hold</code> || 3.667 s || 3.667 s
|-
| <code>annotategoods</code> || Write notes while checking goods || <code>hold</code> || 6.667 s || 6.667 s
|-
| <code>buildhouse</code> || Hammer during construction || <code>hold</code> || 4.167 s || 4.167 s
|-
| <code>checkbody</code> || Examine a body || <code>hold</code> || 3.800 s || 3.800 s
|-
| <code>checkgoods</code> || Inspect goods, variant 1 || <code>hold</code> || 0.030 s || 0.030 s
|-
| <code>checkgoods2</code> || Inspect goods, variant 2 || <code>hold</code> || 0.050 s || 0.050 s
|-
| <code>cleanfloor</code> || Scrub a floor, variant 1 || <code>hold</code> || 4.933 s || 4.933 s
|-
| <code>cleanfloor2</code> || Scrub a floor, variant 2 || <code>hold</code> || 5.133 s || 5.133 s
|-
| <code>cookpan</code> || Cook at a pan || <code>hold</code> || 2.033 s || 2.033 s
|-
| <code>cookspit</code> || Cook at a spit || <code>hold</code> || 0.033 s || 0.033 s
|-
| <code>cookcauldron</code> || Stir a cauldron || <code>hold</code> || 0.833 s || 0.833 s
|-
| <code>countore</code> || Count ore || <code>hold</code> || 7.033 s || 7.033 s
|-
| <code>cutwood</code> || Chop wood / a tree || <code>hold</code> || 2.900 s || 2.900 s
|-
| <code>cutlog</code> || Chop a log at a station || <code>hold</code> || 5.467 s || 32.733 s
|-
| <code>pickrice</code> || Harvest rice || <code>hold</code> || 2.867 s || 2.867 s
|-
| <code>pickaxe</code> || Work with a pickaxe || <code>hold</code> || 2.833 s || 2.833 s
|-
| <code>digground</code> || Dig with a pickaxe || <code>hold</code> || 2.833 s || 2.833 s
|-
| <code>repair</code> || Hammer a ground-level repair || <code>hold</code> || 4.167 s || 4.167 s
|-
| <code>cleanrice</code> || Clean rice at a station || <code>hold</code> || 4.267 s || 4.267 s
|-
| <code>seedrice</code> || Sow rice || <code>hold</code> || 4.500 s || 4.500 s
|-
| <code>smashherbs</code> || Mash herbs at a station || <code>hold</code> || 4.667 s || 4.667 s
|-
| <code>smithanvil</code> || Work at an anvil || <code>hold</code> || 2.733 s || 2.733 s
|-
| <code>smithsharpen</code> || Sharpen at a smithing station || <code>hold</code> || 2.200 s || 2.200 s
|-
| <code>smithwater</code> || Cool metal at a smithing water station || <code>once</code> || 6.433 s || —
|-
| <code>tanning</code> || Work at a tanning station || <code>hold</code> || 5.167 s || 5.167 s
|-
| <code>sweep</code> || Sweep with a broom || <code>hold</code> || 5.700 s || 5.700 s
|-
| <code>carve</code> || Carve while sitting || <code>hold</code> || 4.433 s || 4.433 s
|-
| <code>sitcountore</code> || Count ore while sitting || <code>hold</code> || 5.533 s || 5.533 s
|-
| <code>swordsharpen</code> || Sharpen a sword while sitting || <code>hold</code> || 6.171 s || 6.171 s
|-
| <code>teach</code> || Teach / demonstrate training || <code>hold</code> || 4.500 s || 4.500 s
|-
| <code>trainmagic</code> || Practice magic gestures || <code>hold</code> || 7.100 s || 7.100 s
|-
| <code>trainbow</code> || Practice bow handling || <code>hold</code> || 8.833 s || 8.833 s
|-
| <code>train</code> || Practice one-handed sword movements || <code>hold</code> || 1.667 s || 1.667 s
|-
| <code>train2h</code> || Practice two-handed sword movements || <code>hold</code> || 8.467 s || 8.467 s
|-
| <code>train1h</code> || Practice one-handed melee movements || <code>hold</code> || 5.067 s || 5.067 s
|}

=== Sitting, lying and sleep (19) ===
{| class="wikitable sortable"
! Alias !! Activity !! Recommended mode !! Introduction !! Native loop start
|-
| <code>sit</code> || Sit on a stool / chair || <code>hold</code> || 1.367 s || 5.300 s
|-
| <code>sitthrone</code> || Sit on a throne || <code>hold</code> || 7.667 s || 7.667 s
|-
| <code>sitlisten</code> || Listen while sitting, variant 1 || <code>hold</code> || 5.167 s || 5.167 s
|-
| <code>sitlisten2</code> || Listen while sitting, variant 2 || <code>hold</code> || 7.000 s || 7.000 s
|-
| <code>sitsleep</code> || Doze while sitting || <code>hold</code> || 10.933 s || 10.933 s
|-
| <code>sleeptable</code> || Sleep at a table || <code>hold</code> || 9.233 s || 9.233 s
|-
| <code>sitbedlowleft</code> || Sit on a low bed, left entry || <code>hold</code> || 5.200 s || 5.200 s
|-
| <code>sitbedlowright</code> || Sit on a low bed, right entry || <code>hold</code> || 5.200 s || 5.200 s
|-
| <code>sitbedhighleft</code> || Sit on a high bed, left entry || <code>hold</code> || 5.200 s || 5.200 s
|-
| <code>sitbedhighright</code> || Sit on a high bed, right entry || <code>hold</code> || 5.200 s || 5.200 s
|-
| <code>sleepbedlowleft</code> || Sleep on a low bed, left entry || <code>hold</code> || 15.867 s || 15.867 s
|-
| <code>sleepbedlowright</code> || Sleep on a low bed, right entry || <code>hold</code> || 12.867 s || 12.867 s
|-
| <code>sleepbedhighleft</code> || Sleep on a high bed, left entry || <code>hold</code> || 15.867 s || 15.867 s
|-
| <code>sleepbedhighright</code> || Sleep on a high bed, right entry || <code>hold</code> || 12.867 s || 12.867 s
|-
| <code>lieground</code> || Lie down / sleep on the ground || <code>hold</code> || 10.100 s || 34.133 s
|-
| <code>sitground2</code> || Sit on the ground, alternate route || <code>hold</code> || 7.133 s || 7.133 s
|-
| <code>sleepstand2</code> || Doze while standing, variant 2 || <code>hold</code> || 5.300 s || 5.300 s
|-
| <code>sleepstand3</code> || Doze while standing, variant 3 || <code>hold</code> || 4.417 s || 4.417 s
|-
| <code>leanwall2</code> || Lean against a wall, alternate variant || <code>hold</code> || 4.000 s || 4.000 s
|}

=== Daily activities (19) ===
{| class="wikitable sortable"
! Alias !! Activity !! Recommended mode !! Introduction !! Native loop start
|-
| <code>readbook</code> || Read a book while standing || <code>hold</code> || 3.833 s || 3.833 s
|-
| <code>sitreadbook</code> || Read a book while sitting || <code>hold</code> || 3.600 s || 3.600 s
|-
| <code>readlectern</code> || Read at a lectern || <code>hold</code> || 3.167 s || 3.167 s
|-
| <code>readscroll</code> || Read a scroll || <code>hold</code> || 2.167 s || 2.167 s
|-
| <code>readpaper</code> || Read a sheet of paper || <code>hold</code> || 2.167 s || 2.167 s
|-
| <code>drink</code> || Drink while standing || <code>hold</code> || 4.267 s || 4.267 s
|-
| <code>sitdrink</code> || Drink while sitting || <code>hold</code> || 3.667 s || 3.667 s
|-
| <code>grounddrink</code> || Drink while sitting on the ground || <code>hold</code> || 4.800 s || 4.800 s
|-
| <code>eatbowl</code> || Eat from a bowl while standing || <code>hold</code> || 3.433 s || 3.433 s
|-
| <code>eatmeat</code> || Eat meat while standing || <code>hold</code> || 7.667 s || 7.667 s
|-
| <code>siteatbowl</code> || Eat from a bowl while sitting || <code>hold</code> || 4.500 s || 4.500 s
|-
| <code>siteatmeat</code> || Eat meat while sitting || <code>hold</code> || 5.500 s || 5.500 s
|-
| <code>groundeat</code> || Eat while sitting on the ground || <code>hold</code> || 5.500 s || 5.500 s
|-
| <code>sitsmoke</code> || Smoke while sitting || <code>hold</code> || 4.500 s || 4.500 s
|-
| <code>playlute</code> || Play a lute while standing || <code>hold</code> || 4.100 s || 4.100 s
|-
| <code>sitplaylute</code> || Play a lute while sitting || <code>hold</code> || 6.767 s || 6.767 s
|-
| <code>wash</code> || Wash oneself || <code>hold</code> || 4.067 s || 4.067 s
|-
| <code>washtrough</code> || Wash at a trough, variant 1 || <code>once</code> || 13.667 s || —
|-
| <code>washtrough2</code> || Wash at a trough, variant 2 || <code>once</code> || 9.333 s || —
|}

=== Poses and gestures (18) ===
{| class="wikitable sortable"
! Alias !! Activity !! Recommended mode !! Introduction !! Native loop start
|-
| <code>handsonhips</code> || Stand with hands on hips || <code>hold</code> || 3.364 s || 3.364 s
|-
| <code>crossarmsthorus</code> || Thorus-style crossed arms || <code>hold</code> || 3.467 s || 3.467 s
|-
| <code>pray2</code> || Pray, alternate variant || <code>hold</code> || 5.333 s || 5.333 s
|-
| <code>meditate2</code> || Meditate, alternate variant || <code>hold</code> || 10.667 s || 10.667 s
|-
| <code>listen2</code> || Listen, alternate variant || <code>hold</code> || 2.833 s || 2.833 s
|-
| <code>exhausted2</code> || Show exhaustion, alternate variant || <code>hold</code> || 6.967 s || 6.967 s
|-
| <code>rain1</code> || React to rain, variant 1 || <code>hold</code> || 1.167 s || 1.167 s
|-
| <code>rain2</code> || React to rain, variant 2 || <code>hold</code> || 1.333 s || 1.333 s
|-
| <code>inspectfront</code> || Inspect something ahead || <code>once</code> || 10.000 s || —
|-
| <code>inspectdown</code> || Inspect something below || <code>once</code> || 10.633 s || —
|-
| <code>danceclap</code> || Dance and clap || <code>hold</code> || 2.533 s || 2.533 s
|-
| <code>sitdance</code> || Dance while sitting || <code>hold</code> || 1.267 s || 1.267 s
|-
| <code>airguitar2</code> || Concert air guitar, alternate variant || <code>hold</code> || 0.033 s || 0.033 s
|-
| <code>airkick</code> || Concert air kick || <code>hold</code> || 0.033 s || 0.033 s
|-
| <code>headbang2</code> || Intense headbanging || <code>hold</code> || 0.033 s || 0.033 s
|-
| <code>hairwhip</code> || Concert hair whip || <code>hold</code> || 0.033 s || 0.033 s
|-
| <code>raisefist</code> || Raise a fist at a concert || <code>hold</code> || 0.033 s || 0.033 s
|-
| <code>raisehands</code> || Rapidly raise hands at a concert || <code>hold</code> || 0.033 s || 0.033 s
|}

=== Practical notes ===
* Query [[getPlayerAnimationNames]] and [[getPlayerAnimationInfo]] to build a Lua menu from the running server's catalog. Pass info.looped explicitly when using the recommended mode.
* New props are cosmetic, separately owned components. Stopping or replacing their animation cleans up those components, not the player's inventory/equipment or unrelated world props.
* These are visual activities: no crafting rewards, food consumption, skill changes or scripted story actions. Native voice lines, particles and crafting effects are not replayed by the new visual-only presentation.
* Chairs, beds, anvils, troughs and other stations are not spawned or aligned automatically. Position the character at a suitable object; some station-owned rigs or scenery are separate from the character animation.
* First use may load animation/model assets. Existing request validation, bounded retries and failure diagnostics remain enabled.

=== Catalog-driven example ===
<syntaxhighlight lang="lua">
local info = getPlayerAnimationInfo("smithanvil")
if info then
startAnim(playerId, info.name, info.looped, 0.15)
end
-- End the activity when appropriate:
-- stopAnim(playerId)
</syntaxhighlight>

== Usage ==
<syntaxhighlight lang="lua">
-- Hold a prayer pose using its catalogued loop point.
startAnim(playerId, "pray", true, 0.2)

-- Play a one-shot animation from the beginning.
startAnim(playerId, "puke", false, 0.15)

-- Stop only the tracked scripted animation.
stopAnim(playerId)
</syntaxhighlight>

== Return-value contract ==
For both [[startAnim]] and [[stopAnim]], <code>true</code> means the server accepted the request, updated or retransmitted authoritative state, and attempted reliable delivery. It is not a synchronous client-playback or transport acknowledgement. Requests rejected during server validation return <code>false</code>. Client loading and presentation retries are bounded; terminal misses are written to the animation diagnostic log instead of retrying forever.

== Related functions ==
* [[startAnim]]
* [[stopAnim]]
* [[getPlayerAnimationNames]] (since 0.1.4)
* [[getPlayerAnimationInfo]] (since 0.1.4)

[[Category:Lua API]]
[[Category:Lua Catalogs]]
[[Category:Animation Functions]]


== Activity expansion (from 0.1.9) ==
'''Available from 0.1.9.''' Both the server and observing clients need the matching update.
[[Activity animation catalog]] lists all 844 new aliases with recommended modes and timing: gathering, rice/herb processing, work, crafting gestures, fishing, rest, daily activities, carrying, poses and gestures. [[Activity animations]] includes examples for players and NPCs, all six fishing aliases, cosmetic rod handling and qualification limits. The original 118 aliases remain available.

OnWorldItemPickup

2026-10-20T13:28:56Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= onWorldItemPickup =
<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.2</div>
<div style="color:#111111; margin-top:0.25rem;">This event is available in earlier releases and has corrected or expanded behavior in G1R:MP 0.1.2 and later. The contract below describes the updated behavior.</div>
</div>

Triggered after the server accepts a synchronized world-item pickup and applies its authoritative inventory grant.

== Availability ==
This event is available in '''server-side''' scripts.

== Callback signature ==
<syntaxhighlight lang="lua">
onWorldItemPickup(objectId, playerId, itemKey, quantity, serverTimeMs)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Description
|-
| <code>objectId</code> || <code>int</code> || The positive server-assigned 64-bit world-item object ID.
|-
| <code>playerId</code> || <code>int</code> || The player that picked up the item.
|-
| <code>itemKey</code> || <code>string</code> || The stable item definition key.
|-
| <code>quantity</code> || <code>int</code> || The complete accepted world-stack quantity granted to the player.
|-
| <code>serverTimeMs</code> || <code>int</code> || Server timestamp of the accepted pickup.
|}

== Examples ==
Handle the event:
<syntaxhighlight lang="lua" line>
addEventHandler("onWorldItemPickup", root, function(objectId, playerId, itemKey, quantity, serverTimeMs)
outputDebugString(getPlayerName(playerId) .. " picked up " .. itemKey)
end)
</syntaxhighlight>

== Notes ==
* The server has already added <code>quantity</code> to its authoritative native inventory cache before this observation event. Do not grant the same items again from the handler.
* The picked-up tombstone is broadcast reliably and the object is removed from active late-join state before callbacks run. The bundled GothicRP resource then persists the inventory grant asynchronously.
* Rejected, stale, duplicate, out-of-range, or over-capacity pickup attempts do not emit this event.

[[Category:Lua Events]]
[[Category:Server Events]]
[[Category:World Events]]


'''Available from 0.1.9. Use matching updated server and clients.'''

== Custom-key pickup ==
The existing <code>(objectId, playerId, item, quantity, serverTimeMs)</code> event also reports registered custom keys using their canonical identity. Inventory was already granted by the core; do not give it again. Persist your gamemode inventory as needed. This is a reserved server notification, not remotely triggerable. See [[Custom keys]].

OnWorldItemDropCommitted

2026-10-20T13:28:55Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= onWorldItemDropCommitted =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server-side event, handled on root. All resources running at commit. Deferred notification after the pending drop was committed and its world object published. No extra inventory deduction or completion call is needed. Fields are numbers except canonical item string; timestamp is server monotonic milliseconds captured when the drop was created.

== Callback ==
<syntaxhighlight lang="lua">
addEventHandler("onWorldItemDropCommitted", root, function(objectId, playerId, item, quantity, serverTimeMs)
-- Add server-side handling here; see the Custom keys guide.
end)
</syntaxhighlight>
== Contract ==
Door id is resource-local; playerId is a numeric server player ID; item is the canonical item string. Only parameters shown in this event's signature are passed. eventOrigin is "server"; sourceResource is a table with name="server". No addEvent declaration is needed. This name cannot be opted into remote calls or forged by Lua triggerEvent.

See [[Custom keys#Callbacks and safety|callback delivery and limits]]. Notifications are not cancellable hooks or durable transaction logs; readiness reports do not grant entitlement. See [[Custom keys#Drop, pickup and persistence|drop/pickup persistence]] before changing inventory in a handler.
[[Category:Lua Events]]

OnWorldItemDropCancelled

2026-10-20T13:28:54Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= onWorldItemDropCancelled =
'''Available from 0.1.9. Use matching updated server and clients.'''

Server-side event, handled on root. Captured persistence owner only. Deferred notification after cancellation of a pending drop. The core handles live rollback for a still-connected player; your gamemode owns durable inventory recovery. Do not grant the quantity again. Timestamp is the original drop creation time.

== Callback ==
<syntaxhighlight lang="lua">
addEventHandler("onWorldItemDropCancelled", root, function(objectId, playerId, item, quantity, serverTimeMs)
-- Add server-side handling here; see the Custom keys guide.
end)
</syntaxhighlight>
== Contract ==
Door id is resource-local; playerId is a numeric server player ID; item is the canonical item string. Only parameters shown in this event's signature are passed. eventOrigin is "server"; sourceResource is a table with name="server". No addEvent declaration is needed. This name cannot be opted into remote calls or forged by Lua triggerEvent.

See [[Custom keys#Callbacks and safety|callback delivery and limits]]. Notifications are not cancellable hooks or durable transaction logs; readiness reports do not grant entitlement. See [[Custom keys#Drop, pickup and persistence|drop/pickup persistence]] before changing inventory in a handler.
[[Category:Lua Events]]

OnWorldItemDrop

2026-10-20T13:28:52Z

QCherry: Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits

= onWorldItemDrop =
<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;">AVAILABLE FROM UPDATE 0.1.2</div>
<div style="color:#111111; margin-top:0.25rem;">This event is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Triggered for public server resources after a player-initiated world-item drop is durably committed and published. From 0.1.9, custom keys use this event as a pre-commit request to their defining resource instead; observers use [[onWorldItemDropCommitted]]. Read the custom-key contract below before handling those items.

== Availability ==
This event is available in '''server-side''' scripts.

== Callback signature ==
<syntaxhighlight lang="lua">
onWorldItemDrop(objectId, playerId, itemKey, quantity, serverTimeMs)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Description
|-
| <code>objectId</code> || <code>int</code> || The positive server-assigned 64-bit ID of the published dropped item.
|-
| <code>playerId</code> || <code>int</code> || The player whose inventory supplied the dropped item.
|-
| <code>itemKey</code> || <code>string</code> || The stable inventory and world-item definition key.
|-
| <code>quantity</code> || <code>int</code> || The committed quantity removed from inventory and published in the world.
|-
| <code>serverTimeMs</code> || <code>int</code> || Server timestamp recorded when the accepted drop intent created the quarantined item.
|}

== Examples ==
Handle the event:
<syntaxhighlight lang="lua" line>
addEventHandler("onWorldItemDrop", root, function(objectId, playerId, itemKey, quantity, serverTimeMs)
outputDebugString("Player " .. playerId .. " dropped " .. quantity .. "x " .. itemKey)
end)
</syntaxhighlight>

== Notes ==
* The runtime first quarantines the new object and removes the quantity from the authoritative inventory cache. The bundled GothicRP resource persists that change before confirming the transaction.
* Only a successful durable confirmation publishes the item and emits this callback to public resources. A failed or rolled-back drop publishes no public <code>onWorldItemDrop</code> event and restores the authoritative inventory state when the session is still connected.
* The active item is broadcast reliably before public callbacks run and is then included in late-join state. This is an observation event: do not remove the inventory quantity a second time.
* Player-initiated drops emit this event instead of [[onWorldItemSpawn]].

[[Category:Lua Events]]
[[Category:Server Events]]
[[Category:World Events]]


'''Available from 0.1.9. Use matching updated server and clients.'''

== Custom-key pending drop requests ==
Signature remains <code>(objectId, playerId, item, quantity, serverTimeMs)</code>. For custom keys, only the defining resource receives this pre-commit persistence request. The quantity is already deducted; object publication/pickup is quarantined until [[completeWorldItemDrop]]. Other resources should use [[onWorldItemDropCommitted]] for custom-key observation. Existing ordinary-item GothicRP/observer behavior is preserved. See [[Custom keys#Drop, pickup and persistence|full contract]].