CorsixTH/CorsixTH — pull request #229 by JASheppard (2014-03-16 23:37:38+00:00)
Title: Implemented Hell Deaths & The Lava Hole's Required Sound Code Changes

This pull request's code was created by me and Luís Duarte.

This pull request implements hell deaths and the sound code changes required for the lava hole's sound effects.

It consists of 5 commits which have been rebased with the latest master branch:
1. Fixed a persistance error in idle_spawn.lua
2. use_object: +destroy_user_after_use +after_walk_in
3. +SDL SOUND_OVER Event & Support In Existing Audio Functions
4. New function: playSoundsAtEntityInRandomSequenceWhileFlagATrue()
5. Implemented Hell Deaths

Most of the changes are in the two sound code changing commits. The third commit which implements a new SDL SOUND_OVER event requires a few source code changes.

Female patients can't have hell deaths because there's no animation for them falling into the lava hole.

Bloaty head patients also can't have hell deaths when they die with bloaty heads because there's no death transformation animation for them.

Missing layers in the male on_ground animation make hats disappear and make white shoes become brown. I have made graphics code changes which fix these minor graphics bugs by removing the need for this animation to be used but I've not included these changes in this pull request because they have persistence problems.

## Commit Messages

### 1. Fixed a persistance error in idle_spawn.lua
The persistable function name comment needed to be on the same line as the word "function".

### 2. use_object: +destroy_user_after_use +after_walk_in
The "destroy_user_after_use" parameter is required by lava holes to prevent patients walking out after they've fallen in.

The "after_walk_in" parameter is required to make the grim reaper respond to the moment when the patient has walked on to the lava hole.

* "destroy_user_after_use" Changes @ 71 and @ 321
* "after_walk_in" Changes @ 282

### 3. +SDL SOUND_OVER Event & Support In Existing Audio Functions
Call stack for SOUND_OVER callbacks:
1. SDL_USEREEVNT_SOUND_OVER ->
2. sdl_core.cpp: l_mainloop() @ 221 ->
3. app.lua:onSoundOver(callback_id)@ 915 ->
4. audio.lua:onSoundPlayed(callback_id)@ 306 ->
5. audio.lua.played_sound_callbacks[callback_id]

#### Change List
##### Source code
1) lua_sdl.h:
* +SDL_USEREEVNT_SOUND_OVER

2) sdl_core.cpp:
* @ 221 +SDL event switch statement case for SOUND_OVER events.

3) th_lua_sound.cpp:
a) @ 29 +SOUND_OVER callback variables.
b) @ 188 +SDL Timer callback function: played_sound_callback()
c) @ 228 *Made l_soundfx_play() support SOUND_OVER callbacks.

##### Lua
4) api_version.lua:
* 2037 -> 2673

5) app.lua:
a) @ 915 +onSoundOver()
b) @ 403 +gameEnded(): Required to call Audio:gameEnded()
c) +Calls to gameEnded() @ 408 @ 436 @ 1,175 @ 1,194

6) audio.lua:
a) @ 37 +SOUND_OVER callback variables.
b) @ 41 +gameEnded(): Required to reset the SOUND_OVER callback variables.
c) @ 306 +onSoundPlayed(): Executes SOUND_OVER callbacks.
d) @ 262 *Made playSound() support SOUND_OVER callbacks.

7) entity.lua:
- @ 41 *Made playSound() support SOUND_OVER callbacks.

8) game_ui.lua:
- @ 539 *Made playAnnouncement() support SOUND_OVER callbacks.

9) ui.lua:
a) @ 267 *Made playSound() support SOUND_OVER callbacks.
b) @ 274 *Made playAnnouncement() support SOUND_OVER callbacks.

### 4. New function: playSoundsAtEntityInRandomSequenceWhileFlagATrue()
This function is required to play the lava hole's sounds because its sounds are meant to be played in a random sequence and are therefore not associated with animation frames, so the animation code can't play these sounds.

I think the durations of the pauses between these sounds should be different and randomly determined because I don't think this sound sequence sounds good otherwise especially when there's multiple lava holes.

#### Change list
1) dialogs/menu.lua: -White space.

2) app.lua:
a) @ 32 *SAVEGAME_VERSION = 82 -> 84: Required in this commit because a new afterLoad() sound playing function has been added. 83 has been used in an open pull request.
b) @ 1229 *Added afterLoad() call to world:playLoadedEntitySounds()

3) audio.lua:
a) -White space.
b) @ 39 +self.entities_waiting_for_sound_to_be_enabled{}: Required to support the resumption of sounds being played by the new play function.
c) @ 319 +playSoundsAtEntityInRandomSequenceWhileFlagATrue()
d) @ 339 +playSoundAtEntityInRandomSequenceRecursionHandler()
e) @ 405 +getRandomSilenceLengths(): Required to randomly the determine the durations of the pauses used by the new play function.
f) @ 264 *Modified playSound(): Moved its sound caching statements into a new function to prevent them from having to be duplicated in the new play function.
g) @ 399 +canSoundsBePlayed(): Required to support the resumption of sounds being played by the new play function.
h) @ 421 +onGamePausedStateChanged(paused): Required to support the resumption of sounds being played by the new play function.
i) @ 654 +tellInterestedEntitiesTheyCanNowPlaySounds(): Required to support the resumption of sounds being played by the new play function.
j) +calls to tellInterestedEntitiesTheyCanNowPlaySounds()@ 423
@ 650
k) @ 663 +entityNoLongerWaitingForSoundsToBeTurnedOn(entity): Required to prevent the resumption of sounds being played for an entity which no longer exists or no longer wants its sounds to be resumed.

4) entity.lua:
a) @ 26 +Instance variables for the new play function.
b) @ 75 +playSoundsAtEntityInRandomSequenceWhileFlagATrue()
c) @ 314 +playAfterLoadSound(): Required to support the resumption of sounds being played by the new play function.
d) @ 50 +setFlagA(state)
e) @ 57 +setWaitingForSoundEffectsToBeTurnedOn(state): Required to prevent the resumption of sounds being played for an entity which was playing sounds with the new play function.

5) game_ui.lua:
* @ 720 *modified togglePlaySounds(): So that the keyboard shortcut will have the same response as clicking the menu option, allowing it to disable and enable sounds being played by the new play function.

6) world.lua:
a) @ 966 +Call to audio:onGamePausedStateChanged(): Required to support the resumption of sounds being played by the new play function.
b) @ 971 +isPaused(): Required to support the resumption of sounds being played by the new play function.
c) @ 2326 *modified afterLoad(): Required to support the resumption of sounds being played by the new play function.
d) @ 2332 +playLoadedEntitySounds(): Required to support the resumption of sounds being played by the new play function.

### 5.Implemented Hell Deaths
#### Change list
1) New files:
a) /objects/gates_to_hell.lua
b) /entities/grimreaper.lua

2) app.lua:
* @ 1259 *Modified afterLoad(): So that gates_to_hell objects will be added to the objects lists in worlds from old saved games.

3) die.lua:
a) @ 294 *Modified action_die_start(): So that males can either go to heaven or hell. Heaven deaths are less likely because females can only have them and hell deaths won't happen unless there's enough space.
b) @ 63 +action_die_tick_reaper: Makes hell deaths happen.

4) humanoid.lua:
a) +rise_hell patient animation. @ 58 @ 132
b) @ 499 *Modified Humanoid_startAction(): So that grim reapers with no actions will have the idle action be their default action.

5) patient.lua:
* @ 938 *Modified afterLoad(): So that patients from saved games older than 84 will be given the new rise_hell animation.

6) world.lua:
a) @ 175 +newObjectType(): I've created this function so that app.lua can use it to add the new gates_to_hell objects to worlds from saved games older than 84.
b) @ 538 +checkHellDeathSpawnPoints(): Returns true if there's enough space for a hell death to take place using the spawn points provided as parameters.
c) @ 551 +lavaHoleUseTileUsable():I put this algorithm into its own function to prevent it from having to be duplicated in checkHellDeathSpawnPoints().
d) @ 570 +spawnGrimReaperAndLavaHole()
e) @ 1963 *modified objectPlaced(): I added statements which are required to respond to the spawning of lava holes (gates_to_hell objects).