scatter_units.moon

----
-- Scatters the given kind of units randomly on a given area on the map.
--
-- @tparam number NUMBER the amount of numbers to scatter
-- @tparam {unit_type_id,...} TYPES
-- @tparam number PADDING_RADIUS minimum distance between the units 
-- @tparam SUF FILTER
-- @tparam Unit_WSL UNIT_WSL
-- @treturn {Unit,...} The list containing the created units 
--    
-- An example which scatters some loyal elves on forest hexes in
-- x,y=10-30,20-40, at a minimum of three hexes apart from each other and
-- never on top of or adjacent to any already existing units:
-- @usage SCATTER_UNITS 20, {"Elvish Fighter", "Elvish Archer", "Elvish Shaman"}, 3,
--     {
--         terrain: "Gs^Fp"
--         x: "10-30"
--         y: "20-40"
--         not:
--             filter: {}
--         not:
--             filter_adjacent_location:
--                 filter: {}
--     },             
--     {       
--         side: 2
--         generate_name: true
--         random_traits: true
--         modifications: TRAIT_LOYAL
--     }
SCATTER_UNITS = (NUMBER, TYPES, PADDING_RADIUS, FILTER, UNIT_WSL) ->
    FILTER.include_borders = false -- isn't excluding borders the deafault?
    possible_unit_locations = store_locations FILTER
    res = {}
    j = 1
    for i = 1, NUMBER
        break if #possible_unit_locations == 0
        shuffleArray(possible_unit_locations)
        loc = possible_unit_locations[i]
        with UNIT_WSL
            .x = loc.x
            .y = loc.y
            .type = TYPES[j]
        res[i] = unit UNIT_WSL
        if j == #TYPES then j = 1 else j += 1
        possible_unit_locations = store_locations
            find_in: possible_unit_locations
            not:
                x: loc.x
                y: loc.y
                radius: PADDING_RADIUS
    return res