QCherry: Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release

2026-10-01T10:20:26Z

Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release

New page

= getGameSoundCatalog =
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">PLANNED FOR UPDATE 0.1.7</div>
<div style="color:#111111; margin-top:0.25rem;">This function is planned for G1R:MP 0.1.7. It is not included in the public 0.1.6 release.</div>
</div>

Searches and pages the compiled game sound metadata catalog on the client.

== Syntax ==
<syntaxhighlight lang="lua">
table|false getGameSoundCatalog([string query = "", string category = "", int offset = 0, int limit = 50])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>query</code> || <code>string</code> || no || Optional substring search across key and speaker, case-insensitive for ASCII text. Defaults to an empty string, which matches all entries. Maximum length: 160 bytes.
|-
| <code>category</code> || <code>string</code> || no || Optional exact category: an empty string for all categories, or sfx, music or dialogue. Defaults to an empty string; category names are lowercase and case-sensitive.
|-
| <code>offset</code> || <code>int</code> || no || Zero-based count of matching entries to skip. Must be at least 0; defaults to 0.
|-
| <code>limit</code> || <code>int</code> || no || Maximum number of items to return, from 1 through 200. Defaults to 50.
|}

== Returns ==
Returns a Lua table with <code>items</code> (array of entry tables), <code>total</code> (number of all matches before paging) and <code>offset</code> (the requested zero-based offset), or <code>false</code> for invalid search or paging arguments. Each entry has <code>key</code>, <code>category</code> and <code>speaker</code> strings. Lua array entries are indexed from 1. A valid query with no matches, or an offset beyond the result set, returns an empty <code>items</code> table.

== Examples ==
List the first twenty matching dialogue keys:
<syntaxhighlight lang="lua" line>
local page = getGameSoundCatalog("Diego", "dialogue", 0, 20)
if page then
outputDebugString("Matching dialogue entries: " .. tostring(page.total))
for _, item in ipairs(page.items) do
outputDebugString(item.key .. " | " .. item.speaker)
end
end
</syntaxhighlight>

== Notes ==
* Planned for update 0.1.7; not included in public 0.1.6.
* Available only in client-side resource scripts. See [[Game audio]] for ownership, lifecycle, limits and server-triggered playback.
* Entries are returned in key order. The offset is zero-based even though the Lua items array is one-based.
* Use nil for omitted earlier optional arguments when providing later ones, for example <code>getGameSoundCatalog(nil, "sfx", 0, 20)</code>.
* Search is a substring match, not a regular expression. Copy the exact returned key for playback because key lookup is case-sensitive.
* The catalog contains metadata only. Recordings remain in the player's installed game; membership does not prove availability in every language/version or audible playback.
* Catalog queries are local and synchronous; no ready game session or preload is required.

[[Category:Lua Functions]]
[[Category:Client Functions]]
[[Category:Audio Functions]]

GetGameSoundCatalog - Revision history

QCherry: Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release