QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

2026-09-12T18:33:02Z

Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

New page

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

ShowChapterScreen - Revision history

QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3