Cob Extensions - Searching for units

Ext. ID Ext. Name Type Description
170 UNITS_NEAR GET create search array of units near caller unit
Parameters: SearchFilter, MaxDistance, FreeArrayId, UnitTypeCrcFilter
Result: FoundUnitsCount
171 UNITS_YARDMAP GET create search array with units that share yardmap of caller unit
Parameters: SearchFilter, Sensitivity (0 or 1), FreeArrayId, UnitTypeCrcFilter
Result: FoundUnitsCount
172 UNITS_WHOLEMAP GET create search array with units
Parameters: SearchFilter, MaxDistance, FreeArrayId, UnitTypeCrcFilter
Result: FoundUnitsCount
173 UNITS_ARRAY_RESULT GET Get unit ID from search/spawned units array
Parameters: FreeArrayId, ArrayElementIdx, ArrayType (1 = Units search array, 2 = Spawned minions array)
Result: UnitId
174 RANDOMIZE_UNITS_ARRAY GET randomize entries in result array
Parameters: FreeArrayId, ArrayType (1 = Units search array, 2 = Spawned minions array)
175 FREE_ARRAY_ID GET Prepare and get array ID for unit searching / spawned minions
Parameters: ArrayType (1 = Units search array, 2 = Spawned minions array)
Result: FreeArrayId
176 CLEAR_ARRAY_ID GET Clear array, to make it available for further units searches / spawned minions
Parameters: ArrayType (1 = Units search array, 2 = Spawned minions array), ArrayElementIdx
177 UNIT_NEAREST GET find nearest unit (single), no array will be created
Parameters: SearchFilter, MaxDistance (0 to search whole map), UnitTypeCrcFilter
Result: UnitId or 0 if no unit found
178 DISTANCE GET returns distance between two units
Parameters: UnitId1, UnitId2

This search mechanism is similar to how making queries to databases work. You prepare database to search something, you ask for it, and then whenever you finished working with search results - you ask to free your search ID for further searches.

Advantages vs searching scripts in COB:

- not overloading COB script
- can access search results from different COB methods at any time without using global variables
- no more "units of height x" searches to get ID of specific unit

SearchFilter - can be zero or any of (or a combination that makes sense):

#define usfOwner 1
#define usfAllied 2
#define usfEnemy 4
#define usfAI 8
#define usfExcludeAir 16
#define usfExcludeSea 32
#define usfExcludeBuildings 64
#define usfExcludeNonWeaponed 128
#define usfIncludeInBuildState 256


UnitTypeCrcFilter - unit type CRC ID that you are only looking for

Examples

Yardmap search

{
  var lSearchId, lUnitId, nCurrIdx, nFoundCount;
  while (TRUE)
  {
    lSearchId = get FREE_ARRAY_ID(1);
    // only units of type #20, that are currently on caller unit yardmap
    // owned by caller unit owner, excluding air units
    nFoundCount = get UNITS_YARDMAP(usfOwner + usfExcludeAir, 0, lSearchId, 20);
    if (nFoundCount > 0)
    {
      nCurrIdx = 1;
      while (nCurrIdx <= nFoundCount)
      {
        // result array is 1..nFoundCount size
        lUnitId = get UNITS_ARRAY_RESULT(lSearchId, nCurrIdx, 1);
        // do something with the unit
        nCurrIdx = nCurrIdx + 1;
      }
    }
    // tell TADR to free this search id
    get CLEAR_ARRAY_ID(1, lSearchId);
    sleep rand(1000, 2000);
  }
}

Simple (single unit) search

This type of search don't require preparing/freeing search array.
No filters, whole map, unit type ARMMEX:
lUnitId = get UNIT_NEAREST(0, 0, ARMMEX);

Only enemy units, near by distance of 150, unit type unknown:
lUnitId = get UNIT_NEAREST(usfEnemy, 150);