Particles: ProcessObjectDestruction

       Name: ProcessObjectDestruction                                [Show more]
       Type: Subroutine
   Category: Particles
    Summary: If this particle has hit an object, destroy the object and the
             particle in an explosion, scoring points if it's a bullet
  Deep dive: Particles and particle clouds
             Collisions and bullets
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * MoveAndDrawParticles (Part 1 of 4) calls ProcessObjectDestruction


 Arguments:

   (R0, R1, R2)                     The particle's coordinates

   R7                               Particle flags

   R9                               The altitude of the landscape directly below
                                    the particle


.ProcessObjectDestruction

 SUB     R8, R9, R1                 \ Set R8 = altitude - y-coordinate
                                    \
                                    \ So R8 contains the vertical distance
                                    \ between the particle and the ground

 CMP     R8, #SAFE_HEIGHT           \ If R8 is higher than the minimum safe
 MOVHS   PC, R14                    \ height for avoiding objects on the ground
                                    \ in SAFE_HEIGHT (which is set to 1.5 tile
                                    \ sizes) then return from the subroutine as
                                    \ the particle is too high off the ground to
                                    \ be hitting any objects

 STMFD   R13!, {R2}                 \ Store R2 on the stack so we can retrieve
                                    \ it below

 STR     R14, [R11, #objectType]    \ Store the return address in objectType
                                    \ (the choice of variable is not important,
                                    \ we are just using it as temporary storage
                                    \ here)

 ADD     R14, R11, #objectMap       \ Set R14 to the address of the object map

 AND     R2, R2, #&FF000000         \ Set the bottom three bytes of R2 to zero,
                                    \ leaving just the top byte, so we can use
                                    \ it in the following

 ADD     R14, R14, R0, LSR #24      \ Set R14 = R14 + (R0 >> 24) + (R2 >> 16)
 ADD     R14, R14, R2, LSR #16      \
                                    \ R0 is shifted into the bottom byte of R14,
                                    \ so that's the x-coordinate, and R2 is
                                    \ shifted into the second byte of R14, so
                                    \ that's the z-coordinate, so R14 points to
                                    \ the object map entry for coordinate
                                    \ (R0, R2)

 LDMFD   R13!, {R2}                 \ Retrieve the value of R2 that we stored
                                    \ above, so it contains the particle
                                    \ y-coordinate once again

 LDRB    R8, [R14]                  \ Set R8 to the byte in the object map at
                                    \ the coordinate (R0, R2)

 CMP     R8, #&FF                   \ If the object map entry is &FF, then there
 LDREQ   PC, [R11, #objectType]     \ is no object on the map at the particle's
                                    \ location, so we haven't hit anything, so
                                    \ return from the subroutine by fetching the
                                    \ return address that we stored above

 CMP     R8, #12                    \ If the object being hit by the particle is
 BHS     AddSmallExplosionToBuffer  \ 12 or greater, then the object has already
                                    \ been destroyed, so draw a small explosion
                                    \ by calling AddSmallExplosionToBuffer, and
                                    \ return from the subroutine using a tail
                                    \ call

 ADD     R8, R8, #12                \ Otherwise the particle has just hit an
 STRB    R8, [R14]                  \ undestroyed object, so add 12 to the
                                    \ object's type in the object map to denote
                                    \ that it has been destroyed

 TST     R7, #&00020000             \ If bit 17 the particle flags is clear then
 LDREQ   R8, [R11, #currentScore]   \ the particle doing the hitting is not a
 ADDEQ   R8, R8, #20                \ rock, so it must be a bullet, so increment
 STREQ   R8, [R11, #currentScore]   \ the current score by 20

 MOV     R8, #20                    \ Set R8 = 20 and call AddExplosionToBuffer
 BL      AddExplosionToBuffer       \ to draw a medium-sized explosion where the
                                    \ particle hit

 B       DeleteParticleData         \ Jump to DeleteParticleData to delete the
                                    \ particle, as it gets destroyed in the
                                    \ explosion, and return from the subroutine
                                    \ using a tail call