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

Main Page

2026-09-13T00:41:11Z

QCherry: Place the main wiki heading above release announcements

__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;">
'''G1R:MP 0.1.3 — official release, BUILD106 / Protocol 35.''' Windows client and Windows/Linux dedicated server downloads are available on the [https://g1r-mp.com/download/ Download page]. Update both the client and server. See [[Update 0.1.3]] for scripting additions and migration notes.
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold;">CHAPTER SCREENS — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''2 new server-side functions''': [[showChapterScreen|ShowChapterScreen]] and [[hideChapterScreen|HideChapterScreen]] (also available with lower-camel aliases). Show custom chapter-style title cards without advancing the story. See [[Chapter screens]] for examples, validation, resource ownership and <code>/chaptertest</code>.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">OBSERVER NAMEPLATES — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''12 new server-side functions''' add per-observer text, whole-label visibility and numeric-ID policy. Build directional acquaintance presentation with exclusive resource-owned fields and reliable relevance replay. See [[Observer nameplates]] for APIs, lifecycle, database integration and the optional three-client <code>/nametest</code> sequence. Overhead customization does not anonymize other packets, chat or player lists.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">PLAYER CUSTOMIZATION — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''7 new server-side functions''' provide independent skin-color and tattoo overrides. Existing identity selection has improved head and armor compatibility from update 0.1.3. See [[Player customization]] for examples and reset behavior, and [[Player tattoo catalog]] for all 12 keys.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Skin color:</strong> [[setPlayerSkinColor]] • [[getPlayerSkinColor]] • [[resetPlayerSkinColor]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Tattoos:</strong> [[setPlayerTattoo]] • [[getPlayerTattoo]] • [[resetPlayerTattoo]] • [[getPlayerTattooNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Improved existing API:</strong> [[setPlayerIdentity]] keeps the game-owned body and equipped armor. These are cosmetic controls, not a full NPC body/outfit replacement.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">SCRIPTED CAMERA — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''15 camera functions''' and '''2 client camera events''' are available from G1R:MP 0.1.3. Build login backgrounds, fixed shots, smooth transitions, paths and orbits. See [[Scripted camera]] for examples, limits and client/server differences.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Client and server (10):</strong> [[setCameraPos]] • [[setCameraRot]] • [[setCameraLookAt]] • [[setCameraFOV]] • [[setCameraPose]] • [[moveCameraTo]] • [[playCameraPath]] • [[orbitCamera]] • [[stopCameraMovement]] • [[resetCameraPos]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client read-back (5):</strong> [[getCameraPos]] • [[getCameraRot]] • [[getCameraFOV]] • [[getCameraState]] • [[requestCameraState]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client events (2):</strong> [[onClientCameraCommandResult]] • [[onClientCameraReset]]. Client commands use asynchronous acknowledgements; server calls return only a queued boolean.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">AVAILABLE AND IMPROVED FROM UPDATE 0.1.2</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">The following '''40 Lua functions''' — 29 server-side and 11 client-side — are available from G1R:MP 0.1.2. Existing lifecycle, inventory, JSON, NPC, monster, and world-item APIs also include corrected or expanded behavior from this update.</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Accounts and consumables (4):</strong> [[completePlayerConsumableFinalize]] • [[completePlayerConsumableUse]] • [[getPlayerAccountBindingSerial]] • [[getPlayerConsumableNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>World items (1):</strong> [[spawnItem]] — see also the [[World item catalog]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster identity, health, and combat (5):</strong> [[setMonsterName]] • [[setMonsterIdVisible]] • [[setMonsterMaxHealth]] • [[getMonsterAttackDamage]] • [[setMonsterAttackDamage]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster navigation (6):</strong> [[setMonsterNavigationMode]] • [[setMonsterNavigationCollisionMode]] • [[setMonsterMoveGoal]] • [[stopMonsterMovement]] • [[testMonsterMove]] • [[walkMonsterTo]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>NPC identity and navigation (7):</strong> [[setNpcIdVisible]] • [[setNpcObstacleBehavior]] • [[setNpcNavigationMode]] • [[setNpcNavigationCollisionMode]] • [[setNpcMoveGoal]] • [[stopNpcMovement]] • [[testNpcMove]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Custom navigation blockers (6):</strong> [[createAiNavigationBlocker]] • [[updateAiNavigationBlocker]] • [[setAiNavigationBlockerEnabled]] • [[destroyAiNavigationBlocker]] • [[getAiNavigationBlockerData]] • [[getAiNavigationBlockers]] — see [[NPC and monster navigation collision]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client audio (11):</strong> [[playSound]] • [[playSound3D]] • [[stopSound]] • [[setSoundVolume]] • [[getSoundVolume]] • [[setSoundPaused]] • [[isSoundPaused]] • [[isSoundPlaying]] • [[setSoundLooped]] • [[setSound3DPosition]] • [[setSound3DMinMaxDistance]] — see [[Client audio]].</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Events available from 0.1.2 (8):</strong> [[onNpcIdVisibilityChange]] • [[onMonsterNameChange]] • [[onMonsterIdVisibilityChange]] • [[onMonsterMoveBlocked]] • [[onMonsterMoveComplete]] • [[onNpcMoveBlocked]] • [[onNpcMoveComplete]] • [[onWorldItemDrop]]. Existing [[onPlayerJoin]], [[onPlayerQuit]], [[onWorldItemPickup]], and [[onWorldItemSpawn]] contracts are also improved from 0.1.2.</div>
</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 — 0.1.3 BUILD81]]</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>[[Scripted camera|Scripted camera and moving login backgrounds (0.1.3)]]</li>
<li>[[Chapter screens|Custom chapter title cards (0.1.3)]]</li>
<li>[[Observer nameplates|Observer-specific labels and acquaintance presentation (0.1.3)]]</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>[[: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|Client audio functions]]</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>[[Known issue: MySQL error 2006 (Server has gone away)|Known MySQL/MariaDB issue]]</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;">The reference contains '''312 Lua functions''' and '''94 events''', including '''2 chapter-screen functions, 12 observer/nameplate-ID functions, 7 skin-color/tattoo functions, 15 camera functions and 2 camera events available from update 0.1.3'''. Version notices distinguish newly available APIs from improved contracts in earlier APIs. See [[Chapter screens]] for custom title cards, [[Observer nameplates]] for directional labels, [[Player customization]] for identity, color and tattoos, [[Lua API catalogs]] for validated gameplay keys, and [[Scripted camera]] for camera state and lifecycle rules. APIs marked [[:Category:Experimental Lua API|experimental]] may still change while the multiplayer runtime is under active development.</div>
</div>
</div>

[[Category:Lua API]]

Hosting a G1R:MP dedicated server

2026-09-13T00:29:46Z

QCherry: Update hosting compatibility to 0.1.3 / Protocol 35

{{DISPLAYTITLE:Hosting a G1R:MP dedicated server}}
__NOTOC__

= Hosting a G1R:MP dedicated server =

<div style="border:1px solid #b28a3d; border-left:4px solid #b28a3d; background:#faf9f5; padding:0.9rem 1rem; margin:0.8rem 0 1.2rem;">
'''Public network access is required.''' A server hosted on your own computer still needs a publicly reachable address and the required ports opened or forwarded.
</div>

This requirement also applies when the dedicated server, launcher, and game are running on the same computer. The current 0.1.3 release uses Protocol 35 and the official G1R:MP service for server discovery and connection authorization, including direct-connect attempts. Private-only server addresses are not accepted for public registration. Update both the client and server; see [[Update 0.1.3]].

The official service does not relay gameplay. After authorization, gameplay, voice, and resource traffic connects directly to the public endpoint advertised by the dedicated server. This architecture requires that endpoint to be reachable from the Internet.

== Public address requirement ==

The host must have either:

* a public, externally reachable IP address; or
* a DNS name that resolves to that public address.

Addresses such as <code>127.0.0.1</code>, <code>localhost</code>, <code>192.168.x.x</code>, and <code>10.x.x.x</code> are not reachable from the Internet.

If the server is behind a home router, configure port forwarding from the router's public address to the computer's fixed LAN address. If the ISP uses carrier-grade NAT (CGNAT), ordinary router port forwarding is not sufficient; request a public IP address from the ISP or host the server on a publicly reachable VPS.

For the standard automatic listing configuration, leave <code>listing.publicHost</code> empty. The official service can use the source address of the server heartbeat. Set it only when advertising a public DNS name that resolves to the same server.

<syntaxhighlight lang="ini">
[listing]
publicHost=
</syntaxhighlight>

== Default ports ==

The current default configuration uses the following ports:

{| class="wikitable" style="width:100%;"
! Purpose !! Default port !! Protocol !! Public access
|-
| Gameplay transport || <code>7777</code> || UDP || Required
|-
| Voice relay || <code>7778</code> || UDP || Required when voice chat is enabled
|-
| Resource download service || <code>7780</code> || TCP || Required when <code>http.mode=auto</code> or the built-in HTTP service is used
|-
| RCON administration || <code>7781</code> || TCP || '''Do not expose'''; loopback-only by default
|-
| MariaDB/MySQL || <code>3307</code> in the shipped Gothic RP configuration, or the locally configured database port (commonly <code>3306</code>) || TCP || '''Do not expose''' when the database is on the same host
|}

The server also requires outbound HTTPS access, normally TCP port <code>443</code>, to synchronize with the official G1R:MP service. This is an outbound connection and does not require router port forwarding.

If any ports are changed in <code>serverconf.cfg</code>, update the firewall and router rules to match the configured values.

== Recommended bind configuration ==

The public services should normally listen on all local interfaces:

<syntaxhighlight lang="ini">
[server]
bind=0.0.0.0
port=7777

[voice]
enabled=true
bind=0.0.0.0
port=7778

[http]
mode=auto
bind=0.0.0.0
port=7780
</syntaxhighlight>

Keep RCON restricted to the local machine:

<syntaxhighlight lang="ini">
[rcon]
enabled=true
allowRemote=false
bind=127.0.0.1
port=7781
</syntaxhighlight>

== Player capacity and server password ==

Set the player limit and optional join password in the <code>[server]</code> section. <code>maxPlayers</code> accepts any integer from <code>1</code> through <code>5000</code>, inclusive. The server refuses to start when the value is outside that range.

<syntaxhighlight lang="ini">
[server]
maxPlayers=500
password=
</syntaxhighlight>

The <code>password</code> setting supports three forms:

{| class="wikitable" style="width:100%;"
! Configuration !! Result
|-
| <code>password=</code> || No join password. The server is advertised as public.
|-
| <code>password=a-literal-secret</code> || Uses the literal value from <code>serverconf.cfg</code>. A non-empty password must contain from <code>1</code> through <code>128</code> bytes.
|-
| <code>password=env:VARIABLE</code> || Reads the password from the named environment variable when the server starts. The resolved value must contain from <code>1</code> through <code>128</code> bytes.
|}

The environment-variable form keeps the credential out of <code>serverconf.cfg</code> and is recommended for hosted servers. The variable name must be a valid environment-variable identifier, and the server stops during configuration loading if the variable is missing, empty, longer than 128 bytes, or contains a forbidden control character.

Do not set <code>listing.passworded</code> manually. The advertised <code>passworded</code> value is derived automatically from the resolved <code>[server] password</code>, so the server list and health response cannot claim a password policy different from the one enforced by the server.

Before downloading resources, the launcher checks the server health response. It stops early when <code>players</code> has reached <code>maxPlayers</code>, and it requests a password when <code>passworded</code> is true. These checks provide immediate feedback only: the dedicated server independently enforces the slot limit and validates the password during admission. A stale server-list entry or modified client cannot bypass either rule.

== Resource package limits ==

These expanded values apply from '''update 0.1.3 BUILD81'''. Older 0.1.3 clients must be updated. See [[Scripting limits]] and [[Server configuration limits]] for all other budgets and exact units.

The dedicated server and client enforce matching compatibility limits for Lua scripts and downloadable resources. Values at a stated hard boundary are accepted; a resource that exceeds that boundary is rejected before it can run.

{| class="wikitable" style="width:100%;"
! Limit !! Value !! Scope
|-
| Lua script size || <code>128 MiB</code> || Each individual <code>.lua</code> script.
|-
| Resource file size || <code>256 MiB</code> || Each individual file included in the client resource catalog.
|-
| Catalog file count || <code>262,144</code> files || All client scripts and downloadable files across the complete catalog.
|-
| Catalog payload || <code>32 GiB</code> || Sum of the file sizes declared by the complete client resource catalog.
|-
| Catalog JSON document || <code>128 MiB</code> || Serialized <code>catalog.json</code> metadata returned by the resource service.
|-
| Lua VM memory || <code>1024 MiB</code> by default || Each client-side resource Lua VM uses the 1024 MiB default. For each server-side resource Lua VM, <code>[lua] memoryLimitMB</code> is configurable from <code>4</code> through <code>4096</code> MiB; the shipped default is <code>1024</code> MiB.
|}

The dedicated server validates manifests, script sizes, file counts, payload totals, and catalog JSON size while building the catalog. The client validates the catalog and every downloaded file again before caching or executing it. When <code>http.mode=external</code> is used, a CDN or reverse proxy may impose stricter transfer limits, but it cannot raise the limits enforced by the client.

== Firewall examples ==

=== Windows ===

Run PowerShell as Administrator:

<syntaxhighlight lang="powershell">
New-NetFirewallRule -DisplayName "G1R:MP Gameplay" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 7777
New-NetFirewallRule -DisplayName "G1R:MP Voice" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 7778
New-NetFirewallRule -DisplayName "G1R:MP Resources" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 7780
</syntaxhighlight>

=== Linux with UFW ===

<syntaxhighlight lang="bash">
sudo ufw allow 7777/udp
sudo ufw allow 7778/udp
sudo ufw allow 7780/tcp
</syntaxhighlight>

On a VPS or cloud host, add equivalent inbound rules to the provider firewall or security group as well as the operating-system firewall.

== Testing reachability ==

Test the server from a different Internet connection, such as another household or a mobile hotspot. Testing only from the same LAN can give misleading results because routers handle NAT loopback differently.

A server appearing in the master list confirms that its outbound heartbeat reached the official service. It does not by itself prove that UDP <code>7777</code>, UDP <code>7778</code>, and TCP <code>7780</code> are reachable from the Internet.

Do not solve a connection problem by opening RCON or MariaDB publicly. Those services should remain private.

[[Category:Server administration]]
[[Category:Networking]]

Main Page

2026-09-13T00:29:43Z

QCherry: Announce official 0.1.3 / BUILD106 / Protocol 35

__NOTOC__

<div style="border:1px solid #b28a3d; border-left:4px solid #b28a3d; background:#faf9f5; padding:0.9rem 1rem; margin:0 0 1.2rem;">
'''G1R:MP 0.1.3 — official release, BUILD106 / Protocol 35.''' Windows client and Windows/Linux dedicated server downloads are available on the [https://g1r-mp.com/download/ Download page]. Update both the client and server. See [[Update 0.1.3]] for scripting additions and migration notes.
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold;">CHAPTER SCREENS — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''2 new server-side functions''': [[showChapterScreen|ShowChapterScreen]] and [[hideChapterScreen|HideChapterScreen]] (also available with lower-camel aliases). Show custom chapter-style title cards without advancing the story. See [[Chapter screens]] for examples, validation, resource ownership and <code>/chaptertest</code>.</div>
</div>

<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="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">OBSERVER NAMEPLATES — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''12 new server-side functions''' add per-observer text, whole-label visibility and numeric-ID policy. Build directional acquaintance presentation with exclusive resource-owned fields and reliable relevance replay. See [[Observer nameplates]] for APIs, lifecycle, database integration and the optional three-client <code>/nametest</code> sequence. Overhead customization does not anonymize other packets, chat or player lists.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">PLAYER CUSTOMIZATION — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''7 new server-side functions''' provide independent skin-color and tattoo overrides. Existing identity selection has improved head and armor compatibility from update 0.1.3. See [[Player customization]] for examples and reset behavior, and [[Player tattoo catalog]] for all 12 keys.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Skin color:</strong> [[setPlayerSkinColor]] • [[getPlayerSkinColor]] • [[resetPlayerSkinColor]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Tattoos:</strong> [[setPlayerTattoo]] • [[getPlayerTattoo]] • [[resetPlayerTattoo]] • [[getPlayerTattooNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Improved existing API:</strong> [[setPlayerIdentity]] keeps the game-owned body and equipped armor. These are cosmetic controls, not a full NPC body/outfit replacement.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">SCRIPTED CAMERA — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''15 camera functions''' and '''2 client camera events''' are available from G1R:MP 0.1.3. Build login backgrounds, fixed shots, smooth transitions, paths and orbits. See [[Scripted camera]] for examples, limits and client/server differences.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Client and server (10):</strong> [[setCameraPos]] • [[setCameraRot]] • [[setCameraLookAt]] • [[setCameraFOV]] • [[setCameraPose]] • [[moveCameraTo]] • [[playCameraPath]] • [[orbitCamera]] • [[stopCameraMovement]] • [[resetCameraPos]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client read-back (5):</strong> [[getCameraPos]] • [[getCameraRot]] • [[getCameraFOV]] • [[getCameraState]] • [[requestCameraState]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client events (2):</strong> [[onClientCameraCommandResult]] • [[onClientCameraReset]]. Client commands use asynchronous acknowledgements; server calls return only a queued boolean.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">AVAILABLE AND IMPROVED FROM UPDATE 0.1.2</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">The following '''40 Lua functions''' — 29 server-side and 11 client-side — are available from G1R:MP 0.1.2. Existing lifecycle, inventory, JSON, NPC, monster, and world-item APIs also include corrected or expanded behavior from this update.</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Accounts and consumables (4):</strong> [[completePlayerConsumableFinalize]] • [[completePlayerConsumableUse]] • [[getPlayerAccountBindingSerial]] • [[getPlayerConsumableNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>World items (1):</strong> [[spawnItem]] — see also the [[World item catalog]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster identity, health, and combat (5):</strong> [[setMonsterName]] • [[setMonsterIdVisible]] • [[setMonsterMaxHealth]] • [[getMonsterAttackDamage]] • [[setMonsterAttackDamage]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster navigation (6):</strong> [[setMonsterNavigationMode]] • [[setMonsterNavigationCollisionMode]] • [[setMonsterMoveGoal]] • [[stopMonsterMovement]] • [[testMonsterMove]] • [[walkMonsterTo]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>NPC identity and navigation (7):</strong> [[setNpcIdVisible]] • [[setNpcObstacleBehavior]] • [[setNpcNavigationMode]] • [[setNpcNavigationCollisionMode]] • [[setNpcMoveGoal]] • [[stopNpcMovement]] • [[testNpcMove]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Custom navigation blockers (6):</strong> [[createAiNavigationBlocker]] • [[updateAiNavigationBlocker]] • [[setAiNavigationBlockerEnabled]] • [[destroyAiNavigationBlocker]] • [[getAiNavigationBlockerData]] • [[getAiNavigationBlockers]] — see [[NPC and monster navigation collision]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client audio (11):</strong> [[playSound]] • [[playSound3D]] • [[stopSound]] • [[setSoundVolume]] • [[getSoundVolume]] • [[setSoundPaused]] • [[isSoundPaused]] • [[isSoundPlaying]] • [[setSoundLooped]] • [[setSound3DPosition]] • [[setSound3DMinMaxDistance]] — see [[Client audio]].</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Events available from 0.1.2 (8):</strong> [[onNpcIdVisibilityChange]] • [[onMonsterNameChange]] • [[onMonsterIdVisibilityChange]] • [[onMonsterMoveBlocked]] • [[onMonsterMoveComplete]] • [[onNpcMoveBlocked]] • [[onNpcMoveComplete]] • [[onWorldItemDrop]]. Existing [[onPlayerJoin]], [[onPlayerQuit]], [[onWorldItemPickup]], and [[onWorldItemSpawn]] contracts are also improved from 0.1.2.</div>
</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 — 0.1.3 BUILD81]]</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>[[Scripted camera|Scripted camera and moving login backgrounds (0.1.3)]]</li>
<li>[[Chapter screens|Custom chapter title cards (0.1.3)]]</li>
<li>[[Observer nameplates|Observer-specific labels and acquaintance presentation (0.1.3)]]</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>[[: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|Client audio functions]]</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>[[Known issue: MySQL error 2006 (Server has gone away)|Known MySQL/MariaDB issue]]</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;">The reference contains '''312 Lua functions''' and '''94 events''', including '''2 chapter-screen functions, 12 observer/nameplate-ID functions, 7 skin-color/tattoo functions, 15 camera functions and 2 camera events available from update 0.1.3'''. Version notices distinguish newly available APIs from improved contracts in earlier APIs. See [[Chapter screens]] for custom title cards, [[Observer nameplates]] for directional labels, [[Player customization]] for identity, color and tattoos, [[Lua API catalogs]] for validated gameplay keys, and [[Scripted camera]] for camera state and lifecycle rules. APIs marked [[:Category:Experimental Lua API|experimental]] may still change while the multiplayer runtime is under active development.</div>
</div>
</div>

[[Category:Lua API]]

Update 0.1.3

2026-09-13T00:29:40Z

QCherry: Publish official 0.1.3 release and migration guide

{{DISPLAYTITLE:G1R:MP Update 0.1.3}}
__NOTOC__

= Update 0.1.3 =

'''Official release: 0.1.3, BUILD106, Protocol 35.''' Download the Windows x64 client and matching Windows x64 or Linux x86_64 dedicated server from the [https://g1r-mp.com/download/ official Download page]. The Windows launcher uses the existing automatic update channel.

== Update both sides ==

Protocol 35 requires a matching client and dedicated server. Back up your server configuration, resources and database before upgrading. Stop the dedicated server before replacing its binaries; preserve your own gamemode and configuration rather than overwriting them with examples. The supplied Gothic RP database password is <code>CHANGE_ME</code> and must be configured locally.

The public version is <code>0.1.3</code>. Windows Explorer shows the client file version <code>0.1.3.106</code>; the final number is the launcher build, not a separate Lua API version. See [[Hosting a G1R:MP dedicated server]] for network and port requirements.

== Scripting available from 0.1.3 ==

* '''Scripted camera:''' 15 functions and two client events. Set position, rotation, look-at and FOV; animate transitions, paths and orbits; reset to normal gameplay. See [[Scripted camera]].
* '''Player appearance:''' seven functions for skin color and tattoos, with improved compatibility for the existing identity API. See [[Player customization]] and [[Player tattoo catalog]].
* '''Observer-specific nameplates:''' 12 server functions for per-observer labels, visibility and ID policy. Gamemodes can persist their own directional acquaintance records in a database. See [[Observer nameplates]].
* '''Custom chapter title cards:''' [[showChapterScreen|ShowChapterScreen]] and [[hideChapterScreen|HideChapterScreen]] display presentation-only cards without advancing the story. See [[Chapter screens]].
* '''Expanded scripting budgets:''' see [[Scripting limits]] for the current client/server limits, including timers and resource budgets.

Function pages specify the execution side, accepted arguments, return values and asynchronous acknowledgement rules. Version annotations refer to API availability; they do not make server-only functions callable from client resources.

== Examples and test commands ==

The included Gothic RP resources provide <code>/cameratest</code>, <code>/looktest</code>, <code>/nametest</code> and <code>/chaptertest</code>. Use the linked guides for syntax and prerequisites. Keep administrative test commands restricted to trusted users on public servers. Existing gamemodes are not replaced automatically by the client updater.

== Reference ==

The API reference contains '''312 function pages and 94 event pages'''. Start with [[Main Page]], [[Lua API catalogs]] and [[Lua events]].

[[Category:Lua API]]

Main Page

2026-09-12T18:33:06Z

QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

__NOTOC__

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold;">CHAPTER SCREENS — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''2 new server-side functions''': [[showChapterScreen|ShowChapterScreen]] and [[hideChapterScreen|HideChapterScreen]] (also available with lower-camel aliases). Show custom chapter-style title cards without advancing the story. See [[Chapter screens]] for examples, validation, resource ownership and <code>/chaptertest</code>.</div>
</div>

<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="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">OBSERVER NAMEPLATES — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''12 new server-side functions''' add per-observer text, whole-label visibility and numeric-ID policy. Build directional acquaintance presentation with exclusive resource-owned fields and reliable relevance replay. See [[Observer nameplates]] for APIs, lifecycle, database integration and the optional three-client <code>/nametest</code> sequence. Overhead customization does not anonymize other packets, chat or player lists.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">PLAYER CUSTOMIZATION — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''7 new server-side functions''' provide independent skin-color and tattoo overrides. Existing identity selection has improved head and armor compatibility from update 0.1.3. See [[Player customization]] for examples and reset behavior, and [[Player tattoo catalog]] for all 12 keys.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Skin color:</strong> [[setPlayerSkinColor]] • [[getPlayerSkinColor]] • [[resetPlayerSkinColor]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Tattoos:</strong> [[setPlayerTattoo]] • [[getPlayerTattoo]] • [[resetPlayerTattoo]] • [[getPlayerTattooNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Improved existing API:</strong> [[setPlayerIdentity]] keeps the game-owned body and equipped armor. These are cosmetic controls, not a full NPC body/outfit replacement.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">SCRIPTED CAMERA — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''15 camera functions''' and '''2 client camera events''' are available from G1R:MP 0.1.3. Build login backgrounds, fixed shots, smooth transitions, paths and orbits. See [[Scripted camera]] for examples, limits and client/server differences.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Client and server (10):</strong> [[setCameraPos]] • [[setCameraRot]] • [[setCameraLookAt]] • [[setCameraFOV]] • [[setCameraPose]] • [[moveCameraTo]] • [[playCameraPath]] • [[orbitCamera]] • [[stopCameraMovement]] • [[resetCameraPos]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client read-back (5):</strong> [[getCameraPos]] • [[getCameraRot]] • [[getCameraFOV]] • [[getCameraState]] • [[requestCameraState]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client events (2):</strong> [[onClientCameraCommandResult]] • [[onClientCameraReset]]. Client commands use asynchronous acknowledgements; server calls return only a queued boolean.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">AVAILABLE AND IMPROVED FROM UPDATE 0.1.2</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">The following '''40 Lua functions''' — 29 server-side and 11 client-side — are available from G1R:MP 0.1.2. Existing lifecycle, inventory, JSON, NPC, monster, and world-item APIs also include corrected or expanded behavior from this update.</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Accounts and consumables (4):</strong> [[completePlayerConsumableFinalize]] • [[completePlayerConsumableUse]] • [[getPlayerAccountBindingSerial]] • [[getPlayerConsumableNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>World items (1):</strong> [[spawnItem]] — see also the [[World item catalog]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster identity, health, and combat (5):</strong> [[setMonsterName]] • [[setMonsterIdVisible]] • [[setMonsterMaxHealth]] • [[getMonsterAttackDamage]] • [[setMonsterAttackDamage]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster navigation (6):</strong> [[setMonsterNavigationMode]] • [[setMonsterNavigationCollisionMode]] • [[setMonsterMoveGoal]] • [[stopMonsterMovement]] • [[testMonsterMove]] • [[walkMonsterTo]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>NPC identity and navigation (7):</strong> [[setNpcIdVisible]] • [[setNpcObstacleBehavior]] • [[setNpcNavigationMode]] • [[setNpcNavigationCollisionMode]] • [[setNpcMoveGoal]] • [[stopNpcMovement]] • [[testNpcMove]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Custom navigation blockers (6):</strong> [[createAiNavigationBlocker]] • [[updateAiNavigationBlocker]] • [[setAiNavigationBlockerEnabled]] • [[destroyAiNavigationBlocker]] • [[getAiNavigationBlockerData]] • [[getAiNavigationBlockers]] — see [[NPC and monster navigation collision]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client audio (11):</strong> [[playSound]] • [[playSound3D]] • [[stopSound]] • [[setSoundVolume]] • [[getSoundVolume]] • [[setSoundPaused]] • [[isSoundPaused]] • [[isSoundPlaying]] • [[setSoundLooped]] • [[setSound3DPosition]] • [[setSound3DMinMaxDistance]] — see [[Client audio]].</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Events available from 0.1.2 (8):</strong> [[onNpcIdVisibilityChange]] • [[onMonsterNameChange]] • [[onMonsterIdVisibilityChange]] • [[onMonsterMoveBlocked]] • [[onMonsterMoveComplete]] • [[onNpcMoveBlocked]] • [[onNpcMoveComplete]] • [[onWorldItemDrop]]. Existing [[onPlayerJoin]], [[onPlayerQuit]], [[onWorldItemPickup]], and [[onWorldItemSpawn]] contracts are also improved from 0.1.2.</div>
</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 — 0.1.3 BUILD81]]</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>[[Scripted camera|Scripted camera and moving login backgrounds (0.1.3)]]</li>
<li>[[Chapter screens|Custom chapter title cards (0.1.3)]]</li>
<li>[[Observer nameplates|Observer-specific labels and acquaintance presentation (0.1.3)]]</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>[[: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|Client audio functions]]</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>[[Known issue: MySQL error 2006 (Server has gone away)|Known MySQL/MariaDB issue]]</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;">The reference contains '''312 Lua functions''' and '''94 events''', including '''2 chapter-screen functions, 12 observer/nameplate-ID functions, 7 skin-color/tattoo functions, 15 camera functions and 2 camera events available from update 0.1.3'''. Version notices distinguish newly available APIs from improved contracts in earlier APIs. See [[Chapter screens]] for custom title cards, [[Observer nameplates]] for directional labels, [[Player customization]] for identity, color and tattoos, [[Lua API catalogs]] for validated gameplay keys, and [[Scripted camera]] for camera state and lifecycle rules. APIs marked [[:Category:Experimental Lua API|experimental]] may still change while the multiplayer runtime is under active development.</div>
</div>
</div>

[[Category:Lua API]]

Chapter screens

2026-09-12T18:33:05Z

QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

= Chapter screens =

'''AVAILABLE FROM UPDATE 0.1.3''' — introduced in BUILD85. Use a server and client that both include chapter-screen support. An older protocol-34 client is not sufficient merely because it can connect.

[[showChapterScreen|ShowChapterScreen]] displays a custom, passive chapter-style title card to one player. [[hideChapterScreen|HideChapterScreen]] requests early removal. The lower-camel aliases <code>showChapterScreen</code> and <code>hideChapterScreen</code> behave identically.

This is a presentation API, '''not a story/chapter progression API'''. It does not change quests, saves or the current chapter, and does not start chapter music or a native cutscene. It uses the game's chapter-style widget with fixed background artwork and no image/audio options. It does not request input focus.

== Server-side example ==
Call after the player's character is available, for example from an authenticated server command:

<syntaxhighlight lang="lua" line>
local accepted = ShowChapterScreen(playerId, "CHAPTER I", "Welcome to the Colony", 6000)
-- accepted means the server accepted delivery, not a client render acknowledgement.

-- When the same resource needs to remove its card early:
-- HideChapterScreen(playerId)
</syntaxhighlight>

An empty heading is valid. Omit the fourth argument for 6000 ms; do not pass <code>nil</code> explicitly. There are no new chapter-screen Lua events or client-side Lua bindings.

== Validation and limits ==
{| class="wikitable"
! Field !! Accepted value
|-
| playerId || Connected player ID, finite integer 1–4294967295.
|-
| heading || UTF-8 string, 0–256 bytes.
|-
| title || UTF-8 string, 1–512 bytes.
|-
| durationMs || Finite integer 1000–30000 ms; default 6000 ms.
|-
| Presentation || One custom card per player. A later show replaces the previous card; no display backlog.
|-
| Resource ownership || Up to 8192 distinct tracked player IDs per server resource. Explicit hide/resource cleanup releases tracking; automatic visual expiry is not a Lua acknowledgement.
|-
| Native pending commands || Bounded queue of 32; excess pending commands can be discarded. At most three widget-creation attempts, 500 ms apart.
|}

Limits on strings count '''UTF-8 bytes''', not characters. Invalid UTF-8, NUL, control characters and line breaks (including Unicode line/paragraph separators) are rejected. Text is literal: <code><b>Title</b></code> is not markup. Show accepts exactly three or four arguments; hide accepts exactly one.

== Ownership and lifetime ==
* The latest show becomes the current resource-owned card, including when another resource previously displayed one.
* An old resource's hide/cleanup cannot remove another resource's replacement card. A successful server-side hide is not proof that a visible card was removed.
* Cards expire automatically. Duration starts when the native client processes the show and includes the fades, not server/network delay.
* Disconnect, resource cleanup and player-pawn replacement clear the corresponding presentation. This API is not a pre-spawn loading-screen facility.
* This API is separate from multiplayer suppression of native story triggers. It does '''not''' provide a general switch for disabling story regions, ladder events, conversations or cinematics.

== Bundled GothicRP test ==
The test requires an authenticated player and affects only the caller:

* <code>/chaptertest</code> — default six-second card.
* <code>/chaptertest show My custom title</code> — custom title.
* <code>/chaptertest unicode</code> — Unicode text.
* <code>/chaptertest literal</code> — verifies literal text instead of markup.
* <code>/chaptertest replace</code> — replaces an older card immediately.
* <code>/chaptertest long My title</code> — 30-second card.
* <code>/chaptertest hide</code> — early hide from the same resource.

Check expiration, replacement, movement and native menus/GUI clicks. These are bundled test commands, not additional public Lua functions.

[[Category:Lua API]]
[[Category:Lua Examples]]

HideChapterScreen

2026-09-12T18:33:03Z

QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

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

Request early removal of the calling resource's custom chapter title card for one player. See [[showChapterScreen]] and [[Chapter screens]].

== Syntax ==
<syntaxhighlight lang="lua">
bool HideChapterScreen(int playerId)
bool hideChapterScreen(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 an owned hide request is accepted for delivery. Returns <code>false</code> for invalid arguments, a disconnected player, no tracked chapter ownership for this resource/player, or a rejected runtime action. This is not a client-render acknowledgement.

== Examples ==
Hide a title card previously requested by this same resource:
<syntaxhighlight lang="lua" line>
HideChapterScreen(playerId)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Available from update 0.1.3 (introduced in BUILD85), with matching client support.
* Both spellings in Syntax are aliases. Exactly one argument is accepted.
* Only the current owner can remove the displayed custom card. If another resource replaced it, an older resource's accepted hide is ignored by the client and does not hide the new card.
* The server ownership record is not a visibility query: automatic client expiry does not acknowledge an early hide to Lua. Do not use the return value to determine whether a card was visible.
* The custom card also expires automatically; resource cleanup, disconnect and player-pawn replacement clear the corresponding presentation. This function does not change the story or cancel arbitrary native cutscenes.

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

ShowChapterScreen

2026-09-12T18:33:02Z

QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

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

Show a custom chapter-style title card to one player. Presentation only: this does not advance the story, quests or the saved chapter. See [[Chapter screens]].

== Syntax ==
<syntaxhighlight lang="lua">
bool ShowChapterScreen(int playerId, string heading, string title [, int durationMs = 6000])
bool showChapterScreen(int playerId, string heading, string title [, int durationMs = 6000])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>heading</code> || <code>string</code> || yes || Top line: valid UTF-8, 0–256 bytes; an empty string is allowed.
|-
| <code>title</code> || <code>string</code> || yes || Main line: valid UTF-8, 1–512 bytes.
|-
| <code>durationMs</code> || <code>int</code> || no || Integer 1000–30000 milliseconds, default 6000. Omit this argument to use the default; explicit nil is invalid.
|}

== Returns ==
Returns <code>true</code> when the server accepts the request for delivery. This is not confirmation that the client rendered it. Returns <code>false</code> for invalid arguments, a disconnected player, an ownership-capacity limit or a rejected runtime action.

== Examples ==
Call from a server-side command or event after the player's character is available:
<syntaxhighlight lang="lua" line>
ShowChapterScreen(playerId, "CHAPTER I", "Welcome to the Colony", 6000)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Available from update 0.1.3 (introduced in BUILD85). Both server and client must support this API; matching protocol 34 alone is not sufficient for older clients.
* Both spellings in Syntax are aliases of the same function; they are not separate screens.
* Text is literal, not HTML/RML. Control characters, NUL and line breaks are rejected. UTF-8 limits are bytes, not visible characters.
* One custom chapter screen per player: a later show replaces the previous one, including a screen from another resource. No backlog is retained.
* The screen expires automatically. Duration starts when the native client processes the request and includes its fade-in/fade-out, not network delay.
* Use [[hideChapterScreen]] for an early hide. Hiding and resource cleanup cannot remove a screen currently owned by another resource.
* The server tracks at most 8192 distinct player IDs per resource for chapter ownership until explicit hide/resource cleanup; an already tracked ID can be reused.
* This passive native title card does not request input focus or start chapter gameplay, a cinematic or chapter music. Background artwork is fixed; this API exposes no image/audio parameters.
* Do not use as a pre-spawn loading screen. The native client has a bounded 32-command pending queue and at most three widget-creation attempts at 500 ms intervals.
* The bundled GothicRP test command is <code>/chaptertest</code>; see [[Chapter screens]] for variants.

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

AddEventHandler

2026-09-12T11:51:54Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= addEventHandler =
Attaches a Lua callback to a named event in the current resource.

== Syntax ==
<syntaxhighlight lang="lua">
bool addEventHandler(string eventName, element attachedTo, function handler)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>eventName</code> || <code>string</code> || yes || The event to listen for.
|-
| <code>attachedTo</code> || <code>element</code> || yes || The attachment target. Use <code>root</code> for a global resource handler.
|-
| <code>handler</code> || <code>function</code> || yes || The callback invoked when the event is triggered.
|}

== Returns ==
Returns <code>true</code> when the handler is registered; otherwise returns <code>false</code>.

== Examples ==
Handle a custom event:
<syntaxhighlight lang="lua" line>
addEvent("quest:updated")

local function onQuestUpdated(questId)
print("Quest updated:", questId)
end

addEventHandler("quest:updated", root, onQuestUpdated)
</syntaxhighlight>

== Notes ==
* Available in both client-side and server-side resource scripts.
* Expanded limits apply from update 0.1.3 BUILD81. Client limits: 8192 total handlers per resource and 512 handlers per event. The server has no matching fixed handler-count cap. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Shared Functions]]
[[Category:Event Functions]]

AddEvent

2026-09-12T11:51:52Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= addEvent =
Declares a custom event for the current resource.

== Syntax ==
<syntaxhighlight lang="lua">
bool addEvent(string eventName [, bool allowRemoteTrigger = false])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>eventName</code> || <code>string</code> || yes || The custom event name, up to 128 bytes.
|-
| <code>allowRemoteTrigger</code> || <code>bool</code> || no || Whether the event may be triggered across the client/server boundary.
|}

== Returns ==
Returns <code>true</code> when the event is declared successfully. On the server it returns <code>false</code> if the event was already declared.

== Examples ==
Declare a server event that clients may trigger:
<syntaxhighlight lang="lua" line>
addEvent("inventory:request", true)
</syntaxhighlight>

== Notes ==
* Available in both client-side and server-side resource scripts.
* Only enable remote triggering for events whose arguments and permissions are validated by the receiver.
* Expanded limits apply from update 0.1.3 BUILD81. Client limit: 4096 declared remote event names per resource; the server has no matching fixed declaration-count cap. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Shared Functions]]
[[Category:Event Functions]]

SetTimer

2026-09-12T11:51:51Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= setTimer =
Schedules a Lua function to run after a delay, optionally more than once.

== Syntax ==
<syntaxhighlight lang="lua">
int setTimer(function callback, int intervalMs, int timesToExecute, ...)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>callback</code> || <code>function</code> || yes || The function to execute.
|-
| <code>intervalMs</code> || <code>int</code> || yes || Delay between executions in milliseconds. The minimum is 10.
|-
| <code>timesToExecute</code> || <code>int</code> || yes || Number of executions. Use 0 to repeat indefinitely.
|-
| <code>...</code> || <code>any</code> || no || Optional values passed to the callback each time it runs.
|}

== Returns ==
Returns a positive timer identifier on success, or <code>0</code> when the timer could not be created.

== Examples ==
Print a message three times at one-second intervals:
<syntaxhighlight lang="lua" line>
local timer = setTimer(function(message)
print(message)
end, 1000, 3, "One second passed")
</syntaxhighlight>

== Notes ==
* Available in both client-side and server-side resource scripts.
* Expanded limits apply from update 0.1.3 BUILD81. Client limits: 8192 timers per resource, at most 256 selected callbacks per tick, oldest deadline first, and 32 callback arguments. The server has no corresponding fixed timer-count or callbacks-per-tick cap; memory and execution budgets still apply. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Shared Functions]]
[[Category:Timer Functions]]
[[Category:Utility Functions]]

PlaySound3D

2026-09-12T11:51:50Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= playSound3D =
<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 function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Starts a positional OGG Vorbis sound at a world position owned by the current client resource.

== Syntax ==
<syntaxhighlight lang="lua">
number|false playSound3D(string relativePath, number x, number y, number z [, bool looped = false, number volume = 1, number minDistance = 1, number maxDistance = 50])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>relativePath</code> || <code>string</code> || yes || The exact relative path of a same-resource <code><file download="join"></code> entry ending in <code>.ogg</code>.
|-
| <code>x</code> || <code>number</code> || yes || World X coordinate in metres.
|-
| <code>y</code> || <code>number</code> || yes || World Y coordinate in metres.
|-
| <code>z</code> || <code>number</code> || yes || World Z coordinate in metres.
|-
| <code>looped</code> || <code>bool</code> || no || Whether playback should loop; defaults to false.
|-
| <code>volume</code> || <code>number</code> || no || Initial linear volume from 0 to 1; defaults to 1.
|-
| <code>minDistance</code> || <code>number</code> || no || Distance in metres at or below which the sound retains full volume; defaults to 1.
|-
| <code>maxDistance</code> || <code>number</code> || no || Distance in metres at or beyond which the sound is silent; defaults to 50.
|}

== Returns ==
Returns a non-zero resource-owned sound handle, or <code>false</code> when validation, integrity verification, decoding, or playback setup fails.

== Examples ==
Play a looping forge sound in the world:
<syntaxhighlight lang="lua" line>
local forge = playSound3D(
"sounds/forge.ogg",
125.5, -48.0, 3.25,
true, 0.8, 2.0, 45.0
)
</syntaxhighlight>

== Notes ==
* Available only in client-side resource scripts.
* Coordinates and attenuation distances use metres. Coordinates must be finite and remain within +/-1,000,000 metres on every axis.
* The minimum distance must be at least 0.01 metres. The maximum must be greater than the minimum and no greater than 10,000 metres.
* Positional audio is downmixed to mono as a point source. It remains at full gain through <code>minDistance</code>, fades linearly, and is silent at and beyond <code>maxDistance</code>.
* Resource audio uses the normal Windows default playback endpoint. The communications-device selection is reserved for voice microphone capture and does not reroute 3D playback.
* The native player transform is sampled for the listener only while at least one spatial sound exists; this path does not use Angelscript and does not install a ProcessEvent hook.
* The same declaration, path, integrity, codec, ownership, and active-sound limits as <code>playSound</code> apply.
* Expanded limits apply from update 0.1.3 BUILD81. Client limits: 128 owned sounds per resource and 512 globally. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:Audio Functions]]

PlaySound

2026-09-12T11:51:49Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= playSound =
<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 function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Starts a non-spatial OGG Vorbis sound owned by the current client resource.

== Syntax ==
<syntaxhighlight lang="lua">
number|false playSound(string relativePath [, bool looped = false, number volume = 1])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>relativePath</code> || <code>string</code> || yes || The exact relative path of a same-resource <code><file download="join"></code> entry ending in <code>.ogg</code>.
|-
| <code>looped</code> || <code>bool</code> || no || Whether playback should loop; defaults to false.
|-
| <code>volume</code> || <code>number</code> || no || Initial linear volume from 0 to 1; defaults to 1.
|}

== Returns ==
Returns a non-zero resource-owned sound handle, or <code>false</code> when validation, integrity verification, decoding, or playback setup fails.

== Examples ==
Play a client UI notification:
<syntaxhighlight lang="lua" line>
local sound = playSound("sounds/notification.ogg", false, 0.65)
if not sound then
outputDebugString("Could not start notification audio", 2)
end
</syntaxhighlight>

== Notes ==
* Available only in client-side resource scripts.
* The first audio release supports Ogg Vorbis. An Ogg container using another codec, such as Opus, is not accepted.
* The file must be declared for join-time download by the current resource. URLs, absolute paths, traversal, reparse-point escapes, undeclared files, and files owned by another resource are rejected.
* The runtime revalidates the file size and SHA-256 from the signed resource catalog before decoding it.
* Resource audio uses the normal Windows default playback endpoint. The communications-device selection is reserved for voice microphone capture and does not reroute 2D or 3D playback.
* 2D playback preserves the source channel layout. When source and output sample rates differ, the runtime converts once with the bundled libsamplerate 0.2.2 sinc converter using <code>SRC_SINC_MEDIUM_QUALITY</code> and bypasses miniaudio's pitch-oriented linear converter.
* Each resource may own at most 128 active sounds; the client runtime may own at most 512 in total.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:Audio Functions]]

BindKey

2026-09-12T11:51:47Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= bindKey =
Binds a keyboard or mouse key to a client-side Lua callback and consumes the corresponding game input while the binding is active.

== Syntax ==
<syntaxhighlight lang="lua">
bool bindKey(string keyName, string keyState, function handler [, mixed arguments...])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>keyName</code> || <code>string</code> || yes || The case-insensitive key name, for example <code>tab</code>, <code>f5</code>, <code>mouse1</code> or <code>a</code>.
|-
| <code>keyState</code> || <code>string</code> || yes || The transition to handle: <code>down</code>, <code>up</code> or <code>both</code>.
|-
| <code>handler</code> || <code>function</code> || yes || The callback invoked as <code>handler(keyName, keyState, ...)</code>.
|-
| <code>arguments...</code> || <code>mixed</code> || no || Optional nil, boolean, number or string values appended to every callback invocation.
|}

== Returns ==
Returns <code>true</code> when the binding is registered, or <code>false</code> for an invalid key, invalid state, duplicate binding or exhausted resource limit.

== Examples ==
Show a scoreboard while Tab is held:
<syntaxhighlight lang="lua" line>
local function handleScoreboard(keyName, keyState)
if keyState == "down" then
guiShow(scoreboard)
guiSetInputActive(scoreboard, true)
else
guiSetInputActive(scoreboard, false)
guiHide(scoreboard)
end
end

bindKey("tab", "both", handleScoreboard)
</syntaxhighlight>

== Notes ==
* Available only in client-side resource scripts.
* Bindings are owned by the creating resource and are removed automatically when that resource stops.
* A new binding does not begin while another RmlUi document owns text or pointer input. A key-up transition belonging to an active binding is still delivered so the UI can close safely.
* The client runtime polls keys only while the G1R window is focused. It does not install a global keyboard hook and does not use Unreal ProcessEvent.
* Each resource may register at most 1024 bindings.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:Input Functions]]

SetNpcRoute

2026-09-12T11:51:46Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

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

Assigns an ordered, optionally looping movement route to a resource-owned NPC.

== Syntax ==
<syntaxhighlight lang="lua">
bool setNpcRoute(int npcId, table points [, table options])
</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>points</code> || <code>table</code> || yes || A one-based array of 1-1024 points. Every point has x, y and z in metres and may have yaw in degrees and waitMs from 0 to 3600000.
|-
| <code>options</code> || <code>table</code> || no || Optional <code>{ loop = bool, speed = number, obstacleBehavior = string }</code>; speed is 0.1-12 metres per second and defaults to 1. Available since update 0.1.2, <code>obstacleBehavior</code> accepts <code>"wait"</code> or <code>"avoid"</code>. When omitted, the NPC keeps its current mode; a newly spawned NPC starts in <code>"wait"</code> mode.
|}

== Returns ==
Returns <code>true</code> when the complete route is validated and started; otherwise returns <code>false</code>.

== Examples ==
Patrol between two guard posts:
<syntaxhighlight lang="lua" line>
setNpcRoute(npcId, {
{ x = 10, y = 5, z = 2, yaw = 90, waitMs = 1500 },
{ x = 18, y = 5, z = 2, yaw = 270, waitMs = 1500 },
}, { loop = true, speed = 1.8, obstacleBehavior = "avoid" })
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Movement is simulated by the server and replicated as normal smoothed remote snapshots.
* Every ground route leg is resolved through the conservative server navigation-blocker layer. An unreachable route is rejected; movement never falls back to the authored straight line through a blocker.
* Dynamic capsule spacing keeps NPCs separate from players, monsters and other NPCs. It never permits an NPC to pass through another character.
* The <code>obstacleBehavior</code> option is available since update 0.1.2. Its default <code>"wait"</code> mode stops the NPC until a blocking dynamic capsule clears. <code>"avoid"</code> attempts a safe detour and continues toward the waypoint, falling back to waiting when no valid detour exists.
* Route progress emits <code>onNpcRoutePoint</code> and non-looping completion emits <code>onNpcRouteComplete</code>.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

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

CreateAiNavigationBlocker

2026-09-12T11:51:45Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= createAiNavigationBlocker =
<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 function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Creates a resource-owned static navigation blocker used by server-simulated NPCs and monsters.

== Syntax ==
<syntaxhighlight lang="lua">
string|false createAiNavigationBlocker(table definition)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>definition</code> || <code>table</code> || yes || A validated <code>box</code>, <code>cylinder</code>, or convex <code>polygon</code> definition in metres.
|}

== Returns ==
Returns a new opaque decimal blocker ID string, or <code>false</code> when the definition is invalid or a bounded resource/server limit is reached.

== Examples ==
Block a rotated doorway volume:
<syntaxhighlight lang="lua" line>
local blockerId = createAiNavigationBlocker({
shape = "box",
x = 125.0, y = -48.0, z = 2.0,
width = 2.5, depth = 0.8, height = 4.0,
yaw = 30,
})
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* All coordinates and dimensions use metres. A box uses centre <code>x/y/z</code>, <code>width</code>, <code>depth</code>, <code>height</code>, and optional yaw in degrees. A cylinder uses centre <code>x/y/z</code>, <code>radius</code>, and <code>height</code>. Each dimension must be 0.01-10000 metres.
* A polygon uses <code>points = {{x=...,y=...}, ...}</code> with 3-16 vertices plus <code>minZ</code> and <code>maxZ</code>. It must be finite, simple and convex; clockwise input is normalized. Coordinates are limited to +/-100000 metres.
* Optional <code>enabled</code> defaults to true. The server permits at most 4096 blockers per resource and 16384 total, and also bounds spatial-index growth.
* The blocker is visible to every AI entity whose collision mode includes the custom layer, not only entities owned by the creating resource. Only the creating resource may inspect, update, enable, disable or destroy it.
* Stopping or restarting the owning resource removes all of its blockers automatically. Dynamic player, NPC and monster capsule collision is separate and always remains active.
* Use custom blockers for static geometry and occasional changes such as opening or closing a gate. Moving or toggling blockers every server tick is unsupported; moving characters already use the mandatory dynamic capsule layer.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

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

Create3DText

2026-09-12T11:51:44Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= create3DText =
Creates a server-authoritative world-space text label and replicates it to connected players.

== Syntax ==
<syntaxhighlight lang="lua">
string|false create3DText(string text, number x, number y, number z [, table options])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>text</code> || <code>string</code> || yes || Valid UTF-8 text containing 1-128 characters and at most 256 bytes.
|-
| <code>x</code> || <code>number</code> || yes || World X coordinate in metres.
|-
| <code>y</code> || <code>number</code> || yes || World Y coordinate in metres.
|-
| <code>z</code> || <code>number</code> || yes || World Z coordinate in metres.
|-
| <code>options</code> || <code>table</code> || no || Optional fields: drawDistance (1-1000 metres), scale (0.25-5.0), and integer r, g, b, a color channels (0-255).
|}

== Returns ==
Returns an opaque text identifier string on success, or <code>false</code> when validation or capacity limits reject the request.

== Examples ==
Create a gold world label above an RP meeting point:
<syntaxhighlight lang="lua" line>
local meetingLabel = create3DText(
"Old Camp meeting point",
125.0, -48.5, 3.2,
{
drawDistance = 40.0,
scale = 0.85,
r = 225, g = 185, b = 91, a = 255
}
)

if not meetingLabel then
outputDebugString("Could not create the meeting label", 1)
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The server replicates creation and updates reliably, including the current state for late-joining players.
* The creating resource owns the label. Other resources cannot change or destroy it, and it is removed automatically when its owner stops.
* A resource may own up to 1024 labels, with a server-wide maximum of 8192 labels.
* Store the returned identifier as a string. Do not convert it to a Lua number.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

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

RequestRemote

2026-09-12T11:51:42Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

= requestRemote =
Queues a bounded asynchronous HTTP or HTTPS request from a server-side resource.

== Syntax ==
<syntaxhighlight lang="lua">
number|false requestRemote(string url [, table options], function callback [, table callbackArguments])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>url</code> || <code>string</code> || yes || The absolute public <code>http://</code> or <code>https://</code> URL to request, up to 2048 bytes.
|-
| <code>options</code> || <code>table</code> || no || Optional request settings: <code>method</code>, <code>postData</code> or <code>body</code>, <code>headers</code>, <code>username</code>, <code>password</code>, <code>connectionAttempts</code>, <code>connectTimeout</code>, <code>timeout</code>, and <code>maxRedirects</code>.
|-
| <code>callback</code> || <code>function</code> || yes || Called as <code>callback(responseBody, responseInfo, ...callbackArguments)</code> on the resource's server tick.
|-
| <code>callbackArguments</code> || <code>table</code> || no || Optional one-based array whose values are appended to the callback arguments.
|}

== Returns ==
Returns a numeric request identifier when queued, or <code>false</code> when validation, service availability, or resource limits reject the request.

== Examples ==
=== Example 1 ===
Read and decode a JSON response:
<syntaxhighlight lang="lua" line>
local requestId = requestRemote("https://api.example.com/status", {
headers = { Accept = "application/json" },
connectTimeout = 3000,
timeout = 10000
}, function(body, info, label)
if not info.success then
outputDebugString(label .. " failed: " .. (info.error or "unknown error"))
return
end

local data, errorMessage = fromJSON(body)
if data == false then
outputDebugString(errorMessage)
return
end
outputDebugString(label .. " returned HTTP " .. info.statusCode)
end, {"status service"})
</syntaxhighlight>
=== Example 2 ===
Send a JSON POST request:
<syntaxhighlight lang="lua" line>
local payload = assert(toJSON({ event = "player_join", playerId = playerId }))

requestRemote("https://api.example.com/events", {
method = "POST",
body = payload,
headers = { ["Content-Type"] = "application/json" }
}, function(body, info)
if not info.success then
outputDebugString(info.error or "Remote request failed")
end
end)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The callback information table contains <code>requestId</code>, <code>success</code>, <code>statusCode</code>, <code>headers</code>, <code>effectiveUrl</code>, <code>bytesReceived</code>, <code>durationMs</code>, <code>attempts</code>, <code>aborted</code>, and <code>error</code>.
* Only HTTP and HTTPS are accepted. Loopback, private, link-local, reserved, documentation, and mixed public/private DNS results are rejected. Every redirect target is resolved and validated again.
* DNS answers are pinned for each transfer to prevent rebinding between validation and connection. TLS certificate and hostname verification remain enabled.
* Hard limits are 4 MiB request bodies, 8 MiB response bodies, 128 request headers, 256 response headers, 64 KiB aggregate header bytes, 3 attempts, 10 seconds to connect, 30 seconds total and 3 redirects. Compiled service defaults: 8 workers, 256 queued work items and 32 pending requests per resource.
* If a body is supplied without an explicit method, the method defaults to <code>POST</code>.
* Credentials remain server-side, but resources should still avoid placing secrets in URLs or logs.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Utility Functions]]
[[Category:HTTP Functions]]

FromJSON

2026-09-12T11:51:41Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

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

Parses bounded JSON into Lua values.

== Syntax ==
<syntaxhighlight lang="lua">
mixed|false value, string|nil error = fromJSON(string json)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>json</code> || <code>string</code> || yes || A UTF-8 JSON document up to 1 MiB.
|}

== Returns ==
Returns the decoded value and <code>nil</code> on success. On failure it returns <code>false</code> and an error string.

== Examples ==
Decode a JSON payload safely:
<syntaxhighlight lang="lua" line>
local value, errorMessage = fromJSON(payload)
if value == false then
outputDebugString(errorMessage)
else
outputDebugString(tostring(value.ready))
end
</syntaxhighlight>

== Notes ==
* Available in both server-side and client-side resource scripts.
* JSON is limited to 1 MiB, 64 nested levels, and 65536 cumulative entries.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Shared Functions]]
[[Category:Utility Functions]]

ToJSON

2026-09-12T11:51:40Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

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

Serializes a supported Lua value to bounded JSON.

== Syntax ==
<syntaxhighlight lang="lua">
string|false json, string|nil error = toJSON(mixed value)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>value</code> || <code>mixed</code> || yes || A nil, boolean, finite number, string, or acyclic table containing supported values.
|}

== Returns ==
Returns the JSON string and <code>nil</code> on success. On failure it returns <code>false</code> and an error string.

== Examples ==
Encode a compact payload:
<syntaxhighlight lang="lua" line>
local json, errorMessage = toJSON({ playerId = playerId, ready = true })
if not json then
outputDebugString(errorMessage)
end
</syntaxhighlight>

== Notes ==
* Available in both server-side and client-side resource scripts.
* JSON is limited to 1 MiB, 64 nested levels, and 65536 cumulative entries.
* Expanded limits apply from update 0.1.3 BUILD81. See [[Scripting limits]]; earlier 0.1.3 binaries retain their old limits.

[[Category:Lua Functions]]
[[Category:Shared Functions]]
[[Category:Utility Functions]]

Client audio

2026-09-12T11:51:38Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

{{DISPLAYTITLE:Client audio}}

<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;">Resource-owned OGG Vorbis playback, including positional 3D sound, is available in G1R:MP 0.1.2 and later.</div>
</div>

'''Client audio''' lets a client-side Lua resource play non-spatial interface sounds and positional world sounds. Audio handles belong to the resource that created them and cannot be controlled by another resource.

== Supported files ==

The first release accepts Ogg containers containing '''Vorbis''' audio. Ogg Opus and other codecs are not accepted. Every sound must be declared as a join-time file in the same resource:

<syntaxhighlight lang="xml" line>
<?xml version="1.0" encoding="utf-8"?>
<scripts>
<script src="client.lua" type="client" cache="true" />
<file src="sounds/notification.ogg" download="join" />
<file src="sounds/forge.ogg" download="join" />
</scripts>
</syntaxhighlight>

The runtime accepts only the exact relative path declared by the current resource. URLs, absolute paths, traversal with <code>..</code>, reparse-point escapes, undeclared files, and files owned by another resource are rejected. File size and SHA-256 are checked again against the signed resource catalog before decoding.

== Audio functions ==

* [[playSound]] creates a non-spatial 2D sound.
* [[playSound3D]] creates a positional sound at world coordinates.
* [[stopSound]] stops a sound and invalidates its handle.
* [[setSoundVolume]] and [[getSoundVolume]] control linear volume.
* [[setSoundPaused]] and [[isSoundPaused]] control and inspect pause state.
* [[isSoundPlaying]] checks active playback.
* [[setSoundLooped]] changes looping.
* [[setSound3DPosition]] moves a positional source.
* [[setSound3DMinMaxDistance]] changes its attenuation range.

== Playback quality and output device ==

2D playback preserves the source channel layout, so stereo material remains stereo. A positional source is downmixed to mono because it represents one point in the world. When source and output sample rates differ, the runtime converts once with the bundled libsamplerate 0.2.2 sinc converter using <code>SRC_SINC_MEDIUM_QUALITY</code> and bypasses miniaudio's pitch-oriented linear converter. Matching sample rates are not resampled.

Resource audio and voice playback use the normal Windows default playback device. The Windows communications-device selection is used only for voice microphone capture; it does not redirect or reduce the quality of 2D or 3D playback.

For 3D sound, volume remains full through <code>minDistance</code>, then fades linearly and is silent at and beyond <code>maxDistance</code>. Coordinates and distances use metres. The listener follows the local native player while at least one positional sound exists.

== Local playback ==

<syntaxhighlight lang="lua" line>
local notification = playSound("sounds/notification.ogg", false, 0.65)

local forge = playSound3D(
"sounds/forge.ogg",
125.5, -48.0, 3.25,
true, 0.8,
2.0, 45.0
)

if forge then
setSound3DPosition(forge, 126.0, -48.0, 3.25)
setSound3DMinMaxDistance(forge, 2.0, 60.0)
end
</syntaxhighlight>

== Playing the same 3D sound for every player ==

Audio functions are client-side. To initiate a world sound authoritatively, the server sends a validated event to the client scripts. Using <code>root</code> as the target broadcasts the same reliable ordered event to every connected player.

Calculate the source position once on the server and send identical world coordinates to all clients. Do not recalculate the source from each receiving player's position.

'''server.lua'''

<syntaxhighlight lang="lua" line>
addCommandHandler("forgeaudio", function(playerId)
local position = getPlayerPosition(playerId)
if not position then
return
end

triggerClientEvent(
root,
"forgeAudio:play",
resourceRoot,
position.x + 4.0,
position.y,
position.z
)
end)
</syntaxhighlight>

'''client.lua'''

<syntaxhighlight lang="lua" line>
local forgeSound = false

addEvent("forgeAudio:play", true)
addEventHandler("forgeAudio:play", resourceRoot, function(x, y, z)
if forgeSound then
stopSound(forgeSound)
end

forgeSound = playSound3D(
"sounds/forge.ogg",
x, y, z,
true, 0.8,
1.0, 30.0
)
end)
</syntaxhighlight>

Each client creates its own local handle. Stopping, moving, pausing, or changing a shared sound therefore requires another server event broadcast to the same clients. Delivery is reliable and ordered, but playback start is not sample-accurate and can differ slightly due to network jitter.

== Ownership and limits ==

* From update 0.1.3 BUILD81, a resource can own at most 128 active sounds; the client runtime can own at most 512 in total (previously 32/128). See [[Scripting limits]].
* A handle can be controlled only by the resource that created it.
* Stopping a resource releases all sounds that it still owns.
* A stopped or finished handle must not be reused.
* Validation and playback failures are recorded in the client runtime log.

[[Category:Lua API]]
[[Category:Lua Tutorials]]
[[Category:Audio Functions]]

Hosting a G1R:MP dedicated server

2026-09-12T11:51:35Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

{{DISPLAYTITLE:Hosting a G1R:MP dedicated server}}
__NOTOC__

= Hosting a G1R:MP dedicated server =

<div style="border:1px solid #b28a3d; border-left:4px solid #b28a3d; background:#faf9f5; padding:0.9rem 1rem; margin:0.8rem 0 1.2rem;">
'''Public network access is required.''' A server hosted on your own computer still needs a publicly reachable address and the required ports opened or forwarded.
</div>

This requirement also applies when the dedicated server, launcher, and game are running on the same computer. Protocol 26 uses the official G1R:MP service for server discovery and connection authorization, including direct-connect attempts. Private-only server addresses are not accepted for public registration.

The official service does not relay gameplay. After authorization, gameplay, voice, and resource traffic connects directly to the public endpoint advertised by the dedicated server. This architecture requires that endpoint to be reachable from the Internet.

== Public address requirement ==

The host must have either:

* a public, externally reachable IP address; or
* a DNS name that resolves to that public address.

Addresses such as <code>127.0.0.1</code>, <code>localhost</code>, <code>192.168.x.x</code>, and <code>10.x.x.x</code> are not reachable from the Internet.

If the server is behind a home router, configure port forwarding from the router's public address to the computer's fixed LAN address. If the ISP uses carrier-grade NAT (CGNAT), ordinary router port forwarding is not sufficient; request a public IP address from the ISP or host the server on a publicly reachable VPS.

For the standard automatic listing configuration, leave <code>listing.publicHost</code> empty. The official service can use the source address of the server heartbeat. Set it only when advertising a public DNS name that resolves to the same server.

<syntaxhighlight lang="ini">
[listing]
publicHost=
</syntaxhighlight>

== Default ports ==

The current default configuration uses the following ports:

{| class="wikitable" style="width:100%;"
! Purpose !! Default port !! Protocol !! Public access
|-
| Gameplay transport || <code>7777</code> || UDP || Required
|-
| Voice relay || <code>7778</code> || UDP || Required when voice chat is enabled
|-
| Resource download service || <code>7780</code> || TCP || Required when <code>http.mode=auto</code> or the built-in HTTP service is used
|-
| RCON administration || <code>7781</code> || TCP || '''Do not expose'''; loopback-only by default
|-
| MariaDB/MySQL || <code>3307</code> in the shipped Gothic RP configuration, or the locally configured database port (commonly <code>3306</code>) || TCP || '''Do not expose''' when the database is on the same host
|}

The server also requires outbound HTTPS access, normally TCP port <code>443</code>, to synchronize with the official G1R:MP service. This is an outbound connection and does not require router port forwarding.

If any ports are changed in <code>serverconf.cfg</code>, update the firewall and router rules to match the configured values.

== Recommended bind configuration ==

The public services should normally listen on all local interfaces:

<syntaxhighlight lang="ini">
[server]
bind=0.0.0.0
port=7777

[voice]
enabled=true
bind=0.0.0.0
port=7778

[http]
mode=auto
bind=0.0.0.0
port=7780
</syntaxhighlight>

Keep RCON restricted to the local machine:

<syntaxhighlight lang="ini">
[rcon]
enabled=true
allowRemote=false
bind=127.0.0.1
port=7781
</syntaxhighlight>

== Player capacity and server password ==

Set the player limit and optional join password in the <code>[server]</code> section. <code>maxPlayers</code> accepts any integer from <code>1</code> through <code>5000</code>, inclusive. The server refuses to start when the value is outside that range.

<syntaxhighlight lang="ini">
[server]
maxPlayers=500
password=
</syntaxhighlight>

The <code>password</code> setting supports three forms:

{| class="wikitable" style="width:100%;"
! Configuration !! Result
|-
| <code>password=</code> || No join password. The server is advertised as public.
|-
| <code>password=a-literal-secret</code> || Uses the literal value from <code>serverconf.cfg</code>. A non-empty password must contain from <code>1</code> through <code>128</code> bytes.
|-
| <code>password=env:VARIABLE</code> || Reads the password from the named environment variable when the server starts. The resolved value must contain from <code>1</code> through <code>128</code> bytes.
|}

The environment-variable form keeps the credential out of <code>serverconf.cfg</code> and is recommended for hosted servers. The variable name must be a valid environment-variable identifier, and the server stops during configuration loading if the variable is missing, empty, longer than 128 bytes, or contains a forbidden control character.

Do not set <code>listing.passworded</code> manually. The advertised <code>passworded</code> value is derived automatically from the resolved <code>[server] password</code>, so the server list and health response cannot claim a password policy different from the one enforced by the server.

Before downloading resources, the launcher checks the server health response. It stops early when <code>players</code> has reached <code>maxPlayers</code>, and it requests a password when <code>passworded</code> is true. These checks provide immediate feedback only: the dedicated server independently enforces the slot limit and validates the password during admission. A stale server-list entry or modified client cannot bypass either rule.

== Resource package limits ==

These expanded values apply from '''update 0.1.3 BUILD81'''. Older 0.1.3 clients must be updated. See [[Scripting limits]] and [[Server configuration limits]] for all other budgets and exact units.

The dedicated server and client enforce matching compatibility limits for Lua scripts and downloadable resources. Values at a stated hard boundary are accepted; a resource that exceeds that boundary is rejected before it can run.

{| class="wikitable" style="width:100%;"
! Limit !! Value !! Scope
|-
| Lua script size || <code>128 MiB</code> || Each individual <code>.lua</code> script.
|-
| Resource file size || <code>256 MiB</code> || Each individual file included in the client resource catalog.
|-
| Catalog file count || <code>262,144</code> files || All client scripts and downloadable files across the complete catalog.
|-
| Catalog payload || <code>32 GiB</code> || Sum of the file sizes declared by the complete client resource catalog.
|-
| Catalog JSON document || <code>128 MiB</code> || Serialized <code>catalog.json</code> metadata returned by the resource service.
|-
| Lua VM memory || <code>1024 MiB</code> by default || Each client-side resource Lua VM uses the 1024 MiB default. For each server-side resource Lua VM, <code>[lua] memoryLimitMB</code> is configurable from <code>4</code> through <code>4096</code> MiB; the shipped default is <code>1024</code> MiB.
|}

The dedicated server validates manifests, script sizes, file counts, payload totals, and catalog JSON size while building the catalog. The client validates the catalog and every downloaded file again before caching or executing it. When <code>http.mode=external</code> is used, a CDN or reverse proxy may impose stricter transfer limits, but it cannot raise the limits enforced by the client.

== Firewall examples ==

=== Windows ===

Run PowerShell as Administrator:

<syntaxhighlight lang="powershell">
New-NetFirewallRule -DisplayName "G1R:MP Gameplay" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 7777
New-NetFirewallRule -DisplayName "G1R:MP Voice" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 7778
New-NetFirewallRule -DisplayName "G1R:MP Resources" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 7780
</syntaxhighlight>

=== Linux with UFW ===

<syntaxhighlight lang="bash">
sudo ufw allow 7777/udp
sudo ufw allow 7778/udp
sudo ufw allow 7780/tcp
</syntaxhighlight>

On a VPS or cloud host, add equivalent inbound rules to the provider firewall or security group as well as the operating-system firewall.

== Testing reachability ==

Test the server from a different Internet connection, such as another household or a mobile hotspot. Testing only from the same LAN can give misleading results because routers handle NAT loopback differently.

A server appearing in the master list confirms that its outbound heartbeat reached the official service. It does not by itself prove that UDP <code>7777</code>, UDP <code>7778</code>, and TCP <code>7780</code> are reachable from the Internet.

Do not solve a connection problem by opening RCON or MariaDB publicly. Those services should remain private.

[[Category:Server administration]]
[[Category:Networking]]

Lua API catalogs

2026-09-12T11:51:34Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

{{DISPLAYTITLE:Lua API catalogs}}

See [[Scripting limits|current Lua, resource and API limits for 0.1.3 BUILD81]], [[Server configuration limits|all numeric server configuration bounds]] and [[Player statistic limits|all 59 statistic ranges]].
'''Lua API catalogs''' collect stable, server-validated keys used by G1R:MP resources. Prefer catalog keys and enumeration functions over hard-coded Unreal paths.

== Static catalogs ==
{| class="wikitable"
! Catalog !! Used by
|-
| [[Player skin catalog]] || [[setPlayerSkin]], [[setNpcSkin]]
|-
| [[Player body catalog]] || deprecated compatibility reference for [[setPlayerBody]]
|-
| [[Player face catalog]] || deprecated compatibility reference for [[setPlayerFace]]
|-
| [[Player head catalog]] || deprecated compatibility reference for [[setPlayerHead]]
|-
| [[Player identity catalog]] || supported complete identity setter [[setPlayerIdentity]]
|-
| [[Player tattoo catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.3)</span> || [[setPlayerTattoo]], [[getPlayerTattooNames]]
|-
| [[Synchronized spell catalog]] || basic synchronized spell set for G1R:MP 0.1a
|-
| [[Monster type catalog]] || [[spawnMonster]]
|-
| [[World item catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || [[spawnItem]] and [[spawnTestItem]]
|-
| [[NPC and monster navigation collision]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || NPC and monster collision-source modes and resource-owned AI navigation blockers
|-
| [[Player animation catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || [[startAnim]] and [[stopAnim]]
|}

== Camera scripting ==
[[Scripted camera]] and [[:Category:Camera Functions|Camera Functions]] document camera poses, units, state fields, movement, paths, orbits and client/server ownership. These new functions and their client events are '''available from update 0.1.3'''.

== Player customization ==
[[Player customization]] documents the '''seven skin-color and tattoo functions available from update 0.1.3''', including RGB ranges, independent resets, tattoo removal and persistence. Existing [[setPlayerIdentity]] head/armor handling is '''improved from update 0.1.3'''; it is not a newly introduced identity API or a full NPC body replacement.

== Observer-specific nameplates ==
[[Observer nameplates]] documents the '''12 observer/nameplate-ID functions available from update 0.1.3'''. Text, whole-label visibility and numeric-ID policy resolve independently for each observer/target pair. The guide covers explicit versus effective getters, exclusive per-field resource ownership, lifecycle, configurable limits, developer-owned acquaintance persistence, and the optional <code>/nametest</code> resource. This is overhead presentation, not network anonymity.

== Runtime catalogs ==
These functions return the authoritative keys supported by the running server build:

{| class="wikitable"
! Function !! Values
|-
| [[getPlayerArmorNames]] || Armor keys
|-
| [[getPlayerTattooNames]] || Tattoo preset keys (available from update 0.1.3)
|-
| [[getPlayerWeaponNames]] || Melee weapon keys
|-
| [[getPlayerRangedWeaponNames]] || Bow and crossbow keys
|-
| [[getPlayerAmmunitionNames]] || Ammunition keys
|-
| [[getPlayerRuneNames]] || All rune/spell-item keys; not a synchronization-support list
|-
| [[getSpellCatalog]] || All spell definitions and their <code>implemented</code> status; see [[Synchronized spell catalog]]
|-
| [[getPlayerStatNames]] || Progression statistic keys
|-
| [[getPlayerSkillNames]] || Skill keys
|-
| [[getPlayerGuildNames]] || Guild keys
|}

== Example ==
<syntaxhighlight lang="lua">
local function contains(values, wanted)
for _, value in ipairs(values) do
if value == wanted then
return true
end
end
return false
end

if contains(getPlayerArmorNames(), "none") then
setPlayerArmor(playerId, "none")
end
</syntaxhighlight>

[[Category:Lua API]]
[[Category:Lua Catalogs]]

Main Page

2026-09-12T11:51:33Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

__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="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">OBSERVER NAMEPLATES — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''12 new server-side functions''' add per-observer text, whole-label visibility and numeric-ID policy. Build directional acquaintance presentation with exclusive resource-owned fields and reliable relevance replay. See [[Observer nameplates]] for APIs, lifecycle, database integration and the optional three-client <code>/nametest</code> sequence. Overhead customization does not anonymize other packets, chat or player lists.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">PLAYER CUSTOMIZATION — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''7 new server-side functions''' provide independent skin-color and tattoo overrides. Existing identity selection has improved head and armor compatibility from update 0.1.3. See [[Player customization]] for examples and reset behavior, and [[Player tattoo catalog]] for all 12 keys.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Skin color:</strong> [[setPlayerSkinColor]] • [[getPlayerSkinColor]] • [[resetPlayerSkinColor]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Tattoos:</strong> [[setPlayerTattoo]] • [[getPlayerTattoo]] • [[resetPlayerTattoo]] • [[getPlayerTattooNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Improved existing API:</strong> [[setPlayerIdentity]] keeps the game-owned body and equipped armor. These are cosmetic controls, not a full NPC body/outfit replacement.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">SCRIPTED CAMERA — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''15 camera functions''' and '''2 client camera events''' are available from G1R:MP 0.1.3. Build login backgrounds, fixed shots, smooth transitions, paths and orbits. See [[Scripted camera]] for examples, limits and client/server differences.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Client and server (10):</strong> [[setCameraPos]] • [[setCameraRot]] • [[setCameraLookAt]] • [[setCameraFOV]] • [[setCameraPose]] • [[moveCameraTo]] • [[playCameraPath]] • [[orbitCamera]] • [[stopCameraMovement]] • [[resetCameraPos]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client read-back (5):</strong> [[getCameraPos]] • [[getCameraRot]] • [[getCameraFOV]] • [[getCameraState]] • [[requestCameraState]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client events (2):</strong> [[onClientCameraCommandResult]] • [[onClientCameraReset]]. Client commands use asynchronous acknowledgements; server calls return only a queued boolean.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">AVAILABLE AND IMPROVED FROM UPDATE 0.1.2</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">The following '''40 Lua functions''' — 29 server-side and 11 client-side — are available from G1R:MP 0.1.2. Existing lifecycle, inventory, JSON, NPC, monster, and world-item APIs also include corrected or expanded behavior from this update.</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Accounts and consumables (4):</strong> [[completePlayerConsumableFinalize]] • [[completePlayerConsumableUse]] • [[getPlayerAccountBindingSerial]] • [[getPlayerConsumableNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>World items (1):</strong> [[spawnItem]] — see also the [[World item catalog]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster identity, health, and combat (5):</strong> [[setMonsterName]] • [[setMonsterIdVisible]] • [[setMonsterMaxHealth]] • [[getMonsterAttackDamage]] • [[setMonsterAttackDamage]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster navigation (6):</strong> [[setMonsterNavigationMode]] • [[setMonsterNavigationCollisionMode]] • [[setMonsterMoveGoal]] • [[stopMonsterMovement]] • [[testMonsterMove]] • [[walkMonsterTo]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>NPC identity and navigation (7):</strong> [[setNpcIdVisible]] • [[setNpcObstacleBehavior]] • [[setNpcNavigationMode]] • [[setNpcNavigationCollisionMode]] • [[setNpcMoveGoal]] • [[stopNpcMovement]] • [[testNpcMove]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Custom navigation blockers (6):</strong> [[createAiNavigationBlocker]] • [[updateAiNavigationBlocker]] • [[setAiNavigationBlockerEnabled]] • [[destroyAiNavigationBlocker]] • [[getAiNavigationBlockerData]] • [[getAiNavigationBlockers]] — see [[NPC and monster navigation collision]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client audio (11):</strong> [[playSound]] • [[playSound3D]] • [[stopSound]] • [[setSoundVolume]] • [[getSoundVolume]] • [[setSoundPaused]] • [[isSoundPaused]] • [[isSoundPlaying]] • [[setSoundLooped]] • [[setSound3DPosition]] • [[setSound3DMinMaxDistance]] — see [[Client audio]].</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Events available from 0.1.2 (8):</strong> [[onNpcIdVisibilityChange]] • [[onMonsterNameChange]] • [[onMonsterIdVisibilityChange]] • [[onMonsterMoveBlocked]] • [[onMonsterMoveComplete]] • [[onNpcMoveBlocked]] • [[onNpcMoveComplete]] • [[onWorldItemDrop]]. Existing [[onPlayerJoin]], [[onPlayerQuit]], [[onWorldItemPickup]], and [[onWorldItemSpawn]] contracts are also improved from 0.1.2.</div>
</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 — 0.1.3 BUILD81]]</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>[[Scripted camera|Scripted camera and moving login backgrounds (0.1.3)]]</li>
<li>[[Observer nameplates|Observer-specific labels and acquaintance presentation (0.1.3)]]</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>[[: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|Client audio functions]]</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>[[Known issue: MySQL error 2006 (Server has gone away)|Known MySQL/MariaDB issue]]</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;">The reference contains '''310 Lua functions''' and '''94 events''', including '''12 observer/nameplate-ID functions, 7 skin-color/tattoo functions, 15 camera functions and 2 camera events available from update 0.1.3'''. Version notices distinguish newly available APIs from improved contracts in earlier APIs. See [[Observer nameplates]] for directional labels, [[Player customization]] for identity, color and tattoos, [[Lua API catalogs]] for validated gameplay keys, and [[Scripted camera]] for camera state and lifecycle rules. APIs marked [[:Category:Experimental Lua API|experimental]] may still change while the multiplayer runtime is under active development.</div>
</div>
</div>

[[Category:Lua API]]

Player statistic limits

2026-09-12T11:51:32Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

{{DISPLAYTITLE:Player statistic limits}}
'''Current in update 0.1.3, expanded-budget BUILD81; audited 2026-09-12.''' These statistic ranges were '''not raised''' by the scripting-capacity update: gameplay values are separate from Lua VM storage.

<code>setPlayerStat</code> and its named stat setters reject unknown keys/non-finite values and clamp finite numeric values to the catalog range below. Further authoritative rules still apply (for example current health versus max health, life state and equipment). This table is not a promise that every underlying single-player attribute has independent gameplay support. Query [[getPlayerStatLimits]] and [[getPlayerStatNames]] rather than copying assumptions into a gamemode. See [[Scripting limits]].

== All 59 catalog ranges ==
{| class="wikitable sortable"
! Stat key !! Minimum !! Maximum
|-
| <code>alcohol</code> || 0 || 100000
|-
| <code>max_alcohol</code> || 0 || 100000
|-
| <code>alcohol_depletion_rate</code> || 0 || 100000
|-
| <code>super_armor</code> || 0 || 100000
|-
| <code>max_super_armor</code> || 0 || 100000
|-
| <code>resistance_blunt</code> || 0 || 100000
|-
| <code>resistance_edge</code> || 0 || 100000
|-
| <code>resistance_point</code> || 0 || 100000
|-
| <code>resistance_fire</code> || 0 || 100000
|-
| <code>resistance_energy</code> || 0 || 100000
|-
| <code>resistance_ice</code> || 0 || 100000
|-
| <code>resistance_wind</code> || 0 || 100000
|-
| <code>resistance_falling</code> || 0 || 100000
|-
| <code>dexterity</code> || 0 || 100000
|-
| <code>fatigue</code> || 0 || 100000
|-
| <code>max_fatigue</code> || 0 || 100000
|-
| <code>fatigue_fill_ratio</code> || 0 || 100000
|-
| <code>fatigue_fill_ratio_period</code> || 0 || 100000
|-
| <code>fatigue_max_threshold_index</code> || 0 || 100000
|-
| <code>fatigue_recovery_per_sleep_hour</code> || 0 || 100000
|-
| <code>health</code> || 0 || 100000
|-
| <code>max_health</code> || 1 || 100000
|-
| <code>damage_multiplier</code> || 0 || 100
|-
| <code>health_recovery_per_sleep_hour</code> || 0 || 100000
|-
| <code>level</code> || 0 || 1000
|-
| <code>experience</code> || 0 || 1000000000
|-
| <code>skill_points</code> || 0 || 1000000
|-
| <code>xp_executed_bounty</code> || 0 || 1000000000
|-
| <code>xp_kill_or_defeat_bounty</code> || 0 || 1000000000
|-
| <code>toughness</code> || 0 || 100000
|-
| <code>toughness_a</code> || 0 || 100000
|-
| <code>toughness_b</code> || 0 || 100000
|-
| <code>toughness_c</code> || 0 || 100000
|-
| <code>lockpick_durability</code> || 0 || 100000
|-
| <code>lockpick_precision</code> || 0 || 100000
|-
| <code>mana</code> || 0 || 100000
|-
| <code>max_mana</code> || 0 || 100000
|-
| <code>magician_level</code> || 0 || 6
|-
| <code>mana_recovery_per_sleep_hour</code> || 0 || 100000
|-
| <code>speed_modifier</code> || 0 || 100
|-
| <code>oxygen</code> || 0 || 100000
|-
| <code>max_oxygen</code> || 0 || 100000
|-
| <code>oxygen_depletion_rate</code> || 0 || 100000
|-
| <code>oxygen_recovery_rate</code> || 0 || 100000
|-
| <code>oxygen_critical_level_percent</code> || 0 || 100
|-
| <code>pickpocketing</code> || 0 || 100000
|-
| <code>sleep_time</code> || 0 || 100000
|-
| <code>max_sleep_time</code> || 0 || 100000
|-
| <code>sleep_recovery_amount</code> || 0 || 100000
|-
| <code>sleep_recovery_period</code> || 0 || 100000
|-
| <code>max_rest_time</code> || 0 || 100000
|-
| <code>strength</code> || 0 || 100000
|-
| <code>critical_fists</code> || 0 || 100
|-
| <code>critical_one_hand</code> || 0 || 100
|-
| <code>critical_two_hand</code> || 0 || 100
|-
| <code>critical_orc</code> || 0 || 100
|-
| <code>swampweed</code> || 0 || 100000
|-
| <code>max_swampweed</code> || 0 || 100000
|-
| <code>swampweed_depletion_rate</code> || 0 || 100000
|}

== Source audit ==
<code>shared/PlayerProgressionCatalog.hpp</code> (Stats, 59 entries); <code>server/src/scripting/ScriptRuntime.cpp</code> (set_player_stat_value).

[[Category:Lua API]]

Server configuration limits

2026-09-12T11:51:31Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

{{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 ==
<code>server/src/config/ServerConfig.cpp</code> (every numeric <code>parse_unsigned</code> setting), <code>ServerConfig.hpp</code>, <code>server/src/database/DatabaseTypes.hpp</code>, <code>shared/native_protocol.hpp</code>. Audit: 2026-09-12, protocol 34, expanded-budget 0.1.3 BUILD81.

[[Category:Lua API]]

Scripting limits

2026-09-12T11:51:30Z

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

{{DISPLAYTITLE:Scripting 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).''' Earlier 0.1.3 binaries have smaller capacities. Update the server and the complete client/launcher package before relying on the expanded limits.</div>

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>os</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.

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

== 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 this update.

== 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 uses the 27-key validated animation catalog. <code>startAnim</code> blend argument range is 0..2 seconds. Catalog keys are not raw montage paths.
* 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.
* 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.

== Source audit and practical use ==
Audit date: '''2026-09-12'''; expanded-budget '''0.1.3 BUILD81''', protocol '''34'''. Changes increase capacities, not packet layouts. Main sources:

* <code>shared/resource_limits.hpp</code>, <code>resource_event_protocol.hpp</code>, <code>client_ipc_protocol.hpp</code>, <code>scripting/LuaJson.hpp</code>/<code>.cpp</code>, <code>CameraProtocol.hpp</code>, <code>PlayerProgressionCatalog.hpp</code>, <code>PlayerAnimationCatalog.hpp</code>, <code>NameplateValidation.hpp</code>.
* <code>server/src/config/ServerConfig.cpp</code>/<code>.hpp</code>, <code>server/src/scripting/ScriptRuntime.cpp</code>, <code>server/src/resources/ResourceManager.cpp</code>, resource catalog/manifest, database, HTTP, voice and world implementations, <code>server/enet_server.cpp</code>.
* <code>client-runtime/src/scripting/ClientScriptRuntime.cpp</code>/<code>.hpp</code>, <code>app/ClientRuntimeMain.cpp</code>, catalog, audio and UI implementations.

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

Category:Nameplate Functions

2026-09-09T03:08:57Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

Server-side functions for reliable, validated overhead player labels. Twelve observer-specific and numeric-ID policy functions are available from update 0.1.3; see [[Observer nameplates]] for directional overrides, field ownership, resets, lifecycle and privacy boundaries.

[[Category:Player Functions]]

Lua API catalogs

2026-09-09T03:08:56Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

{{DISPLAYTITLE:Lua API catalogs}}
'''Lua API catalogs''' collect stable, server-validated keys used by G1R:MP resources. Prefer catalog keys and enumeration functions over hard-coded Unreal paths.

== Static catalogs ==
{| class="wikitable"
! Catalog !! Used by
|-
| [[Player skin catalog]] || [[setPlayerSkin]], [[setNpcSkin]]
|-
| [[Player body catalog]] || deprecated compatibility reference for [[setPlayerBody]]
|-
| [[Player face catalog]] || deprecated compatibility reference for [[setPlayerFace]]
|-
| [[Player head catalog]] || deprecated compatibility reference for [[setPlayerHead]]
|-
| [[Player identity catalog]] || supported complete identity setter [[setPlayerIdentity]]
|-
| [[Player tattoo catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.3)</span> || [[setPlayerTattoo]], [[getPlayerTattooNames]]
|-
| [[Synchronized spell catalog]] || basic synchronized spell set for G1R:MP 0.1a
|-
| [[Monster type catalog]] || [[spawnMonster]]
|-
| [[World item catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || [[spawnItem]] and [[spawnTestItem]]
|-
| [[NPC and monster navigation collision]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || NPC and monster collision-source modes and resource-owned AI navigation blockers
|-
| [[Player animation catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || [[startAnim]] and [[stopAnim]]
|}

== Camera scripting ==
[[Scripted camera]] and [[:Category:Camera Functions|Camera Functions]] document camera poses, units, state fields, movement, paths, orbits and client/server ownership. These new functions and their client events are '''available from update 0.1.3'''.

== Player customization ==
[[Player customization]] documents the '''seven skin-color and tattoo functions available from update 0.1.3''', including RGB ranges, independent resets, tattoo removal and persistence. Existing [[setPlayerIdentity]] head/armor handling is '''improved from update 0.1.3'''; it is not a newly introduced identity API or a full NPC body replacement.

== Observer-specific nameplates ==
[[Observer nameplates]] documents the '''12 observer/nameplate-ID functions available from update 0.1.3'''. Text, whole-label visibility and numeric-ID policy resolve independently for each observer/target pair. The guide covers explicit versus effective getters, exclusive per-field resource ownership, lifecycle, configurable limits, developer-owned acquaintance persistence, and the optional <code>/nametest</code> resource. This is overhead presentation, not network anonymity.

== Runtime catalogs ==
These functions return the authoritative keys supported by the running server build:

{| class="wikitable"
! Function !! Values
|-
| [[getPlayerArmorNames]] || Armor keys
|-
| [[getPlayerTattooNames]] || Tattoo preset keys (available from update 0.1.3)
|-
| [[getPlayerWeaponNames]] || Melee weapon keys
|-
| [[getPlayerRangedWeaponNames]] || Bow and crossbow keys
|-
| [[getPlayerAmmunitionNames]] || Ammunition keys
|-
| [[getPlayerRuneNames]] || All rune/spell-item keys; not a synchronization-support list
|-
| [[getSpellCatalog]] || All spell definitions and their <code>implemented</code> status; see [[Synchronized spell catalog]]
|-
| [[getPlayerStatNames]] || Progression statistic keys
|-
| [[getPlayerSkillNames]] || Skill keys
|-
| [[getPlayerGuildNames]] || Guild keys
|}

== Example ==
<syntaxhighlight lang="lua">
local function contains(values, wanted)
for _, value in ipairs(values) do
if value == wanted then
return true
end
end
return false
end

if contains(getPlayerArmorNames(), "none") then
setPlayerArmor(playerId, "none")
end
</syntaxhighlight>

[[Category:Lua API]]
[[Category:Lua Catalogs]]

Main Page

2026-09-09T03:08:55Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

__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="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">OBSERVER NAMEPLATES — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''12 new server-side functions''' add per-observer text, whole-label visibility and numeric-ID policy. Build directional acquaintance presentation with exclusive resource-owned fields and reliable relevance replay. See [[Observer nameplates]] for APIs, lifecycle, database integration and the optional three-client <code>/nametest</code> sequence. Overhead customization does not anonymize other packets, chat or player lists.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">PLAYER CUSTOMIZATION — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''7 new server-side functions''' provide independent skin-color and tattoo overrides. Existing identity selection has improved head and armor compatibility from update 0.1.3. See [[Player customization]] for examples and reset behavior, and [[Player tattoo catalog]] for all 12 keys.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Skin color:</strong> [[setPlayerSkinColor]] • [[getPlayerSkinColor]] • [[resetPlayerSkinColor]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Tattoos:</strong> [[setPlayerTattoo]] • [[getPlayerTattoo]] • [[resetPlayerTattoo]] • [[getPlayerTattooNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Improved existing API:</strong> [[setPlayerIdentity]] keeps the game-owned body and equipped armor. These are cosmetic controls, not a full NPC body/outfit replacement.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">SCRIPTED CAMERA — AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">'''15 camera functions''' and '''2 client camera events''' are available from G1R:MP 0.1.3. Build login backgrounds, fixed shots, smooth transitions, paths and orbits. See [[Scripted camera]] for examples, limits and client/server differences.</div>
<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Client and server (10):</strong> [[setCameraPos]] • [[setCameraRot]] • [[setCameraLookAt]] • [[setCameraFOV]] • [[setCameraPose]] • [[moveCameraTo]] • [[playCameraPath]] • [[orbitCamera]] • [[stopCameraMovement]] • [[resetCameraPos]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client read-back (5):</strong> [[getCameraPos]] • [[getCameraRot]] • [[getCameraFOV]] • [[getCameraState]] • [[requestCameraState]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client events (2):</strong> [[onClientCameraCommandResult]] • [[onClientCameraReset]]. Client commands use asynchronous acknowledgements; server calls return only a queued boolean.</div>
</div>

<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin:0 0 1.25rem;">
<div style="color:#111; font-size:1.05rem; font-weight:bold; letter-spacing:0.04em;">AVAILABLE AND IMPROVED FROM UPDATE 0.1.2</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.55;">The following '''40 Lua functions''' — 29 server-side and 11 client-side — are available from G1R:MP 0.1.2. Existing lifecycle, inventory, JSON, NPC, monster, and world-item APIs also include corrected or expanded behavior from this update.</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Accounts and consumables (4):</strong> [[completePlayerConsumableFinalize]] • [[completePlayerConsumableUse]] • [[getPlayerAccountBindingSerial]] • [[getPlayerConsumableNames]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>World items (1):</strong> [[spawnItem]] — see also the [[World item catalog]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster identity, health, and combat (5):</strong> [[setMonsterName]] • [[setMonsterIdVisible]] • [[setMonsterMaxHealth]] • [[getMonsterAttackDamage]] • [[setMonsterAttackDamage]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Monster navigation (6):</strong> [[setMonsterNavigationMode]] • [[setMonsterNavigationCollisionMode]] • [[setMonsterMoveGoal]] • [[stopMonsterMovement]] • [[testMonsterMove]] • [[walkMonsterTo]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>NPC identity and navigation (7):</strong> [[setNpcIdVisible]] • [[setNpcObstacleBehavior]] • [[setNpcNavigationMode]] • [[setNpcNavigationCollisionMode]] • [[setNpcMoveGoal]] • [[stopNpcMovement]] • [[testNpcMove]]</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Custom navigation blockers (6):</strong> [[createAiNavigationBlocker]] • [[updateAiNavigationBlocker]] • [[setAiNavigationBlockerEnabled]] • [[destroyAiNavigationBlocker]] • [[getAiNavigationBlockerData]] • [[getAiNavigationBlockers]] — see [[NPC and monster navigation collision]].</div>
<div style="color:#111; margin-top:0.35rem; line-height:1.65;"><strong>Client audio (11):</strong> [[playSound]] • [[playSound3D]] • [[stopSound]] • [[setSoundVolume]] • [[getSoundVolume]] • [[setSoundPaused]] • [[isSoundPaused]] • [[isSoundPlaying]] • [[setSoundLooped]] • [[setSound3DPosition]] • [[setSound3DMinMaxDistance]] — see [[Client audio]].</div>

<div style="color:#111; margin-top:0.65rem; line-height:1.65;"><strong>Events available from 0.1.2 (8):</strong> [[onNpcIdVisibilityChange]] • [[onMonsterNameChange]] • [[onMonsterIdVisibilityChange]] • [[onMonsterMoveBlocked]] • [[onMonsterMoveComplete]] • [[onNpcMoveBlocked]] • [[onNpcMoveComplete]] • [[onWorldItemDrop]]. Existing [[onPlayerJoin]], [[onPlayerQuit]], [[onWorldItemPickup]], and [[onWorldItemSpawn]] contracts are also improved from 0.1.2.</div>
</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>[[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>[[Scripted camera|Scripted camera and moving login backgrounds (0.1.3)]]</li>
<li>[[Observer nameplates|Observer-specific labels and acquaintance presentation (0.1.3)]]</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>[[: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|Client audio functions]]</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>[[Known issue: MySQL error 2006 (Server has gone away)|Known MySQL/MariaDB issue]]</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;">The reference contains '''310 Lua functions''' and '''94 events''', including '''12 observer/nameplate-ID functions, 7 skin-color/tattoo functions, 15 camera functions and 2 camera events available from update 0.1.3'''. Version notices distinguish newly available APIs from improved contracts in earlier APIs. See [[Observer nameplates]] for directional labels, [[Player customization]] for identity, color and tattoos, [[Lua API catalogs]] for validated gameplay keys, and [[Scripted camera]] for camera state and lifecycle rules. APIs marked [[:Category:Experimental Lua API|experimental]] may still change while the multiplayer runtime is under active development.</div>
</div>
</div>

[[Category:Lua API]]

Observer nameplates

2026-09-09T03:08:52Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

{{DISPLAYTITLE:Observer nameplates}}
<div style="background:#fff8f8; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111; padding:0.95rem 1.1rem; margin-bottom:1rem; font-weight:bold;">OBSERVER NAMEPLATES — AVAILABLE FROM UPDATE 0.1.3</div>

These '''12 new server-side functions''' control overhead labels for an ordered pair of connected human players: '''observer → target'''. They are universal presentation primitives: the gamemode owns acquaintance rules, permissions, character/account identifiers and database persistence. They do not replace [[setPlayerName]] or change the player's character appearance.

== Function reference ==
{| class="wikitable"
! Function !! Purpose
|-
| [[setPlayerNameplateTextFor]] / [[getPlayerNameplateTextFor]] / [[resetPlayerNameplateTextFor]] || Set, read or remove an explicit text override for one pair.
|-
| [[setPlayerNameplateVisibleFor]] / [[isPlayerNameplateVisibleFor]] / [[resetPlayerNameplateVisibleFor]] || Control the complete overhead label for one pair, including numeric ID and speaking suffix.
|-
| [[setPlayerNameplateIdVisibleFor]] / [[isPlayerNameplateIdVisibleFor]] / [[resetPlayerNameplateIdVisibleFor]] || Control only the numeric session-ID suffix for one pair.
|-
| [[getPlayerNameplateStateFor]] || Read effective policy, explicit override flags and raw values together.
|-
| [[setPlayerNameplateIdVisible]] / [[isPlayerNameplateIdVisible]] || Set/read the global numeric-ID fallback, default <code>true</code>.
|}
All twelve functions have PascalCase aliases, for example <code>SetPlayerNameplateTextFor</code>. The first ten take <code>observerId, targetId</code>; both must be different connected human-player session IDs. NPC IDs, persistent character IDs, invalid IDs and self-pairs are rejected.

== Independent fields and current defaults ==
Each field resolves independently: '''pair override → current global field → native default'''. A text override does not force visibility or suppress the numeric ID. An ID override does not hide the name or mute voice. Whole-label visibility <code>false</code> hides text, ID and the speaking suffix; voice audio routing is unchanged.

<syntaxhighlight lang="lua">
-- A sees B as a stranger; C knows B. B's view of A is unchanged.
setPlayerNameplateTextFor(playerA, playerB, "Stranger")
setPlayerNameplateTextFor(playerC, playerB, "Known friend")
setPlayerNameplateIdVisibleFor(playerA, playerB, false)

-- Reset only A's text. A now uses B's CURRENT global text/name,
-- while A's explicit ID-hidden override remains.
resetPlayerNameplateTextFor(playerA, playerB)
</syntaxhighlight>

Existing [[setPlayerNameplateText]], [[resetPlayerNameplateText]] and [[setPlayerNameplateVisible]] remain global fallback controls; they do not clear pair overrides. [[getPlayerNameplateText]] returns global custom text or <code>false</code> when unset. [[isPlayerNameplateVisible]] reads the global visibility policy, not the observer-specific result. Global settings are not resource-owned and are not reverted automatically when the writing resource stops.

== Reading explicit versus effective state ==
[[getPlayerNameplateTextFor]] returns '''only an explicit pair text string''', otherwise <code>false</code>. It never returns inherited text. The two <code>is...For</code> getters return the effective boolean after inheritance; <code>false</code> can also mean an invalid pair.

[[getPlayerNameplateStateFor]] returns this table, or <code>false</code> for an invalid pair/unavailable service:
{| class="wikitable"
! Field !! Meaning
|-
| <code>text</code>, <code>visible</code>, <code>idVisible</code> || Effective text string and boolean policies. Text excludes the system ID and speaking suffixes.
|-
| <code>textOverridden</code>, <code>visibilityOverridden</code>, <code>idVisibilityOverridden</code> || Whether the corresponding explicit pair field exists.
|-
| <code>textOverride</code> || Explicit string, or <code>false</code> when absent.
|-
| <code>visibleOverride</code>, <code>idVisibleOverride</code> || Explicit boolean, or <code>false</code> when absent. Use the flag to distinguish absent from explicitly false.
|}

<syntaxhighlight lang="lua">
local state = getPlayerNameplateStateFor(observerId, targetId)
if state then
outputDebugString(state.text)
if state.visibilityOverridden and state.visibleOverride == false then
outputDebugString("Explicitly hidden for this observer")
end
end
</syntaxhighlight>
The table is a '''resource-global, read-only server view''': it includes fields owned by other resources. It is not an AOI test or client-render acknowledgement. Effective text may be non-empty while visibility is false. Distance, native presentation rules and asynchronous delivery still determine whether pixels are rendered.

== Validation and exclusive resource ownership ==
* New boolean setters require real Lua booleans; <code>0</code>, <code>1</code>, strings and <code>nil</code> are not substitutes. IDs must be finite positive integers. Invalid argument counts return <code>false</code>.
* Text must be valid UTF-8, at most '''48 Unicode code points and 96 bytes'''. It is rejected, not truncated, on invalid UTF-8, controls, <code><</code>, <code>></code>, <code>&</code>, BOM, or the shared validator's disallowed zero-width/bidirectional formatting characters. Empty text means reset.
* The resource that first writes a pair field owns that field exclusively. '''Another resource cannot overwrite or reset it until the owner releases it.''' Different fields of the same pair can have different owners.
* An identical owned write or reset of an absent field succeeds without a state change. A foreign write/reset fails. Always check the returned boolean; a failed mutation does not grant ownership.
* Reset removes only the selected owned field and follows the '''current''' fallback. It does not restore a captured old global value.
* The core does not impose an RP permission or acquaintance policy. Validate permissions and remote-event senders in your own trusted server resource.

== Relevance, reconnect and resource stop ==
Accepted changes are sent reliably to the affected observer when relevant. Pair overrides remain stored outside synchronization range; the current resolved state is replayed on late join and AOI re-entry. Resource stop removes only that resource's fields. Disconnect of either endpoint clears affected pairs, and session-generation checks prevent stale state from applying to a reused numeric player ID.

These overrides are '''runtime state, not persistent database relations'''. After reconnect or resource restart the gamemode must restore its policy. Global nameplate state also ends when that player disconnects. A setter returning <code>true</code> means server acceptance, not proof that another client has rendered the label.

== Configurable bounds ==
Default server configuration:
<syntaxhighlight lang="ini">
[nameplates]
maxPairs=250000
maxPairsPerResource=250000
mutationsPerSecond=4096
mutationBurst=8192
</syntaxhighlight>
Capacity keys accept <code>1..1000000</code>; mutation rate/burst accept <code>1..250000</code>. A pair counts once globally and once per resource owning any of its fields. The per-resource token bucket charges changed, non-reset field writes. Identical writes, resets and cleanup do not consume tokens. A capacity/rate rejection returns <code>false</code>; batch large restores over ticks and retry with bounded scheduling, not a tight loop.

Defaults can hold all <code>500 × 499</code> directed pairs. A sparse global-default-plus-known-exceptions design usually uses fewer entries and less work.

== Building a persistent acquaintance system ==
The server developer supplies the database schema and adapter. Store directional relationships by stable '''character IDs''', not temporary <code>playerId</code>. Decide whether <code>A knows B</code> implies a reciprocal relationship; the engine deliberately does not assume this.

A possible policy:
# When a character becomes ready, establish its global label as <code>Stranger (<characterId>)</code> and global numeric-ID policy as false. Choose one resource to own this global policy, and do so before exposing the character under your gamemode's login/spawn flow.
# For each observer who knows that character, set a pair text override with the known name. Do not call [[setPlayerName]] to simulate a stranger: that changes the canonical name used by other systems.
# On new acquaintances or forgotten relations, update/reset only the relevant directional pair. Check returned booleans for resource conflicts or rate limits.
# On reconnect/resource restart, rebuild policy in bounded batches from your own database. Core pair cleanup does not revert global settings for you.

'''Guard asynchronous DB results against both endpoints changing.''' Capture both session objects/generations, both stable character IDs, and your resource's load epoch before starting a query. Before applying its result, verify every captured value is still current and both players are connected and character-ready. <code>isPlayerConnected</code> alone cannot detect ID reuse or a character switch.

<syntaxhighlight lang="lua">
-- Integration sketch: sessions, loadEpoch and queryAcquaintance are YOUR
-- gamemode's state/DB adapter, not extra G1R:MP API functions.
local observerSession = sessions[observerId]
local targetSession = sessions[targetId]
local requestEpoch = loadEpoch
local observerCharacter = observerSession.characterId
local targetCharacter = targetSession.characterId

queryAcquaintance(observerCharacter, targetCharacter, function(knownName)
if loadEpoch ~= requestEpoch
or sessions[observerId] ~= observerSession
or sessions[targetId] ~= targetSession
or observerSession.characterId ~= observerCharacter
or targetSession.characterId ~= targetCharacter
or not observerSession.characterReady or not targetSession.characterReady
or not isPlayerConnected(observerId) or not isPlayerConnected(targetId) then
return
end
-- Adapter returns a validated name or false; handle DB failures separately.
local accepted
if type(knownName) == "string" then
accepted = setPlayerNameplateTextFor(observerId, targetId, knownName)
elseif knownName == false then
accepted = resetPlayerNameplateTextFor(observerId, targetId)
end
if accepted == false then
outputDebugString("Acquaintance presentation rejected; check ownership or limits")
end
end)
</syntaxhighlight>
Initialize and validate both session objects before entering this sketch; replace them on session/character changes and invalidate <code>loadEpoch</code> when abandoning a restore batch.

== Privacy boundary ==
'''Hiding an overhead label is not network anonymity.''' Canonical names still exist in identity packets, [[getPlayerName]], ordinary player-list and chat flows unless those systems independently become recipient-aware. This feature neither changes account credentials nor guarantees that a client cannot inspect canonical identity elsewhere. For consistent stranger RP, apply one server-side recipient-aware resolver to each relevant chat/roster/UI path as a separate gamemode concern.

== Optional three-client test ==
The shipped <code>nameplate_test</code> resource is '''not autostarted'''. Start it explicitly in the server console:
<syntaxhighlight lang="text">
start nameplate_test
</syntaxhighlight>
The bundled GothicRP adapter requires an authenticated test operator with <code>admin.players</code> and <code>RP.Config.testTools.enabled == true</code>. All participants must be logged in and fully spawned. An authenticated test owner can still stop the test after permissions/settings change. Other gamemodes need their own trusted server-resource adapter; do not expose the test event as remotely callable.

<syntaxhighlight lang="text">
/nametest start <A ID> <B ID> <C ID>
/nametest next
/nametest status
/nametest stop
</syntaxhighlight>
Use three different connected players with no existing overrides on the six directed pairs. Only the starter controls the active sequence. English chat messages guide '''10 steps''': directional text, ID hiding, complete-label hiding, visibility restore, acquaintance text, reverse direction, text reset, visibility/ID reset, AOI re-entry and final cleanup.

Step 9 requires moving B outside the server synchronization range and back, then checking each client's intended label without a stale/canonical-name flash. Optional disconnect or resource-stop checks terminate the sequence and clear test-owned fields. The test does not change globals, database records, equipment or player positions; global controls have separate C++ tests. Chat readback verifies server state, so '''all three clients must still inspect actual visuals'''. Use matching protocol-34 server/client builds.

[[Category:Lua API]]
[[Category:Lua Examples]]
[[Category:Nameplate Functions]]

SetPlayerNameplateVisible

2026-09-09T03:08:51Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

= setPlayerNameplateVisible =
Sets a player's global overhead visibility fallback for observers without an explicit visibility override.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerNameplateVisible(int playerId, bool visible)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>visible</code> || <code>bool</code> || yes || Whether the overhead label should be rendered.
|}

== Returns ==
Returns <code>true</code> when the state was accepted; otherwise returns <code>false</code>.

== Examples ==
Hide a label while disguised:
<syntaxhighlight lang="lua" line>
setPlayerNameplateVisible(playerId, false)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Visibility is reliable, server-authoritative and replayed on relevance entry. A per-observer visibility override takes precedence.
* False hides the complete overhead label, including its numeric ID and speaking suffix; it does not mute voice audio. Text and ID policy are preserved.

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

IsPlayerNameplateVisible

2026-09-09T03:08:50Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

= isPlayerNameplateVisible =
Reads the global overhead nameplate visibility policy, before per-observer overrides.

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

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

== Returns ==
Returns the global visibility boolean, or <code>false</code> for an invalid player. This does not report rendered pixels, distance or per-observer overrides.

== Examples ==
Check label visibility:
<syntaxhighlight lang="lua" line>
if not isPlayerNameplateVisible(playerId) then
outputDebugString("Nameplate hidden")
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Use [[isPlayerNameplateVisibleFor]] for a particular observer/target pair.

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

ResetPlayerNameplateText

2026-09-09T03:08:49Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

= resetPlayerNameplateText =
Removes a player's global custom overhead text, restoring the canonical player name as the fallback.

== Syntax ==
<syntaxhighlight lang="lua">
bool resetPlayerNameplateText(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 state was reset; otherwise returns <code>false</code>.

== Examples ==
Remove a temporary roleplay label:
<syntaxhighlight lang="lua" line>
resetPlayerNameplateText(playerId)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Does not clear per-observer text overrides or change visibility/ID policy. See [[Observer nameplates]].

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

SetPlayerNameplateText

2026-09-09T03:08:48Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

= setPlayerNameplateText =
Changes a player's server-authoritative overhead nameplate text.

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

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>text</code> || <code>string</code> || yes || Validated UTF-8 text, or an empty string to restore the default player name.
|}

== Returns ==
Returns <code>true</code> when the global text was accepted; otherwise returns <code>false</code>. This is not a client-render acknowledgement.

== Examples ==
Show a roleplay label:
<syntaxhighlight lang="lua" line>
setPlayerNameplateText(playerId, "Militia Guard")
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Text is limited to 48 Unicode code points and 96 UTF-8 bytes.
* Control characters, HTML delimiters, ampersands, byte-order marks and bidirectional formatting characters are rejected.
* The reliable state is replayed during relevance entry and late join.
* Changes the global fallback only. An explicit [[setPlayerNameplateTextFor|per-observer text override]] still wins; visibility and ID policy are preserved. Custom text does not automatically hide the numeric ID.

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

GetPlayerNameplateText

2026-09-09T03:08:46Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

= getPlayerNameplateText =
Returns a player's custom overhead nameplate text.

== Syntax ==
<syntaxhighlight lang="lua">
string|false getPlayerNameplateText(int playerId)
</syntaxhighlight>

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

== Returns ==
Returns the global custom UTF-8 text, or <code>false</code> when no global custom text is set or the player is invalid.

== Examples ==
Read a roleplay label:
<syntaxhighlight lang="lua" line>
local text = getPlayerNameplateText(playerId)
if text and text ~= "" then
outputDebugString(text)
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Reads the global field, not a per-observer override. Use [[getPlayerNameplateStateFor]] for the resolved observer/target view.
* The numeric ID and speaking marker are not part of the returned text. Numeric ID visibility has separate global and per-observer controls from 0.1.3.

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

IsPlayerNameplateIdVisible

2026-09-09T03:08:45Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Reads the global numeric-ID visibility policy before per-observer overrides.

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

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

== Returns ==
Returns the global ID visibility boolean (default true), or <code>false</code> for an invalid player/service. It does not report whether a nameplate is currently rendered.

== Examples ==
Read global ID policy:
<syntaxhighlight lang="lua" line>
local visible = isPlayerNameplateIdVisible(playerId)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Use [[isPlayerNameplateIdVisibleFor]] or [[getPlayerNameplateStateFor]] for a particular observer. A globally visible ID can still be hidden because the whole nameplate is hidden.
* PascalCase alias: <code>IsPlayerNameplateIdVisible</code>.

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

SetPlayerNameplateIdVisible

2026-09-09T03:08:43Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Sets the global numeric session-ID visibility fallback for a human player's overhead label.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerNameplateIdVisible(int playerId, bool visible)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>visible</code> || <code>bool</code> || yes || Strict boolean; true restores the normal ID suffix, false hides only that suffix.
|}

== Returns ==
Returns <code>true</code> when the server accepts the global policy; otherwise <code>false</code>. This is not a client-render acknowledgement.

== Examples ==
Keep a roleplay label while removing its numeric session ID:
<syntaxhighlight lang="lua" line>
setPlayerNameplateText(playerId, "Stranger")
setPlayerNameplateIdVisible(playerId, false)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Defaults to true. A per-observer ID override takes precedence. Text, whole-label visibility and speaking state are preserved; custom text never automatically hides IDs.
* Uses existing global-state semantics: not resource-owned and not automatically reverted when the calling resource stops. The runtime state ends on player disconnect; persistent policy must be reapplied by the gamemode.
* Not a permission boundary or anonymous networking mode; canonical identity remains available in other packets/UI. See [[Observer nameplates]].
* PascalCase alias: <code>SetPlayerNameplateIdVisible</code>.

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

GetPlayerNameplateStateFor

2026-09-09T03:08:42Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Returns the resolved server-side overhead policy and explicit override flags for an observer/target pair.

== Syntax ==
<syntaxhighlight lang="lua">
table|false getPlayerNameplateStateFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns a table with effective <code>text</code> (string), <code>visible</code> (bool), <code>idVisible</code> (bool); flags <code>textOverridden</code>, <code>visibilityOverridden</code>, <code>idVisibilityOverridden</code>; and raw <code>textOverride</code> (string or false), <code>visibleOverride</code> (bool), <code>idVisibleOverride</code> (bool). Unset raw fields are false, so use the corresponding flag to distinguish unset from an explicit false. Returns <code>false</code> for an invalid pair or unavailable service.

== Examples ==
Distinguish inherited visibility from an explicit hidden override:
<syntaxhighlight lang="lua" line>
local state = getPlayerNameplateStateFor(observerId, targetId)
if state then
outputDebugString(state.text)
if state.visibilityOverridden and state.visibleOverride == false then
outputDebugString("Explicitly hidden for this observer")
end
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* Effective text excludes the system numeric-ID suffix and speaking marker. It can be non-empty even when visible is false.
* The read-only view includes fields owned by any resource. It is not a render acknowledgement, AOI test, or a secure concealment of canonical identity.
* PascalCase alias: <code>GetPlayerNameplateStateFor</code>.

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

ResetPlayerNameplateIdVisibleFor

2026-09-09T03:08:40Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Removes only the calling resource's numeric session-ID visibility override for one observer/target pair.

== Syntax ==
<syntaxhighlight lang="lua">
bool resetPlayerNameplateIdVisibleFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns <code>true</code> when the owned field is removed or was already absent; <code>false</code> for an invalid pair/service or a field owned by another resource.

== Examples ==
Resume inheritance from the current global setting:
<syntaxhighlight lang="lua" line>
resetPlayerNameplateIdVisibleFor(observerId, targetId)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* A pair field is exclusively owned by the resource that first sets it. Another resource cannot overwrite or reset that field; other fields remain independent. An absent reset and an identical owned write are successful no-ops.
* Pair overrides survive leaving the synchronization range, but are cleared for both endpoints on disconnect and for their owning resource on stop. State is replayed reliably when the target becomes relevant again; no database persistence is automatic.
* Limits default to 250,000 active pairs globally and per resource, with a per-resource mutation token bucket of 4,096/s and an 8,192 burst. New/changed non-reset writes consume tokens; resets and cleanup do not. See the guide for configuration keys.
* Does not restore a saved global snapshot or clear another field. The current target fallback is used immediately in server state; rendering remains asynchronous.
* PascalCase alias: <code>ResetPlayerNameplateIdVisibleFor</code>.

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

IsPlayerNameplateIdVisibleFor

2026-09-09T03:08:39Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Reads the effective numeric session-ID visibility policy for one observer/target pair.

== Syntax ==
<syntaxhighlight lang="lua">
bool isPlayerNameplateIdVisibleFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns the effective boolean after pair/global inheritance, or <code>false</code> for an invalid pair/service. Use [[getPlayerNameplateStateFor]] to distinguish an explicit false from an unset override.

== Examples ==
Read the selected pair without changing state:
<syntaxhighlight lang="lua" line>
local value = isPlayerNameplateIdVisibleFor(observerId, targetId)
outputDebugString(tostring(value))
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* The read-only view is resource-global; it is not limited to fields owned by the calling resource.
* PascalCase alias: <code>IsPlayerNameplateIdVisibleFor</code>.

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

SetPlayerNameplateIdVisibleFor

2026-09-09T03:08:37Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Overrides a target player's overhead numeric session-ID visibility for one observer only.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerNameplateIdVisibleFor(int observerId, int targetId, bool visible)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|-
| <code>visible</code> || <code>bool</code> || yes || Strict boolean: false removes only the numeric ID suffix, retaining text and any speaking marker.
|}

== Returns ==
Returns <code>true</code> when the server accepts the change or an identical owned no-op; <code>false</code> for invalid arguments/endpoints, ownership conflicts, unavailable service or exhausted limits. Acceptance is not a client-render acknowledgement.

== Examples ==
Change only observer A's view of target B:
<syntaxhighlight lang="lua" line>
local accepted = setPlayerNameplateIdVisibleFor(observerId, targetId, false)
if not accepted then
outputDebugString("Nameplate override rejected")
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* A pair field is exclusively owned by the resource that first sets it. Another resource cannot overwrite or reset that field; other fields remain independent. An absent reset and an identical owned write are successful no-ops.
* Pair overrides survive leaving the synchronization range, but are cleared for both endpoints on disconnect and for their owning resource on stop. State is replayed reliably when the target becomes relevant again; no database persistence is automatic.
* Limits default to 250,000 active pairs globally and per resource, with a per-resource mutation token bucket of 4,096/s and an 8,192 burst. New/changed non-reset writes consume tokens; resets and cleanup do not. See the guide for configuration keys.
* Only actual Lua booleans are accepted; numbers, strings, nil and missing arguments return false. Voice audio routing is not changed.
* PascalCase alias: <code>SetPlayerNameplateIdVisibleFor</code>.

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

ResetPlayerNameplateVisibleFor

2026-09-09T03:08:36Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Removes only the calling resource's whole-label visibility override for one observer/target pair.

== Syntax ==
<syntaxhighlight lang="lua">
bool resetPlayerNameplateVisibleFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns <code>true</code> when the owned field is removed or was already absent; <code>false</code> for an invalid pair/service or a field owned by another resource.

== Examples ==
Resume inheritance from the current global setting:
<syntaxhighlight lang="lua" line>
resetPlayerNameplateVisibleFor(observerId, targetId)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* A pair field is exclusively owned by the resource that first sets it. Another resource cannot overwrite or reset that field; other fields remain independent. An absent reset and an identical owned write are successful no-ops.
* Pair overrides survive leaving the synchronization range, but are cleared for both endpoints on disconnect and for their owning resource on stop. State is replayed reliably when the target becomes relevant again; no database persistence is automatic.
* Limits default to 250,000 active pairs globally and per resource, with a per-resource mutation token bucket of 4,096/s and an 8,192 burst. New/changed non-reset writes consume tokens; resets and cleanup do not. See the guide for configuration keys.
* Does not restore a saved global snapshot or clear another field. The current target fallback is used immediately in server state; rendering remains asynchronous.
* PascalCase alias: <code>ResetPlayerNameplateVisibleFor</code>.

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

IsPlayerNameplateVisibleFor

2026-09-09T03:08:34Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Reads the effective whole-label visibility policy for one observer/target pair.

== Syntax ==
<syntaxhighlight lang="lua">
bool isPlayerNameplateVisibleFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns the effective boolean after pair/global inheritance, or <code>false</code> for an invalid pair/service. Use [[getPlayerNameplateStateFor]] to distinguish an explicit false from an unset override.

== Examples ==
Read the selected pair without changing state:
<syntaxhighlight lang="lua" line>
local value = isPlayerNameplateVisibleFor(observerId, targetId)
outputDebugString(tostring(value))
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* The read-only view is resource-global; it is not limited to fields owned by the calling resource.
* PascalCase alias: <code>IsPlayerNameplateVisibleFor</code>.

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

SetPlayerNameplateVisibleFor

2026-09-09T03:08:33Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Overrides a target player's overhead whole-label visibility for one observer only.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerNameplateVisibleFor(int observerId, int targetId, bool visible)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|-
| <code>visible</code> || <code>bool</code> || yes || Strict boolean: false hides the entire label, including ID and speaking suffix; true permits it under normal rendering rules.
|}

== Returns ==
Returns <code>true</code> when the server accepts the change or an identical owned no-op; <code>false</code> for invalid arguments/endpoints, ownership conflicts, unavailable service or exhausted limits. Acceptance is not a client-render acknowledgement.

== Examples ==
Change only observer A's view of target B:
<syntaxhighlight lang="lua" line>
local accepted = setPlayerNameplateVisibleFor(observerId, targetId, false)
if not accepted then
outputDebugString("Nameplate override rejected")
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* A pair field is exclusively owned by the resource that first sets it. Another resource cannot overwrite or reset that field; other fields remain independent. An absent reset and an identical owned write are successful no-ops.
* Pair overrides survive leaving the synchronization range, but are cleared for both endpoints on disconnect and for their owning resource on stop. State is replayed reliably when the target becomes relevant again; no database persistence is automatic.
* Limits default to 250,000 active pairs globally and per resource, with a per-resource mutation token bucket of 4,096/s and an 8,192 burst. New/changed non-reset writes consume tokens; resets and cleanup do not. See the guide for configuration keys.
* Only actual Lua booleans are accepted; numbers, strings, nil and missing arguments return false. Voice audio routing is not changed.
* PascalCase alias: <code>SetPlayerNameplateVisibleFor</code>.

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

ResetPlayerNameplateTextFor

2026-09-09T03:08:31Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Removes only the calling resource's text override for one observer/target pair.

== Syntax ==
<syntaxhighlight lang="lua">
bool resetPlayerNameplateTextFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns <code>true</code> when the owned field is removed or was already absent; <code>false</code> for an invalid pair/service or a field owned by another resource.

== Examples ==
Resume inheritance from the current global setting:
<syntaxhighlight lang="lua" line>
resetPlayerNameplateTextFor(observerId, targetId)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* A pair field is exclusively owned by the resource that first sets it. Another resource cannot overwrite or reset that field; other fields remain independent. An absent reset and an identical owned write are successful no-ops.
* Pair overrides survive leaving the synchronization range, but are cleared for both endpoints on disconnect and for their owning resource on stop. State is replayed reliably when the target becomes relevant again; no database persistence is automatic.
* Limits default to 250,000 active pairs globally and per resource, with a per-resource mutation token bucket of 4,096/s and an 8,192 burst. New/changed non-reset writes consume tokens; resets and cleanup do not. See the guide for configuration keys.
* Does not restore a saved global snapshot or clear another field. The current target fallback is used immediately in server state; rendering remains asynchronous.
* PascalCase alias: <code>ResetPlayerNameplateTextFor</code>.

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

GetPlayerNameplateTextFor

2026-09-09T03:08:30Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Returns the explicit text override for one observer/target pair, not its inherited global/default text.

== Syntax ==
<syntaxhighlight lang="lua">
string|false getPlayerNameplateTextFor(int observerId, int targetId)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|}

== Returns ==
Returns the explicit pair text string, or <code>false</code> when no pair text override exists or the pair/service is invalid. Use [[getPlayerNameplateStateFor]] for inherited effective text.

== Examples ==
Read the selected pair without changing state:
<syntaxhighlight lang="lua" line>
local value = getPlayerNameplateTextFor(observerId, targetId)
outputDebugString(tostring(value))
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* The read-only view is resource-global; it is not limited to fields owned by the calling resource.
* PascalCase alias: <code>GetPlayerNameplateTextFor</code>.

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

SetPlayerNameplateTextFor

2026-09-09T03:08:28Z

QCherry: Document universal per-observer nameplates and test resource available from update 0.1.3

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

Overrides a target player's overhead text for one observer only.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerNameplateTextFor(int observerId, int targetId, string text)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>observerId</code> || <code>int</code> || yes || The connected human player who will see the label.
|-
| <code>targetId</code> || <code>int</code> || yes || The different connected human player whose overhead label is controlled.
|-
| <code>text</code> || <code>string</code> || yes || UTF-8 label; an empty string resets this pair's text override.
|}

== Returns ==
Returns <code>true</code> when the server accepts the change or an identical owned no-op; <code>false</code> for invalid arguments/endpoints, ownership conflicts, unavailable service or exhausted limits. Acceptance is not a client-render acknowledgement.

== Examples ==
Change only observer A's view of target B:
<syntaxhighlight lang="lua" line>
local accepted = setPlayerNameplateTextFor(observerId, targetId, "Known friend")
if not accepted then
outputDebugString("Nameplate override rejected")
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ordered pair is observer -> target; the reverse pair is independent. Both IDs must be distinct, connected session IDs, not persistent character IDs or NPC IDs.
* Each field resolves independently: explicit pair override, then the target's current global field, then the native default. Getters expose server policy, not whether pixels are currently rendered.
* No built-in acquaintance database or gamemode permission policy is assumed. See [[Observer nameplates]] for resource ownership, limits, persistence and privacy boundaries.
* A pair field is exclusively owned by the resource that first sets it. Another resource cannot overwrite or reset that field; other fields remain independent. An absent reset and an identical owned write are successful no-ops.
* Pair overrides survive leaving the synchronization range, but are cleared for both endpoints on disconnect and for their owning resource on stop. State is replayed reliably when the target becomes relevant again; no database persistence is automatic.
* Limits default to 250,000 active pairs globally and per resource, with a per-resource mutation token bucket of 4,096/s and an 8,192 burst. New/changed non-reset writes consume tokens; resets and cleanup do not. See the guide for configuration keys.
* Text is limited to 48 Unicode code points and 96 UTF-8 bytes. Invalid UTF-8, control characters, <code><</code>, <code>></code>, <code>&</code>, byte-order marks, zero-width and bidirectional formatting characters rejected by the shared validator are not accepted.
* Custom text never changes the canonical player name and does not implicitly hide the ID. Use [[setPlayerNameplateIdVisibleFor]] separately.
* PascalCase alias: <code>SetPlayerNameplateTextFor</code>.

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

Category:Appearance Functions

2026-09-09T02:32:39Z

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

Server-side functions for authoritative identity and cosmetic appearance. Seven independent skin-color and tattoo functions are available from update 0.1.3; see [[Player customization]] and [[Player tattoo catalog]]. Existing [[setPlayerIdentity]] head/armor handling is improved from update 0.1.3 while retaining the game-owned body and equipped armor. Older body/face compatibility APIs remain separately marked deprecated.

[[Category:Server Functions]]

Lua API catalogs

2026-09-09T02:32:38Z

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

{{DISPLAYTITLE:Lua API catalogs}}
'''Lua API catalogs''' collect stable, server-validated keys used by G1R:MP resources. Prefer catalog keys and enumeration functions over hard-coded Unreal paths.

== Static catalogs ==
{| class="wikitable"
! Catalog !! Used by
|-
| [[Player skin catalog]] || [[setPlayerSkin]], [[setNpcSkin]]
|-
| [[Player body catalog]] || deprecated compatibility reference for [[setPlayerBody]]
|-
| [[Player face catalog]] || deprecated compatibility reference for [[setPlayerFace]]
|-
| [[Player head catalog]] || deprecated compatibility reference for [[setPlayerHead]]
|-
| [[Player identity catalog]] || supported complete identity setter [[setPlayerIdentity]]
|-
| [[Player tattoo catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.3)</span> || [[setPlayerTattoo]], [[getPlayerTattooNames]]
|-
| [[Synchronized spell catalog]] || basic synchronized spell set for G1R:MP 0.1a
|-
| [[Monster type catalog]] || [[spawnMonster]]
|-
| [[World item catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || [[spawnItem]] and [[spawnTestItem]]
|-
| [[NPC and monster navigation collision]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || NPC and monster collision-source modes and resource-owned AI navigation blockers
|-
| [[Player animation catalog]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available from update 0.1.2)</span> || [[startAnim]] and [[stopAnim]]
|}

== Camera scripting ==
[[Scripted camera]] and [[:Category:Camera Functions|Camera Functions]] document camera poses, units, state fields, movement, paths, orbits and client/server ownership. These new functions and their client events are '''available from update 0.1.3'''.

== Player customization ==
[[Player customization]] documents the '''seven skin-color and tattoo functions available from update 0.1.3''', including RGB ranges, independent resets, tattoo removal and persistence. Existing [[setPlayerIdentity]] head/armor handling is '''improved from update 0.1.3'''; it is not a newly introduced identity API or a full NPC body replacement.

== Runtime catalogs ==
These functions return the authoritative keys supported by the running server build:

{| class="wikitable"
! Function !! Values
|-
| [[getPlayerArmorNames]] || Armor keys
|-
| [[getPlayerTattooNames]] || Tattoo preset keys (available from update 0.1.3)
|-
| [[getPlayerWeaponNames]] || Melee weapon keys
|-
| [[getPlayerRangedWeaponNames]] || Bow and crossbow keys
|-
| [[getPlayerAmmunitionNames]] || Ammunition keys
|-
| [[getPlayerRuneNames]] || All rune/spell-item keys; not a synchronization-support list
|-
| [[getSpellCatalog]] || All spell definitions and their <code>implemented</code> status; see [[Synchronized spell catalog]]
|-
| [[getPlayerStatNames]] || Progression statistic keys
|-
| [[getPlayerSkillNames]] || Skill keys
|-
| [[getPlayerGuildNames]] || Guild keys
|}

== Example ==
<syntaxhighlight lang="lua">
local function contains(values, wanted)
for _, value in ipairs(values) do
if value == wanted then
return true
end
end
return false
end

if contains(getPlayerArmorNames(), "none") then
setPlayerArmor(playerId, "none")
end
</syntaxhighlight>

[[Category:Lua API]]
[[Category:Lua Catalogs]]