HammeriteAudioRuntime

Audio. Inherits RefCounted

Process-wide access to the audio managers, the game's sound-type table, and the bake.

The HammeriteAudio autoload is the friendly front door, but it cannot be the place this state lives. An autoload is only an identifier inside a running scene tree: a node that mentions one by name will not even compile in a headless tool script, which would put every node in this addon - and everything that tests them - out of reach of the test runner. So the registry is static, here, and the autoload delegates to it. Same lifetime, same single instance, no dependency on the scene tree existing. A game reaches for this directly only where there is no tree to reach the autoload through: a headless bake, a CI run, a tool script.

Properties

Methods

Constants

GRAPH_KEY

const GRAPH_KEY = &"audio"

Where HammeriteMap.custom_data keeps a baked graph, and so what bake() writes and what a map arriving with one is heard through.

AMBIENCE

const AMBIENCE = &"ambience"

What a map's sounds are called, as kinds of HammeriteReferences: a room's ambience, by id, and the recording in sounds that a sound entity plays.

SOUND_FILE

const SOUND_FILE = &"sound_file"

The HammeriteReferences kind a sound entity's sound_file is recorded under: a name in sounds.

Property descriptions

changes

var changes: HammeriteAudioRuntime.Changes = <unknown>

Announces Changes.manager_changed whenever a manager is recorded for a map or forgotten: for a node holding a manager it looked up earlier, or one still waiting for any.

sound_types

var sound_types: HammeriteAudioSoundTypes = null

The game's sound types; see HammeriteAudioSoundTypes. Assigned once at startup, and reaching every manager already serving a map as well as the ones that come after.

mix_settings

var mix_settings: HammeriteAudioMixSettings = null

How every map's sound is mixed; see HammeriteAudioMixSettings. Assigned once at startup, and reaching every manager already serving a map as well as the ones that come after. Null puts the defaults back.

materials

var materials: HammeriteAudioMaterials

What each material does to sound; see HammeriteAudioMaterials. Assigned once at startup, and read by every bake from then on. Null puts the defaults back, and reading it never answers null - the defaults are built on the first ask.

presets

var presets: HammeriteAudioPreset[]

The reverb characters a room can be given, by HammeriteAudioPreset.id; see HammeriteAudioPreset. Assigned once at startup, and read by every bake and by the brush inspector's dropdown from then on. An empty array puts Hammerite's sixteen back, and reading it never answers an empty one - they are built on the first ask. A game adds a room of its own kind through add_preset() rather than editing the addon. Whatever a preset's id is, that is what a brush stores and what a baked graph names, so a game's own belong outside HammeriteAudioPreset.Kind's range.

material_resolver

var material_resolver: Callable = Callable()

Which material a texture IS: called as resolver(texture_name) and returning a material name in materials, or an empty StringName for a texture it cannot place. The game's question, not Hammerite's. A texture name belongs to geometry; what it MEANS belongs to whoever authored the level, and a game that already decides what a wall is made of - for footsteps, for what an arrow does about it - should decide it once and for acoustics too.

HammeriteAudio.material_resolver = func(texture: String) -> StringName:
return my_surfaces.material_of(texture)

Without one, material_name_for() falls back to reading the material word of <stratum>_<material>_<specifier>. That is a convention, not a law, which is the whole reason this seam exists.

ambient_resolver

var ambient_resolver: Callable = Callable()

What an ambience id sounds like: called as resolver(id) and returning an AudioStream, or null for an id the game has no recording of. The id is the game's vocabulary, so the game answers it. With no resolver an id is taken as a name in sounds, the way an env_sound names its file.

sounds

var sounds: HammeriteAssetLibrary = <unknown>

Where a sound entity's or an emitter's sound_file becomes a recording (#87): a name such as doors/creak.ogg, found in the game's search paths or its own sources.

HammeriteAudio.sounds.search_paths = ["res://sounds"]

Empty until the game gives it a search path or a source: with neither, no sound resolves and every play reports No sound called ....

ambient_bus

var ambient_bus: StringName = &"Master"

The bus a room's ambience plays on. Not the Hammerite Audio bus: a bed is already a recording of a space, and the room's reverb on top of it would be the room twice.

Method descriptions

upgrade_map()

static func upgrade_map(map: HammeriteMap) -> void

Move what a map saved before #249 keeps under this addon's old name to where it is read now: the room properties (acoustic/ to audio/), every variant's graph, and a sound's use_acoustic_propagation. Quietly, and nothing for a map that has none of it. Done as a map is handed to HammeriteAudio.integrate()'s maps and to bake(), before anything reads it.

bake()

static func bake(map: HammeriteMap) -> HammeriteAudioBakeReport

Build map's audio graph from the world it has compiled, store it in the map, and say what the bake made. This is how a graph comes to exist, wherever from: the editor's Audio Portals tool, a headless or CI bake, or a game that bakes as it loads a map that shipped without one. Static, and naming no autoload, so a --script run can call it. The map must have compiled its world - the bake reads the rooms and the openings between them, not the brushwork. Reading them costs a fraction of what putting the map together did: about 154 ms on a 256-room level, against 1.1 s of compile. Baking a map whose worldrep is NOT built yet builds it, which is that whole compile; from a HammeriteMap3D prefer HammeriteAudio.bake(), which waits for the map to be put together first. What the author wrote is kept: an existing graph is built into rather than replaced, so the room presets, the openings' names and their standing occlusion survive a rebake. A map with no graph at all gets one on the default presets.

get_manager()

static func get_manager(context: Node = null) -> HammeriteAudioManager

The manager that applies to context, or null if there is none yet. Resolved by walking up to the HammeriteMap3D the node lives under, since a node inside a map belongs to that map's acoustics. A node outside any map - a player parented to the scene root, which is the normal arrangement - falls back to the only manager there is, and says so rather than guessing when there are several.

register_entity_types()

static func register_entity_types() -> void

Declare env_sound and env_sound_environment, unless something already has: a game that refined one with HammeriteEntityTypeRegistry.extend_point() keeps what it added. From the autoload, so a game knows them before it builds a map, with or without the editor.

add_preset()

static func add_preset(preset: HammeriteAudioPreset) -> void

Add preset to presets, replacing whatever had its id, and declare the brush schema again so the reverb dropdown lists it.

material_name_for()

static func material_name_for(texture_name: String) -> StringName

Which material the texture texture_name is, through material_resolver. Falling back, with no resolver, to the material word of <stratum>_<material>_<specifier> - the second word where there are three or more, the first where there are fewer, compared whole. Whole rather than as a substring because a substring made textile tile and put iron in environment (#241); a fallback that guesses wrong quietly is worse than one that says it does not know.

material_for_texture()

static func material_for_texture(texture_name: String) -> HammeriteAudioMaterial

What the material of texture texture_name does to sound: material_name_for() looked up in materials, or the table's default for a texture nothing places.

ambient_stream()

static func ambient_stream(id: String) -> AudioStream

The recording for ambience id, through ambient_resolver.

class Changes

Where a change of which manager serves a map is announced.

Signals

manager_changed

signal manager_changed(map_3d: HammeriteMap3D)

map_3d has been given a manager, or a new one in place of the last, or has none any more. Every handle the one before gave out is gone.