3D objects: DeleteObject

       Name: DeleteObject                                            [Show more]
       Type: Subroutine
   Category: 3D objects
    Summary: Delete an object, removing it from the landscape and vacating its
             object number
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * DrainObjectEnergy calls DeleteObject
             * ExpendEnemyEnergy calls DeleteObject
             * PerformHyperspace calls DeleteObject
             * ProcessActionKeys (Part 2 of 2) calls DeleteObject


 Arguments:

   X                    The number of the object to delete


 Returns:

   X                    X is preserved


.DeleteObject

 LDA xObject,X          \ Set (xTile, zTile) to the tile coordinates of the
 STA xTile              \ tile containing object #X
 LDA zObject,X
 STA zTile

 JSR GetTileData        \ Set A to the tile data for the tile anchored at
                        \ (xTile, zTile), which we ignore, but this also sets
                        \ the tile page in tileDataPage and the index in Y, so
                        \ tileDataPage+Y now points to the tile data entry in
                        \ the tileData table for object #X

 LDA objectFlags,X      \ Set A to the object flags for object #X

 CMP #%01000000         \ If both bits 6 and 7 of the object flags for object #X
 BCC delo1              \ are clear then object #X is not stacked on top of
                        \ another object, so jump to delo1 to remove object #X
                        \ from the tile itself

                        \ If we get here then object #X is stacked on top of
                        \ another object, and the number of that object is in
                        \ bits 0 to 5 of the object flags for object #X, which
                        \ is currently in A

 ORA #%11000000         \ Set bits of 6 and 7 of A to create a byte with the
                        \ number of the object below object #X in bits 0 to 5,
                        \ and bits 6 and 7 set
                        \
                        \ We now set this as the updated tile data for the tile
                        \ that used to contain object #X at the top of the
                        \ stack, but which now contains the next object down on
                        \ the top of the stack instead

 BNE delo2              \ Jump to delo2 to store A as the new tile data for this
                        \ tile (this BNE is effectively a JMP as the value of A
                        \ before the ORA has to have at least one of bits 6 and
                        \ 7 set, so the result of the ORA is never zero)

.delo1

                        \ If we get here then object #X is not stacked on top of
                        \ another object, so we can remove the object from the
                        \ tile by changing the tile data into the following
                        \ format:
                        \
                        \   * The low nibble contains the tile shape, which in
                        \     this case is flat because only flat tiles can
                        \     contain objects, so we need to set the low nibble
                        \     to shape 0 (to indicate a flat tile)
                        \
                        \   * The high nibble contains the altitude of the tile
                        \     corner in the front-left corner of the tile
                        \
                        \ The altitude of object #X is a 16-bit value in
                        \ yObject(Hi Lo), where the yObjectLo part is
                        \ effectively a fractional part of the altitude that
                        \ describes how far the object is above the tile itself
                        \
                        \ Tile altitudes are whole numbers, so the altitude of
                        \ the tile on which object #X is placed is given in the
                        \ high byte of the object's 16-bit altitude

 LDA yObjectHi,X        \ Set the high nibble of A to the high byte of the
 ASL A                  \ altitude of object #X (which is the tile's altitude)
 ASL A                  \ and set the low nibble to zero to indicate a flat tile
 ASL A                  \
 ASL A                  \ A is now in the format required for the tileData table
                        \ for a flat tile that doesn't contain an object, so we
                        \ can update the tile's data to remove object #X from
                        \ the tile

.delo2

 STA (tileDataPage),Y   \ Update the tile data for object #X to the value in A
                        \ (as we set Y to the relevant index with the call to
                        \ GetTileData above)

 LDA #%10000000         \ Set bit 7 of the object flags for object #X to denote
 STA objectFlags,X      \ that object number X has not been allocated to an
                        \ object and is reusable, so this effectively deletes
                        \ the object

 RTS                    \ Return from the subroutine