3D objects: PlaceObjectBelow

       Name: PlaceObjectBelow                                        [Show more]
       Type: Subroutine
   Category: 3D objects
    Summary: Attempt to place an object on a tile that is below the maximum
             altitude specified in A
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * ExpendEnemyEnergy calls PlaceObjectBelow
             * PerformHyperspace calls PlaceObjectBelow
             * SpawnPlayer calls PlaceObjectBelow
             * SpawnTrees calls PlaceObjectBelow


 Arguments:

   A                    The maximum desired altitude of the object (though we
                        may end up placing the object higher than this)

   X                    The number of the object to add to the tile


 Returns:

   C flag               Status flag:

                          * Clear if the object was successfully placed on a
                            tile

                          * Set if the object was not placed on a suitable tile


.PlaceObjectBelow

 STA tileAltitude       \ Store the maximum altitude in tileAltitude

 LDA #0                 \ We now loop through the landscape tiles, trying to
 STA loopCounter        \ find a suitable location for the object, so set a
                        \ loop counter to count 255 iterations for each loop

.objb1

 DEC loopCounter        \ Decrement the loop counter

 BNE objb2              \ If we have not counted all 255 iterations yet, jump to
                        \ objb2 to skip the following

                        \ If we get here then we have tried 255 tiles at the
                        \ altitude in tileAltitude, but without success, so we
                        \ move to a higher altitude and try again

 INC tileAltitude       \ Increment the altitude in tileAltitude to move up by
                        \ one coordinate (where a tile-sized cube is one
                        \ coordinate across)

 LDA tileAltitude       \ If we just incremented tileAltitude to 12 then we have
 CMP #12                \ gone past the highest altitude possible, so jump to
 BCS objb3              \ objb3 to return from the subroutine with the C flag
                        \ set to indicate failure

                        \ Otherwise keep going to look for a suitable tile at
                        \ the new, higher altitude

.objb2

                        \ We now try to pick a tile in the landscape that might
                        \ be suitable for placing our object

 JSR GetNextSeed0To30   \ Set A to the next number from the landscape's sequence
                        \ of seed numbers, converted to the range 0 to 30

 STA xTile              \ Set xTile to this seed number, so it points to a
                        \ tile corner that anchors a tile (so the tile corner
                        \ isn't along the right edge of the landscape)

 JSR GetNextSeed0To30   \ Set A to the next number from the landscape's sequence
                        \ of seed numbers, converted to the range 0 to 30

 STA zTile              \ Set zTile to this seed number, so it points to a
                        \ tile corner that anchors a tile (so the tile corner
                        \ isn't along the far edge of the landscape)

 JSR GetTileData        \ Set A to the tile data for the tile anchored at
                        \ (xTile, zTile), setting the C flag if the tile
                        \ contains an object

 BCS objb1              \ If the tile already contains an object, jump to objb1
                        \ to try another tile from the landscape's sequence of
                        \ seed numbers

 AND #%00001111         \ If the tile shape in the low nibble of the tile data
 BNE objb1              \ is non-zero, then the tile is not flat, so jump to
                        \ objb1 to try another tile from the landscape's
                        \ sequence of seed numbers

 LDA (tileDataPage),Y   \ Set A to the tile data for the tile anchored at
                        \ (xTile, zTile)

 LSR A                  \ Set A to the tile altitude, which is in the top nibble
 LSR A                  \ of the tile data
 LSR A
 LSR A

 CMP tileAltitude       \ If the altitude of the chosen tile is equal to or
 BCS objb1              \ higher than the minimum altitude in tileAltitude, then
                        \ this tile is too high, so jump to objb1 to try another
                        \ tile from the landscape's sequence of seed numbers

                        \ If we get here then we have found a tile that is below
                        \ the altitude in tileAltitude and which doesn't already
                        \ contain an object, so we can use this for placing our
                        \ object

 JSR PlaceObjectOnTile  \ Place object #X on the tile anchored at (xTile, zTile)

 CLC                    \ Clear the C flag to indicate that we have successfully
                        \ placed the object on a tile

 RTS                    \ Return from the subroutine

.objb3

 SEC                    \ Set the C flag to indicate that we have failed to
                        \ place the object on a suitable tile

 RTS                    \ Return from the subroutine