ShowChapterScreen
showChapterScreen
AVAILABLE FROM UPDATE 0.1.3
This function is available in G1R:MP 0.1.3 and later. The contract below includes the compatibility guarantees introduced in that update.
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
bool ShowChapterScreen(int playerId, string heading, string title [, int durationMs = 6000])
bool showChapterScreen(int playerId, string heading, string title [, int durationMs = 6000])
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
playerId |
int |
yes | The connected player identifier. |
heading |
string |
yes | Top line: valid UTF-8, 0–256 bytes; an empty string is allowed. |
title |
string |
yes | Main line: valid UTF-8, 1–512 bytes. |
durationMs |
int |
no | Integer 1000–30000 milliseconds, default 6000. Omit this argument to use the default; explicit nil is invalid. |
Returns
Returns true when the server accepts the request for delivery. This is not confirmation that the client rendered it. Returns false 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:
ShowChapterScreen(playerId, "CHAPTER I", "Welcome to the Colony", 6000)
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
/chaptertest; see Chapter screens for variants.