The Theme: SpawnAlien

       Name: SpawnAlien                                              [Show more]
       Type: Subroutine
   Category: The Theme
    Summary: If the Theme is enabled and the current wave does not yet have
             eight aliens in it, spawn a new alien
  Deep dive: Alien feeding and growth patterns
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * MainLoop (Part 1 of 15) calls SpawnAlien


 This routine tries to add a new alien to the current wave. It sets the alien's
 state to 0, and chooses a random object ID from the range 16 to 29 for the
 alien. If this object ID is already in use by an alien that we've already
 spawned for this wave, then it aborts the spawning, otherwise it allocates the
 object ID to the new alien's alienObjectId entry and our new alien is spawned.

 This means that aliens only ever spawn in the fixed locations for objects 16
 to 29, which can be seen in the xObjectLo table.

 This is called SUTR in the original source code.


.SpawnAlien

 LDX themeStatus        \ If bit 7 of themeStatus is set, then the Theme is not
 BMI spaw3              \ enabled, so jump to spaw3 to return from the
                        \ subroutine

 BEQ spaw3              \ If themeStatus is zero, then we have already spawned
                        \ all eight aliens in this wave, so return from the
                        \ subroutine

 LDA onGround           \ If onGround is non-zero, then we are on the ground, so
 BNE spaw3              \ jump to spaw3 to return from the subroutine

                        \ If we get here, themeStatus is in the range 1 to 8 and
                        \ we are not on the ground, so the Theme has started but
                        \ we haven't yet spawned all eight aliens in the current
                        \ wave, so we need to spawn another alien (specifically
                        \ the alien whose ID is in themeStatus)

 STA alienState-1,X     \ We know A is 0, as we just passed through a BNE above,
                        \ so this zeroes the state of the alien whose number is
                        \ in themeStatus, so it starts its feeding routine from
                        \ scratch

                        \ We now need to allocate an object ID to this alien,
                        \ from the range 16 to 29, making sure we don't reuse
                        \ any objects that are currently in use by other aliens
                        \ in the wave

 LDA VIA+&64            \ Read the 6522 User VIA T1C-L timer 1 low-order
                        \ counter (SHEILA &64), which decrements one million
                        \ times a second and will therefore be pretty random

 AND #15                \ Reduce the random number to the range 0 to 15

 CMP #14                \ If the random number is >= 14 (12.5% chance), jump to
 BCS spaw3              \ spaw3 to return from the subroutine

 ORA #16                \ Increase the random number to the range 16 to 29, to
                        \ give us a potential object ID

 DEC themeStatus        \ We are spawning a new alien, so decrement the counter
                        \ in themeStatus so it reflects the number of aliens
                        \ that still have to spawn to complete this wave

 LDX #8                 \ We now need to confirm that this object ID isn't being
                        \ used by any other aliens that we've already spawned in
                        \ this wave, so set X to act as a loop counter, going
                        \ from 8 down to themeStatus (so this works through the
                        \ IDs of the aliens that we have already spawned in this
                        \ wave, as we start spawning at ID 8 and work our way
                        \ down to 1)

.spaw1

 DEX                    \ Decrement the loop counter

 CPX themeStatus        \ If X <> themeStatus, jump to spaw2 to check this
 BNE spaw2              \ alien's object ID

 STA alienObjectId,X    \ Otherwise we have run through all the other aliens in
                        \ this wave and none of them are using this object ID,
                        \ so set this as the object ID for this alien

 RTS                    \ Return from the subroutine

.spaw2

 CMP alienObjectId,X    \ If the object ID for the X-th alien does not match our
 BNE spaw1              \ random number, then jump back to spaw1 to move on to
                        \ the next alien

 INC themeStatus        \ Otherwise we've found an alien that is already using
                        \ the object ID we generated above, so we give up on
                        \ spawning this alien, incrementing the alien counter
                        \ in themeStatus so that it's back to the original value
                        \ (so we can have another go at spawning an alien on the
                        \ next call to SpawnAlien)

.spaw3

 RTS                    \ Return from the subroutine