QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

2026-09-12T18:33:05Z

Document ShowChapterScreen/HideChapterScreen available from update 0.1.3

New page

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

Chapter screens - Revision history

QCherry: Document ShowChapterScreen/HideChapterScreen available from update 0.1.3