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.