Chapter screens
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 displays a custom, passive chapter-style title card to one player. HideChapterScreen requests early removal. The lower-camel aliases showChapterScreen and hideChapterScreen 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:
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)
An empty heading is valid. Omit the fourth argument for 6000 ms; do not pass nil explicitly. There are no new chapter-screen Lua events or client-side Lua bindings.
Validation and limits
| 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: <b>Title</b> 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:
/chaptertest— default six-second card./chaptertest show My custom title— custom title./chaptertest unicode— Unicode text./chaptertest literal— verifies literal text instead of markup./chaptertest replace— replaces an older card immediately./chaptertest long My title— 30-second card./chaptertest hide— 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.