QCherry: Document upcoming 0.1.6: area notification Lua API, door and pickup improvements; not a release

2026-09-26T22:22:23Z

Document upcoming 0.1.6: area notification Lua API, door and pickup improvements; not a release

New page

'''Available from update 0.1.6 (upcoming).''' These functions are not included in public 0.1.5. Use a matching client and server with area-notification support.

[[ShowAreaNotification]] displays a passive, native-style area banner in the upper-right HUD for one player. [[HideAreaNotification]] removes the current banner early when called by its owning resource. Both lines can be customized independently. Lower-camel aliases <code>showAreaNotification</code> and <code>hideAreaNotification</code> are supported.

== Example: two custom lines ==
Call from a server script after the player's character is available:
<syntaxhighlight lang="lua">
local accepted = ShowAreaNotification(playerId, "Entering territory", "Bandit Camp", 5000)
-- Or use Unicode text:
ShowAreaNotification(playerId, "Wkraczasz na teren", "Stary Obóz — Старий табір", 7000)

-- Called later by the same resource, if an early hide is needed:
-- HideAreaNotification(playerId)
</syntaxhighlight>

The first string is the smaller heading; the second is the main area name. An empty heading is allowed. Omit the duration argument to use 5000 ms; do not pass <code>nil</code> explicitly. Polish characters and Cyrillic were confirmed in the development in-game test. Glyph coverage still depends on the bundled fonts; this is not a promise that every Unicode symbol or emoji is supported.

== Behavior and ownership ==
* Server-side API only, targeting one connected player. No new client-side Lua functions or result events.
* One custom area banner per player. The latest accepted show replaces the previous banner and its timer, even if another resource created it.
* Only the current owning resource may dismiss that banner. Cleanup or hide from an older owner cannot remove another resource's replacement.
* Resource stop requests cleanup. Disconnect and world/player-pawn replacement clear the presentation. There is no late-join replay or automatic database persistence.
* Duration includes fade-in/fade-out and starts when the native client processes the request, not when the server sends it. This is not a pre-spawn loading-screen API.
* <code>true</code> means the server accepted the request for delivery, not that the player saw it. Invalid arguments, unavailable players or transport/capacity rejection return <code>false</code>. Hide can return <code>false</code> when the resource has no tracked banner for that player.
* Passive display: no keyboard/mouse capture, teleport, chapter change, quest progression, collision or streaming changes. Text is literal, not HTML/RML.

== Validation and limits ==
{| class="wikitable"
! Parameter / resource !! Limit
|-
| playerId || Connected numeric 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 5000 ms.
|-
| Ownership tracking || At most 8192 distinct tracked player IDs per resource. Explicit hide/resource cleanup releases tracking; visual expiry is not a server acknowledgement.
|-
| Client pending commands || Bounded queue of 32; overflow may discard pending commands. Do not send a banner every frame.
|-
| Creation retries || At most three attempts, 500 ms apart.
|}

String limits count UTF-8 '''bytes''', not characters. Malformed UTF-8, NUL, control characters and line breaks (including Unicode line/paragraph separators) are rejected. Show requires exactly three or four arguments; hide requires exactly one.

== Automatic discovery notices ==
From 0.1.6 the multiplayer client suppresses the visual presentation of the game's automatic area-discovery banner (for example, “New area discovered / Old Camp”). Custom banners remain available through this API.

This does '''not''' disable region triggers, erase discovery records or alter quest/save/streaming state. Native notification lifetime and queue processing remain intact; unrelated notifications are not globally disabled. For persistent first-visit messages, the gamemode should track discovered areas per player and call this API when appropriate.

See [[Chapter screens]] for the separate chapter-style title-card API, and [[Update 0.1.6]] for other upcoming changes.

[[Category:Lua API]]
[[Category:Lua Examples]]

Area notifications - Revision history

QCherry: Document upcoming 0.1.6: area notification Lua API, door and pickup improvements; not a release