PreloadGameSound

preloadGameSound

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.

Requests preparation of a catalog sound in the installed game and caches successful capability metadata for this client resource.

Syntax

number|false preloadGameSound(string key)

Parameters

Name	Type	Required	Description
key	string	yes	Exact, case-sensitive key from getGameSoundCatalog. Accepts catalog entries only; no filename, URL or arbitrary event name.

Returns

Returns a positive integer request ID when accepted, or false when rejected locally. This is not a playback handle. The asynchronous onClientGameSoundResult contains capability metadata on success; getGameSoundInfo then exposes that metadata for this resource.

Examples

Preload a sound and inspect the metadata after its result arrives:

local key = "event:/SFX/UI/SFX_UI_Jingle_LevelUp"
local preloadRequest
addEventHandler("onClientGameSoundResult", resourceRoot,
    function(requestId, ok, reason, dataJson)
        if requestId ~= preloadRequest then return end
        if ok then
            local info = getGameSoundInfo(key)
            outputDebugString("Capabilities known: " .. tostring(info.capabilitiesKnown))
        else
            outputDebugString("Preload failed: " .. reason)
        end
    end)
preloadRequest = preloadGameSound(key)
if not preloadRequest then outputDebugString("Preload request rejected") 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.
• Preloading does not play a sound. Playback can also prepare its required assets automatically.
• Successful event preparation reports eventSamplesPreloaded = true. For dialogue, voicePreloadRequested = true indicates a request to the game's localization system; voicePreloadConfirmed remains false. A resolved recording path is not proof that voice samples were loaded or heard.
• There is no spatial argument. Dialogue preloading prepares the 2D template; a subsequent 3D dialogue play uses a separate cache entry.
• Each resource may hold at most 64 native cache entries. Playback also uses this cache. Entries remain until resource/session cleanup; there is no individual unload function.
• Preload results can fail asynchronously, including preload-cache-full, sample-load-failed, localized-recording-path-missing or a timeout.