3D objects: GetObjectNumber

       Name: GetObjectNumber                                         [Show more]
       Type: Subroutine
   Category: 3D objects
    Summary: Fetch an object number that we can use for a new object of the
             specified type, and add the type to the objectTypes table
  Deep dive: Object management
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * AddEnemiesToTiles calls GetObjectNumber
             * ExpendEnemyEnergy calls GetObjectNumber
             * PerformHyperspace calls GetObjectNumber
             * SpawnPlayer calls GetObjectNumber
             * SpawnTrees calls GetObjectNumber
             * ProcessActionKeys (Part 2 of 2) calls via GetObjectNumber+3


 This routine looks for an object number that isn't currently allocated to an
 object so we can use it to spawn a new object via one of the spawning
 routines. It does this by searching the objectFlags table for a free number
 to allocate. If there is no free number then the routine returns with the
 C flag set, otherwise the C flag is clear, the object type is added to the
 objectTypes table, and X and currentObject are set to the number that we can
 use to spawn the new object.

 Note that this routine only finds a free number and adds the object type to
 the objectTypes table. It doesn't spawn the object - that needs to be done by
 calling SpawnObjectOnTile or SpawnObjectBelow, for example.


 Arguments:

   A                    The type of object that we want to create:

                          * 0 = Robot (one of which is the player)

                          * 1 = Sentry

                          * 2 = Tree

                          * 3 = Boulder

                          * 4 = Meanie

                          * 5 = The Sentinel

                          * 6 = The Sentinel's tower


 Returns:

   X                    The number to use for the new object (if successful)

   currentObject        The number to use for the new object (if successful)

   C flag               Status flag:

                          * Clear if an object number was successfully found

                          * Set if there is no free number for the new object


 Other entry points:

   GetObjectNumber+3    Find an available object number to use for a new object
                        of the type specified in keyPress

                        The keyPress and objectType variables share the same
                        memory location, so this lets us store object types in
                        the key press codes in keyLoggerConfig, so that pressing
                        one of the "create" keys will automatically look for an
                        object number for that type of object


.GetObjectNumber

 STA objectType         \ Store the object type in objectType for future
                        \ reference

 LDX #63                \ In order to be able to create a new object, we need to
                        \ find an unallocated object number in the objectFlags
                        \ table
                        \
                        \ The game can support up to 64 objects, each with its
                        \ own number (0 to 63), so set a counter in X to work
                        \ through the object numbers until we find one that is
                        \ not allocated to an object

.sobj1

 LDA objectFlags,X      \ Set A to the object flags for object #X, which are
                        \ stored in the X-th entry in the objectFlags table

 BMI sobj2              \ If bit 7 of object flags for object #X is set then
                        \ this object number is not yet allocated to an object,
                        \ so jump to sobj2 use this number for our new object

 DEX                    \ Otherwise decrement the counter in X to move on to the
                        \ next object number

 BPL sobj1              \ Loop back to sobj1 to check the next object number

 SEC                    \ If we get here then we have checked all 64 object
                        \ numbers and none of them are free, so set the C flag
                        \ to indicate that we have failed to find an object
                        \ number for the new object

 RTS                    \ Return from the subroutine

.sobj2

                        \ If we get here then we have found an unallocated
                        \ object number in the objectFlags table at index X

 STX currentObject      \ Set currentObject to the object number in X

 LDA objectType         \ Set the corresponding entry in the objectTypes table
 STA objectTypes,X      \ to the object type that we are spawning, which we
                        \ stored in objectType above

 CLC                    \ Clear the C flag to indicate that we have successfully
                        \ added a new object to the objectFlags table

 RTS                    \ Return from the subroutine