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

2026-10-01T10:21:00Z

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

New page

'''Planned for update 0.1.7. These functions are not included in the public 0.1.6 release.'''

Game audio lets a client resource play built-in Gothic Remake sound effects, music and localized dialogue. Use catalog keys rather than filenames. The recordings remain in the player's installed game; this API does not redistribute them.

All functions on this page are '''client-side''' and use the exact lower-camel names shown below. Existing resource-file audio and voice chat are separate systems and remain unchanged.

== API overview ==
{| class="wikitable"
! Function !! Purpose !! Immediate return
|-
| [[playSoundFromGame]] || Request listener-relative / 2D playback. || Sound handle or false.
|-
| [[playSound3DFromGame]] || Request playback at a world position. || Sound handle or false.
|-
| [[stopGameSound]] || Stop one owned sound, including a pending start. || Request ID or false.
|-
| [[setGameSoundVolume]] || Set an owned sound's volume. || Request ID or false.
|-
| [[setGameSoundPaused]] || Pause or resume an owned sound. || Request ID or false.
|-
| [[setGameSound3DPosition]] || Move a source created with the 3D function. || Request ID or false.
|-
| [[setGameSound3DMinMaxDistance]] || Change that 3D source's attenuation distances. || Request ID or false.
|-
| [[getGameSoundState]] || Read the latest accumulated state of an owned handle. || Table or false.
|-
| [[preloadGameSound]] || Request preparation and native capability information. || Request ID or false.
|-
| [[getGameSoundInfo]] || Read catalog metadata plus this resource's last successful preload metadata. || Table or false.
|-
| [[getGameSoundCatalog]] || Search and paginate the built-in catalog. || Page table or false.
|}

[[onClientGameSoundResult]] reports asynchronous results and lifecycle changes to the owning resource.

== Find a sound ==
<syntaxhighlight lang="lua">
local page = getGameSoundCatalog("Diego", "dialogue", 0, 20)
if page then
for _, item in ipairs(page.items) do
outputDebugString(item.key .. " | " .. item.category .. " | " .. item.speaker)
end
outputDebugString("Matching entries: " .. tostring(page.total))
end
</syntaxhighlight>

The defaults are an empty query, all categories, offset 0 and a page size of 50. Categories are <code>""</code>, <code>"sfx"</code>, <code>"music"</code> and <code>"dialogue"</code>. Search matches key/speaker, case-insensitively for ASCII names. A catalog entry identifies an allowed request; it does not guarantee that every game build or installed voice language contains a playable recording. The complete identifier list is in [[Game dialogue catalog]], not just the examples below.

Examples of catalog keys:
* <code>event:/SFX/UI/SFX_UI_Jingle_LevelUp</code>
* <code>event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop</code>
* <code>event:/MUSIC/Locations/Explore/oldCamp/oldCampRing_day_explore</code>
* <code>voice/INFO_DIEGO_BARRIERE_11_01</code>

== Playback and asynchronous results ==
Install the result handler before requesting playback:
<syntaxhighlight lang="lua">
addEventHandler("onClientGameSoundResult", resourceRoot,
function(requestId, ok, reason, dataJson)
local data = fromJSON(dataJson)
if not ok then
outputDebugString("Game audio failed: " .. tostring(reason))
end
if type(data) == "table" and data.id and data.state then
outputDebugString("Sound " .. tostring(data.id) .. ": " .. data.state)
end
end)

local sound = playSoundFromGame(
"event:/SFX/UI/SFX_UI_Jingle_LevelUp", {volume = 0.5})
if not sound then
outputDebugString("Game audio request was not accepted.")
end
</syntaxhighlight>

A returned handle means the request was accepted, '''not''' that the sound is already playing. The play request ID equals its sound handle. Later control calls return their own request IDs; the result's <code>data.id</code> identifies the affected sound. <code>requestId == 0</code> identifies an unsolicited state/lifecycle notification.

The event's fourth argument is '''JSON text''', not a Lua table. Decode it with [[fromJSON]] and check its type. Results are operation-dependent; do not assume every field is present.

Typical states are <code>loading</code>, <code>starting</code>, <code>playing</code>, <code>paused</code>, followed by <code>finished</code>, <code>stopped</code> or <code>failed</code>. States may be skipped; short sounds can finish before the next script poll. The terminal states cannot be restarted: create a new handle to play again.

<code>confirmed</code> is context-sensitive: a playing/finished observation confirms native playback was observed; a successful explicit stop may also set it to true to confirm the stop. Cancellation before startup can yield stopped with confirmed=false. It never proves that a player heard the sound. Check <code>state</code> together with <code>confirmed</code>, not the flag alone.

== 3D placement and controls ==
Coordinates and distances are in '''metres''', not Unreal centimetres. Supply a position in the same coordinate system as the multiplayer world-position API:
<syntaxhighlight lang="lua">
local fire

function startExampleFire(x, y, z)
if fire then stopGameSound(fire) end
fire = playSound3DFromGame(
"event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop",
x, y, z, {volume = 0.6, minDistance = 1, maxDistance = 30})
return fire
end

function moveExampleFire(x, y, z)
if not fire then return false end
return setGameSound3DPosition(fire, x, y, z)
end

function stopExampleFire()
if not fire then return false end
local requestId = stopGameSound(fire)
fire = nil
return requestId
end
</syntaxhighlight>

After successful playback, the same resource can use <code>setGameSoundVolume(fire, 0.2)</code>, <code>setGameSoundPaused(fire, true)</code>, <code>setGameSoundPaused(fire, false)</code> and <code>setGameSound3DMinMaxDistance(fire, 1, 8)</code>. Observe the asynchronous results rather than assuming that a truthy request ID means a completed control operation. Position and distance controls reject handles created with the non-3D function.

Options may be omitted, nil or an empty table. Defaults are <code>{volume = 1, minDistance = 1, maxDistance = 30}</code>. Unknown option names are rejected. Use actual numbers and booleans of the documented types; arbitrary wrong types can raise Lua argument errors rather than returning false.

== Localized dialogue ==
<syntaxhighlight lang="lua">
local voice = playSoundFromGame("voice/INFO_DIEGO_BARRIERE_11_01", {volume = 0.8})
if not voice then
outputDebugString("Dialogue request was rejected.")
end
</syntaxhighlight>

The game's selected voice language determines the recording. Playing a line does not run a conversation graph, quest or subtitle scene. There is no language-override parameter and no substitution of another character's line or an alternate language by this API. Missing recordings or unavailable native facilities produce explicit errors.

The same voice key can be used with [[playSound3DFromGame]] for a world-positioned voice. The current implementation uses the game's own archive-aware audio loading rather than accepting a raw recording path.

== Preloading and metadata ==
<syntaxhighlight lang="lua">
local key = "event:/SFX/Objects/Fire/SFX_OBJ_Fire_Campfire_BurnLoop"
local requestId = preloadGameSound(key)
-- Wait for this requestId in onClientGameSoundResult.
-- After successful completion, getGameSoundInfo(key) includes native metadata.
</syntaxhighlight>

Catalog metadata initially includes <code>key</code>, <code>category</code>, <code>speaker</code>, <code>capabilitiesKnown=false</code> and <code>verifiedInGame=false</code>. Successful preload enriches this resource's cached info with fields such as <code>authoredSpatial</code>, <code>oneShot</code>, <code>loopMode</code> and <code>eventSamplesPreloaded</code>. Playback alone does not populate that info cache. <code>verifiedInGame</code> remains false; it is not a per-player listening test result.

'''Voice preload is a request, not an independently confirmed recording preload.''' A successful result can contain <code>voicePreloadRequested=true</code>, <code>voicePreloadConfirmed=false</code> and <code>recordingResolved=true</code>. Loaded event samples or a resolved recording do not prove that the voice PCM is ready or audible. Do not turn these flags into a claim that a dialogue has played.

== Authored behavior and music ==
* Looping, sustain and musical layers come from the authored event. There is no forced-loop option; <code>oneShot=false</code> does not guarantee a simple repeating loop.
* Non-3D playback of an authored spatial sound uses a source following the local camera, with per-instance attenuation. The reported mode is <code>listener-relative</code>. Truly 2D events report <code>authored-2d</code>; world-positioned playback reports <code>world-3d</code>.
* A 3D request for an authored 2D event fails with <code>event-is-2d</code>. Metadata and errors should be checked for each chosen key.
* This API does not stop the game's existing ambient music or change its global mixer/listener settings. Custom music can overlap native music. Game/user audio settings can affect what is heard.
* There are no bus/VCA, global event, arbitrary programmer-sound, raw pointer, URL or filesystem-path controls.

== Multiplayer and lifetime ==
Playback is '''local to each client'''. A server resource may select recipients with [[triggerClientEvent]], and a matching client handler can call these functions. There is no automatic broadcast, late-join replay or sample-accurate cross-client synchronization. Maintain desired persistent ambient sounds in your own resource and create them for newly joined clients when their world is ready.

Handles belong to the client resource that created them. Another resource cannot query/control them. Do not send a handle to another player or store it in a database as a persistent ID. Handles are not reused during the client runtime's lifetime, but become invalid after resource/lifecycle cleanup; older terminal records can be evicted.

Resource stop, disconnect, world replacement or loss of the native owner heartbeat clean up only the instances/preloads owned by this API. A world-reset notification has requestId=0, ok=false, reason=<code>world-reset</code> and an empty data object. Clear your script's saved handles in that case. Native NPC dialogue, other resources' file audio and voice chat are not globally stopped.

== Limits and error handling ==
See [[Scripting limits#Game audio (upcoming 0.1.7)|Game audio limits]] for numeric validation, capacity and timeouts. Cold loading can take time; preload a small useful selection instead of the entire catalog, and do not retry every frame.

Immediate false means the request was not accepted: for example an unknown key, invalid numeric range, foreign/ended handle, unavailable gameplay, or full capacity. No asynchronous completion is promised for a rejected request. Accepted requests can still fail later. Examples include <code>event-is-2d</code>, <code>preload-cache-full</code>, <code>native-queue-full</code>, <code>native-loading-timeout</code>, <code>native-timeout</code>, <code>localized-recording-path-missing</code>, <code>playback-not-observed</code>, <code>listener-lost</code> and <code>sound-not-owned-or-ended</code>.

Log the reason and available result fields, stop retry loops, and provide a fallback in your resource. Do not infer acoustic success from request acceptance or from the existence of a catalog entry.

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

Game audio - Revision history

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