Enable sound hooks for soundpack builders

[nexusmrsep]

Summary

SUMMARY: Infrastructure "Enable sound hooks for soundpack builders"

Purpose of change

Let me start from a statement: Sounds and music are very important for every game, as they bring in the vibe, the atmosphere, and provide better immersion if correctly applied.

Idea for this PR emerged in my conversation with @ralreegorganon.
We discussed sound packs, and realized that not many sounds::sound triggers were actually defined with actual hooks for physical sfx triggers. A brief investigation showed that there was no reason that it should be like that, and initial base infrastructure was already in sounds::sound, just rarely used.

I also noticed that SOUNDPACKS.md documentation file was fairly outdated and missing a ton of existing hooks, not to mention hooks that should be there.
Creating soundset.json - a vital file for sound packs, where sfx are linked to sound files - is a lot harder for sound developers without having all the hooks listed properly in one place.

I aimed to change that in this PR, in hope for better sound pack to emerge.
Kudos to all who work on them anyway.

Describe the solution

• enable as much sfx hooks for the developers on exisitng sounds::sound triggers as possible
• update documentation to list all the triggers (sfx types and variants)
• fix problems with non-standard sound effects,
• check if some often-executed hooks won't stack to deafen the player // use optional sfx generation

All in all, this will allow a huge number of sounds to be played.
It would be futile to list them here, but check out the updated SOUNDPACKS.md to see the full list.

Describe alternatives you've considered

Vocalizing every speech in the game. Nah, that's far future.

Additional context

N/A

[nexusmrsep]

Added new approach for activity sounds - needed something to get sound effects out of the loop of do_turn that automatically takes into account variable action's time, and fades out at action's end.

As a result I created sfx::play_activity_sound() and sfx::end_activity_sounds(). First one plays sfx at a dedicated channel and controls if the activity still lasts to avoid loop/replay and the latter fades out the sfx and clears the activity check. Also added misc|timber sound hook for falling trees.

Tested with hooks: tool|axe and misc|timber, with real sfx plugged in, and I must say, cutting trees was never so much fun. Could cut the whole forest just for the sound of an axe chopping and trees falling. Honey for my ears.

[nexusmrsep]

Another BIG change for this PR:

Problem:
Generic clear_obstacle sound is used too often when moving through grass and other slowing down terrain. Too generic, too obnoxious in long run.

Solution:
Default obstacle sound and default/generic movement_on_terrain_group sounds can now be overridden by terrain specific sounds defined in the soundset.
In other words (exempt from updated documentation):

# player movement sfx
important: `plmove <terrain>` has priority over default `plmove|walk_<what>` (excluding `|barefoot`)
example: if `plmove|t_grass_long` is defined it will be played before default `plmove|walk_grass` default for all grassy terrains

plmove <terrain>|<vehicle_part>
plmove walk_grass|walk_dirt|walk_metal|walk_water|walk_tarmac|walk_barefoot|clear_obstacle

What does that mean realy?
It means that you will be able to set sounds for moving on t_grass, t_grass_long, t_grass_tall, t_shrub
etc. to avoid obnoxious repetitions of rustling sound used for generic clear_obstacle sound.

[nexusmrsep]

Next thing I'm working on is preparing the game's sound engine to work properly with vehicles.
My aim is to do what VULKAN managed to do back in the day (at least part of it), but it never went in into vanilla.

In the Part 1 I enabled, previously non-existent:

• engine_start, engine_stop sfx hook support, engine_working still has to be reworked to be an ambient sound with adjustable volume to work as intended, but its enabled for now as a dummy sfx
• vehicle_open <vehicle_part> and vehicle_close <vehicle_part> sfx hooks - you can define sounds for opening, closing doors, trunks, hatches and other openable parts

And also I adjusted the sound volume of engine starting failures, so the volume is now dependent on engine noise factor.

[nexusmrsep]

I've added extended support for vehicle sfx:

    # vehicle sounds - engine and other parts in action
    # note: defaults are executed when specific option is not defined
* `engine_start <vehicle_part>` # note: specific engine start (id of any engine/motor/steam_engine/paddle/oar/sail/etc. )
* `engine_start combustion|electric|muscle|wind` # default engine starts groups
* `engine_stop <vehicle_part>` # note: specific engine stop (id of any engine/motor/steam_engine/paddle/oar/sail/etc. )
* `engine_stop combustion|electric|muscle|wind` # default engine stop groups

    # note: internal engine sound is dynamically pitch shifted depending on vehicle speed
    # it is an ambient looped sound with dedicated channel
* `engine_working_internal <vehicle_part>` # note: sound of engine working heard inside vehicle
* `engine_working_internal combustion|electric|muscle|wind` # default engine working (inside) groups

    # note: external engine sound volume and pan is dynamically shifted depending on distance and angle to vehicle
    # volume heard at given distance is linked to engine's `noise_factor` and stress to the engine (see `vehicle::noise_and_smoke()` )
    # it is an ambient looped sound with dedicated channel
    # this is a single-channel solution (TODO: multi-channel for every heard vehicle); it picks loudest heard vehicle
    # there is no pitch shift here (may be introduced when need for it emerges)
* `engine_working_external <vehicle_part>` # note: sound of engine working heard outside vehicle
* `engine_working_external combustion|electric|muscle|wind` # default engine working (outside) groups

    # note: gear_up/gear_down is done automatically by pitch manipulation
    # gear shift is dependant on max safe speed, and works in assumption, that there are
    # 6 forward gears, gear 0 = neutral, and gear -1 = reverse
* `vehicle gear_shift`

To sum it up:

• you can set both internal and external engine noise that will be varied by in-game mechanics
• you can set gear shift sound, modulated in-game
• you can set engine start/stop sounds for each engine type

This concludes this PR.
Possible TODO paths from this point:

• multi-channel support for external engine sfx, so you can hear multiple working vehicles simultaneously - I haven't done it from the start, because SDL_mixer is not the best tool to work with, and does not provide ways to reserve and manage specific channels on the go. No wonder Vulcan went for Audiere in the first place.
• music for cars/mp3/etc.
• adding hooked sound events for other possible actions/events in game that have not been initially equipped with any

[nexusmrsep]

Full list of SFX events/hooks as of now:

    ## open/close doors
* `open_door default|<furniture>|<terrain>`
* `close_door default|<furniture>|<terrain>`

    # smashing attempts and results, few special ones and furniture/terrain specific
* `bash default`
* `smash wall|door|door_boarded|glass|swing|web|paper_torn|metal`
* `smash_success hit_vehicle|smash_glass_contents|smash_cloth|<furniture>|<terrain>`
* `smash_fail default|<furniture>|<terrain>`

    # melee sounds
* `melee_swing default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing`
* `melee_hit_flesh default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing|<weapon>`
* `melee_hit_metal default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing!<weapon>`
* `melee_hit <weapon>` # note: use weapon id "null" for unarmed attacks

    # firearm/ranged weapon sounds
* `fire_gun <weapon>|brass_eject|empty`
* `fire_gun_distant <weapon>`
* `reload <weapon>`
* `bullet_hit hit_flesh|hit_wall|hit_metal|hit_glass|hit_water`

    # enviromental sfx, here divided by sections for clarity
* `environment thunder_near|thunder_far`
* `environment daytime|nighttime`
* `environment indoors|indoors_rain|underground`
* `environment <weather_type>` # examples: `WEATHER_DRIZZLE|WEATHER_RAINY|WEATHER_THUNDER|WEATHER_FLURRIES|WEATHER_SNOW|WEATHER_SNOWSTORM`
* `environment alarm|church_bells|police_siren`
* `environment deafness_shock|deafness_tone_start|deafness_tone_light|deafness_tone_medium|deafness_tone_heavy`

    # misc environmental sounds
* `footstep default|light|clumsy|bionic`
* `explosion default|small|huge`

    # ambient danger theme for seeing large numbers of zombies
* `danger_low`
* `danger_medium`
* `danger_high`
* `danger_extreme`

    # chainsaw pack
* `chainsaw_cord     chainsaw_on`
* `chainsaw_start    chainsaw_on`
* `chainsaw_start    chainsaw_on`
* `chainsaw_stop     chainsaw_on`
* `chainsaw_idle     chainsaw_on`
* `melee_swing_start chainsaw_on`
* `melee_swing_end   chainsaw_on`
* `melee_swing       chainsaw_on`
* `melee_hit_flesh   chainsaw_on`
* `melee_hit_metal   chainsaw_on`
* `weapon_theme      chainsaw`

    # monster death and bite attacks
* `mon_death zombie_death|zombie_gibbed`
* `mon_bite bite_miss|bite_hit`

* `melee_attack monster_melee_hit`

* `player_laugh laugh_f|laugh_m`

    # player movement sfx
    important: `plmove <terrain>` has priority over default `plmove|walk_<what>` (excluding `|barefoot`)
    example: if `plmove|t_grass_long` is defined it will be played before default `plmove|walk_grass` default for all grassy terrains

* `plmove <terrain>|<vehicle_part>`
* `plmove walk_grass|walk_dirt|walk_metal|walk_water|walk_tarmac|walk_barefoot|clear_obstacle`

    # fatigue
* `plmove fatigue_m_low|fatigue_m_med|fatigue_m_high|fatigue_f_low|fatigue_f_med|fatigue_f_high`

    # player hurt sounds
* `deal_damage hurt_f|hurt_m`

    # player death and end-game sounds
* `clean_up_at_end game_over|death_m|death_f`

    # variuos bionic sounds
* `bionic elec_discharge|elec_crackle_low|elec_crackle_med|elec_crackle_high|elec_blast|elec_blast_muffled|acid_discharge|pixelated`
* `bionic bio_resonator|bio_hydraulics|`

    # various tools/traps being used (including some associated terrain/furniture)
* `tool alarm_clock|jackhammer|pickaxe|oxytorch|hacksaw|axe|shovel|crowbar|boltcutters|compactor|gaspump|noise_emitter|repair_kit|camera_shutter|handcuffs`
* `tool geiger_low|geiger_medium|geiger_high`
* `trap bubble_wrap|bear_trap|snare|teleport|dissector`

    # various activities
* `activity burrow`

    # musical instruments, `_bad` is used when you fail to play it well
* `musical_instrument <instrument>`
* `musical_instrument_bad <instrument>`

    # various shouts and screams
* `shout default|scream|scream_tortured|roar|squeak|shriek|wail|howl`

    # speach, it is currently linked with either item or monster id, or is special `NPC` or `NPC_loud`
    # TODO: full vocalization of speech.json
* `speech <item_id>` # examples: talking_doll, creepy_doll, Granade, 
* `speech <monster_id>` # examples: eyebot, minitank, mi-go, many robots
* `speech NPC_m|NPC_f|NPC_m_loud|NPC_f_loud` # special for NPCs
* `speech robot` # special for robotic voice from a machine etc.

    # radio chatter
* `radio static|inaudible_chatter`

    # humming sounds of various origin
* `humming electric|machinery`

    # sounds related to (burning) fire
* `fire ignition`

    # vehicle sounds - engine and other parts in action
    # note: defaults are executed when specific option is not defined
* `engine_start <vehicle_part>` # note: specific engine start (id of any engine/motor/steam_engine/paddle/oar/sail/etc. )
* `engine_start combustion|electric|muscle|wind` # default engine starts groups
* `engine_stop <vehicle_part>` # note: specific engine stop (id of any engine/motor/steam_engine/paddle/oar/sail/etc. )
* `engine_stop combustion|electric|muscle|wind` # default engine stop groups

    # note: internal engine sound is dynamically pitch shifted depending on vehicle speed
    # it is an ambient looped sound with dedicated channel
* `engine_working_internal <vehicle_part>` # note: sound of engine working heard inside vehicle
* `engine_working_internal combustion|electric|muscle|wind` # default engine working (inside) groups

    # note: external engine sound volume and pan is dynamically shifted depending on distance and angle to vehicle
    # volume heard at given distance is linked to engine's `noise_factor` and stress to the engine (see `vehicle::noise_and_smoke()` )
    # it is an ambient looped sound with dedicated channel
    # this is a single-channel solution (TODO: multi-channel for every heard vehicle); it picks loudest heard vehicle
    # there is no pitch shift here (may be introduced when need for it emerges)
* `engine_working_external <vehicle_part>` # note: sound of engine working heard outside vehicle
* `engine_working_external combustion|electric|muscle|wind` # default engine working (outside) groups

    # note: gear_up/gear_down is done automatically by pitch manipulation
    # gear shift is dependant on max safe speed, and works in assumption, that there are
    # 6 forward gears, gear 0 = neutral, and gear -1 = reverse
* `vehicle gear_shift`


* `vehicle engine_backfire|engine_bangs_start|fault_immobiliser_beep|engine_single_click_fail|engine_multi_click_fail|engine_stutter_fail|engine_clanking_fail`
* `vehicle horn_loud|horn_medium|horn_low|rear_beeper|chimes|car_alarm`
* `vehicle reaper|scoop|scoop_thump`


* `vehicle_open <vehicle_part>` # note: id of: doors, trunks, hatches, etc.
* `vehicle_close <vehicle part>`

    # miscellaneous sounds
* `misc flashbang|flash|shockwave|earthquake|stairs_movement|stones_grinding|bomb_ticking|lit_fuse|cow_bell|bell|timber`
* `misc rc_car_hits_obstacle|rc_car_drives`
* `misc default|whistle|airhorn|horn_bicycle|servomotor`
* `misc beep|ding|`
* `misc rattling|spitting|coughing|heartbeat|puff|inhale|exhale|insect_wings|snake_hiss` # mostly organic noises

[kevingranade]

This pull request has been mentioned on Cataclysm: Dark Days Ahead. There might be relevant details there:

https://discourse.cataclysmdda.org/t/announcing-incoming-new-features-for-sound-pack-developers/19975/1

[nexusmrsep]

Jenkins failed to AStyle check, and either of my local 3.1 and 3.0.1 AStyle version could not find anything to astyle in game.cpp. Travis failed due to test fail in vehicles (irrelevant to this PR).

[AdonaiJr]

Thank you so much for pushing it a bit further! My dream is seeing those Vulkan audio video on youtube happen once again!