Gameplay: UpdatePlayerEnergy

       Name: UpdatePlayerEnergy                                      [Show more]
       Type: Subroutine
   Category: Gameplay
    Summary: Update the player's energy levels by adding or subtracting the
             amount of energy in a specific object
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * PerformHyperspace calls UpdatePlayerEnergy
             * ProcessActionKeys (Part 2 of 2) calls UpdatePlayerEnergy


 Arguments:

   X                    The number of the object whose energy is being added to
                        or subtracted from the player's energy

   C flag               Controls whether we add or subtract the energy:

                          * Clear = add object #X's energy to the player's
                                    energy

                          * Set = Subtract object #X's energy from the player's
                                  energy


 Returns:

   C flag               Result flag:

                          * Clear if the player still has a positive energy
                            level after the update

                          * Set if the player now has a negative energy level,
                            which means the Sentinel has won


.UpdatePlayerEnergy

 LDY objectTypes,X      \ Set Y to the object type of object #X

 LDA playerEnergy       \ Set A to the player's current energy level

 BCC uple1              \ If the C flag argument is clear, jump to uple1 to add
                        \ the energies

                        \ Otherwise the C flag argument is set, so we subtract
                        \ object #X's energy from the player's energy in A

 SBC objectTypeEnergy,Y \ The objectTypeEnergy table contains the energy levels
                        \ for each of the object types, so this subtracts the
                        \ energy of object #X from the player's energy in A
                        \
                        \ The subtraction works because we know the C flag is
                        \ set, as we just passed through a BCC

 BCS uple2              \ If the subtraction didn't underflow then the player
                        \ still has some energy left, so jump to uple2 to return
                        \ from the subroutine with the C flag clear

 SEC                    \ The player now has negative energy, so return from the
                        \ subroutine with the C flag set to indicate this

 RTS                    \ Return from the subroutine

.uple1

                        \ If we get here then the C flag argument is clear, so
                        \ we add object #X's energy to the player's energy in A

 ADC objectTypeEnergy,Y \ The objectTypeEnergy table contains the energy levels
                        \ for each of the object types, so this adds the energy
                        \ of object #X to the player's energy in A
                        \
                        \ The addition works because we know the C flag is
                        \ clear, as we got here by taking a BCC

.uple2

 AND #63                \ Cap the value in A to a maximum of 63, so the player's
                        \ energy is always in the range 0 to 63

 STA playerEnergy       \ Update the player's energy level to the new level in A

 CLC                    \ Clear the C flag to indicate that the player still has
                        \ a positive amount of energy (i.e. 0 or above)

 RTS                    \ Return from the subroutine