GetGameSoundCatalog

getGameSoundCatalog

PLANNED FOR UPDATE 0.1.7

This function is planned for G1R:MP 0.1.7. It is not included in the public 0.1.6 release.

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

Syntax

table|false getGameSoundCatalog([string query = "", string category = "", int offset = 0, int limit = 50])

Parameters

Name	Type	Required	Description
query	string	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.
category	string	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.
offset	int	no	Zero-based count of matching entries to skip. Must be at least 0; defaults to 0.
limit	int	no	Maximum number of items to return, from 1 through 200. Defaults to 50.

Returns

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

Examples

List the first twenty matching dialogue keys:

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

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 getGameSoundCatalog(nil, "sfx", 0, 20).
• 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.