Game audio (audio.core) #

The sound of a game on every target: mixing buses, music by state, 2D and 3D effects, ambience areas and a table "game event to sound". Readable offline: gripforge docs audio-core, or the MCP tool gripforge_docs (topic audio-core).

What it is for #

A new game has sound without any asset: every kit brings default correspondences from its events to sounds, and audio.core ships a set of procedural base sounds (interface clicks, footsteps, jumps, hits, pickups, a vehicle engine, three music loops). The kit decides nothing of the game: it plays what the events say. To change what is heard, change the table, not the code.

It is installed by default in every new game, with ui.menu, input.remap and settings.graphics. The player's mix is the Audio tab of the Options screen (ui.menu).

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "audio.core" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "audio.core",
                              config: { "volumes": { "music": 50 },
                                        "sounds": { "footstep": { "src": ["lib:abc", "lib:def"] } } } }

It requires only game.engine. Only the keys that differ from the defaults need to be written. The full reference is gripforge kit api audio.core.

Buses #

master, music, sfx (effects), voice, ambience, ui (interface). Volume goes from 0 to 100 (gain = (v/100)^2), each bus can be muted, and master applies over the others. While the game is paused, sfx, voice and ambience are silenced (music and interface go on; voiceDuringPause: true keeps dialogue audible). The player's choices are saved in the player settings, outside game saves. Loading a save stops the sounds that were playing (past events are not replayed) and restarts the current music track.

Settings and defaults #

Sounds #

The bank maps a sound id (footstep, ui.click, music.combat, my_door) to a definition: src (several sources are variants, one is picked at random, never the same twice in a row), bus, volume, pitch, volumeJitter, pitchJitter (random plus or minus fraction per play), loop, spatial (3D) with minDistance, maxDistance, rolloff (inverse or linear), priority (0 to 100), limit (instances at once), duration, tags.

A source is base:<name> (procedural), lib:<id> (an audio asset of the library), slot:<id> (an asset slot), an engine path (res://… on Godot, a Resources path on Unity, /Game/… on Unreal) or a URL on the web.

Base sounds: ui.click, ui.hover, ui.confirm, ui.back, ui.error, ui.open, jump, land, footstep, hit, impact, swing, shot, reload, pickup, coin, checkpoint, success, fail, door, explosion, thunder, vehicle.engine (loop), ambience.wind, ambience.night (loops), music.menu, music.exploration, music.combat (loops). A project sound with the same id replaces one.

Correspondences (cues) #

A cue is { event, action, sound | state, when, unless, ifVar, volume, pitch, key, param, range, pitchRange, volumeRange }:

• play (default) plays sound when event fires. when and unless match payload fields, ifVar game variables. A 3D sound is placed at the payload's x, y, z (or position), else at the entity named by key (default entity). A looping sound plays once per key (one engine per vehicle).
• stop stops the looping voice of sound for that key.
• param drives a sound from a payload number (range to pitchRange or volumeRange): an engine pitch from the speed.
• music switches the music state.
• event: "var:<path>" fires when a game variable changes (payload { value, previous }).

{ "cues": [
  { "event": "door.opened", "sound": "my_door", "volume": 0.8 },
  { "event": "surface.footstep", "sound": "" },
  { "event": "boss.started", "action": "music", "state": "combat" }
] }

An empty sound mutes the defaults of that event. defaultCues: false turns all the kits' defaults off.

Music and ambience #

music.states maps a state to a playlist (menu, exploration, combat by default), music.playlists holds { tracks, shuffle, loop }, music.fade is the crossfade in seconds, music.initial the state when the game starts without a menu. By default the title screen plays menu, play plays exploration, encounters and bosses play combat, a cleared encounter returns to exploration.

Ambience areas are { id, sound, x, y, z, radius, fade, volume }: radius 0 means everywhere, the gain is full inside the radius and fades out over fade.

Service, events, variables #

Service audio.core: play(sound, { position, volume, pitch, key }) (a voice id, 0 when not played), playAt(sound, x, y, z), stop(voice), stopSound(sound), stopAll(), trigger(event, payload), setMusicState(state), musicState(), playPlaylist(id), nextTrack(), stopMusic(), music(), setListener(x, y, z), gainAt(sound, x, y, z), ambience(), volume(bus), setVolume(bus, v), muted(bus), setMuted(bus, on), busGain(bus), mixer(), voices(), stats(), bank(), sound(id), search(tag), cuesFor(event), reset(), reload(). The options tab is settings.audio (optionFields(lang), setOption(id, value)).

Events: audio.mix, audio.reset, audio.music. Variables: audio.volume.<bus>, audio.muted.<bus>, audio.music, audio.voices. The kit listens to every event of the bus: that is the cue table.

Hooks and modding #

A service: it takes no decision, so it declares no hook. A game or a mod changes the table. A mod may override volumes, muted, defaultCues, cues, music and ambience, all naming sounds by their id in the bank, so it remaps sounds the game already has. Not moddable: sounds (a source may be a URL or a path, the bank is the game's), maxVoices, seed, tab. The player's mix is a player setting: a mod changes the defaults, never what the player chose.

{ "schema": "gripforge.mod/1", "id": "quiet_music", "name": "Quiet music", "version": "1.0.0",
  "requires": { "audio.core": "^1" }, "config": { "audio.core": { "volumes": { "music": 40 } } } }

Acoustics (Rust only, off by default) #

acoustics: { enabled, rooms, portals, obstacles } turns on a shared propagation model: non-overlapping rooms in metres, door propagation, extra occluding boxes, reverb profiles and hearing for stealth. It is provided as the capability audio.acoustics (acousticSample(query), acoustics(command)) which consumers feature-detect. Only the Rust host computes it; the web player consumes the parameters, and the older engine scripts do not implement it. A game save holds only the acoustic scene.

Engines #

When it does not do what you expect #