Title screen: ShowGameOverScreen

       Name: ShowGameOverScreen                                      [Show more]
       Type: Subroutine
   Category: Title screen
    Summary: Display the game over screen
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * MainGameLoop calls ShowGameOverScreen
             * ProcessGameplay calls ShowGameOverScreen


 Arguments:

   A                    The number of 2400-dot plotting cycles to perform when
                        decaying the screen from the landscape view to the game
                        over screen

                          * 5 = 12,000 dots for when the player runs out of
                                energy when trying to hyperspace

                          * 30 = 72,000 dots for when the player is absorbed by
                                 the Sentinel

   titleObjectToDraw    The type of object that caused the player's demise (be
                        it the Sentinel, a sentry, a meanie or the player
                        themselves)


.ShowGameOverScreen

 PHA                    \ Store the argument in A on the stack, so we can fetch
                        \ it later

 JSR FlushSoundBuffers  \ Flush all four sound channel buffers

 JSR ClearIconsScanner  \ Clear the energy icon and scanner row at the top of
                        \ the screen

 LDA #6                 \ Set soundEffect = 6 so the sound is processed as the
 STA soundEffect        \ game over sound

 LDA #250               \ Set gameOverSoundPitch = 250 to start the sound effect
 STA gameOverSoundPitch \ processing for the game over sound

 PLA                    \ Retrieve the argument A from the stack, so it contains
                        \ the number of black dots to draw on the screen

 JSR DecayScreenToBlack \ Decay the screen to black with a mass of A * 2400
                        \ randomly placed black dots

 LDY #0                 \ Set sightsByteCount to zero to reset the sights pixel
 STY sightsByteCount    \ byte stash

 STY sightsAreVisible   \ Clear bit 7 of sightsAreVisible to indicate that the
                        \ sights are not visible

 LDA titleObjectToDraw  \ Call SpawnTitleObject to spawn an object of type
 JSR SpawnTitleObject   \ titleObjectToDraw as object #1, using the
                        \ configuration specified in Y (i.e. 0), so the object
                        \ is spawned for use in the game over screen
                        \
                        \ By the time the game ends, titleObjectToDraw has been
                        \ set to the type of object that caused the player's
                        \ demise (be it the Sentinel, a sentry, a meanie or the
                        \ player themselves), so this call spawns that object
                        \ as object #1

 LDA #3                 \ Set screenBackground = 3 so the next time the screen
 STA screenBackground   \ is cleared, it shows a black background with stars

 LDA #1                 \ Set currentObject = 1 so the call to DrawUpdatedObject
 STA currentObject      \ draws object #1

 LDA #%11000000         \ Set bit 7 of drawLandscape so the interrupt handler
 STA drawLandscape      \ draws random black dots on the screen, so we combine
                        \ dithering of object #1 to the screen while at the same
                        \ time fading the screen to black, to create the
                        \ hypnotic effect of the winning entity fading in and
                        \ out of the screen as the game ends

 STA ditherObjectSights \ Set bits 6 and 7 of ditherObjectSights so the call to
                        \ DrawUpdatedObject removes the sights from the screen
                        \ and dithers object #1 onto the screen

 LSR doNotDitherObject  \ Clear bit 7 of doNotDitherObject to enable objects to
                        \ be updated on the screen with a dithered effect

 LDA #50                \ Call the PlayMusic routine with A = 50 to play the
 JSR PlayMusic          \ game over music

 JSR DrawUpdatedObject  \ Draw the current object (or the landscape where the
                        \ object used to be) into the screen buffer and dither
                        \ it onto the screen, pixel by pixel and randomly

 LDA #30                \ Smother the screen in 30 * 2400 = 72,000 randomly
 JMP DecayScreenToBlack \ placed black dots to decay the screen to black,
                        \ returning from the subroutine using a tail call