Gameplay: PerformHyperspace

       Name: PerformHyperspace                                       [Show more]
       Type: Subroutine
   Category: Gameplay
    Summary: Hyperspace the player to a brand new tile, ideally at the same
             altitude as the current tile
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * ApplyTactics (Part 2 of 8) calls PerformHyperspace
             * ProcessActionKeys (Part 1 of 2) calls PerformHyperspace


 Returns:

   C flag               Returns:

                          * Clear if the hyperspace was a success, or if the
                            player didn't have enough energy to hyperspace

                          * Set if we could not spawn a robot to use as the
                            destination for the hyperspace


.PerformHyperspace

 LDA #0                 \ Spawn a robot (an object of type 0), returning the
 JSR SpawnObject        \ object number of the new object in X and currentObject

 LDX playerObject       \ Set A to the high byte of the altitude of the player
 LDA yObjectHi,X        \ object (i.e. the high byte of the player object's
                        \ y-coordinate in yObjectHi)

 CLC                    \ Increment A so it's one coordinate higher than the
 ADC #1                 \ player object, so the call to PlaceObjectBelow will
                        \ try to hyperspace the player to the same height as
                        \ before

 LDX currentObject      \ Set X to the object number of the new robot that we
                        \ spawned above

 JSR PlaceObjectBelow   \ Attempt to place the new robot on a tile that is below
                        \ the maximum altitude specified in A (though we may end
                        \ up placing the object higher than this)

 BCS hypr4              \ If the call to PlaceObjectBelow sets the C flag then
                        \ the object has not been successfully placed, so jump
                        \ to hypr4 to return from the subroutine with the C flag
                        \ set to indicate that we haven't managed to hyperspace
                        \ the player

 SEC                    \ Call UpdatePlayerEnergy with the C flag set to
 JSR UpdatePlayerEnergy \ subtract the amount of energy in object #X from the
                        \ player's energy
                        \
                        \ Object #X is the robot we just spawned, so this will
                        \ subtract three energy units from the player

 BCC hypr1              \ If the player still has positive energy then the call
                        \ to UpdatePlayerEnergy will clear the C flag, so jump
                        \ to hypr1 to keep going

                        \ If we get here then the player doesn't have enough
                        \ energy to create a robot for hyperspacing

 JSR DeleteObject       \ Delete object #X and remove it from the landscape, so
                        \ we remove the robot that we just spawned

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

 LDA #%10000000         \ Set bit 7 of hyperspaceEndsGame to indicate that the
 STA hyperspaceEndsGame \ game has ended with a hyperspace, and clear bit 6 to
                        \ indicate that the game has ended because the player
                        \ has run out of energy

 BNE hypr3              \ Jump to hypr3 to return from the subroutine (this BNE
                        \ is effectively a JMP as A is never zero)

.hypr1

 LDA #0                 \ Call the PlayMusic routine with A = 0 to play the
 JSR PlayMusic          \ hyperspace music

 LDX playerObject       \ If the player is not on the Sentinel's tile in terms
 LDA xObject,X          \ of the x-coordinate, jump to hypr2
 CMP xTileSentinel
 BNE hypr2

 LDA zObject,X          \ If the player is not on the Sentinel's tile in terms
 CMP zTileSentinel      \ of the z-coordinate, jump to hypr2
 BNE hypr2

                        \ The player is on the Sentinel's tile in both axes, so
                        \ they must have hyperspaced while standing on top of
                        \ the Sentinel's tower, so they have just completed this
                        \ landscape

 LDA #%11000000         \ Set bit 7 of hyperspaceEndsGame to indicate that the
 STA hyperspaceEndsGame \ game has ended with a hyperspace, and set bit 6 to
                        \ indicate that the game has ended because the player
                        \ has won by hyperspacing from the Sentinel's tower

 LDA #%10000000         \ Set bit 7 of doNotPlayLandscape so that when we finish
 STA doNotPlayLandscape \ the landscape, the landscape generation process will
                        \ return normally, without previewing the landscape
                        \
                        \ As the last step in winning a game is to hyperspace
                        \ onto the Sentinel's tower, this ensures that winning a
                        \ level will then display that landscape's secret code
                        \ rather than displaying the preview and making us play
                        \ it again

.hypr2

 JSR FocusOnKeyAction   \ Tell the game to start focusing effort on the key
                        \ action that has been initiated (i.e. the hyperspace)

 LDX currentObject      \ Set the player's object number to that of the new
 STX playerObject       \ robot that we spawned above, so this effectively
                        \ performs the hyperspace into the new robot

.hypr3

 LDA #%10000000         \ Set bit 7 of playerHasMovedTile to indicate that the
 STA playerHasMovedTile \ player has moved to a new tile

 CLC                    \ Clear the C flag to indicate that we have successfully
                        \ hyperspaced the player

.hypr4

 RTS                    \ Return from the subroutine