1# Soundpacks 2 3A soundpack can be installed in the `data/sound` directory. It has to be a subdirectory that contains at least a file named `soundpack.txt`. It can include any number of json files which add any number of `sound_effect` or playlists. 4 5## soundpack.txt format 6 7The `soundpack.txt` file format needs 2 values, a NAME and a VIEW. The NAME value should be unique. The VIEW value will be shown in the options menu. Every line starting with a `#` is a comment line. 8 9``` 10#Basic provided soundpack 11#Name of the soundpack 12NAME: basic 13#Viewing name of the soundpack 14VIEW: Basic 15``` 16 17## JSON format 18 19### Sound effects 20 21Sound effects can be included with a format like this: 22 23```javascript 24[ 25 { 26 "type": "sound_effect", 27 "id": "menu_move", 28 "volume": 100, 29 "files": [ "nenadsimic_menu_selection_click.wav" ] 30 }, 31 { 32 "type": "sound_effect", 33 "id": "fire_gun", 34 "volume": 90, 35 "variant": "bio_laser_gun", 36 "files": [ "guns/energy_generic/weapon_fire_laser.ogg" ] 37 } 38] 39``` 40 41Adding variety: If for a certain `id`'s `variant` multiple `files` are defined, they will be chosen at random when `variant` is played. 42 43The volume key may range from 0-100. 44 45Cataclysm has its own set of user-controllable volumes that will additionally affect the sound. These range from 0-128, and the default is 100. This means that at default volume, any sound that Cataclysm plays will default to playing at about 78% of the maximum; if you are working on sounds in an external audio editor, expect Cataclysm at default volume settings to play that sound file back quieter than your editor does. 46 47### Preloading SFX 48 49Sound effects can be included for preloading with a format like this: 50 51```javascript 52[ 53 { 54 "type": "sound_effect_preload", 55 "preload": [ { "id": "environment", "variant": "daytime" }, { "id": "environment" } ] 56 } 57] 58``` 59 60### Playlist 61 62A playlist can be included with a format like this: 63 64```javascript 65[ 66 { 67 "type": "playlist", 68 "playlists": [ 69 { 70 "id": "title", 71 "shuffle": false, 72 "files": [ { "file": "Dark_Days_Ahead_demo_2.wav", "volume": 100 }, { "file": "cataclysmthemeREV6.wav", "volume": 90 } ] 73 } 74 ] 75 } 76] 77``` 78 79Each sound effect is identified by an id and a variant. If a sound effect is played with a variant that does not exist in the json files, but a variant "default" exists, then the "default" variant is played instead. The file name of the sound effect is relative to the soundpack directory, so if the file name is set to "sfx.wav" and your soundpack is in `data/sound/mypack`, the file must be placed at `data/sound/mypack/sfx.wav`. 80 81## JSON Format Sound Effects List 82 83A full list of sound effect IDs and variants is given in the following. Each line in the list has the following format: 84 85`id variant1|variant2` 86 87Where `id` describes the ID of the sound effect, and a list of variants separated by | follows. When the variants are omitted, the variant "default" is assumed. Where the variants do not represent literal strings, but variables, they will be enclosed in `<` `>`. For instance, `<furniture>` is a placeholder for any valid furniture ID (as in the furniture definition JSON). 88 89### Open/close doors 90 91* `open_door default|<furniture>|<terrain>` 92* `close_door default|<furniture>|<terrain>` 93 94### Smashing attempts and results 95 96Includes special ones that are furniture/terrain specific. 97 98* `bash default` 99* `smash wall|door|door_boarded|glass|swing|web|paper_torn|metal` 100* `smash_success hit_vehicle|smash_glass_contents|smash_cloth|<furniture>|<terrain>` 101* `smash_fail default|<furniture>|<terrain>` 102 103### Melee 104 105* `melee_swing default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing` 106* `melee_hit_flesh default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing|<weapon>` 107* `melee_hit_metal default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing!<weapon>` 108* `melee_hit <weapon>` # note: use weapon id "null" for unarmed attacks 109 110### Firearm/ranged weapon 111 112* `fire_gun <weapon>|brass_eject|empty` 113* `fire_gun_distant <weapon>` 114* `reload <weapon>` 115* `bullet_hit hit_flesh|hit_wall|hit_metal|hit_glass|hit_water` 116 117### Environmental SFX 118 119Divided by sections for clarity. 120 121* `environment thunder_near|thunder_far` 122* `environment daytime|nighttime` 123* `environment indoors|indoors_rain|underground` 124* `environment <weather_type>` # examples: `WEATHER_DRIZZLE|WEATHER_RAINY|WEATHER_THUNDER|WEATHER_FLURRIES|WEATHER_SNOW|WEATHER_SNOWSTORM` 125* `environment alarm|church_bells|police_siren` 126* `environment deafness_shock|deafness_tone_start|deafness_tone_light|deafness_tone_medium|deafness_tone_heavy` 127 128### Misc environmental sounds 129 130* `footstep default|light|clumsy|bionic` 131* `explosion default|small|huge` 132 133### Ambient danger theme 134 135Triggered by seeing large numbers of zombies. 136 137* `danger_low` 138* `danger_medium` 139* `danger_high` 140* `danger_extreme` 141 142### Chainsaw pack 143 144* `chainsaw_cord chainsaw_on` 145* `chainsaw_start chainsaw_on` 146* `chainsaw_start chainsaw_on` 147* `chainsaw_stop chainsaw_on` 148* `chainsaw_idle chainsaw_on` 149* `melee_swing_start chainsaw_on` 150* `melee_swing_end chainsaw_on` 151* `melee_swing chainsaw_on` 152* `melee_hit_flesh chainsaw_on` 153* `melee_hit_metal chainsaw_on` 154* `weapon_theme chainsaw` 155 156### Monster death and bite attacks 157 158* `mon_death zombie_death|zombie_gibbed` 159* `mon_bite bite_miss|bite_hit` 160* `melee_attack monster_melee_hit` 161* `player_laugh laugh_f|laugh_m` 162 163### Player movement sfx 164 165Important: `plmove <terrain>` has priority over default `plmove|walk_<what>` (excluding `|barefoot`). 166 167Example: if `plmove|t_grass_long` is defined it will be played before default `plmove|walk_grass` default for all grassy terrains. 168 169* `plmove <terrain>|<vehicle_part>` 170* `plmove walk_grass|walk_dirt|walk_metal|walk_water|walk_tarmac|walk_barefoot|clear_obstacle` 171 172### Fatigue 173 174* `plmove fatigue_m_low|fatigue_m_med|fatigue_m_high|fatigue_f_low|fatigue_f_med|fatigue_f_high` 175 176### Player hurt 177 178* `deal_damage hurt_f|hurt_m` 179 180### Player death and end-game 181 182* `clean_up_at_end game_over|death_m|death_f` 183 184### Various bionics 185 186* `bionic elec_discharge|elec_crackle_low|elec_crackle_med|elec_crackle_high|elec_blast|elec_blast_muffled|acid_discharge|pixelated` 187* `bionic bio_resonator|bio_hydraulics|` 188 189### Various tools/traps being used 190 191Includes some associated terrain/furniture. 192 193* `tool alarm_clock|jackhammer|pickaxe|oxytorch|hacksaw|axe|shovel|crowbar|boltcutters|compactor|gaspump|noise_emitter|repair_kit|camera_shutter|handcuffs` 194* `tool geiger_low|geiger_medium|geiger_high` 195* `trap bubble_wrap|bear_trap|snare|teleport|dissector|glass_caltrop|glass` 196 197### Various activities 198 199* `activity burrow` 200 201### Musical instruments 202 203* `musical_instrument <instrument>` 204* `musical_instrument_bad <instrument>`: used when you fail to play well 205 206### Various shouts and screams 207 208* `shout default|scream|scream_tortured|roar|squeak|shriek|wail|howl` 209 210### Speech 211 212This is currently linked with either item or monster id, with the exception of NPCs and robots. 213 214TODO: full vocalization of speech.json 215 216* `speech <item_id>` # examples: `talking_doll`, `creepy_doll`, `granade` (sic), 217* `speech <monster_id>` # examples: eyebot, minitank, mi-go, many robots 218* `speech NPC_m|NPC_f|NPC_m_loud|NPC_f_loud` # special for NPCs 219* `speech robot` # special for robotic voice from a machine etc. 220 221### Radio chatter 222 223* `radio static|inaudible_chatter` 224 225### Humming sounds of various origins 226 227* `humming electric|machinery` 228 229### Fire 230 231* `fire ignition` 232 233### Vehicle 234 235Engines and other parts in action. The defaults are executed when a specific option is not defined. 236 237* `engine_start <vehicle_part>`: specific engine start (ID of any `engine`/`motor`/`steam_engine`/`paddle`/`oar`/`sail`/etc.) 238* `engine_start combustion|electric|muscle|wind`: default engine starts groups 239* `engine_stop <vehicle_part>`: specific engine stop (ID of any `engine`/`motor`/`steam_engine`/`paddle`/`oar`/`sail`/etc.) 240* `engine_stop combustion|electric|muscle|wind`: default engine stop groups 241 242 Internal engine sound is dynamically pitch shifted depending on vehicle speed. It is an ambient looped sound with a dedicated channel. 243* `engine_working_internal <vehicle_part>`: sound of engine working heard inside vehicle 244* `engine_working_internal combustion|electric|muscle|wind`: default engine working (inside) groups 245 246 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 its own dedicated channel. This is a single-channel solution that picks loudest heard vehicle (TODO: multi-channel for every heard vehicle). There is no pitch shift here (may be introduced when need for it emerges). 247* `engine_working_external <vehicle_part>`: sound of engine working heard outside vehicle 248* `engine_working_external combustion|electric|muscle|wind`: default engine working (outside) groups 249 250 `gear_up`/`gear_down` is done automatically by pitch manipulation. Gear shift is dependent on max safe speed, and works on the assumption that there are 6 forward gears, gear 0 is neutral, and gear -1 is reverse. 251* `vehicle gear_shift` 252* `vehicle engine_backfire|engine_bangs_start|fault_immobiliser_beep|engine_single_click_fail|engine_multi_click_fail|engine_stutter_fail|engine_clanking_fail` 253* `vehicle horn_loud|horn_medium|horn_low|rear_beeper|chimes|car_alarm` 254* `vehicle reaper|scoop|scoop_thump` 255* `vehicle_open <vehicle_part>` # id of: doors, trunks, hatches, etc. 256* `vehicle_close <vehicle part>` 257 258### Miscellaneous 259 260* `misc flashbang|flash|shockwave|earthquake|stairs_movement|stones_grinding|bomb_ticking|lit_fuse|cow_bell|bell|timber` 261* `misc rc_car_hits_obstacle|rc_car_drives` 262* `misc default|whistle|airhorn|horn_bicycle|servomotor` 263* `misc beep|ding|` 264* `misc rattling|spitting|coughing|heartbeat|puff|inhale|exhale|insect_wings|snake_hiss` # mostly organic noises 265