https://g1r-mp.com/wiki/index.php?action=history&feed=atom&title=PreloadGameSoundPreloadGameSound - Revision history2026-10-01T15:25:43ZRevision history for this page on the wikiMediaWiki 1.46.0https://g1r-mp.com/wiki/index.php?title=PreloadGameSound&diff=1184&oldid=prevQCherry: Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release2026-10-01T10:20:43Z<p>Document upcoming 0.1.7 game audio: 11 client APIs, result event, limits and complete dialogue catalog; not a release</p>
<p><b>New page</b></p><div>= preloadGameSound =<br />
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;"><br />
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">PLANNED FOR UPDATE 0.1.7</div><br />
<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><br />
</div><br />
<br />
Requests preparation of a catalog sound in the installed game and caches successful capability metadata for this client resource.<br />
<br />
== Syntax ==<br />
<syntaxhighlight lang="lua"><br />
number|false preloadGameSound(string key)<br />
</syntaxhighlight><br />
<br />
== Parameters ==<br />
{| class="wikitable"<br />
! Name !! Type !! Required !! Description<br />
|-<br />
| <code>key</code> || <code>string</code> || yes || Exact, case-sensitive key from [[getGameSoundCatalog]]. Accepts catalog entries only; no filename, URL or arbitrary event name.<br />
|}<br />
<br />
== Returns ==<br />
Returns a positive integer request ID when accepted, or <code>false</code> 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.<br />
<br />
== Examples ==<br />
Preload a sound and inspect the metadata after its result arrives:<br />
<syntaxhighlight lang="lua" line><br />
local key = "event:/SFX/UI/SFX_UI_Jingle_LevelUp"<br />
local preloadRequest<br />
addEventHandler("onClientGameSoundResult", resourceRoot,<br />
function(requestId, ok, reason, dataJson)<br />
if requestId ~= preloadRequest then return end<br />
if ok then<br />
local info = getGameSoundInfo(key)<br />
outputDebugString("Capabilities known: " .. tostring(info.capabilitiesKnown))<br />
else<br />
outputDebugString("Preload failed: " .. reason)<br />
end<br />
end)<br />
preloadRequest = preloadGameSound(key)<br />
if not preloadRequest then outputDebugString("Preload request rejected") end<br />
</syntaxhighlight><br />
<br />
== Notes ==<br />
* Planned for update 0.1.7; not included in public 0.1.6.<br />
* Available only in client-side resource scripts. See [[Game audio]] for ownership, lifecycle, limits and server-triggered playback.<br />
* Preloading does not play a sound. Playback can also prepare its required assets automatically.<br />
* Successful event preparation reports <code>eventSamplesPreloaded = true</code>. For dialogue, <code>voicePreloadRequested = true</code> indicates a request to the game's localization system; <code>voicePreloadConfirmed</code> remains false. A resolved recording path is not proof that voice samples were loaded or heard.<br />
* There is no spatial argument. Dialogue preloading prepares the 2D template; a subsequent 3D dialogue play uses a separate cache entry.<br />
* 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.<br />
* Preload results can fail asynchronously, including <code>preload-cache-full</code>, <code>sample-load-failed</code>, <code>localized-recording-path-missing</code> or a timeout.<br />
<br />
[[Category:Lua Functions]]<br />
[[Category:Client Functions]]<br />
[[Category:Audio Functions]]</div>QCherry